public abstract class URLConnection extends Object
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.
URL.setURLStreamHandlerFactory(java.net.URLStreamHandlerFactory)
to register handlers for other
protocol types.Modifier and Type | Field and Description |
---|---|
protected boolean |
allowUserInteraction
Unused by Android.
|
protected boolean |
connected
Specifies whether this
URLConnection is already connected to the
remote resource. |
protected boolean |
doInput
Specifies whether this
URLConnection allows receiving data. |
protected boolean |
doOutput
Specifies whether this
URLConnection allows sending data. |
protected long |
ifModifiedSince
The data must be modified more recently than this time in milliseconds
since January 1, 1970, GMT to be transmitted.
|
protected URL |
url
The URL which represents the remote target of this
URLConnection . |
protected boolean |
useCaches
Specifies whether the using of caches is enabled or the data has to be
recent for every request.
|
Modifier | Constructor and Description |
---|---|
protected |
URLConnection(URL url)
Creates a new
URLConnection instance pointing to the resource
specified by the given URL. |
Modifier and Type | Method and Description |
---|---|
void |
addRequestProperty(String field,
String newValue)
Adds the given property to the request header.
|
abstract void |
connect()
Opens a connection to the resource.
|
boolean |
getAllowUserInteraction()
Returns
allowUserInteraction . |
int |
getConnectTimeout()
Returns the connect timeout in milliseconds.
|
Object |
getContent()
Returns an object representing the content of the resource this
URLConnection is connected to. |
Object |
getContent(Class[] types)
Returns an object representing the content of the resource this
URLConnection is connected to. |
String |
getContentEncoding()
Returns the content encoding type specified by the response header field
content-encoding or null if this field is not set. |
int |
getContentLength()
Returns the content length in bytes specified by the response header field
content-length or -1 if this field is not set. |
String |
getContentType()
Returns the MIME-type of the content specified by the response header field
content-type or null if type is unknown. |
long |
getDate()
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. |
static boolean |
getDefaultAllowUserInteraction()
Returns the default value of
allowUserInteraction . |
static String |
getDefaultRequestProperty(String field)
Deprecated.
|
boolean |
getDefaultUseCaches()
Returns the default setting whether this connection allows using caches.
|
boolean |
getDoInput()
Returns the value of the option
doInput which specifies whether this
connection allows to receive data. |
boolean |
getDoOutput()
Returns the value of the option
doOutput which specifies whether
this connection allows to send data. |
long |
getExpiration()
Returns the timestamp when this response will be expired in milliseconds
since January 1, 1970 GMT or
0 if this timestamp is unknown. |
static FileNameMap |
getFileNameMap()
Returns the table which is used by all
URLConnection instances to
determine the MIME-type according to a file extension. |
String |
getHeaderField(int pos)
Returns the header value at the field position
pos or null
if the header has fewer than pos fields. |
String |
getHeaderField(String key)
Returns the value of the header field specified by
key or null if there is no field with this name. |
long |
getHeaderFieldDate(String field,
long defaultValue)
Returns the specified header value as a date in milliseconds since January
1, 1970 GMT.
|
int |
getHeaderFieldInt(String field,
int defaultValue)
Returns the specified header value as a number.
|
String |
getHeaderFieldKey(int posn)
Returns the name of the header field at the given position
posn or
null if there are fewer than posn fields. |
Map<String,List<String>> |
getHeaderFields()
Returns an unmodifiable map of the response-header fields and values.
|
long |
getIfModifiedSince()
Returns the point of time since when the data must be modified to be
transmitted.
|
InputStream |
getInputStream()
Returns an
InputStream for reading data from the resource pointed by
this URLConnection . |
long |
getLastModified()
Returns the value of the response header field
last-modified or
0 if this value is not set. |
OutputStream |
getOutputStream()
Returns an
OutputStream for writing data to this URLConnection . |
Permission |
getPermission()
Returns a
Permission object representing all needed permissions to
open this connection. |
int |
getReadTimeout()
Returns the read timeout in milliseconds, or
0 if reads never
timeout. |
Map<String,List<String>> |
getRequestProperties()
Returns an unmodifiable map of general request properties used by this
connection.
|
String |
getRequestProperty(String field)
Returns the value of the request header property specified by {code field}
or
null if there is no field with this name. |
URL |
getURL()
Returns the URL represented by this
URLConnection . |
boolean |
getUseCaches()
Returns the value of the flag which specifies whether this
URLConnection allows to use caches. |
static String |
guessContentTypeFromName(String url)
Determines the MIME-type of the given resource
url by resolving
the filename extension with the internal FileNameMap. |
static String |
guessContentTypeFromStream(InputStream is)
Determines the MIME-type of the resource represented by the input stream
is by reading its first few characters. |
void |
setAllowUserInteraction(boolean newValue)
Sets
allowUserInteraction . |
void |
setConnectTimeout(int timeoutMillis)
Sets the maximum time in milliseconds to wait while connecting.
|
static void |
setContentHandlerFactory(ContentHandlerFactory contentFactory)
Sets the internally used content handler factory.
|
static void |
setDefaultAllowUserInteraction(boolean allows)
Sets the default value for
allowUserInteraction . |
static void |
setDefaultRequestProperty(String field,
String value)
Deprecated.
|
void |
setDefaultUseCaches(boolean newValue)
Sets the default value for the flag indicating whether this connection
allows to use caches.
|
void |
setDoInput(boolean newValue)
Sets the flag indicating whether this
URLConnection allows input. |
void |
setDoOutput(boolean newValue)
Sets the flag indicating whether this
URLConnection allows
output. |
static void |
setFileNameMap(FileNameMap map)
Sets the internal map which is used by all
URLConnection
instances to determine the MIME-type according to a filename extension. |
void |
setIfModifiedSince(long newValue)
Sets the point of time since when the data must be modified to be
transmitted.
|
void |
setReadTimeout(int timeoutMillis)
Sets the maximum time to wait for an input stream read to complete before
giving up.
|
void |
setRequestProperty(String field,
String newValue)
Sets the value of the specified request header field.
|
void |
setUseCaches(boolean newValue)
Sets the flag indicating whether this connection allows to use caches or
not.
|
String |
toString()
Returns the string representation containing the name of this class and
the URL.
|
protected URL url
URLConnection
.protected long ifModifiedSince
protected boolean useCaches
protected boolean connected
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.protected boolean doOutput
URLConnection
allows sending data.protected boolean doInput
URLConnection
allows receiving data.protected boolean allowUserInteraction
getAllowUserInteraction()
and setAllowUserInteraction(boolean)
.protected URLConnection(URL url)
URLConnection
instance pointing to the resource
specified by the given URL.url
- the URL which represents the resource this URLConnection
will point to.public abstract void connect() throws IOException
IOException
- if an error occurs while connecting to the resource.public boolean getAllowUserInteraction()
allowUserInteraction
. Unused by Android.public Object getContent() throws IOException
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.public Object getContent(Class[] types) throws IOException
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.public String getContentEncoding()
content-encoding
or null
if this field is not set.content-encoding
.public int getContentLength()
content-length
or -1
if this field is not set.content-length
.public String getContentType()
content-type
or null
if type is unknown.content-type
.public long getDate()
0
if this timestamp is
unknown.public static boolean getDefaultAllowUserInteraction()
allowUserInteraction
. Unused by Android.@Deprecated public static String getDefaultRequestProperty(String field)
getRequestProperty(java.lang.String)
public boolean getDefaultUseCaches()
defaultUseCaches
.useCaches
public boolean getDoInput()
doInput
which specifies whether this
connection allows to receive data.true
if this connection allows input, false
otherwise.doInput
public boolean getDoOutput()
doOutput
which specifies whether
this connection allows to send data.true
if this connection allows output, false
otherwise.doOutput
public long getExpiration()
0
if this timestamp is unknown.expires
.public static FileNameMap getFileNameMap()
URLConnection
instances to
determine the MIME-type according to a file extension.public String getHeaderField(int pos)
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
.public Map<String,List<String>> getHeaderFields()
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.
public Map<String,List<String>> getRequestProperties()
public void addRequestProperty(String field, String newValue)
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
.public String getHeaderField(String key)
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.public long getHeaderFieldDate(String field, long defaultValue)
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.public int getHeaderFieldInt(String field, int defaultValue)
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.public String getHeaderFieldKey(int posn)
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.public long getIfModifiedSince()
ifModifiedSince
public InputStream getInputStream() throws IOException
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.public long getLastModified()
last-modified
or
0
if this value is not set.last-modified
header field.public OutputStream getOutputStream() throws IOException
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.public Permission getPermission() throws IOException
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.public String getRequestProperty(String field)
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.public URL getURL()
URLConnection
.public boolean getUseCaches()
URLConnection
allows to use caches.true
if using caches is allowed, false
otherwise.public static String guessContentTypeFromName(String url)
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.public static String guessContentTypeFromStream(InputStream is) throws IOException
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.public void setAllowUserInteraction(boolean newValue)
allowUserInteraction
. Unused by Android.public static void setContentHandlerFactory(ContentHandlerFactory contentFactory)
contentFactory
- the content factory to be set.Error
- if the factory has been already set.public static void setDefaultAllowUserInteraction(boolean allows)
allowUserInteraction
. Unused by Android.@Deprecated public static void setDefaultRequestProperty(String field, String value)
setRequestProperty(String, String)
.public void setDefaultUseCaches(boolean newValue)
URLConnection
s are unaffected.newValue
- the default value of the flag to be used for new connections.useCaches
public void setDoInput(boolean newValue)
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.doInput
public void setDoOutput(boolean newValue)
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.doOutput
public static void setFileNameMap(FileNameMap map)
URLConnection
instances to determine the MIME-type according to a filename extension.map
- the MIME table to be set.public void setIfModifiedSince(long newValue)
0
.newValue
- the time in milliseconds since January 1, 1970 GMT.IllegalStateException
- if this URLConnection
has already been connected.ifModifiedSince
public void setRequestProperty(String field, String newValue)
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
.public void setUseCaches(boolean newValue)
newValue
- the value of the flag to be set.IllegalStateException
- if this method attempts to change the flag after the
connection has been established.useCaches
public void setConnectTimeout(int timeoutMillis)
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
.public int getConnectTimeout()
public void setReadTimeout(int timeoutMillis)
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.public int getReadTimeout()
0
if reads never
timeout.