java.net
Class URLConnection

java.lang.Object
  java.net.URLConnection

Direct Known Subclasses:

HttpURLConnection, JarURLConnection

public abstract class URLConnection
extends Object

Concrete implementations of the abstract URLConnection class provide a communication link to a URL for exchanging data with a specific protocol type. A URLConnection can only be set up after the instantiation but before connecting to the remote resource.

Since:

Android 1.0

Nested Class Summary

(package private) static class

URLConnection.DefaultContentHandler

Field Summary

protected boolean	allowUserInteraction Specifies whether this URLConnection allows user interaction as it is needed for authentication purposes.
protected boolean	connected Specifies whether this URLConnection is already connected to the remote resource.
(package private) static Hashtable<String,Object>	contentHandlers Cache for storing content handler
(package private) ContentHandler	defaultHandler
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.

Constructor Summary

protected

URLConnection(URL url) Creates a new URLConnection instance pointing to the resource specified by the given URL.

Method Summary

void	addRequestProperty(String field, String newValue) Adds the given property to the request header.
abstract void	connect() Establishes the connection to the earlier configured resource.
boolean	getAllowUserInteraction() Gets the option value which indicates whether user interaction is allowed on this URLConnection.
int	getConnectTimeout() Gets the configured connecting timeout.
Object	getContent() Gets an object representing the content of the resource this URLConnection is connected to.
Object	getContent(Class[] types) Gets an object representing the content of the resource this URLConnection is connected to.
String	getContentEncoding() Gets the content encoding type specified by the response header field content-encoding or null if this field is not set.
int	getContentLength() Gets the content length in bytes specified by the response header field content-length or -1 if this field is not set.
String	getContentType() Gets the MIME-type of the content specified by the response header field content-type or null if type is unknown.
long	getDate() Gets 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() Gets the default setting whether this connection allows user interaction.
static String	getDefaultRequestProperty(String field) Deprecated. Use getRequestProperty(java.lang.String)
boolean	getDefaultUseCaches() Gets the default setting whether this connection allows using caches.
boolean	getDoInput() Gets the value of the option doInput which specifies whether this connection allows to receive data.
boolean	getDoOutput() Gets the value of the option doOutput which specifies whether this connection allows to send data.
long	getExpiration() Gets 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() Gets the table which is used by all URLConnection instances to determine the MIME-type according to a file extension.
String	getHeaderField(int pos) Gets the header value at the field position pos or null if the header has fewer than pos fields.
String	getHeaderField(String key) Gets 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) Gets the specified header value as a date in milliseconds since January 1, 1970 GMT.
int	getHeaderFieldInt(String field, int defaultValue) Gets the specified header value as a number.
String	getHeaderFieldKey(int posn) Gets 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() Gets an unchangeable map of the response-header fields and values.
long	getIfModifiedSince() Gets the point of time since when the data must be modified to be transmitted.
InputStream	getInputStream() Gets an InputStream for reading data from the resource pointed by this URLConnection.
long	getLastModified() Gets the value of the response header field last-modified or 0 if this value is not set.
OutputStream	getOutputStream() Gets an OutputStream for writing data to this URLConnection.
Permission	getPermission() Gets a Permission object representing all needed permissions to open this connection.
int	getReadTimeout() Gets the configured timeout for reading from the input stream of an established connection to the resource.
Map<String,List<String>>	getRequestProperties() Gets an unchangeable map of general request properties used by this connection.
String	getRequestProperty(String field) Gets the value of the request header property specified by {code field} or null if there is no field with this name.
URL	getURL() Gets the URL represented by this URLConnection.
boolean	getUseCaches() Gets 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 the flag indicating whether this connection allows user interaction or not.
void	setConnectTimeout(int timeout) Sets the timeout value in milliseconds for establishing the connection to the resource pointed by this URLConnection instance.
static void	setContentHandlerFactory(ContentHandlerFactory contentFactory) Sets the internally used content handler factory.
static void	setDefaultAllowUserInteraction(boolean allows) Sets the default value for the flag indicating whether this connection allows user interaction or not.
static void	setDefaultRequestProperty(String field, String value) Deprecated. Use setRequestProperty(java.lang.String, java.lang.String) of an existing URLConnection instance.
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 timeout) Sets the timeout value in milliseconds for reading from the input stream of an established connection to the resource.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

url

protected URL url

The URL which represents the remote target of this URLConnection.

Since:

Android 1.0

defaultHandler

ContentHandler defaultHandler

ifModifiedSince

protected long ifModifiedSince

The data must be modified more recently than this time in milliseconds since January 1, 1970, GMT to be transmitted.

Since:

Android 1.0

useCaches

protected boolean useCaches

Specifies whether the using of caches is enabled or the data has to be recent for every request.

Since:

Android 1.0

connected

protected boolean connected

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.

Since:

Android 1.0

doOutput

protected boolean doOutput

Specifies whether this URLConnection allows sending data.

Since:

Android 1.0

doInput

protected boolean doInput

Specifies whether this URLConnection allows receiving data.

Since:

Android 1.0

allowUserInteraction

protected boolean allowUserInteraction

Specifies whether this URLConnection allows user interaction as it is needed for authentication purposes.

Since:

Android 1.0

contentHandlers

static Hashtable<String,Object> contentHandlers

Cache for storing content handler

Constructor Detail

URLConnection

protected URLConnection(URL url)

Creates a new URLConnection instance pointing to the resource specified by the given URL.

Parameters:

url - the URL which represents the resource this URLConnection will point to.

Since:

Android 1.0

Method Detail

connect

public abstract void connect()
                      throws IOException

Establishes the connection to the earlier configured resource. The connection can only be set up before this method has been called.

Throws:

IOException - if an error occurs while connecting to the resource.

Since:

Android 1.0

getAllowUserInteraction

public boolean getAllowUserInteraction()

Gets the option value which indicates whether user interaction is allowed on this URLConnection.

Returns:

the value of the option allowUserInteraction.

Since:

Android 1.0

See Also:

allowUserInteraction

getContent

public Object getContent()
                  throws IOException

Gets 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.

Returns:

the content representing object.

Throws:

IOException - if an error occurs obtaining the content.

Since:

Android 1.0

getContent

public Object getContent(Class[] types)
                  throws IOException

Gets 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.

Parameters:

types - the list of acceptable content types.

Returns:

the content representing object or null if the content type does not match with one of the specified types.

Throws:

IOException - if an error occurs obtaining the content.

Since:

Android 1.0

getContentEncoding

public String getContentEncoding()

Gets the content encoding type specified by the response header field content-encoding or null if this field is not set.

Returns:

the value of the response header field content-encoding.

Since:

Android 1.0

getContentLength

public int getContentLength()

Gets the content length in bytes specified by the response header field content-length or -1 if this field is not set.

Returns:

the value of the response header field content-length.

Since:

Android 1.0

getContentType

public String getContentType()

Gets the MIME-type of the content specified by the response header field content-type or null if type is unknown.

Returns:

the value of the response header field content-type.

Since:

Android 1.0

getDate

public long getDate()

Gets 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 sending timestamp of the current response.

Since:

Android 1.0

getDefaultAllowUserInteraction

public static boolean getDefaultAllowUserInteraction()

Gets the default setting whether this connection allows user interaction.

Returns:

the value of the default setting defaultAllowUserInteraction.

Since:

Android 1.0

See Also:

allowUserInteraction

getDefaultRequestProperty

@Deprecated
public static String getDefaultRequestProperty(String field)

Deprecated. Use getRequestProperty(java.lang.String)

Gets the default value for the specified request field or null if the field could not be found. The current implementation of this method returns always null.

Parameters:

field - the request field whose default value shall be returned.

Returns:

the default value for the given field.

Since:

Android 1.0

getDefaultUseCaches

public boolean getDefaultUseCaches()

Gets the default setting whether this connection allows using caches.

Returns:

the value of the default setting defaultUseCaches.

Since:

Android 1.0

See Also:

useCaches

getDoInput

public boolean getDoInput()

Gets the value of the option doInput which specifies whether this connection allows to receive data.

Returns:

true if this connection allows input, false otherwise.

Since:

Android 1.0

See Also:

doInput

getDoOutput

public boolean getDoOutput()

Gets the value of the option doOutput which specifies whether this connection allows to send data.

Returns:

true if this connection allows output, false otherwise.

Since:

Android 1.0

See Also:

doOutput

getExpiration

public long getExpiration()

Gets the timestamp when this response will be expired in milliseconds since January 1, 1970 GMT or 0 if this timestamp is unknown.

Returns:

the value of the response header field expires.

Since:

Android 1.0

getFileNameMap

public static FileNameMap getFileNameMap()

Gets the table which is used by all URLConnection instances to determine the MIME-type according to a file extension.

Returns:

the file name map to determine the MIME-type.

Since:

Android 1.0

getHeaderField

public String getHeaderField(int pos)

Gets the header value at the field position pos or null if the header has fewer than pos fields. The current implementation of this method returns always null.

Parameters:

pos - the field position of the response header.

Returns:

the value of the field at position pos.

Since:

Android 1.0

getHeaderFields

public Map<String,List<String>> getHeaderFields()

Gets 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.

Returns:

the response-header representing generic map.

Since:

Android 1.0

getRequestProperties

public Map<String,List<String>> getRequestProperties()

Gets 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 request-property representing generic map.

Since:

Android 1.0

addRequestProperty

public void addRequestProperty(String field,
                               String newValue)

Adds the given property to the request header. Existing properties with the same name will not be overwritten by this method.

Parameters:

field - the request property field name to add.

newValue - the value of the property which is to add.

Throws:

IllegalStateException - if the connection has been already established.

NullPointerException - if the property name is null.

Since:

Android 1.0

getHeaderField

public String getHeaderField(String key)

Gets the value of the header field specified by key or null if there is no field with this name. The current implementation of this method returns always null.

Parameters:

key - the name of the header field.

Returns:

the value of the header field.

Since:

Android 1.0

getHeaderFieldDate

public long getHeaderFieldDate(String field,
                               long defaultValue)

Gets 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.

Parameters:

field - the header field name whose value is needed.

defaultValue - the default value if no field has been found.

Returns:

the value of the specified header field as a date in milliseconds.

Since:

Android 1.0

getHeaderFieldInt

public int getHeaderFieldInt(String field,
                             int defaultValue)

Gets 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.

Parameters:

field - the header field name whose value is needed.

defaultValue - the default value if no field has been found.

Returns:

the value of the specified header field as a number.

Since:

Android 1.0

getHeaderFieldKey

public String getHeaderFieldKey(int posn)

Gets the name of the header field at the given position posn or null if there are fewer than posn fields. The current implementation of this method returns always null.

Parameters:

posn - the position of the header field which has to be returned.

Returns:

the header field name at the given position.

Since:

Android 1.0

getIfModifiedSince

public long getIfModifiedSince()

Gets 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:

the time in milliseconds since January 1, 1970 GMT.

Since:

Android 1.0

See Also:

ifModifiedSince

getInputStream

public InputStream getInputStream()
                           throws IOException

Gets 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.

Returns:

the InputStream to read data from.

Throws:

IOException - if no InputStream could be created.

Since:

Android 1.0

getLastModified

public long getLastModified()

Gets the value of the response header field last-modified or 0 if this value is not set.

Returns:

the value of the last-modified header field.

Since:

Android 1.0

getOutputStream

public OutputStream getOutputStream()
                             throws IOException

Gets an OutputStream for writing data to this URLConnection. It throws an UnknownServiceException by default. This method must be overridden by its subclasses.

Returns:

the OutputStream to write data.

Throws:

IOException - if no OutputStream could be created.

Since:

Android 1.0

getPermission

public Permission getPermission()
                         throws IOException

Gets 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.

Returns:

the permission object representing the needed permissions to open this connection.

Throws:

IOException - if an I/O error occurs while creating the permission object.

Since:

Android 1.0

getRequestProperty

public String getRequestProperty(String field)

Gets the value of the request header property specified by {code field} or null if there is no field with this name. The current implementation of this method returns always null.

Parameters:

field - the name of the request header property.

Returns:

the value of the property.

Throws:

IllegalStateException - if the connection has been already established.

Since:

Android 1.0

getURL

public URL getURL()

Gets the URL represented by this URLConnection.

Returns:

the URL of this connection.

Since:

Android 1.0

getUseCaches

public boolean getUseCaches()

Gets the value of the flag which specifies whether this URLConnection allows to use caches.

Returns:

true if using caches is allowed, false otherwise.

Since:

Android 1.0

guessContentTypeFromName

public static String guessContentTypeFromName(String url)

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.

Parameters:

url - the URL with the filename to get the MIME type.

Returns:

the guessed content type or null if the type could not be determined.

Since:

Android 1.0

guessContentTypeFromStream

public static String guessContentTypeFromStream(InputStream is)
                                         throws IOException

Determines the MIME-type of the resource represented by the input stream is by reading its first few characters.

Parameters:

is - the resource representing input stream to determine the content type.

Returns:

the guessed content type or null if the type could not be determined.

Throws:

IOException - if an I/O error occurs while reading from the input stream.

Since:

Android 1.0

setAllowUserInteraction

public void setAllowUserInteraction(boolean newValue)

Sets the flag indicating whether this connection allows user interaction or not. This method can only be called prior to the connection establishment.

Parameters:

newValue - the value of the flag to be set.

Throws:

IllegalStateException - if this method attempts to change the flag after the connection has been established.

Since:

Android 1.0

See Also:

allowUserInteraction

setContentHandlerFactory

public static void setContentHandlerFactory(ContentHandlerFactory contentFactory)

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.

Parameters:

contentFactory - the content factory to be set.

Throws:

Error - if the security manager does not allow to set the content factory or it has been already set earlier ago.

Since:

Android 1.0

setDefaultAllowUserInteraction

public static void setDefaultAllowUserInteraction(boolean allows)

Sets the default value for the flag indicating whether this connection allows user interaction or not. Existing URLConnections are unaffected.

Parameters:

allows - the default value of the flag to be used for new connections.

Since:

Android 1.0

See Also:

defaultAllowUserInteraction, allowUserInteraction

setDefaultRequestProperty

@Deprecated
public static void setDefaultRequestProperty(String field,
                                                        String value)

Deprecated. Use setRequestProperty(java.lang.String, java.lang.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 current implementation of this method does nothing.

Parameters:

field - the request header field to be set.

value - the default value to be used.

Since:

Android 1.0

setDefaultUseCaches

public void setDefaultUseCaches(boolean newValue)

Sets the default value for the flag indicating whether this connection allows to use caches. Existing URLConnections are unaffected.

Parameters:

newValue - the default value of the flag to be used for new connections.

Since:

Android 1.0

See Also:

defaultUseCaches, useCaches

setDoInput

public void setDoInput(boolean newValue)

Sets the flag indicating whether this URLConnection allows input. It cannot be set after the connection is established.

Parameters:

newValue - the new value for the flag to be set.

Throws:

IllegalAccessError - if this method attempts to change the value after the connection has been already established.

Since:

Android 1.0

See Also:

doInput

setDoOutput

public void setDoOutput(boolean newValue)

Sets the flag indicating whether this URLConnection allows output. It cannot be set after the connection is established.

Parameters:

newValue - the new value for the flag to be set.

Throws:

IllegalAccessError - if this method attempts to change the value after the connection has been already established.

Since:

Android 1.0

See Also:

doOutput

setFileNameMap

public 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.

Parameters:

map - the MIME table to be set.

Since:

Android 1.0

setIfModifiedSince

public void setIfModifiedSince(long newValue)

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.

Parameters:

newValue - the time in milliseconds since January 1, 1970 GMT.

Throws:

IllegalStateException - if this URLConnection has already been connected.

Since:

Android 1.0

See Also:

ifModifiedSince

setRequestProperty

public void setRequestProperty(String field,
                               String newValue)

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.

Parameters:

field - the request header field to be set.

newValue - the new value of the specified property.

Throws:

IllegalStateException - if the connection has been already established.

NullPointerException - if the parameter field is null.

Since:

Android 1.0

setUseCaches

public void setUseCaches(boolean newValue)

Sets the flag indicating whether this connection allows to use caches or not. This method can only be called prior to the connection establishment.

Parameters:

newValue - the value of the flag to be set.

Throws:

IllegalStateException - if this method attempts to change the flag after the connection has been established.

Since:

Android 1.0

See Also:

useCaches

setConnectTimeout

public void setConnectTimeout(int timeout)

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.

Parameters:

timeout - the connecting timeout in milliseconds.

Throws:

IllegalArgumentException - if the parameter timeout is less than zero.

Since:

Android 1.0

getConnectTimeout

public int getConnectTimeout()

Gets the configured connecting timeout.

Returns:

the connecting timeout value in milliseconds.

Since:

Android 1.0

setReadTimeout

public void setReadTimeout(int timeout)

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.

Parameters:

timeout - the reading timeout in milliseconds.

Throws:

IllegalArgumentException - if the parameter timeout is less than zero.

Since:

Android 1.0

getReadTimeout

public int getReadTimeout()

Gets the configured timeout for reading from the input stream of an established connection to the resource.

Returns:

the reading timeout value in milliseconds.

Since:

Android 1.0

toString

public String toString()

Returns the string representation containing the name of this class and the URL.

Overrides:

toString in class Object

Returns:

the string representation of this URLConnection instance.

Since:

Android 1.0