OpenJDK 27 · java.net.URLConnection · APIdia, the JavaDoc alternative

The abstract class URLConnection is the superclass of all classes that represent a communications link between the application and a URL. Instances of this class can be used both to read from and to write to the resource referenced by the URL.

In general, creating a connection to a URL is a multistep process:

The connection object is created by invoking the openConnection method on a URL.
The setup parameters and general request properties are manipulated.
The actual connection to the remote object is made, using the connect method.
The remote object becomes available. The header fields and the contents of the remote object can be accessed.

The setup parameters are modified using the following methods:

setAllowUserInteraction
setDoInput
setDoOutput
setIfModifiedSince
setUseCaches

and the general request properties are modified using the method:

setRequestProperty

Default values for the AllowUserInteraction and UseCaches parameters can be set using the methods setDefaultAllowUserInteraction and setDefaultUseCaches.

Each of the above set methods has a corresponding get method to retrieve the value of the parameter or general request property. The specific parameters and general request properties that are applicable are protocol specific.

The following methods are used to access the header fields and the contents after the connection is made to the remote object:

getContent
getHeaderField
getInputStream
getOutputStream

Certain header fields are accessed frequently. The methods:

getContentEncoding
getContentLength
getContentType
getDate
getExpiration
getLastModified

provide convenient access to these fields. The getContentType method is used by the getContent method to determine the type of the remote object; subclasses may find it convenient to override the getContentType method.

In the common case, all of the pre-connection parameters and general request properties can be ignored: the pre-connection parameters and request properties default to sensible values. For most clients of this interface, there are only two interesting methods: getInputStream and getContent, which are mirrored in the URL class by convenience methods.

More information on the request properties and header fields of an http connection can be found at:

http://www.ietf.org/rfc/rfc2616.txt

Invoking the close() methods on the InputStream or OutputStream of an URLConnection after a request may free network resources associated with this instance, unless particular protocol specifications specify different behaviours for it.

Modifier and Type	Field and Description
protected boolean	allowUserInteraction If `true`, this `URL` is being examined in a context in which it makes sense to allow user interactions such as popping up an authentication dialog.
protected boolean	connected If `false`, this connection object has not created a communications link to the specified URL.
private int	connectTimeout
private static final String	contentClassPrefix
private static final String	contentPathProp
private static boolean	defaultAllowUserInteraction
private static final ConcurrentHashMap<String, Boolean>	defaultCaching
private static volatile boolean	defaultUseCaches
protected boolean	doInput This variable is set by the `setDoInput` method.
protected boolean	doOutput This variable is set by the `setDoOutput` method.
private static volatile ContentHandlerFactory	factory The ContentHandler factory.
private static volatile FileNameMap	fileNameMap
private static final Hashtable<String, ContentHandler>	handlers
protected long	ifModifiedSince Some protocols support skipping the fetching of the object unless the object has been modified more recently than a certain time.
private int	readTimeout
private MessageHeader	requests
protected URL	url The URL represents the remote object on the World Wide Web to which this connection is opened.
protected boolean	useCaches If `true`, the protocol is allowed to use caching whenever it can.

Access	Constructor and Description
protected	URLConnection(URL the specified URL. url) Constructs a URL connection to the specified URL.

Method Summary

Modifier and Type	Method and Description
public void	addRequestProperty(String the keyword by which the request is known (e.g., "`Accept`"). key, String the value associated with it. value) Adds a general request property specified by a key-value pair.
private void	checkConnected()
private static boolean	checkfpx(InputStream is) Check for FlashPix image data in InputStream is.
public abstract void	connect() Opens a communications link to the resource referenced by this URL, if such a connection has not already been established.
public boolean	Returns: the value of the `allowUserInteraction` field for this object. getAllowUserInteraction() Returns the value of the `allowUserInteraction` field for this object.
public int	Returns: an `int` that indicates the connect timeout value in milliseconds getConnectTimeout() Returns setting for connect timeout.
public Object	Returns: the object fetched. The `instanceof` operator should be used to determine the specific kind of object returned. getContent() Retrieves the contents of this URL connection.
public Object	Returns: the object fetched that is the first match of the type specified in the classes array. null if none of the requested types are supported. The `instanceof` operator should be used to determine the specific kind of object returned. getContent(Class<?>[] the `Class` array indicating the requested types classes) Retrieves the contents of this URL connection.
public String	Returns: the content encoding of the resource that the URL references, or `null` if not known. getContentEncoding() Returns the value of the `content-encoding` header field.
private ContentHandler	getContentHandler() Gets the Content Handler appropriate for this connection.
private String	getContentHandlerPkgPrefixes() Returns a vertical bar separated list of package prefixes for potential content handlers.
public int	Returns: the content length of the resource that this connection's URL references, `-1` if the content length is not known, or if the content length is greater than Integer.MAX_VALUE. getContentLength() Returns the value of the `content-length` header field.
public long	Returns: the content length of the resource that this connection's URL references, or `-1` if the content length is not known. getContentLengthLong() Returns the value of the `content-length` header field as a long.
public String	Returns: the content type of the resource that the URL references, or `null` if not known. getContentType() Returns the value of the `content-type` header field.
public long	Returns: the sending date of the resource that the URL references, or `0` if not known. The value returned is the number of milliseconds since January 1, 1970 GMT. getDate() Returns the value of the `date` header field.
public static boolean	Returns: the default value of the `allowUserInteraction` field. getDefaultAllowUserInteraction() Returns the default value of the `allowUserInteraction` field.
public static String	Returns: the value of the default request property for the specified key. getDefaultRequestProperty(String the keyword by which the request is known (e.g., "Accept"). key) Deprecated The instance specific getRequestProperty method should be used after an appropriate instance of URLConnection is obtained. Returns the value of the default request property.
public boolean	Returns: the default value of a `URLConnection`'s `useCaches` flag. getDefaultUseCaches() Returns the default value of a `URLConnection`'s `useCaches` flag.
public static boolean	Returns: the default value of the `useCaches` flag for the given protocol. getDefaultUseCaches(String the protocol whose defaultUseCaches setting is required protocol) Returns the default value of the `useCaches` flag for the given protocol.
public boolean	Returns: the value of this `URLConnection`'s `doInput` flag. getDoInput() Returns the value of this `URLConnection`'s `doInput` flag.
public boolean	Returns: the value of this `URLConnection`'s `doOutput` flag. getDoOutput() Returns the value of this `URLConnection`'s `doOutput` flag.
public long	Returns: the expiration date of the resource that this URL references, or 0 if not known. The value is the number of milliseconds since January 1, 1970 GMT. getExpiration() Returns the value of the `expires` header field.
public static FileNameMap	Returns: the FileNameMap getFileNameMap() Loads filename map (a mimetable) from a data file.
public String	Returns: the value of the named header field, or `null` if there is no such field in the header. getHeaderField(String the name of a header field. name) Returns the value of the named header field.
public String	Returns: the value of the `n`^th header field or `null` if there are fewer than `n+1` fields getHeaderField(int an index, where `n>=0` n) Returns the value for the `n`^th header field.
public long	Returns: the value of the field, parsed as a date. The value of the `defaultValue` argument is returned if the field is missing or malformed. getHeaderFieldDate(String the name of the header field. name, long a default value. defaultValue) Returns the value of the named field parsed as date.
public int	Returns: the value of the named field, parsed as an integer. The `defaultValue` value is returned if the field is missing or malformed. getHeaderFieldInt(String the name of the header field. name, int the default value. defaultValue) Returns the value of the named field parsed as a number.
public String	Returns: the key for the `n`^th header field, or `null` if there are fewer than `n+1` fields when `n > 0`. getHeaderFieldKey(int an index, where `n>=0` n) Returns the key for the `n`^th header field.
public long	Returns: the value of the named field, parsed as a long. The `defaultValue` value is returned if the field is missing or malformed. getHeaderFieldLong(String the name of the header field. name, long the default value. defaultValue) Returns the value of the named field parsed as a number.
public Map<String, List<String>>	Returns: a Map of header fields getHeaderFields() Returns an unmodifiable Map of the header fields.
public long	Returns: the value of this object's `ifModifiedSince` field. getIfModifiedSince() Returns the value of this object's `ifModifiedSince` field.
public InputStream	Returns: an input stream that reads from this open connection. getInputStream() Returns an input stream that reads from this open connection.
public long	Returns: the date the resource referenced by this `URLConnection` was last modified, or 0 if not known. getLastModified() Returns the value of the `last-modified` header field.
public OutputStream	Returns: an output stream that writes to this connection. getOutputStream() Returns an output stream that writes to this connection.
public Permission	Returns: the permission object representing the permission necessary to make the connection represented by this URLConnection. getPermission() Deprecated for removal since 25. Permissions can no longer be used for controlling access to resources as the Security Manager is no longer supported. Returns a permission object representing the permission necessary to make the connection represented by this object.
public int	Returns: an `int` that indicates the read timeout value in milliseconds getReadTimeout() Returns setting for read timeout.
public Map<String, List<String>>	Returns: a Map of the general request properties for this connection. getRequestProperties() Returns an unmodifiable Map of general request properties for this connection.
public String	Returns: the value of the named general request property for this connection. If key is null, then null is returned. getRequestProperty(String the keyword by which the request is known (e.g., "Accept"). key) Returns the value of the named general request property for this connection.
public URL	Returns: the value of this `URLConnection`'s `URL` field. getURL() Returns the value of this `URLConnection`'s `URL` field.
public boolean	Returns: the value of this `URLConnection`'s `useCaches` field. getUseCaches() Returns the value of this `URLConnection`'s `useCaches` field.
public static String	Returns: a guess as to what the content type of the object is, based upon its file name. guessContentTypeFromName(String a filename. fname) Tries to determine the content type of an object, based on the specified "file" component of a URL.
public static String	Returns: a guess at the content type, or `null` if none can be determined. guessContentTypeFromStream(InputStream an input stream that supports marks. is) Tries to determine the type of an input stream based on the characters at the beginning of the input stream.
private ContentHandler	lookupContentHandlerClassFor(String contentType) Looks for a content handler in a user-definable set of places.
private ContentHandler	lookupContentHandlerViaProvider(String contentType)
private static int	readBytes(int[] c, int len, InputStream is) Tries to read the specified number of bytes from the stream Returns -1, If EOF is reached before len bytes are read, returns 0 otherwise
public void	setAllowUserInteraction(boolean the new value. allowuserinteraction) Set the value of the `allowUserInteraction` field of this `URLConnection`.
public void	setConnectTimeout(int an `int` that specifies the connect timeout value in milliseconds timeout) Sets a specified timeout value, in milliseconds, to be used when opening a communications link to the resource referenced by this URLConnection.
public static synchronized void	setContentHandlerFactory(ContentHandlerFactory the desired factory. fac) Sets the `ContentHandlerFactory` of an application.
public static void	setDefaultAllowUserInteraction(boolean the new value. defaultallowuserinteraction) Sets the default value of the `allowUserInteraction` field for all future `URLConnection` objects to the specified value.
public static void	setDefaultRequestProperty(String the keyword by which the request is known (e.g., "`Accept`"). key, String the value associated with the key. value) Deprecated The instance specific setRequestProperty method should be used after an appropriate instance of URLConnection is obtained. Invoking this method will have no effect. Sets the default value of a general request property.
public void	setDefaultUseCaches(boolean the new value. defaultusecaches) Sets the default value of the `useCaches` field to the specified value.
public static void	setDefaultUseCaches(String the protocol to set the default for protocol, boolean whether caching is enabled by default for the given protocol defaultVal) Sets the default value of the `useCaches` field for the named protocol to the given value.
public void	setDoInput(boolean the new value. doinput) Sets the value of the `doInput` field for this `URLConnection` to the specified value.
public void	setDoOutput(boolean the new value. dooutput) Sets the value of the `doOutput` field for this `URLConnection` to the specified value.
public static void	setFileNameMap(FileNameMap the FileNameMap to be set map) Sets the FileNameMap.
public void	setIfModifiedSince(long the new value. ifmodifiedsince) Sets the value of the `ifModifiedSince` field of this `URLConnection` to the specified value.
public void	setReadTimeout(int an `int` that specifies the timeout value to be used in milliseconds timeout) Sets the read timeout to a specified timeout, in milliseconds.
public void	setRequestProperty(String the keyword by which the request is known (e.g., "`Accept`"). key, String the value associated with it. value) Sets the general request property.
public void	setUseCaches(boolean a `boolean` indicating whether or not to allow caching usecaches) Sets the value of the `useCaches` field of this `URLConnection` to the specified value.
private static long	skipForward(InputStream is, long toSkip) Skips through the specified number of bytes from the stream until either EOF is reached, or the specified number of bytes have been skipped
private String	stripOffParameters(String contentType)
public String	Returns: a string representation of this `URLConnection`. toString() Overrides java.lang.Object.toString. Returns a `String` representation of this URL connection.
private String	typeToPackageName(String contentType) Utility function to map a MIME content type into an equivalent pair of class name components.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

public abstract Class URLConnection

Field Summary

Constructor Summary

Method Summary