FileDocCategorySizeDatePackage
URLConnection.javaAPI DocAndroid 1.5 API36955Wed May 06 22:41:04 BST 2009java.net

URLConnection

public abstract class URLConnection extends Object
Concrete implementations of the abstract {@code URLConnection} class provide a communication link to a URL for exchanging data with a specific protocol type. A {@code URLConnection} can only be set up after the instantiation but before connecting to the remote resource.
since
Android 1.0

Fields Summary
protected URL
url
The URL which represents the remote target of this {@code URLConnection}.
private String
contentType
private static boolean
defaultAllowUserInteraction
private static boolean
defaultUseCaches
ContentHandler
defaultHandler
private long
lastModified
protected long
ifModifiedSince
The data must be modified more recently than this time in milliseconds since January 1, 1970, GMT to be transmitted.
protected boolean
useCaches
Specifies whether the using of caches is enabled or the data has to be recent for every request.
protected boolean
connected
Specifies whether this {@code URLConnection} is already connected to the remote resource. If this field is set to {@code true} the flags for setting up the connection are not changeable anymore.
protected boolean
doOutput
Specifies whether this {@code URLConnection} allows sending data.
protected boolean
doInput
Specifies whether this {@code URLConnection} allows receiving data.
protected boolean
allowUserInteraction
Specifies whether this {@code URLConnection} allows user interaction as it is needed for authentication purposes.
private static ContentHandlerFactory
contentHandlerFactory
private int
readTimeout
private int
connectTimeout
static Hashtable
contentHandlers
Cache for storing content handler
private static FileNameMap
fileNameMap
A hashtable that maps the filename extension (key) to a MIME-type (element)
Constructors Summary
protected URLConnection(URL url)
Creates a new {@code URLConnection} instance pointing to the resource specified by the given URL.

param
url the URL which represents the resource this {@code URLConnection} will point to.
since
Android 1.0


                                                                
       
        this.url = url;
Methods Summary
public voidaddRequestProperty(java.lang.String field, java.lang.String newValue)
Adds the given property to the request header. Existing properties with the same name will not be overwritten by this method.

param
field the request property field name to add.
param
newValue the value of the property which is to add.
throws
IllegalStateException if the connection has been already established.
throws
NullPointerException if the property name is {@code null}.
since
Android 1.0

        if (connected) {
            throw new IllegalStateException(Msg.getString("K0037")); //$NON-NLS-1$
        }
        if (field == null) {
            throw new NullPointerException(Msg.getString("KA007")); //$NON-NLS-1$
        }
public abstract voidconnect()
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

public booleangetAllowUserInteraction()
Gets the option value which indicates whether user interaction is allowed
on this {@code URLConnection}.
return
the value of the option {@code allowUserInteraction}.
see
#allowUserInteraction
since
Android 1.0
        return allowUserInteraction;
    
public intgetConnectTimeout()
Gets the configured connecting timeout.
return
the connecting timeout value in milliseconds.
since
Android 1.0
        return connectTimeout;
    
public java.lang.ObjectgetContent()
Gets an object representing the content of the resource this {@code
URLConnection} is connected to. First, it attempts to get the content
type from the method {@code 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.
return
the content representing object.
throws
IOException
if an error occurs obtaining the content.
since
Android 1.0
        if (!connected) {
            connect();
        }

        if ((contentType = getContentType()) == null) {
            if ((contentType = guessContentTypeFromName(url.getFile())) == null) {
                contentType = guessContentTypeFromStream(getInputStream());
            }
        }
        if (contentType != null) {
            return getContentHandler(contentType).getContent(this);
        }
        return null;
    
public java.lang.ObjectgetContent(java.lang.Class[] types)
Gets an object representing the content of the resource this {@code
URLConnection} is connected to. First, it attempts to get the content
type from the method {@code 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 {@code types}.
param
types
the list of acceptable content types.
return
the content representing object or {@code 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
        if (!connected) {
            connect();
        }

        if ((contentType = getContentType()) == null) {
            if ((contentType = guessContentTypeFromName(url.getFile())) == null) {
                contentType = guessContentTypeFromStream(getInputStream());
            }
        }
        if (contentType != null) {
            return getContentHandler(contentType).getContent(this, types);
        }
        return null;
    
public java.lang.StringgetContentEncoding()
Gets the content encoding type specified by the response header field
{@code content-encoding} or {@code null} if this field is not set.
return
the value of the response header field {@code content-encoding}.
since
Android 1.0
        return getHeaderField("Content-Encoding"); //$NON-NLS-1$
    
private java.net.ContentHandlergetContentHandler(java.lang.String type)
Returns the specific ContentHandler that will handle the type {@code
contentType}.
param
type
The type that needs to be handled
return
An instance of the Content Handler
        // Replace all non-alphanumeric character by '_'
        final String typeString = parseTypeString(type.replace('/", '."));

        // if there's a cached content handler, use it
        Object cHandler = contentHandlers.get(type);
        if (cHandler != null) {
            return (ContentHandler) cHandler;
        }

        if (contentHandlerFactory != null) {
            cHandler = contentHandlerFactory.createContentHandler(type);
            if (!(cHandler instanceof ContentHandler)) {
                throw new UnknownServiceException();
            }
            contentHandlers.put(type, cHandler);
            return (ContentHandler) cHandler;
        }

        // search through the package list for the right class for the Content
        // Type
        String packageList = AccessController
                .doPrivileged(new PriviAction<String>(
                        "java.content.handler.pkgs")); //$NON-NLS-1$
        if (packageList != null) {
            final StringTokenizer st = new StringTokenizer(packageList, "|"); //$NON-NLS-1$
            while (st.countTokens() > 0) {
                try {
                    Class<?> cl = Class.forName(st.nextToken() + "." //$NON-NLS-1$
                            + typeString, true, ClassLoader
                            .getSystemClassLoader());
                    cHandler = cl.newInstance();
                } catch (ClassNotFoundException e) {
                } catch (IllegalAccessException e) {
                } catch (InstantiationException e) {
                }
            }
        }

        if (cHandler == null) {
            cHandler = AccessController
                    .doPrivileged(new PrivilegedAction<Object>() {
                        public Object run() {
                            try {
                                String className = "org.apache.harmony.luni.internal.net.www.content." //$NON-NLS-1$
                                        + typeString;
                                return Class.forName(className).newInstance();
                            } catch (ClassNotFoundException e) {
                            } catch (IllegalAccessException e) {
                            } catch (InstantiationException e) {
                            }
                            return null;
                        }
                    });
        }
        if (cHandler != null) {
            if (!(cHandler instanceof ContentHandler)) {
                throw new UnknownServiceException();
            }
            contentHandlers.put(type, cHandler); // if we got the handler,
            // cache it for next time
            return (ContentHandler) cHandler;
        }

        return defaultHandler;
    
public intgetContentLength()
Gets the content length in bytes specified by the response header field
{@code content-length} or {@code -1} if this field is not set.
return
the value of the response header field {@code content-length}.
since
Android 1.0
        return getHeaderFieldInt("Content-Length", -1); //$NON-NLS-1$
    
public java.lang.StringgetContentType()
Gets the MIME-type of the content specified by the response header field
{@code content-type} or {@code null} if type is unknown.
return
the value of the response header field {@code content-type}.
since
Android 1.0
        return getHeaderField("Content-Type"); //$NON-NLS-1$
    
public longgetDate()
Gets the timestamp when this response has been sent as a date in
milliseconds since January 1, 1970 GMT or {@code 0} if this timestamp is
unknown.
return
the sending timestamp of the current response.
since
Android 1.0
        return getHeaderFieldDate("Date", 0); //$NON-NLS-1$
    
public static booleangetDefaultAllowUserInteraction()
Gets the default setting whether this connection allows user interaction.
return
the value of the default setting {@code
defaultAllowUserInteraction}.
see
#allowUserInteraction
since
Android 1.0
        return defaultAllowUserInteraction;
    
public static java.lang.StringgetDefaultRequestProperty(java.lang.String field)
Gets the default value for the specified request {@code field} or {@code
null} if the field could not be found. The current implementation of this
method returns always {@code null}.
param
field
the request field whose default value shall be returned.
return
the default value for the given field.
deprecated
Use {@link #getRequestProperty}
since
Android 1.0
        return null;
    
public booleangetDefaultUseCaches()
Gets the default setting whether this connection allows using caches.
return
the value of the default setting {@code defaultUseCaches}.
see
#useCaches
since
Android 1.0
        return defaultUseCaches;
    
public booleangetDoInput()
Gets the value of the option {@code doInput} which specifies whether this
connection allows to receive data.
return
{@code true} if this connection allows input, {@code false}
otherwise.
see
#doInput
since
Android 1.0
        return doInput;
    
public booleangetDoOutput()
Gets the value of the option {@code doOutput} which specifies whether
this connection allows to send data.
return
{@code true} if this connection allows output, {@code false}
otherwise.
see
#doOutput
since
Android 1.0
        return doOutput;
    
public longgetExpiration()
Gets the timestamp when this response will be expired in milliseconds
since January 1, 1970 GMT or {@code 0} if this timestamp is unknown.
return
the value of the response header field {@code expires}.
since
Android 1.0
        return getHeaderFieldDate("Expires", 0); //$NON-NLS-1$
    
public static java.net.FileNameMapgetFileNameMap()
Gets the table which is used by all {@code URLConnection} instances to
determine the MIME-type according to a file extension.
return
the file name map to determine the MIME-type.
since
Android 1.0
        // Must use lazy initialization or there is a bootstrap problem
        // trying to load the MimeTable resource from a .jar before
        // JarURLConnection has finished initialization.
        if (fileNameMap == null) {
            fileNameMap = new MimeTable();
        }
        return fileNameMap;
    
public java.lang.StringgetHeaderField(int pos)
Gets the header value at the field position {@code pos} or {@code null}
if the header has fewer than {@code pos} fields. The current
implementation of this method returns always {@code null}.
param
pos
the field position of the response header.
return
the value of the field at position {@code pos}.
since
Android 1.0
        return null;
    
public java.lang.StringgetHeaderField(java.lang.String key)
Gets the value of the header field specified by {@code key} or {@code
null} if there is no field with this name. The current implementation of
this method returns always {@code null}.
param
key
the name of the header field.
return
the value of the header field.
since
Android 1.0
        return null;
    
public longgetHeaderFieldDate(java.lang.String field, long defaultValue)
Gets the specified header value as a date in milliseconds since January
1, 1970 GMT. Returns the {@code defaultValue} if no such header field
could be found.
param
field
the header field name whose value is needed.
param
defaultValue
the default value if no field has been found.
return
the value of the specified header field as a date in
milliseconds.
since
Android 1.0
        String date = getHeaderField(field);
        if (date == null) {
            return defaultValue;
        }
        return Util.parseDate(date);
    
public intgetHeaderFieldInt(java.lang.String field, int defaultValue)
Gets the specified header value as a number. Returns the {@code
defaultValue} if no such header field could be found or the value could
not be parsed as an {@code Integer}.
param
field
the header field name whose value is needed.
param
defaultValue
the default value if no field has been found.
return
the value of the specified header field as a number.
since
Android 1.0
        try {
            return Integer.parseInt(getHeaderField(field));
        } catch (NumberFormatException e) {
            return defaultValue;
        }
    
public java.lang.StringgetHeaderFieldKey(int posn)
Gets the name of the header field at the given position {@code posn} or
{@code null} if there are fewer than {@code posn} fields. The current
implementation of this method returns always {@code null}.
param
posn
the position of the header field which has to be returned.
return
the header field name at the given position.
since
Android 1.0
        return null;
    
public java.util.MapgetHeaderFields()
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.
return
the response-header representing generic map.
since
Android 1.0
        return Collections.emptyMap();
    
public longgetIfModifiedSince()
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.
return
the time in milliseconds since January 1, 1970 GMT.
see
#ifModifiedSince
since
Android 1.0
        return ifModifiedSince;
    
public java.io.InputStreamgetInputStream()
Gets an {@code InputStream} for reading data from the resource pointed by
this {@code URLConnection}. It throws an UnknownServiceException by
default. This method must be overridden by its subclasses.
return
the InputStream to read data from.
throws
IOException
if no InputStream could be created.
since
Android 1.0
        throw new UnknownServiceException(Msg.getString("K004d")); //$NON-NLS-1$
    
public longgetLastModified()
Gets the value of the response header field {@code last-modified} or
{@code 0} if this value is not set.
return
the value of the {@code last-modified} header field.
since
Android 1.0
        if (lastModified != -1) {
            return lastModified;
        }
        return lastModified = getHeaderFieldDate("Last-Modified", 0); //$NON-NLS-1$
    
public java.io.OutputStreamgetOutputStream()
Gets an {@code OutputStream} for writing data to this {@code
URLConnection}. It throws an {@code UnknownServiceException} by default.
This method must be overridden by its subclasses.
return
the OutputStream to write data.
throws
IOException
if no OutputStream could be created.
since
Android 1.0
        throw new UnknownServiceException(Msg.getString("K005f")); //$NON-NLS-1$
    
public java.security.PermissiongetPermission()
Gets a {@code Permission} object representing all needed permissions to
open this connection. The returned permission object depends on the state
of the connection and will be {@code null} if no permissions are
necessary. By default, this method returns {@code AllPermission}.
Subclasses should overwrite this method to return an appropriate
permission object.
return
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
        return new java.security.AllPermission();
    
public intgetReadTimeout()
Gets the configured timeout for reading from the input stream of an
established connection to the resource.
return
the reading timeout value in milliseconds.
since
Android 1.0
        return readTimeout;
    
public java.util.MapgetRequestProperties()
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.
return
the request-property representing generic map.
since
Android 1.0
        if (connected) {
            throw new IllegalStateException(Msg.getString("K0037")); //$NON-NLS-1$
        }
        return Collections.emptyMap();
    
public java.lang.StringgetRequestProperty(java.lang.String field)
Gets the value of the request header property specified by {code field}
or {@code null} if there is no field with this name. The current
implementation of this method returns always {@code null}.
param
field
the name of the request header property.
return
the value of the property.
throws
IllegalStateException
if the connection has been already established.
since
Android 1.0
        if (connected) {
            throw new IllegalStateException(Msg.getString("K0037")); //$NON-NLS-1$
        }
        return null;
    
public java.net.URLgetURL()
Gets the URL represented by this {@code URLConnection}.
return
the URL of this connection.
since
Android 1.0
        return url;
    
public booleangetUseCaches()
Gets the value of the flag which specifies whether this {@code
URLConnection} allows to use caches.
return
{@code true} if using caches is allowed, {@code false} otherwise.
since
Android 1.0
        return useCaches;
    
public static java.lang.StringguessContentTypeFromName(java.lang.String url)
Determines the MIME-type of the given resource {@code url} by resolving
the filename extension with the internal FileNameMap. Any fragment
identifier is removed before processing.
param
url
the URL with the filename to get the MIME type.
return
the guessed content type or {@code null} if the type could not be
determined.
since
Android 1.0
        return getFileNameMap().getContentTypeFor(url);
    
public static java.lang.StringguessContentTypeFromStream(java.io.InputStream is)
Determines the MIME-type of the resource represented by the input stream
{@code is} by reading its first few characters.
param
is
the resource representing input stream to determine the
content type.
return
the guessed content type or {@code 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
        if (!is.markSupported()) {
            return null;
        }
        is.mark(4);
        char[] chars = new char[4];
        for (int i = 0; i < chars.length; i++) {
            chars[i] = (char) is.read();
        }
        is.reset();
        if ((chars[0] == 'P") && (chars[1] == 'K")) {
            return "application/zip"; //$NON-NLS-1$
        }
        if ((chars[0] == 'G") && (chars[1] == 'I")) {
            return "image/gif"; //$NON-NLS-1$
        }
        if (new String(chars).trim().startsWith("<")) { //$NON-NLS-1$
            return "text/html"; //$NON-NLS-1$
        }
        return null;
    
private java.lang.StringparseTypeString(java.lang.String typeString)
Performs any necessary string parsing on the input string such as
converting non-alphanumeric character into underscore.
param
typeString
the parsed string
return
the string to be parsed
        StringBuffer typeStringBuffer = new StringBuffer(typeString);
        for (int i = 0; i < typeStringBuffer.length(); i++) {
            // if non-alphanumeric, replace it with '_'
            char c = typeStringBuffer.charAt(i);
            if (!(Character.isLetter(c) || Character.isDigit(c) || c == '.")) {
                typeStringBuffer.setCharAt(i, '_");
            }
        }
        return typeStringBuffer.toString();
    
public voidsetAllowUserInteraction(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.
param
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.
see
#allowUserInteraction
since
Android 1.0
        if (connected) {
            throw new IllegalStateException(Msg.getString("K0037")); //$NON-NLS-1$
        }
        this.allowUserInteraction = newValue;
    
public voidsetConnectTimeout(int timeout)
Sets the timeout value in milliseconds for establishing the connection to
the resource pointed by this {@code URLConnection} instance. A {@code
SocketTimeoutException} is thrown if the connection could not be
established in this time. Default is {@code 0} which stands for an
infinite timeout.
param
timeout
the connecting timeout in milliseconds.
throws
IllegalArgumentException
if the parameter {@code timeout} is less than zero.
since
Android 1.0
        if (0 > timeout) {
            throw new IllegalArgumentException(Msg.getString("K0036")); //$NON-NLS-1$
        }
        this.connectTimeout = timeout;
    
public static synchronized voidsetContentHandlerFactory(java.net.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.
param
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
        if (contentHandlerFactory != null) {
            throw new Error(Msg.getString("K004e")); //$NON-NLS-1$
        }
        SecurityManager sManager = System.getSecurityManager();
        if (sManager != null) {
            sManager.checkSetFactory();
        }
        contentHandlerFactory = contentFactory;
    
public static voidsetDefaultAllowUserInteraction(boolean allows)
Sets the default value for the flag indicating whether this connection
allows user interaction or not. Existing {@code URLConnection}s are
unaffected.
param
allows
the default value of the flag to be used for new connections.
see
#defaultAllowUserInteraction
see
#allowUserInteraction
since
Android 1.0
        defaultAllowUserInteraction = allows;
    
public static voidsetDefaultRequestProperty(java.lang.String field, java.lang.String value)
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.
param
field
the request header field to be set.
param
value
the default value to be used.
deprecated
Use {@link #setRequestProperty} of an existing {@code
URLConnection} instance.
since
Android 1.0
    
public voidsetDefaultUseCaches(boolean newValue)
Sets the default value for the flag indicating whether this connection
allows to use caches. Existing {@code URLConnection}s are unaffected.
param
newValue
the default value of the flag to be used for new connections.
see
#defaultUseCaches
see
#useCaches
since
Android 1.0
        // BEGIN android-removed
        // Setting the default doesn't concern the current connection.
        // if (connected) {
        //     throw new IllegalAccessError(Msg.getString("K0037")); //$NON-NLS-1$
        // }
        // END android-removed
        defaultUseCaches = newValue;
    
public voidsetDoInput(boolean newValue)
Sets the flag indicating whether this {@code URLConnection} allows input.
It cannot be set after the connection is established.
param
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.
see
#doInput
since
Android 1.0
        if (connected) {
            throw new IllegalStateException(Msg.getString("K0037")); //$NON-NLS-1$
        }
        this.doInput = newValue;
    
public voidsetDoOutput(boolean newValue)
Sets the flag indicating whether this {@code URLConnection} allows
output. It cannot be set after the connection is established.
param
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.
see
#doOutput
since
Android 1.0
        if (connected) {
            throw new IllegalStateException(Msg.getString("K0037")); //$NON-NLS-1$
        }
        this.doOutput = newValue;
    
public static voidsetFileNameMap(java.net.FileNameMap map)
Sets the internal map which is used by all {@code URLConnection}
instances to determine the MIME-type according to a filename extension.
param
map
the MIME table to be set.
since
Android 1.0
        SecurityManager manager = System.getSecurityManager();
        if (manager != null) {
            manager.checkSetFactory();
        }
        fileNameMap = map;
    
public voidsetIfModifiedSince(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 {@code 0}.
param
newValue
the time in milliseconds since January 1, 1970 GMT.
throws
IllegalStateException
if this {@code URLConnection} has already been connected.
see
#ifModifiedSince
since
Android 1.0
        if (connected) {
            throw new IllegalStateException(Msg.getString("K0037")); //$NON-NLS-1$
        }
        this.ifModifiedSince = newValue;
    
public voidsetReadTimeout(int timeout)
Sets the timeout value in milliseconds for reading from the input stream
of an established connection to the resource. A {@code
SocketTimeoutException} is thrown if the connection could not be
established in this time. Default is {@code 0} which stands for an
infinite timeout.
param
timeout
the reading timeout in milliseconds.
throws
IllegalArgumentException
if the parameter {@code timeout} is less than zero.
since
Android 1.0
        if (0 > timeout) {
            throw new IllegalArgumentException(Msg.getString("K0036")); //$NON-NLS-1$
        }
        this.readTimeout = timeout;
    
public voidsetRequestProperty(java.lang.String field, java.lang.String newValue)
Sets the value of the specified request header field. The value will only
be used by the current {@code URLConnection} instance. This method can
only be called before the connection is established.
param
field
the request header field to be set.
param
newValue
the new value of the specified property.
throws
IllegalStateException
if the connection has been already established.
throws
NullPointerException
if the parameter {@code field} is {@code null}.
since
Android 1.0
        if (connected) {
            throw new IllegalStateException(Msg.getString("K0037")); //$NON-NLS-1$
        }
        if (field == null) {
            throw new NullPointerException(Msg.getString("KA007")); //$NON-NLS-1$
        }
    
public voidsetUseCaches(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.
param
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.
see
#useCaches
since
Android 1.0
        if (connected) {
            throw new IllegalStateException(Msg.getString("K0037")); //$NON-NLS-1$
        }
        this.useCaches = newValue;
    
public java.lang.StringtoString()
Returns the string representation containing the name of this class and
the URL.
return
the string representation of this {@code URLConnection} instance.
since
Android 1.0
        return getClass().getName() + ":" + url.toString(); //$NON-NLS-1$