Android
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
Known Indirect Subclasses

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()
Returns 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)
Returns the object pointed to by this URL.
          Object  getContent()
Returns the object pointed to by this URL.
          String  getContentEncoding()
Returns the Content encoding type of the response body, null if no such field is found in the header response.
          int  getContentLength()
Returns the length of the content or body in the response header in bytes.
          String  getContentType()
Returns the type of the content.
          long  getDate()
Returns 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()
Returns whether this connection allow user interaction by default.
      static    String  getDefaultRequestProperty(String field)
This method is deprecated. Use getRequestProperty(String)
          boolean  getDefaultUseCaches()
Returns whether this connection use caches by default.
          boolean  getDoInput()
Returns whether this connection supports input.
          boolean  getDoOutput()
Returns whether this connection supports output.
          long  getExpiration()
Returns 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()
Returns the MIME table of this URL connection.
          String  getHeaderField(int pos)
Returns the value of the field at position pos.
          String  getHeaderField(String key)
Returns the value of the field corresponding to the key Returns null if there is no such field.
          long  getHeaderFieldDate(String field, long defaultValue)
Returns the date value in the form of milliseconds since epoch corresponding to the field field.
          int  getHeaderFieldInt(String field, int defaultValue)
Returns the integer value of the specified field.
          String  getHeaderFieldKey(int posn)
Returns the name of the field at position specified by posn, null if there are fewer than posn fields.
          Map<StringList<String>>  getHeaderFields()
Provides an unmodifiable map of the connection header values.
          long  getIfModifiedSince()
Returns the value of ifModifiedSince of this connection in milliseconds since epoch
          InputStream  getInputStream()
Creates an InputStream for reading from this URL Connection.
          long  getLastModified()
Returns 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()
Returns the permissions necessary to make the connection.
          int  getReadTimeout()
Returns a timeout of reading by milliseconds
          Map<StringList<String>>  getRequestProperties()
Provides an unmodifiable map of the request properties.
          String  getRequestProperty(String field)
Returns the value corresponding to the field in the request Header, null if no such field exists.
          URL  getURL()
Returns the URL of this connection
          boolean  getUseCaches()
Returns 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(String)
          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()
Returns the name of the class of the URLConnection
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)

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()

Returns 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)

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

Returns

  • a non-null object

Throws

IOException if an IO error occurred

public String getContentEncoding()

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

Returns

  • The content encoding type

See Also

public int getContentLength()

Returns 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

See Also

public String getContentType()

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

Returns

  • The type of the content

public long getDate()

Returns 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()

Returns 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(String)

Returns 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()

Returns whether this connection use caches by default.

Returns

  • true if this connection use caches by default, false otherwise

public boolean getDoInput()

Returns whether this connection supports input.

Returns

  • true if this connection supports input, false otherwise

public boolean getDoOutput()

Returns whether this connection supports output.

Returns

  • true if this connection supports output, false otherwise

public long getExpiration()

Returns 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()

Returns the MIME table of this URL connection.

Returns

  • FileNameMap

public String getHeaderField(int pos)

Returns the value of the field at position pos. Returns 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

public String getHeaderField(String key)

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

Parameters

key the name of the header field

Returns

  • The value of the header field

public long getHeaderFieldDate(String field, long defaultValue)

Returns the date value in the form of milliseconds since epoch corresponding to the field field. Returns 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

public int getHeaderFieldInt(String field, int defaultValue)

Returns the integer value of the specified field. Returns 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)

Returns 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

public Map<StringList<String>> 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()

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

Returns

  • the time since epoch

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

public long getLastModified()

Returns 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

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

public Permission getPermission()

Returns 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<StringList<String>> 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)

Returns 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

public URL getURL()

Returns the URL of this connection

Returns

  • the URL of this connection

public boolean getUseCaches()

Returns 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

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

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(String)

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

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

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

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

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

public String toString()

Returns the name of the class of the URLConnection

Returns

  • The string representation of this URLConnection
Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:48