Android - An Open Handset Alliance Project

java.net
public abstract class

java.net.URLConnection

java.lang.Object
	java.net.URLConnection

The URLConnection class is responsible for establishing a connection to an URL for a given protocol. The correct URLConnection subclass to call is determined by URLStreamHandler.openConnection().

Known Direct Subclasses

HttpURLConnection, JarURLConnection

Known Indirect Subclasses

HttpsURLConnection

Summary

Fields

protected	boolean	allowUserInteraction
protected	boolean	connected
protected	boolean	doInput
protected	boolean	doOutput
protected	long	ifModifiedSince
protected	URL	url
protected	boolean	useCaches

Protected Constructors

					URLConnection(URL url)
					Creates a URLConnection pointing to the resource specified by the `url`

Public Methods

			void	addRequestProperty(String field, String newValue)
				Adds the given request property.
abstract			void	connect()
				Establishes the connection to the resource specified by this `URL` with this `method`, along with other options that can only be set before this connection is made.
			boolean	getAllowUserInteraction()
				Answers the value of `allowUserInteraction` which indicates if this connection allows user interaction
			int	getConnectTimeout()
				Returns a timeout of connection by milliseconds
			Object	getContent(Class[] types)
				Answers the object pointed to by this `URL`.
			Object	getContent()
				Answers the object pointed to by this `URL`.
			String	getContentEncoding()
				Answers the Content encoding type of the response body, null if no such field is found in the header response.
			int	getContentLength()
				Answers the length of the content or body in the response header in bytes.
			String	getContentType()
				Answers the type of the content.
			long	getDate()
				Answers the date in milliseconds since epoch when this response header was created, or 0 if the field `Date` is not found in the header.
		static	boolean	getDefaultAllowUserInteraction()
				Answers whether this connection allow user interaction by default.
		static	String	getDefaultRequestProperty(String field)
				This method is deprecated. Use getRequestProperty().
			boolean	getDefaultUseCaches()
				Answers whether this connection use caches by default.
			boolean	getDoInput()
				Answers whether this connection supports input.
			boolean	getDoOutput()
				Answers whether this connection supports output.
			long	getExpiration()
				Answers the date in milliseconds since epoch when this response header expires or 0 if the field `Expires` is not found in the header.
		static	FileNameMap	getFileNameMap()
				Answers the MIME table of this URL connection.
			String	getHeaderField(int pos)
				Answers the value of the field at position `pos.`
			String	getHeaderField(String key)
				Answers the value of the field corresponding to the `key` Answers `null` if there is no such field.
			long	getHeaderFieldDate(String field, long defaultValue)
				Answers the date value in the form of milliseconds since epoch corresponding to the field `field`.
			int	getHeaderFieldInt(String field, int defaultValue)
				Answers the integer value of the specified field.
			String	getHeaderFieldKey(int posn)
				Answers the name of the field at position specified by `posn`, null if there are fewer than `posn` fields.
			Map	getHeaderFields()
				Provides an unmodifiable map of the connection header values.
			long	getIfModifiedSince()
				Answers the value of `ifModifiedSince` of this connection in milliseconds since epoch
			InputStream	getInputStream()
				Creates an InputStream for reading from this URL Connection.
			long	getLastModified()
				Answers the value of the field `Last-Modified` in the response header, 0 if no such field exists
			OutputStream	getOutputStream()
				Creates an OutputStream for writing to this URL Connection.
			Permission	getPermission()
				Answers the permissions necessary to make the connection.
			int	getReadTimeout()
				Returns a timeout of reading by milliseconds
			Map	getRequestProperties()
				Provides an unmodifiable map of the request properties.
			String	getRequestProperty(String field)
				Answers the value corresponding to the field in the request Header, null if no such field exists.
			URL	getURL()
				Answers the `URL` of this connection
			boolean	getUseCaches()
				Answers whether this connection uses caches
		static	String	guessContentTypeFromName(String url)
				Determines the MIME type of the file specified by the `string` URL, using the filename extension.
		static	String	guessContentTypeFromStream(InputStream is)
				Examines the bytes of the input stream and returns the MIME type, null if no content type can be deduced.
			void	setAllowUserInteraction(boolean newValue)
				Sets the flag indicating whether this connection allows user interaction This can only be called prior to connection establishment.
			void	setConnectTimeout(int timeout)
				Sets a timeout for connection to perform non-block.
	synchronized	static	void	setContentHandlerFactory(ContentHandlerFactory contentFactory)
				Sets the current content handler factory to be `contentFactory`.
		static	void	setDefaultAllowUserInteraction(boolean allows)
				Set whether user interaction is allowed by default.
		static	void	setDefaultRequestProperty(String field, String value)
				This method is deprecated. Use getRequestProperty().
			void	setDefaultUseCaches(boolean newValue)
				Set whether caches are used by default.
			void	setDoInput(boolean newValue)
				Sets whether this URLConnection allows input.
			void	setDoOutput(boolean newValue)
				Sets whether this URLConnection allows output.
		static	void	setFileNameMap(FileNameMap map)
				With permission from the security manager, this method sets the `map` to be the MIME Table of this URL connection.
			void	setIfModifiedSince(long newValue)
				Sets the header field `ifModifiedSince`.
			void	setReadTimeout(int timeout)
				Sets a timeout for reading to perform non-block.
			void	setRequestProperty(String field, String newValue)
				Sets the value of the request header field `field` to `newValue` Only the current URL Connection is affected.
			void	setUseCaches(boolean newValue)
				Sets the flag indicating if this connection uses caches.
			String	toString()
				Answers the name of the class of the `URLConnection`

Methods inherited from class java.lang.Object

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

	Object	clone()
		Answers a new instance of the same class as the receiver, whose slots have been filled in with the values in the slots of the receiver.
	boolean	equals(Object o)
		Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
	void	finalize()
		Called by the virtual machine when there are no longer any (non-weak) references to the receiver.
final	Class	getClass()
		Answers the unique instance of java.lang.Class which represents the class of the receiver.
	int	hashCode()
		Answers an integer hash code for the receiver.
final	void	notify()
		Causes one thread which is `wait` ing on the receiver to be made ready to run.
final	void	notifyAll()
		Causes all threads which are `wait` ing on the receiver to be made ready to run.
	String	toString()
		Answers a string containing a concise, human-readable description of the receiver.
final	void	wait(long time, int frac)
		Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by `notify` or `notifyAll`) or the expiration of the timeout.
final	void	wait(long time)
		Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by `notify` or `notifyAll`) or the expiration of the timeout.
final	void	wait()
		Causes the thread which sent this message to be made not ready to run pending some change in the receiver (as indicated by `notify` or `notifyAll`).

Details

Fields

protected boolean allowUserInteraction

protected boolean connected

protected boolean doInput

protected boolean doOutput

protected long ifModifiedSince

protected URL url

protected boolean useCaches

Protected Constructors

protected URLConnection(URL url)

Creates a URLConnection pointing to the resource specified by the url

Public Methods

public void addRequestProperty(String field, String newValue)

Adds the given request property. Will not overwrite any existing properties associated with the given field name.

Parameters

field	the request property field name
newValue	the property value

Throws

IllegalStateException	- if connection already established
NullPointerException	- if field is null

public abstract void connect()

Establishes the connection to the resource specified by this URL with this method, along with other options that can only be set before this connection is made.

Throws

IOException	If an error occurs while connecting

public boolean getAllowUserInteraction()

Answers the value of allowUserInteraction which indicates if this connection allows user interaction

Returns

the value of the flag

public int getConnectTimeout()

Returns a timeout of connection by milliseconds

Returns

timeout of connection by milliseconds

public Object getContent(Class[] types)

Answers the object pointed to by this URL. It first attempts to get the content type from getContentType(), which looks for the response header field "Content-Type". If none is found, it will guess the content type from the filename extension. If that fails, it will guess by inspecting the stream.

Parameters

types	The list of acceptable content types

Returns

Object The object of the resource pointed by this URL, or null if the content does not match a specified content type.

Throws

IOException	If an error occurred obtaining the content.

public Object getContent()

Returns

a non-null object

Throws

IOException	if an IO error occurred

public String getContentEncoding()

Answers the Content encoding type of the response body, null if no such field is found in the header response.

Returns

The content encoding type

public int getContentLength()

Answers the length of the content or body in the response header in bytes. Answer -1 if Content-Length cannot be found in the response header.

Returns

The length of the content

public String getContentType()

Answers the type of the content. Answers null if there's no such field.

Returns

The type of the content

public long getDate()

Answers the date in milliseconds since epoch when this response header was created, or 0 if the field Date is not found in the header.

Returns

Date in millisecond since epoch

public static boolean getDefaultAllowUserInteraction()

Answers whether this connection allow user interaction by default.

Returns

the value of defaultAllowUserInteraction

public static String getDefaultRequestProperty(String field)

This method is deprecated. Use getRequestProperty().

Answers the default value for the field specified by field, null if there's no such field.

Parameters

field	the field to get the request property for

Returns

the field to be looked up

public boolean getDefaultUseCaches()

Answers whether this connection use caches by default.

Returns

true if this connection use caches by default, false otherwise

public boolean getDoInput()

Answers whether this connection supports input.

Returns

true if this connection supports input, false otherwise

public boolean getDoOutput()

Answers whether this connection supports output.

Returns

true if this connection supports output, false otherwise

public long getExpiration()

Answers the date in milliseconds since epoch when this response header expires or 0 if the field Expires is not found in the header.

Returns

Date in milliseconds since epoch

public static FileNameMap getFileNameMap()

Answers the MIME table of this URL connection.

Returns

FileNameMap

public String getHeaderField(int pos)

Answers the value of the field at position

pos.
 Answers null if there are fewer than pos fields
 in the response header.





    Parameters
    
    
        pos
        the position of the field
      
    
    






    Returns
    The value of the field








    See Also
    
    getHeaderFieldDate(String, long)
    getHeaderFieldInt(String, int)
    getHeaderFieldKey(int)

pos	the position of the field





 
    
        public 
         
         
         
         
        String
        getHeaderField(String key)
    
    




Answers the value of the field corresponding to the key
 Answers null if there is no such field.





    Parameters
    
    
        key
        the name of the header field
      
    
    






    Returns
    The value of the header field








    See Also
    
    getHeaderFieldDate(String, long)
    getHeaderFieldInt(String, int)
    getHeaderFieldKey(int)
    
    
    









 
    
        public 
         
         
         
         
        long
        getHeaderFieldDate(String field, long defaultValue)
    
    




Answers the date value in the form of milliseconds since epoch
 corresponding to the field field. Answers
 defaultValue if no such field can be found in the response
 header.





    Parameters
    
    
        field
        the field in question
      
    
        defaultValue
        the default value if no field is found
      
    
    






    Returns
    milliseconds since epoch








    See Also
    
    ifModifiedSince
    setIfModifiedSince(long)
    
    
    









 
    
        public 
         
         
         
         
        int
        getHeaderFieldInt(String field, int defaultValue)
    
    




Answers the integer value of the specified field. Answers default value
 defaultValue if no such field exists.





    Parameters
    
    
        field
        the field to return
      
    
        defaultValue
        to be returned if field> does not exist
      
    
    






    Returns
    value of the field















 
    
        public 
         
         
         
         
        String
        getHeaderFieldKey(int posn)
    
    




Answers the name of the field at position specified by posn,
 null if there are fewer than posn fields.





    Parameters
    
    
        posn
        the position to look for; the first field being 0
      
    
    






    Returns
    the name of the field








    See Also
    
    getHeaderFieldDate(String, long)
    getHeaderFieldInt(String, int)
    getHeaderField(int)
    getHeaderField(String)
    getHeaderFieldDate(String, long)
    getHeaderFieldInt(String, int)
    getHeaderFieldKey(int)
    
    
    









 
    
        public 
         
         
         
         
        Map
        getHeaderFields()
    
    




Provides an unmodifiable map of the connection header values. The map
 keys are the String header field names. Each map value is a List of the
 header field values associated with that key name.








    Returns
    the mapping of header field names to values














 
    
        public 
         
         
         
         
        long
        getIfModifiedSince()
    
    




Answers the value of ifModifiedSince of this connection in
 milliseconds since epoch








    Returns
    the time since epoch








    See Also
    
    ifModifiedSince
    setIfModifiedSince(long)
    
    
    









 
    
        public 
         
         
         
         
        InputStream
        getInputStream()
    
    




Creates an InputStream for reading from this URL Connection. It throws
 UnknownServiceException by default. This method should be overridden by
 its subclasses








    Returns
    The InputStream to read from





    Throws
    
      
            IOException
            If an InputStream could not be created
        
    
    






    See Also
    
    getContent()
    getContent(Class[])
    getOutputStream()
    InputStream
    IOException
    
    
    









 
    
        public 
         
         
         
         
        long
        getLastModified()
    
    




Answers the value of the field Last-Modified in the
 response header, 0 if no such field exists








    Returns
    the value of the field last modified








    See Also
    
    Date
    getDate()
    getExpiration()
    
    
    









 
    
        public 
         
         
         
         
        OutputStream
        getOutputStream()
    
    




Creates an OutputStream for writing to this URL Connection. It throws
 UnknownServiceException by default. This method should be overridden by
 subclasses.








    Returns
    The OutputStream to write to





    Throws
    
      
            IOException
            If an OutputStream could not be created
        
    
    






    See Also
    
    getContent()
    getContent(Class[])
    getInputStream()
    IOException
    
    
    









 
    
        public 
         
         
         
         
        Permission
        getPermission()
    
    




Answers the permissions necessary to make the connection. Depending on
 the protocol, this can be any of the permission subclasses. The
 permission returned may also depend on the state of the connection, E.G
 In the case of HTTP, redirection can change the applicable permission if
 the host changed.
 
 
 By default, this methods returns AllPermission.
 Subclasses should override this and return the appropriate permission
 object.








    Returns
    the permission object governing the connection





    Throws
    
      
            IOException
            if an IO exception occurs during the creation of the
             permission object.

        
    
    












 
    
        public 
         
         
         
         
        int
        getReadTimeout()
    
    




Returns a timeout of reading by milliseconds








    Returns
    timeout of reading by milliseconds















 
    
        public 
         
         
         
         
        Map
        getRequestProperties()
    
    




Provides an unmodifiable map of the request properties. The map keys are
 Strings, the map values are each a List of Strings, with each request
 property name mapped to its corresponding property values.








    Returns
    the mapping of request property names to values














 
    
        public 
         
         
         
         
        String
        getRequestProperty(String field)
    
    




Answers the value corresponding to the field in the request Header, null
 if no such field exists.





    Parameters
    
    
        field
        the field to get the property for
      
    
    






    Returns
    the field to look up





    Throws
    
      
            IllegalStateException
            -
             if connection already established
        
    
    






    See Also
    
    getDefaultRequestProperty(String)
    setDefaultRequestProperty(String, String)
    setRequestProperty(String, String)
    
    
    









 
    
        public 
         
         
         
         
        URL
        getURL()
    
    




Answers the URL of this connection








    Returns
    the URL of this connection








    See Also
    
    URL
    URLConnection(URL)
    
    
    









 
    
        public 
         
         
         
         
        boolean
        getUseCaches()
    
    




Answers whether this connection uses caches








    Returns
    the value of the flag















 
    
        public 
        static 
         
         
         
        String
        guessContentTypeFromName(String url)
    
    




Determines the MIME type of the file specified by the
  string  URL, using the filename extension. Any fragment
 identifier is removed before processing.





    Parameters
    
    
        url
        the MIME type of the file.
      
    
    






    Returns
    the string representation of an URL








    See Also
    
    FileNameMap
    getContentTypeFor(String)
    getContentType()
    guessContentTypeFromStream(InputStream)
    
    
    









 
    
        public 
        static 
         
         
         
        String
        guessContentTypeFromStream(InputStream is)
    
    




Examines the bytes of the input stream and returns the MIME type, null if
 no content type can be deduced.





    Parameters
    
    
        is
        the input stream for the URL
      
    
    






    Returns
    the type of the input stream





    Throws
    
      
            IOException
            If an IO error occurs

        
    
    












 
    
        public 
         
         
         
         
        void
        setAllowUserInteraction(boolean newValue)
    
    




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





    Parameters
    
    
        newValue
        the value of the flag to be set
      
    
    








    Throws
    
      
            IllegalStateException
            if this method attempts to change the flag after a connection
             has been established

        
    
    












 
    
        public 
         
         
         
         
        void
        setConnectTimeout(int timeout)
    
    




Sets a timeout for connection to perform non-block. Default is zero.
 Timeout of zero means infinite.





    Parameters
    
    
        timeout
        timeout for connection in milliseconds.
      
    
    








    Throws
    
      
            IllegalArgumentException
            if timeout is less than zero.

        
    
    












 
    
        public 
        static 
         
         
        synchronized 
        void
        setContentHandlerFactory(ContentHandlerFactory contentFactory)
    
    




Sets the current content handler factory to be
 contentFactory. It can only do so with the permission of
 the security manager. The ContentFactory can only be specified once
 during the lifetime of an application.





    Parameters
    
    
        contentFactory
        the factory
      
    
    








    Throws
    
      
            Error
            if a ContentFactory has been created before SecurityException
             if the security manager does not allow this action
        
    
    






    See Also
    
    ContentHandler
    ContentHandlerFactory
    SecurityException
    checkSetFactory()
    
    
    









 
    
        public 
        static 
         
         
         
        void
        setDefaultAllowUserInteraction(boolean allows)
    
    




Set whether user interaction is allowed by default. Existing
 URLConnections are unaffected.





    Parameters
    
    
        allows
        allow user interaction

      
    
    

















 
    
        public 
        static 
         
         
         
        void
        setDefaultRequestProperty(String field, String value)
    
    




    
This method is deprecated.

    Use getRequestProperty().




Sets the field in the default request header with the
 value value





    Parameters
    
    
        field
        the request header field to be set
      
    
        value
        the new value
      
    
    

















 
    
        public 
         
         
         
         
        void
        setDefaultUseCaches(boolean newValue)
    
    




Set whether caches are used by default. Existing URLConnections are
 unaffected.





    Parameters
    
    
        newValue
        the value of the flag to be set
      
    
    











    See Also
    
    getDefaultUseCaches()
    getUseCaches()
    setUseCaches(boolean)
    useCaches
    
    
    









 
    
        public 
         
         
         
         
        void
        setDoInput(boolean newValue)
    
    




Sets whether this URLConnection allows input. It cannot be set after the
 connection is made.





    Parameters
    
    
        newValue
        boolean
      
    
    








    Throws
    
      
            IllegalAccessError
            Exception thrown when this method attempts to change the
             value after connected
        
    
    






    See Also
    
    doInput
    getDoInput()
    setDoInput(boolean)
    IllegalAccessError
    
    
    









 
    
        public 
         
         
         
         
        void
        setDoOutput(boolean newValue)
    
    




Sets whether this URLConnection allows output. It cannot be set after the
 connection is made.





    Parameters
    
    
        newValue
        boolean
      
    
    








    Throws
    
      
            IllegalAccessError
            Exception thrown when this method attempts to change the
             value after connected
        
    
    






    See Also
    
    doOutput
    getDoOutput()
    setDoOutput(boolean)
    IllegalAccessError
    
    
    









 
    
        public 
        static 
         
         
         
        void
        setFileNameMap(FileNameMap map)
    
    




With permission from the security manager, this method sets the
 map to be the MIME Table of this URL connection.





    Parameters
    
    
        map
        the MIME table to be set.

      
    
    

















 
    
        public 
         
         
         
         
        void
        setIfModifiedSince(long newValue)
    
    




Sets the header field ifModifiedSince.





    Parameters
    
    
        newValue
        number of milliseconds since epoch
      
    
    








    Throws
    
      
            IllegalStateException
            if already connected.

        
    
    












 
    
        public 
         
         
         
         
        void
        setReadTimeout(int timeout)
    
    




Sets a timeout for reading to perform non-block. Default is zero. Timeout
 of zero means infinite.





    Parameters
    
    
        timeout
        timeout for reading in milliseconds.
      
    
    








    Throws
    
      
            IllegalArgumentException
            if timeout is less than zero.

        
    
    












 
    
        public 
         
         
         
         
        void
        setRequestProperty(String field, String newValue)
    
    




Sets the value of the request header field  field  to
 newValue Only the current URL Connection is affected. It
 can only be called before the connection is made





    Parameters
    
    
        field
        the field
      
    
        newValue
        the field's new value
      
    
    








    Throws
    
      
            IllegalStateException
            -
             if connection already established
        
      
            NullPointerException
            -
             if field is null
        
    
    






    See Also
    
    getDefaultRequestProperty(String)
    setDefaultRequestProperty(String, String)
    getRequestProperty(String)
    
    
    









 
    
        public 
         
         
         
         
        void
        setUseCaches(boolean newValue)
    
    




Sets the flag indicating if this connection uses caches. This value
 cannot be set after the connection is made.





    Parameters
    
    
        newValue
        the value of the flag to be set
      
    
    








    Throws
    
      
            IllegalStateException
            Exception thrown when this method attempts to change the
             value after connected
        
    
    






    See Also
    
    getDefaultUseCaches()
    setDefaultUseCaches(boolean)
    getUseCaches()
    useCaches
    
    
    









 
    
        public 
         
         
         
         
        String
        toString()
    
    




Answers the name of the class of the URLConnection 








    Returns
    The string representation of this URLConnection








    See Also
    
    getURL()
    URLConnection(URL)

HttpURLConnection	This abstract subclass of `URLConnection` defines method for managing HTTP connection according to the description given by RFC 2068
JarURLConnection	This class establishes a connection to a URL using the jar protocol.

field	the field in question
defaultValue	the default value if no field is found

field	the field to return
defaultValue	to be returned if `field>` does not exist


e.g. "intent" or "activity"

Android - An Open Handset Alliance Project

Documentation

Goodies

java.net.URLConnection

Known Direct Subclasses

Known Indirect Subclasses

Summary

Fields

Protected Constructors

Public Methods

Methods inherited from class java.lang.Object

Details

Fields

protected boolean allowUserInteraction

protected boolean connected

protected boolean doInput

protected boolean doOutput

protected long ifModifiedSince

protected URL url

protected boolean useCaches

Protected Constructors

protected URLConnection(URL url)

Public Methods

public void addRequestProperty(String field, String newValue)

Parameters

Throws

public abstract void connect()

Throws

See Also

public boolean getAllowUserInteraction()

Returns

See Also

public int getConnectTimeout()

Returns

public Object getContent(Class[] types)

Parameters

Returns

Throws

public Object getContent()

Returns

Throws

See Also

public String getContentEncoding()

Returns

See Also

public int getContentLength()

Returns

See Also

public String getContentType()

Returns

See Also

public long getDate()

Returns

See Also

public static boolean getDefaultAllowUserInteraction()

Returns

See Also

public static String getDefaultRequestProperty(String field)

Parameters

Returns

public boolean getDefaultUseCaches()

Returns

See Also

public boolean getDoInput()

Returns

See Also

public boolean getDoOutput()

Returns

See Also

public long getExpiration()

Returns

See Also

public static FileNameMap getFileNameMap()

Returns

public String getHeaderField(int pos)

Parameters

Returns

See Also

public String getHeaderField(String key)

Parameters