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 | Unused by Android. | ||||||||||
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
allowUserInteraction . | |||||||||||
Returns the connect timeout in milliseconds.
| |||||||||||
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 or cannot be represented as an
int . | |||||||||||
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 value of
allowUserInteraction . | |||||||||||
This method was deprecated
in API level 1.
Use
getRequestProperty(String) instead.
| |||||||||||
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 unmodifiable 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 read timeout in milliseconds, or
0 if reads never
timeout. | |||||||||||
Returns an unmodifiable 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
allowUserInteraction . | |||||||||||
Sets the maximum time in milliseconds to wait while connecting.
| |||||||||||
Sets the internally used content handler factory.
| |||||||||||
Sets the default value for
allowUserInteraction . | |||||||||||
This method was deprecated
in API level 1.
Use
setRequestProperty(String, String) instead.
| |||||||||||
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 maximum time to wait for an input stream read to complete before
giving up.
| |||||||||||
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
|
Unused by Android. This field can be accessed via getAllowUserInteraction()
and setAllowUserInteraction(boolean)
.
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 allowUserInteraction
. Unused by Android.
Returns the connect timeout in milliseconds. (See {#setConnectTimeout}.)
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 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 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 or cannot be represented as an
int
.
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 value of allowUserInteraction
. Unused by Android.
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 int
.
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 unmodifiable 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 read timeout in milliseconds, or 0
if reads never
timeout.
Returns an unmodifiable 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 allowUserInteraction
. Unused by Android.
Sets the maximum time in milliseconds to wait while connecting.
Connecting to a server will fail with a SocketTimeoutException
if
the timeout elapses before a connection is established. The default value
of 0
causes us to do a blocking connect. This does not mean we
will never time out, but it probably means you'll get a TCP timeout
after several minutes.
Warning: if the hostname resolves to multiple IP addresses, this client will try each in RFC 3484 order. If connecting to each of these addresses fails, multiple timeouts will elapse before the connect attempt throws an exception. Host names that support both IPv6 and IPv4 always have at least 2 IP addresses.
IllegalArgumentException | if timeoutMillis < 0 .
|
---|
Sets the internally used content handler factory. The content factory can only be set once during the lifetime of the application.
contentFactory | the content factory to be set. |
---|
Error | if the factory has been already set. |
---|
Sets the default value for allowUserInteraction
. Unused by Android.
This method was deprecated
in API level 1.
Use setRequestProperty(String, String)
instead.
Does nothing.
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 maximum time to wait for an input stream read to complete before
giving up. Reading will fail with a SocketTimeoutException
if the
timeout elapses before data becomes available. The default value of
0
disables read timeouts; read attempts will block indefinitely.
timeoutMillis | the read timeout in milliseconds. Non-negative. |
---|
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.