HttpURLConnection

Class Overview

An URLConnection for HTTP (RFC 2616) used to send and receive data over the web. Data may be of any type and length. This class may be used to send and receive streaming data whose length is not known in advance.

Uses of this class follow a pattern:

1. Obtain a new HttpURLConnection by calling URL.openConnection() and casting the result to HttpURLConnection.
2. Prepare the request. The primary property of a request is its URI. Request headers may also include metadata such as credentials, preferred content types, and session cookies.
3. Optionally upload a request body. Instances must be configured with setDoOutput(true) if they include a request body. Transmit data by writing to the stream returned by getOutputStream().
4. Read the response. Response headers typically include metadata such as the response body's content type and length, modified dates and session cookies. The response body may be read from the stream returned by getInputStream(). If the response has no body, that method returns an empty stream.
5. Disconnect. Once the response body has been read, the HttpURLConnection should be closed by calling disconnect(). Disconnecting frees all resources held by a connection.

For example, to retrieve the webpage at http://www.android.com/:

   URL url = new URL("http://www.android.com/");
   HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
   try {
     InputStream in = new BufferedInputStream(urlConnection.getInputStream());
     readStream(in);
    finally {
     urlConnection.disconnect();
   }
 }

Secure Communication with HTTPS

Calling openConnection() on a URL with the "https" scheme will return an HttpsURLConnection.

This class attempts to create secure connections using common TLS extensions and SSL deflate compression. Should that fail, the connection will be retried with SSL3 only.

Response Handling

HttpURLConnection will follow up to five HTTP redirects. It will follow redirects from one origin server to another. This implementation doesn't follow redirects from HTTPS to HTTP or vice versa.

If the HTTP response indicates that an error occurred, getInputStream() will throw an IOException. Use getErrorStream() to read the error response. The headers can be read in the normal way using getHeaderFields(),

Posting Content

To upload data to a web server, configure the connection for output using setDoOutput(true).

For best performance, you should call either setFixedLengthStreamingMode(int) when the body length is known in advance, or setChunkedStreamingMode(int) when it is not. Otherwise HttpURLConnection will be forced to buffer the complete request body in memory before it is transmitted, wasting (and possibly exhausting) heap and increasing latency.

For example, to perform an upload:

   HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
   try {
     urlConnection.setDoOutput(true);
     urlConnection.setChunkedStreamingMode(0);

     OutputStream out = new BufferedOutputStream(urlConnection.getOutputStream());
     writeStream(out);

     InputStream in = new BufferedInputStream(urlConnection.getInputStream());
     readStream(in);
    finally {
     urlConnection.disconnect();
   }
 }

Performance

The input and output streams returned by this class are not buffered. Most callers should wrap the returned streams with BufferedInputStream or BufferedOutputStream. Callers that do only bulk reads or writes may omit buffering.

When transferring large amounts of data to or from a server, use streams to limit how much data is in memory at once. Unless you need the entire body to be in memory at once, process it as a stream (rather than storing the complete body as a single byte array or string).

To reduce latency, this class may reuse the same underlying Socket for multiple request/response pairs. As a result, HTTP connections may be held open longer than necessary. Calls to disconnect() return the socket to a pool of connected sockets. This behavior can be disabled by setting the "http.keepAlive" system property to "false" before issuing any HTTP requests. The "http.maxConnections" property may be used to control how many idle connections to each server will be held.

By default, this implementation of HttpURLConnection requests that servers use gzip compression. Since getContentLength() returns the number of bytes transmitted, you cannot use that method to predict how many bytes can be read from getInputStream(). Instead, read that stream until it is exhausted: when read() returns -1. Gzip compression can be disabled by setting the acceptable encodings in the request header:

   urlConnection.setRequestProperty("Accept-Encoding", "identity");
 

Handling Network Sign-On

Some Wi-Fi networks block Internet access until the user clicks through a sign-on page. Such sign-on pages are typically presented by using HTTP redirects. You can use getURL() to test if your connection has been unexpectedly redirected. This check is not valid until after the response headers have been received, which you can trigger by calling getHeaderFields() or getInputStream(). For example, to check that a response was not redirected to an unexpected host:

   HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
   try {
     InputStream in = new BufferedInputStream(urlConnection.getInputStream());
     if (!url.getHost().equals(urlConnection.getURL().getHost())) {
       // we were redirected! Kick the user out to the browser to sign on?
     
     ...
   } finally {
     urlConnection.disconnect();
   }
 }

HTTP Authentication

HttpURLConnection supports HTTP basic authentication. Use Authenticator to set the VM-wide authentication handler:

   Authenticator.setDefault(new Authenticator() {
     protected PasswordAuthentication getPasswordAuthentication() {
       return new PasswordAuthentication(username, password.toCharArray());
     
   });
 }

Unless paired with HTTPS, this is not a secure mechanism for user authentication. In particular, the username, password, request and response are all transmitted over the network without encryption.

Sessions with Cookies

To establish and maintain a potentially long-lived session between client and server, HttpURLConnection includes an extensible cookie manager. Enable VM-wide cookie management using CookieHandler and CookieManager:

   CookieManager cookieManager = new CookieManager();
   CookieHandler.setDefault(cookieManager);
 

By default, CookieManager accepts cookies from the origin server only. Two other policies are included: ACCEPT_ALL and ACCEPT_NONE. Implement CookiePolicy to define a custom policy.

The default CookieManager keeps all accepted cookies in memory. It will forget these cookies when the VM exits. Implement CookieStore to define a custom cookie store.

In addition to the cookies set by HTTP responses, you may set cookies programmatically. To be included in HTTP request headers, cookies must have the domain and path properties set.

By default, new instances of HttpCookie work only with servers that support RFC 2965 cookies. Many web servers support only the older specification, RFC 2109. For compatibility with the most web servers, set the cookie version to 0.

For example, to receive www.twitter.com in French:

   HttpCookie cookie = new HttpCookie("lang", "fr");
   cookie.setDomain("twitter.com");
   cookie.setPath("/");
   cookie.setVersion(0);
   cookieManager.getCookieStore().add(new URI("http://twitter.com/"), cookie);
 

HTTP Methods

HttpURLConnection uses the GET method by default. It will use POST if setDoOutput(true) has been called. Other HTTP methods (OPTIONS, HEAD, PUT, DELETE and TRACE) can be used with setRequestMethod(String).

Proxies

By default, this class will connect directly to the origin server. It can also connect via an HTTP or SOCKS proxy. To use a proxy, use URL.openConnection(Proxy) when creating the connection.

IPv6 Support

This class includes transparent support for IPv6. For hosts with both IPv4 and IPv6 addresses, it will attempt to connect to each of a host's addresses until a connection is established.

Response Caching

HttpURLConnection supports a VM-wide HTTP response cache. Implement ResponseCache and use setDefault(ResponseCache) to install a custom cache. Implementing this API is onerous: correct implementations should follow all caching rules defined by Section 13 of RFC 2616.

Each instance of HttpURLConnection may be used for one request/response pair. Instances of this class are not thread safe.

Summary

Constants
int	HTTP_ACCEPTED	Numeric status code, 202: Accepted
int	HTTP_BAD_GATEWAY	Numeric status code, 502: Bad Gateway
int	HTTP_BAD_METHOD	Numeric status code, 405: Bad Method
int	HTTP_BAD_REQUEST	Numeric status code, 400: Bad Request
int	HTTP_CLIENT_TIMEOUT	Numeric status code, 408: Client Timeout
int	HTTP_CONFLICT	Numeric status code, 409: Conflict
int	HTTP_CREATED	Numeric status code, 201: Created
int	HTTP_ENTITY_TOO_LARGE	Numeric status code, 413: Entity too large
int	HTTP_FORBIDDEN	Numeric status code, 403: Forbidden
int	HTTP_GATEWAY_TIMEOUT	Numeric status code, 504: Gateway timeout
int	HTTP_GONE	Numeric status code, 410: Gone
int	HTTP_INTERNAL_ERROR	Numeric status code, 500: Internal error
int	HTTP_LENGTH_REQUIRED	Numeric status code, 411: Length required
int	HTTP_MOVED_PERM	Numeric status code, 301 Moved permanently
int	HTTP_MOVED_TEMP	Numeric status code, 302: Moved temporarily
int	HTTP_MULT_CHOICE	Numeric status code, 300: Multiple choices
int	HTTP_NOT_ACCEPTABLE	Numeric status code, 406: Not acceptable
int	HTTP_NOT_AUTHORITATIVE	Numeric status code, 203: Not authoritative
int	HTTP_NOT_FOUND	Numeric status code, 404: Not found
int	HTTP_NOT_IMPLEMENTED	Numeric status code, 501: Not implemented
int	HTTP_NOT_MODIFIED	Numeric status code, 304: Not modified
int	HTTP_NO_CONTENT	Numeric status code, 204: No content
int	HTTP_OK	Numeric status code, 200: OK
int	HTTP_PARTIAL	Numeric status code, 206: Partial
int	HTTP_PAYMENT_REQUIRED	Numeric status code, 402: Payment required
int	HTTP_PRECON_FAILED	Numeric status code, 412: Precondition failed
int	HTTP_PROXY_AUTH	Numeric status code, 407: Proxy authentication required
int	HTTP_REQ_TOO_LONG	Numeric status code, 414: Request too long
int	HTTP_RESET	Numeric status code, 205: Reset
int	HTTP_SEE_OTHER	Numeric status code, 303: See other
int	HTTP_SERVER_ERROR	This constant is deprecated. Use HTTP_INTERNAL_ERROR
int	HTTP_UNAUTHORIZED	Numeric status code, 401: Unauthorized
int	HTTP_UNAVAILABLE	Numeric status code, 503: Unavailable
int	HTTP_UNSUPPORTED_TYPE	Numeric status code, 415: Unsupported type
int	HTTP_USE_PROXY	Numeric status code, 305: Use proxy
int	HTTP_VERSION	Numeric status code, 505: Version not supported

Fields
protected int	chunkLength	If the HTTP chunked encoding is enabled this parameter defines the chunk-length.
protected int	fixedContentLength	If using HTTP fixed-length streaming mode this parameter defines the fixed length of content.
protected boolean	instanceFollowRedirects	Flag to define whether the protocol will automatically follow redirects or not.
protected String	method	The HTTP request method of this HttpURLConnection.
protected int	responseCode	The status code of the response obtained from the HTTP request.
protected String	responseMessage	The HTTP response message which corresponds to the response code.

[Expand] Inherited Fields

From class java.net.URLConnection 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. 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 Constructors
	HttpURLConnection(URL url) Constructs a new HttpURLConnection instance pointing to the resource specified by the url.

Public Methods
abstract void	disconnect() Closes the connection to the HTTP server.
String	getContentEncoding() Returns the encoding used to transmit the response body over the network.
InputStream	getErrorStream() Returns an input stream from the server in the case of an error such as the requested file has not been found on the remote server.
static boolean	getFollowRedirects() Returns the value of followRedirects which indicates if this connection follows a different URL redirected by the server.
long	getHeaderFieldDate(String field, long defaultValue) Returns the date value in milliseconds since 01.01.1970, 00:00h corresponding to the header field field.
boolean	getInstanceFollowRedirects() Returns whether this connection follows redirects.
Permission	getPermission() Returns the permission object (in this case SocketPermission) with the host and the port number as the target name and "resolve, connect" as the action list.
String	getRequestMethod() Returns the request method which will be used to make the request to the remote HTTP server.
int	getResponseCode() Returns the response code returned by the remote HTTP server.
String	getResponseMessage() Returns the response message returned by the remote HTTP server.
void	setChunkedStreamingMode(int chunkLength) Stream a request body whose length is not known in advance.
void	setFixedLengthStreamingMode(int contentLength) If the length of a HTTP request body is known ahead, sets fixed length to enable streaming without buffering.
static void	setFollowRedirects(boolean auto) Sets the flag of whether this connection will follow redirects returned by the remote server.
void	setInstanceFollowRedirects(boolean followRedirects) Sets whether this connection follows redirects.
void	setRequestMethod(String method) Sets the request command which will be sent to the remote HTTP server.
abstract boolean	usingProxy() Returns whether this connection uses a proxy server or not.

[Expand] Inherited Methods
From class java.net.URLConnection 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 the option value which indicates whether user interaction is allowed on this URLConnection. int getConnectTimeout() Returns the configured connecting timeout. 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. 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 setting whether this connection allows user interaction. static String getDefaultRequestProperty(String field) This method is deprecated. Use getRequestProperty(String) 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<String, List<String>> getHeaderFields() Returns an unchangeable 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 getOutputStream() Returns an OutputStream for writing data to this URLConnection. Permission getPermission() Returns a Permission object representing all needed permissions to open this connection. int getReadTimeout() Returns the configured timeout for reading from the input stream of an established connection to the resource. Map<String, List<String>> getRequestProperties() Returns an unchangeable map of general request properties used by this connection. String getRequestProperty(String field) Returns the value of the request header property specified by {code field} or null if there is no field with this name. URL getURL() Returns the URL represented by this URLConnection. boolean getUseCaches() Returns 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. synchronized 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) This method is deprecated. Use setRequestProperty(String, 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.
From class java.lang.Object Object clone() Creates and returns a copy of this Object. boolean equals(Object o) Compares this instance with the specified object and indicates if they are equal. void finalize() Called before the object's memory is reclaimed by the VM. final Class<?> getClass() Returns the unique instance of Class that represents this object's class. int hashCode() Returns an integer hash code for this object. final void notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString() Returns a string containing a concise, human-readable description of this object. final void wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait(long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.