URLConnection

public abstract class URLConnection extends Object
Known Direct Subclasses
Known Indirect Subclasses

A connection to a URL for reading or writing. For HTTP connections, see HttpURLConnection for documentation of HTTP-specific features.

For example, to retrieve ftp://mirror.csclub.uwaterloo.ca/index.html:

   URL url = new URL("ftp://mirror.csclub.uwaterloo.ca/index.html");
   URLConnection urlConnection = url.openConnection();
   InputStream in = new BufferedInputStream(urlConnection.getInputStream());
   try {
     readStream(in);
   } finally {
     in.close();
   }
 

URLConnection must be configured before it has connected to the remote resource. Instances of URLConnection are not reusable: you must use a different instance for each connection to a resource.

Timeouts

URLConnection supports two timeouts: a connect timeout and a read timeout. By default, operations never time out.

Built-in Protocols

  • File
    Resources from the local file system can be loaded using file: URIs. File connections can only be used for input.
  • FTP
    File Transfer Protocol (RFC 959) is supported, but with no public subclass. FTP connections can be used for input or output but not both.

    By default, FTP connections will be made using anonymous as the username and the empty string as the password. Specify alternate usernames and passwords in the URL: ftp://username:password@host/path.

  • HTTP and HTTPS
    Refer to the HttpURLConnection and HttpsURLConnection subclasses.

Registering Additional Protocols

Use setURLStreamHandlerFactory(URLStreamHandlerFactory) to register handlers for other protocol types.

Field Summary

protected boolean allowUserInteraction Unused by Android.
protected boolean connected Specifies whether this URLConnection is already connected to the remote resource.
protected boolean doInput Specifies whether this URLConnection allows receiving data.
protected boolean doOutput Specifies whether this URLConnection allows sending data.
protected long ifModifiedSince The data must be modified more recently than this time in milliseconds since January 1, 1970, GMT to be transmitted.
protected URL url The URL which represents the remote target of this URLConnection.
protected boolean useCaches Specifies whether the using of caches is enabled or the data has to be recent for every request.

Protected Constructor Summary

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

Public Method Summary

void
addRequestProperty(String field, String newValue)
Adds the given property to the request header.
abstract void
connect()
Opens a connection to the resource.
boolean
getAllowUserInteraction()
Returns allowUserInteraction.
int
getConnectTimeout()
Returns the connect timeout in milliseconds.
Object
getContent()
Returns an object representing the content of the resource this URLConnection is connected to.
Object
getContent(Class[] types)
Returns an object representing the content of the resource this URLConnection is connected to.
String
getContentEncoding()
Returns the content encoding type specified by the response header field content-encoding or null if this field is not set.
int
getContentLength()
Returns the content length in bytes specified by the response header field content-length or -1 if this field is not set or cannot be represented as an int.
String
getContentType()
Returns the MIME-type of the content specified by the response header field content-type or null if type is unknown.
long
getDate()
Returns the timestamp when this response has been sent as a date in milliseconds since January 1, 1970 GMT or 0 if this timestamp is unknown.
static boolean
getDefaultAllowUserInteraction()
Returns the default value of allowUserInteraction.
static String
getDefaultRequestProperty(String field)
This method was deprecated. Use getRequestProperty(String) instead.
boolean
getDefaultUseCaches()
Returns the default setting whether this connection allows using caches.
boolean
getDoInput()
Returns the value of the option doInput which specifies whether this connection allows to receive data.
boolean
getDoOutput()
Returns the value of the option doOutput which specifies whether this connection allows to send data.
long
getExpiration()
Returns the timestamp when this response will be expired in milliseconds since January 1, 1970 GMT or 0 if this timestamp is unknown.
static FileNameMap
getFileNameMap()
Returns the table which is used by all URLConnection instances to determine the MIME-type according to a file extension.
String
getHeaderField(String key)
Returns the value of the header field specified by key or null if there is no field with this name.
String
getHeaderField(int pos)
Returns the header value at the field position pos or null if the header has fewer than pos fields.
long
getHeaderFieldDate(String field, long defaultValue)
Returns the specified header value as a date in milliseconds since January 1, 1970 GMT.
int
getHeaderFieldInt(String field, int defaultValue)
Returns the specified header value as a number.
String
getHeaderFieldKey(int posn)
Returns the name of the header field at the given position posn or null if there are fewer than posn fields.
Map<StringList<String>>
getHeaderFields()
Returns an unmodifiable map of the response-header fields and values.
long
getIfModifiedSince()
Returns the point of time since when the data must be modified to be transmitted.
InputStream
getInputStream()
Returns an InputStream for reading data from the resource pointed by this URLConnection.
long
getLastModified()
Returns the value of the response header field last-modified or 0 if this value is not set.
OutputStream