java.lang.Object | |
↳ | java.net.URLConnection |
Known Direct Subclasses |
Known Indirect Subclasses |
A connection to a URL for reading or writing. For HTTP connections, see
HttpURLConnection
for documentation of HTTP-specific features.
For example, to retrieve ftp://mirror.csclub.uwaterloo.ca/index.html
:
URL url = new URL("ftp://mirror.csclub.uwaterloo.ca/index.html");
URLConnection urlConnection = url.openConnection();
InputStream in = new BufferedInputStream(urlConnection.getInputStream());
try {
readStream(in);
finally {
in.close();
}
}
URLConnection
must be configured before it has connected to the
remote resource. Instances of URLConnection
are not reusable: you
must use a different instance for each connection to a resource.
URLConnection
supports two timeouts: a connect timeout
and a read timeout
. By default,
operations never time out.
file:
URIs. File connections can only be used for input.
By default, FTP connections will be made using anonymous
as
the username and the empty string as the password. Specify alternate
usernames and passwords in the URL: ftp://username:password@host/path
.
HttpURLConnection
and HttpsURLConnection
subclasses.
JarURLConnection
subclass.
setURLStreamHandlerFactory(URLStreamHandlerFactory)
to register handlers for other
protocol types.
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
allowUserInteraction | Specifies whether this URLConnection allows user interaction as
it is needed for authentication purposes. |
||||||||||
connected | Specifies whether this URLConnection is already connected to the
remote resource. |
||||||||||
doInput | Specifies whether this URLConnection allows receiving data. |
||||||||||
doOutput | Specifies whether this URLConnection allows sending data. |
||||||||||
ifModifiedSince | The data must be modified more recently than this time in milliseconds since January 1, 1970, GMT to be transmitted. | ||||||||||
url | The URL which represents the remote target of this URLConnection . |
||||||||||
useCaches | Specifies whether the using of caches is enabled or the data has to be recent for every request. |
Protected Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Creates a new
URLConnection instance pointing to the resource
specified by the given URL. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Adds the given property to the request header.
| |||||||||||
Opens a connection to the resource.
| |||||||||||
Returns the option value which indicates whether user interaction is allowed
on this
URLConnection . | |||||||||||
Returns the configured connecting timeout.
| |||||||||||
Returns an object representing the content of the resource this
URLConnection is connected to. | |||||||||||
Returns an object representing the content of the resource this
URLConnection is connected to. | |||||||||||
Returns the content encoding type specified by the response header field
content-encoding or null if this field is not set. | |||||||||||
Returns the content length in bytes specified by the response header field
content-length or -1 if this field is not set. | |||||||||||
Returns the MIME-type of the content specified by the response header field
content-type or null if type is unknown. | |||||||||||
Returns the timestamp when this response has been sent as a date in
milliseconds since January 1, 1970 GMT or
0 if this timestamp is
unknown. | |||||||||||
Returns the default setting whether this connection allows user interaction.
| |||||||||||
This method is deprecated.
Use
getRequestProperty(String)
| |||||||||||
Returns the default setting whether this connection allows using caches.
| |||||||||||
Returns the value of the option
doInput which specifies whether this
connection allows to receive data. | |||||||||||
Returns the value of the option
doOutput which specifies whether
this connection allows to send data. | |||||||||||
Returns the timestamp when this response will be expired in milliseconds
since January 1, 1970 GMT or
0 if this timestamp is unknown. | |||||||||||
Returns the table which is used by all
URLConnection instances to
determine the MIME-type according to a file extension. | |||||||||||
Returns the value of the header field specified by
key or null if there is no field with this name. | |||||||||||
Returns the header value at the field position
pos or null
if the header has fewer than pos fields. | |||||||||||
Returns the specified header value as a date in milliseconds since January
1, 1970 GMT.
| |||||||||||
Returns the specified header value as a number.
| |||||||||||
Returns the name of the header field at the given position
posn or
null if there are fewer than posn fields. | |||||||||||
Returns an unchangeable map of the response-header fields and values.
| |||||||||||
Returns the point of time since when the data must be modified to be
transmitted.
| |||||||||||
Returns an
InputStream for reading data from the resource pointed by
this URLConnection . | |||||||||||
Returns the value of the response header field
last-modified or
0 if this value is not set. | |||||||||||
Returns an
OutputStream for writing data to this URLConnection . | |||||||||||
Returns a
Permission object representing all needed permissions to
open this connection. | |||||||||||
Returns the configured timeout for reading from the input stream of an
established connection to the resource.
| |||||||||||
Returns an unchangeable map of general request properties used by this
connection.
| |||||||||||
Returns the value of the request header property specified by {code field}
or
null if there is no field with this name. | |||||||||||
Returns the URL represented by this
URLConnection . | |||||||||||
Returns the value of the flag which specifies whether this
URLConnection allows to use caches. | |||||||||||
Determines the MIME-type of the given resource
url by resolving
the filename extension with the internal FileNameMap. | |||||||||||
Determines the MIME-type of the resource represented by the input stream
is by reading its first few characters. | |||||||||||
Sets the flag indicating whether this connection allows user interaction
or not.
| |||||||||||
Sets the timeout value in milliseconds for establishing the connection to
the resource pointed by this
URLConnection instance. | |||||||||||
Sets the internally used content handler factory.
| |||||||||||
Sets the default value for the flag indicating whether this connection
allows user interaction or not.
| |||||||||||
This method is deprecated.
Use
setRequestProperty(String, String) of an existing URLConnection instance.
| |||||||||||
Sets the default value for the flag indicating whether this connection
allows to use caches.
| |||||||||||
Sets the flag indicating whether this
URLConnection allows input. | |||||||||||
Sets the flag indicating whether this
URLConnection allows
output. | |||||||||||
Sets the internal map which is used by all
URLConnection
instances to determine the MIME-type according to a filename extension. | |||||||||||
Sets the point of time since when the data must be modified to be
transmitted.
| |||||||||||
Sets the timeout value in milliseconds for reading from the input stream
of an established connection to the resource.
| |||||||||||
Sets the value of the specified request header field.
| |||||||||||
Sets the flag indicating whether this connection allows to use caches or
not.
| |||||||||||
Returns the string representation containing the name of this class and
the URL.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class java.lang.Object
|
Specifies whether this URLConnection
allows user interaction as
it is needed for authentication purposes.
Specifies whether this URLConnection
is already connected to the
remote resource. If this field is set to true
the flags for
setting up the connection are not changeable anymore.
Specifies whether this URLConnection
allows receiving data.
Specifies whether this URLConnection
allows sending data.
The data must be modified more recently than this time in milliseconds since January 1, 1970, GMT to be transmitted.
The URL which represents the remote target of this URLConnection
.
Specifies whether the using of caches is enabled or the data has to be recent for every request.
Creates a new URLConnection
instance pointing to the resource
specified by the given URL.
url | the URL which represents the resource this URLConnection will point to.
|
---|
Adds the given property to the request header. Existing properties with the same name will not be overwritten by this method.
field | the request property field name to add. |
---|---|
newValue | the value of the property which is to add. |
IllegalStateException | if the connection has been already established. |
---|---|
NullPointerException | if the property name is null . |
Opens a connection to the resource. This method will not reconnect to a resource after the initial connection has been closed.
IOException | if an error occurs while connecting to the resource. |
---|
Returns the option value which indicates whether user interaction is allowed
on this URLConnection
.
allowUserInteraction
.Returns the configured connecting timeout.
Returns an object representing the content of the resource this URLConnection
is connected to. First, it attempts to get the content
type from the method getContentType()
which looks at the response
header field "Content-Type". If none is found it will guess the content
type from the filename extension. If that fails the stream itself will be
used to guess the content type.
IOException | if an error occurs obtaining the content. |
---|
Returns an object representing the content of the resource this URLConnection
is connected to. First, it attempts to get the content
type from the method getContentType()
which looks at the response
header field "Content-Type". If none is found it will guess the content
type from the filename extension. If that fails the stream itself will be
used to guess the content type. The content type must match with one of
the list types
.
types | the list of acceptable content types. |
---|
null
if the content
type does not match with one of the specified types.IOException | if an error occurs obtaining the content. |
---|
Returns the content encoding type specified by the response header field
content-encoding
or null
if this field is not set.
content-encoding
.
Returns the content length in bytes specified by the response header field
content-length
or -1
if this field is not set.
content-length
.
Returns the MIME-type of the content specified by the response header field
content-type
or null
if type is unknown.
content-type
.
Returns the timestamp when this response has been sent as a date in
milliseconds since January 1, 1970 GMT or 0
if this timestamp is
unknown.
Returns the default setting whether this connection allows user interaction.
defaultAllowUserInteraction
.
This method is deprecated.
Use getRequestProperty(String)
Returns the default value for the specified request field
or null
if the field could not be found. The base implementation of this
method returns always null
.
field | the request field whose default value shall be returned. |
---|
Returns the default setting whether this connection allows using caches.
defaultUseCaches
.Returns the value of the option doInput
which specifies whether this
connection allows to receive data.
true
if this connection allows input, false
otherwise.Returns the value of the option doOutput
which specifies whether
this connection allows to send data.
true
if this connection allows output, false
otherwise.Returns the timestamp when this response will be expired in milliseconds
since January 1, 1970 GMT or 0
if this timestamp is unknown.
expires
.
Returns the table which is used by all URLConnection
instances to
determine the MIME-type according to a file extension.
Returns the value of the header field specified by key
or null
if there is no field with this name. The base implementation of
this method returns always null
.
Some implementations (notably HttpURLConnection
) include a mapping
for the null key; in HTTP's case, this maps to the HTTP status line and is
treated as being at position 0 when indexing into the header fields.
key | the name of the header field. |
---|
Returns the header value at the field position pos
or null
if the header has fewer than pos
fields. The base
implementation of this method returns always null
.
Some implementations (notably HttpURLConnection
) include a mapping
for the null key; in HTTP's case, this maps to the HTTP status line and is
treated as being at position 0 when indexing into the header fields.
pos | the field position of the response header. |
---|
pos
.
Returns the specified header value as a date in milliseconds since January
1, 1970 GMT. Returns the defaultValue
if no such header field
could be found.
field | the header field name whose value is needed. |
---|---|
defaultValue | the default value if no field has been found. |
Returns the specified header value as a number. Returns the defaultValue
if no such header field could be found or the value could
not be parsed as an Integer
.
field | the header field name whose value is needed. |
---|---|
defaultValue | the default value if no field has been found. |
Returns the name of the header field at the given position posn
or
null
if there are fewer than posn
fields. The base
implementation of this method returns always null
.
Some implementations (notably HttpURLConnection
) include a mapping
for the null key; in HTTP's case, this maps to the HTTP status line and is
treated as being at position 0 when indexing into the header fields.
posn | the position of the header field which has to be returned. |
---|
Returns an unchangeable map of the response-header fields and values. The response-header field names are the key values of the map. The map values are lists of header field values associated with a particular key name.
Some implementations (notably HttpURLConnection
) include a mapping
for the null key; in HTTP's case, this maps to the HTTP status line and is
treated as being at position 0 when indexing into the header fields.
Returns the point of time since when the data must be modified to be transmitted. Some protocols transmit data only if it has been modified more recently than a particular time.
Returns an InputStream
for reading data from the resource pointed by
this URLConnection
. It throws an UnknownServiceException by
default. This method must be overridden by its subclasses.
IOException | if no InputStream could be created. |
---|
Returns the value of the response header field last-modified
or
0
if this value is not set.
last-modified
header field.
Returns an OutputStream
for writing data to this URLConnection
. It throws an UnknownServiceException
by default.
This method must be overridden by its subclasses.
IOException | if no OutputStream could be created. |
---|
Returns a Permission
object representing all needed permissions to
open this connection. The returned permission object depends on the state
of the connection and will be null
if no permissions are
necessary. By default, this method returns AllPermission
.
Subclasses should overwrite this method to return an appropriate
permission object.
IOException | if an I/O error occurs while creating the permission object. |
---|
Returns the configured timeout for reading from the input stream of an established connection to the resource.
Returns an unchangeable map of general request properties used by this connection. The request property names are the key values of the map. The map values are lists of property values of the corresponding key name.
Returns the value of the request header property specified by {code field}
or null
if there is no field with this name. The base
implementation of this method returns always null
.
field | the name of the request header property. |
---|
IllegalStateException | if the connection has been already established. |
---|
Returns the URL represented by this URLConnection
.
Returns the value of the flag which specifies whether this URLConnection
allows to use caches.
true
if using caches is allowed, false
otherwise.
Determines the MIME-type of the given resource url
by resolving
the filename extension with the internal FileNameMap. Any fragment
identifier is removed before processing.
url | the URL with the filename to get the MIME type. |
---|
null
if the type could not be
determined.
Determines the MIME-type of the resource represented by the input stream
is
by reading its first few characters.
is | the resource representing input stream to determine the content type. |
---|
null
if the type could not be
determined.IOException | if an I/O error occurs while reading from the input stream. |
---|
Sets the flag indicating whether this connection allows user interaction or not. This method can only be called prior to the connection establishment.
newValue | the value of the flag to be set. |
---|
IllegalStateException | if this method attempts to change the flag after the connection has been established. |
---|
Sets the timeout value in milliseconds for establishing the connection to
the resource pointed by this URLConnection
instance. A SocketTimeoutException
is thrown if the connection could not be
established in this time. Default is 0
which stands for an
infinite timeout.
timeout | the connecting timeout in milliseconds. |
---|
IllegalArgumentException | if the parameter timeout is less than zero.
|
---|
Sets the internally used content handler factory. The content factory can only be set if it is allowed by the security manager and only once during the lifetime of the application.
contentFactory | the content factory to be set. |
---|
Error | if the security manager does not allow to set the content factory or it has been already set earlier ago. |
---|
Sets the default value for the flag indicating whether this connection
allows user interaction or not. Existing URLConnection
s are
unaffected.
allows | the default value of the flag to be used for new connections. |
---|
This method is deprecated.
Use setRequestProperty(String, String)
of an existing URLConnection
instance.
Sets the default value of the specified request header field. This value will be used for the specific field of every newly created connection. The base implementation of this method does nothing.
field | the request header field to be set. |
---|---|
value | the default value to be used. |
Sets the default value for the flag indicating whether this connection
allows to use caches. Existing URLConnection
s are unaffected.
newValue | the default value of the flag to be used for new connections. |
---|
Sets the flag indicating whether this URLConnection
allows input.
It cannot be set after the connection is established.
newValue | the new value for the flag to be set. |
---|
IllegalAccessError | if this method attempts to change the value after the connection has been already established. |
---|
Sets the flag indicating whether this URLConnection
allows
output. It cannot be set after the connection is established.
newValue | the new value for the flag to be set. |
---|
IllegalAccessError | if this method attempts to change the value after the connection has been already established. |
---|
Sets the internal map which is used by all URLConnection
instances to determine the MIME-type according to a filename extension.
map | the MIME table to be set. |
---|
Sets the point of time since when the data must be modified to be
transmitted. Some protocols transmit data only if it has been modified
more recently than a particular time. The data will be transmitted
regardless of its timestamp if this option is set to 0
.
newValue | the time in milliseconds since January 1, 1970 GMT. |
---|
IllegalStateException | if this URLConnection has already been connected. |
---|
Sets the timeout value in milliseconds for reading from the input stream
of an established connection to the resource. A SocketTimeoutException
is thrown if the connection could not be
established in this time. Default is 0
which stands for an
infinite timeout.
timeout | the reading timeout in milliseconds. |
---|
IllegalArgumentException | if the parameter timeout is less than zero.
|
---|
Sets the value of the specified request header field. The value will only
be used by the current URLConnection
instance. This method can
only be called before the connection is established.
field | the request header field to be set. |
---|---|
newValue | the new value of the specified property. |
IllegalStateException | if the connection has been already established. |
---|---|
NullPointerException | if the parameter field is null .
|
Sets the flag indicating whether this connection allows to use caches or not. This method can only be called prior to the connection establishment.
newValue | the value of the flag to be set. |
---|
IllegalStateException | if this method attempts to change the flag after the connection has been established. |
---|
Returns the string representation containing the name of this class and the URL.
URLConnection
instance.