HttpsURLConnection | API reference | Android Developers (original) (raw)
public abstract class HttpsURLConnection extends [HttpURLConnection](/reference/java/net/HttpURLConnection) ``
| java.lang.Object | ||
|---|---|---|
| ↳ | java.net.URLConnection | |
| ↳ | java.net.HttpURLConnection | |
| ↳ |
HttpsURLConnection extends HttpURLConnection with support for https-specific features.
See http://www.w3.org/pub/WWW/Protocols/ and RFC 2818 for more details on the https specification.
This class uses HostnameVerifier andSSLSocketFactory. There are default implementations defined for both classes. However, the implementations can be replaced on a per-class (static) or per-instance basis. All new HttpsURLConnections instances will be assigned the "default" static values at instance creation, but they can be overriden by calling the appropriate per-instance set method(s) beforeconnecting.
Summary
| Inherited constants |
|---|
| From classjava.net.HttpURLConnection int HTTP_ACCEPTED HTTP Status-Code 202: Accepted. int HTTP_BAD_GATEWAY HTTP Status-Code 502: Bad Gateway. int HTTP_BAD_METHOD HTTP Status-Code 405: Method Not Allowed. int HTTP_BAD_REQUEST HTTP Status-Code 400: Bad Request. int HTTP_CLIENT_TIMEOUT HTTP Status-Code 408: Request Time-Out. int HTTP_CONFLICT HTTP Status-Code 409: Conflict. int HTTP_CREATED HTTP Status-Code 201: Created. int HTTP_ENTITY_TOO_LARGE HTTP Status-Code 413: Request Entity Too Large. int HTTP_FORBIDDEN HTTP Status-Code 403: Forbidden. int HTTP_GATEWAY_TIMEOUT HTTP Status-Code 504: Gateway Timeout. int HTTP_GONE HTTP Status-Code 410: Gone. int HTTP_INTERNAL_ERROR HTTP Status-Code 500: Internal Server Error. int HTTP_LENGTH_REQUIRED HTTP Status-Code 411: Length Required. int HTTP_MOVED_PERM HTTP Status-Code 301: Moved Permanently. int HTTP_MOVED_TEMP HTTP Status-Code 302: Temporary Redirect. int HTTP_MULT_CHOICE HTTP Status-Code 300: Multiple Choices. int HTTP_NOT_ACCEPTABLE HTTP Status-Code 406: Not Acceptable. int HTTP_NOT_AUTHORITATIVE HTTP Status-Code 203: Non-Authoritative Information. int HTTP_NOT_FOUND HTTP Status-Code 404: Not Found. int HTTP_NOT_IMPLEMENTED HTTP Status-Code 501: Not Implemented. int HTTP_NOT_MODIFIED HTTP Status-Code 304: Not Modified. int HTTP_NO_CONTENT HTTP Status-Code 204: No Content. int HTTP_OK HTTP Status-Code 200: OK. int HTTP_PARTIAL HTTP Status-Code 206: Partial Content. int HTTP_PAYMENT_REQUIRED HTTP Status-Code 402: Payment Required. int HTTP_PRECON_FAILED HTTP Status-Code 412: Precondition Failed. int HTTP_PROXY_AUTH HTTP Status-Code 407: Proxy Authentication Required. int HTTP_REQ_TOO_LONG HTTP Status-Code 414: Request-URI Too Large. int HTTP_RESET HTTP Status-Code 205: Reset Content. int HTTP_SEE_OTHER HTTP Status-Code 303: See Other. int HTTP_SERVER_ERROR This constant was deprecated in API level 15. it is misplaced and shouldn't have existed. int HTTP_UNAUTHORIZED HTTP Status-Code 401: Unauthorized. int HTTP_UNAVAILABLE HTTP Status-Code 503: Service Unavailable. int HTTP_UNSUPPORTED_TYPE HTTP Status-Code 415: Unsupported Media Type. int HTTP_USE_PROXY HTTP Status-Code 305: Use Proxy. int HTTP_VERSION HTTP Status-Code 505: HTTP Version Not Supported. |
| Fields | |
|---|---|
| protectedHostnameVerifier | hostnameVerifier The hostnameVerifier for this object. |
| Inherited fields |
|---|
| From classjava.net.HttpURLConnection protected int chunkLength The chunk-length when using chunked encoding streaming mode for output. protected int fixedContentLength The fixed content-length when using fixed-length streaming mode. protected long fixedContentLengthLong The fixed content-length when using fixed-length streaming mode. protected boolean instanceFollowRedirects If true, the protocol will automatically follow redirects. protectedString method The HTTP method (GET,POST,PUT,etc.). protected int responseCode An int representing the three digit HTTP Status-Code. protectedString responseMessage The HTTP response message. |
| From classjava.net.URLConnection protected boolean allowUserInteraction If true, this URL is being examined in a context in which it makes sense to allow user interactions such as popping up an authentication dialog. protected boolean connected If false, this connection object has not created a communications link to the specified URL. protected boolean doInput This variable is set by the setDoInput method. protected boolean doOutput This variable is set by the setDoOutput method. protected long ifModifiedSince Some protocols support skipping the fetching of the object unless the object has been modified more recently than a certain time. protectedURL url The URL represents the remote object on the World Wide Web to which this connection is opened. protected boolean useCaches If true, the protocol is allowed to use caching whenever it can. |
| Protected constructors |
|---|
| HttpsURLConnection(URL url) Creates an HttpsURLConnection using the URL specified. |
| Public methods | |
|---|---|
| abstractString | getCipherSuite() Returns the cipher suite in use on this connection. |
| staticHostnameVerifier | getDefaultHostnameVerifier() Gets the default HostnameVerifier that is inherited by new instances of this class. |
| staticSSLSocketFactory | getDefaultSSLSocketFactory() Gets the default static SSLSocketFactory that is inherited by new instances of this class. |
| HostnameVerifier | getHostnameVerifier() Gets the HostnameVerifier in place on this instance. |
| abstractCertificate[] | getLocalCertificates() Returns the certificate(s) that were sent to the server during handshaking. |
| Principal | getLocalPrincipal() Returns the principal that was sent to the server during handshaking. |
| Principal | getPeerPrincipal() Returns the server's principal which was established as part of defining the session. |
| SSLSocketFactory | getSSLSocketFactory() Gets the SSL socket factory to be used when creating sockets for secure https URL connections. |
| abstractCertificate[] | getServerCertificates() Returns the server's certificate chain which was established as part of defining the session. |
| static void | setDefaultHostnameVerifier(HostnameVerifier v) Sets the default HostnameVerifier inherited by a new instance of this class. |
| static void | setDefaultSSLSocketFactory(SSLSocketFactory sf) Sets the default SSLSocketFactory inherited by new instances of this class. |
| void | setHostnameVerifier(HostnameVerifier v) Sets the HostnameVerifier for this instance. |
| void | setSSLSocketFactory(SSLSocketFactory sf) Sets the SSLSocketFactory to be used when this instance creates sockets for secure https URL connections. |
| Inherited methods |
|---|
| From class java.net.HttpURLConnection abstract void disconnect() Indicates that other requests to the server are unlikely in the near future. InputStream getErrorStream() Returns the error stream if the connection failed but the server sent useful data nonetheless. static boolean getFollowRedirects() Returns a boolean indicating whether or not HTTP redirects (3xx) should be automatically followed. String getHeaderField(int n) Returns the value for the nth header field. long getHeaderFieldDate(String name, long Default) Returns the value of the named field parsed as date. String getHeaderFieldKey(int n) Returns the key for the nth header field. boolean getInstanceFollowRedirects() Returns the value of this HttpURLConnection'sinstanceFollowRedirects field. Permission getPermission() Returns a SocketPermission object representing the permission necessary to connect to the destination host and port. String getRequestMethod() Get the request method. int getResponseCode() Gets the status code from an HTTP response message. String getResponseMessage() Gets the HTTP response message, if any, returned along with the response code from a server. void setChunkedStreamingMode(int chunklen) This method is used to enable streaming of a HTTP request body without internal buffering, when the content length is not known in advance. void setFixedLengthStreamingMode(int contentLength) This method is used to enable streaming of a HTTP request body without internal buffering, when the content length is known in advance. void setFixedLengthStreamingMode(long contentLength) This method is used to enable streaming of a HTTP request body without internal buffering, when the content length is known in advance. static void setFollowRedirects(boolean set) Sets whether HTTP redirects (requests with response code 3xx) should be automatically followed by this class. void setInstanceFollowRedirects(boolean followRedirects) Sets whether HTTP redirects (requests with response code 3xx) should be automatically followed by this HttpURLConnection instance. void setRequestMethod(String method) Set the method for the URL request, one of: GETPOSTHEADOPTIONSPUTDELETETRACE are legal, subject to protocol restrictions. abstract boolean usingProxy() Indicates if the connection is going through a proxy. |
| From class java.net.URLConnection void addRequestProperty(String key, String value) Adds a general request property specified by a key-value pair. abstract void connect() Opens a communications link to the resource referenced by this URL, if such a connection has not already been established. boolean getAllowUserInteraction() Returns the value of the allowUserInteraction field for this object. int getConnectTimeout() Returns setting for connect timeout. Object getContent() Retrieves the contents of this URL connection. Object getContent(Class[] classes) Retrieves the contents of this URL connection. String getContentEncoding() Returns the value of the content-encoding header field. int getContentLength() Returns the value of the content-length header field. long getContentLengthLong() Returns the value of the content-length header field as a long. String getContentType() Returns the value of the content-type header field. long getDate() Returns the value of the date header field. static boolean getDefaultAllowUserInteraction() Returns the default value of the allowUserInteraction field. staticString getDefaultRequestProperty(String key) This method was deprecated in API level 15. The instance specific getRequestProperty method should be used after an appropriate instance of URLConnection is obtained. boolean getDefaultUseCaches() Returns the default value of a URLConnection'suseCaches flag. boolean getDoInput() Returns the value of this URLConnection'sdoInput flag. boolean getDoOutput() Returns the value of this URLConnection'sdoOutput flag. long getExpiration() Returns the value of the expires header field. staticFileNameMap getFileNameMap() Returns a FileNameMap implementation suitable for guessing a content type based on a URL's "file" component. String getHeaderField(String name) Returns the value of the named header field. String getHeaderField(int n) Returns the value for the nth header field. long getHeaderFieldDate(String name, long Default) Returns the value of the named field parsed as date. int getHeaderFieldInt(String name, int Default) Returns the value of the named field parsed as a number. String getHeaderFieldKey(int n) Returns the key for the nth header field. long getHeaderFieldLong(String name, long Default) Returns the value of the named field parsed as a number. Map<String, List<String>> getHeaderFields() Returns an unmodifiable Map of the header fields. long getIfModifiedSince() Returns the value of this object's ifModifiedSince field. InputStream getInputStream() Returns an input stream that reads from this open connection. long getLastModified() Returns the value of the last-modified header field. OutputStream getOutputStream() Returns an output stream that writes to this connection. Permission getPermission() Returns a permission object representing the permission necessary to make the connection represented by this object. int getReadTimeout() Returns setting for read timeout. Map<String, List<String>> getRequestProperties() Returns an unmodifiable Map of general request properties for this connection. String getRequestProperty(String key) Returns the value of the named general request property for this connection. URL getURL() Returns the value of this URLConnection's URL field. boolean getUseCaches() Returns the value of this URLConnection'suseCaches field. staticString guessContentTypeFromName(String fname) Tries to determine the content type of an object, based on the specified "file" component of a URL. staticString guessContentTypeFromStream(InputStream is) Tries to determine the type of an input stream based on the characters at the beginning of the input stream. void setAllowUserInteraction(boolean allowuserinteraction) Set the value of the allowUserInteraction field of this URLConnection. void setConnectTimeout(int timeout) Sets a specified timeout value, in milliseconds, to be used when opening a communications link to the resource referenced by this URLConnection. static void setContentHandlerFactory(ContentHandlerFactory fac) Sets the ContentHandlerFactory of an application. static void setDefaultAllowUserInteraction(boolean defaultallowuserinteraction) Sets the default value of theallowUserInteraction field for all futureURLConnection objects to the specified value. static void setDefaultRequestProperty(String key, String value) This method was deprecated in API level 15. The instance specific setRequestProperty method should be used after an appropriate instance of URLConnection is obtained. Invoking this method will have no effect. void setDefaultUseCaches(boolean defaultusecaches) Sets the default value of the useCaches field to the specified value. void setDoInput(boolean doinput) Sets the value of the doInput field for thisURLConnection to the specified value. void setDoOutput(boolean dooutput) Sets the value of the doOutput field for thisURLConnection to the specified value. static void setFileNameMap(FileNameMap map) Sets the FileNameMap. void setIfModifiedSince(long ifmodifiedsince) Sets the value of the ifModifiedSince field of this URLConnection to the specified value. void setReadTimeout(int timeout) Sets the read timeout to a specified timeout, in milliseconds. void setRequestProperty(String key, String value) Sets the general request property. void setUseCaches(boolean usecaches) Sets the value of the useCaches field of thisURLConnection to the specified value. String toString() Returns a String representation of this URL connection. |
| From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. finalClass<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted. |
Fields
hostnameVerifier
protected HostnameVerifier hostnameVerifier
The hostnameVerifier for this object.
Protected constructors
HttpsURLConnection
protected HttpsURLConnection (URL url)
Creates an HttpsURLConnection using the URL specified.
| Parameters | |
|---|---|
| url | URL: the URL |
Public methods
getCipherSuite
public abstract String getCipherSuite ()
Returns the cipher suite in use on this connection.
| Returns | |
|---|---|
| String | the cipher suite |
| Throws | |
|---|---|
| IllegalStateException | if this method is called before the connection has been established. |
getDefaultHostnameVerifier
public static HostnameVerifier getDefaultHostnameVerifier ()
Gets the default HostnameVerifier that is inherited by new instances of this class.
| Returns | |
|---|---|
| HostnameVerifier | the default host name verifier |
getDefaultSSLSocketFactory
public static SSLSocketFactory getDefaultSSLSocketFactory ()
Gets the default static SSLSocketFactory that is inherited by new instances of this class.
The socket factories are used when creating sockets for secure https URL connections.
| Returns | |
|---|---|
| SSLSocketFactory | the default SSLSocketFactory |
getHostnameVerifier
public HostnameVerifier getHostnameVerifier ()
Gets the HostnameVerifier in place on this instance.
| Returns | |
|---|---|
| HostnameVerifier | the host name verifier |
getLocalCertificates
public abstract Certificate[] getLocalCertificates ()
Returns the certificate(s) that were sent to the server during handshaking.
Note: This method is useful only when using certificate-based cipher suites.
When multiple certificates are available for use in a handshake, the implementation chooses what it considers the "best" certificate chain available, and transmits that to the other side. This method allows the caller to know which certificate chain was actually sent.
| Returns | |
|---|---|
| Certificate[] | an ordered array of certificates, with the client's own certificate first followed by any certificate authorities. If no certificates were sent, then null is returned. |
| Throws | |
|---|---|
| IllegalStateException | if this method is called before the connection has been established. |
getLocalPrincipal
public Principal getLocalPrincipal ()
Returns the principal that was sent to the server during handshaking.
Note: Subclasses should override this method. If not overridden, it will default to returning the X500Principal of the end-entity certificate that was sent to the server for certificate-based ciphersuites or, return null for non-certificate based ciphersuites, such as Kerberos.
| Returns | |
|---|---|
| Principal | the principal sent to the server. Returns an X500Principal of the end-entity certificate for X509-based cipher suites, and KerberosPrincipal for Kerberos cipher suites. If no principal was sent, then null is returned. |
| Throws | |
|---|---|
| IllegalStateException | if this method is called before the connection has been established. |
getPeerPrincipal
public Principal getPeerPrincipal ()
Returns the server's principal which was established as part of defining the session.
Note: Subclasses should override this method. If not overridden, it will default to returning the X500Principal of the server's end-entity certificate for certificate-based ciphersuites, or throw an SSLPeerUnverifiedException for non-certificate based ciphersuites, such as Kerberos.
| Returns | |
|---|---|
| Principal | the server's principal. Returns an X500Principal of the end-entity certiticate for X509-based cipher suites, and KerberosPrincipal for Kerberos cipher suites. |
| Throws | |
|---|---|
| IllegalStateException | if this method is called before the connection has been established. |
| SSLPeerUnverifiedException | if the peer was not verified |
getSSLSocketFactory
public SSLSocketFactory getSSLSocketFactory ()
Gets the SSL socket factory to be used when creating sockets for secure https URL connections.
| Returns | |
|---|---|
| SSLSocketFactory | the SSLSocketFactory |
getServerCertificates
public abstract Certificate[] getServerCertificates ()
Returns the server's certificate chain which was established as part of defining the session.
Note: This method can be used only when using certificate-based cipher suites; using it with non-certificate-based cipher suites, such as Kerberos, will throw an SSLPeerUnverifiedException.
| Returns | |
|---|---|
| Certificate[] | an ordered array of server certificates, with the peer's own certificate first followed by any certificate authorities. |
| Throws | |
|---|---|
| IllegalStateException | if this method is called before the connection has been established. |
| SSLPeerUnverifiedException | if the peer is not verified. |
setDefaultHostnameVerifier
public static void setDefaultHostnameVerifier (HostnameVerifier v)
Sets the default HostnameVerifier inherited by a new instance of this class.
Developers are strongly discouraged from changing the defaultHostnameVerifier as [getDefaultHostnameVerifier()](/reference/javax/net/ssl/HttpsURLConnection#getDefaultHostnameVerifier%28%29) is used by several classes for hostname verification on Android.
| User | Effect |
|---|---|
| Android's default TrustManager, as used with Android's defaultSSLContext, SSLSocketFactory and SSLSocket implementations. | The HostnameVerifier is used to verify the peer's certificate hostname after connecting if SSLParameters.setEndpointIdentificationAlgorithm("HTTPS") has been called. Instances use the current default HostnameVerifier at verification time. |
| SSLCertificateSocketFactory | The current default HostnameVerifier is used from various createSocket methods. See SSLCertificateSocketFactory for details; for example android.net.SSLCertificateSocketFactory.createSocket(String,int). |
| Android's default HttpsURLConnection implementation. | The HostnameVerifier is used after a successful TLS handshake to verify the URI host against the TLS session server. Instances use the default HostnameVerifier set when they were created unless overridden with setHostnameVerifier(HostnameVerifier). Android's HttpsURLConnection relies on the HostnameVerifier for the entire hostname verification step. |
If this method is not called, the default HostnameVerifier will check the hostname according to RFC 2818.
| Parameters | |
|---|---|
| v | HostnameVerifier: the default host name verifier |
| Throws | |
|---|---|
| IllegalArgumentException | if the HostnameVerifier parameter is null. |
| SecurityException | if a security manager exists and itscheckPermission method does not allowSSLPermission("setHostnameVerifier") |
setDefaultSSLSocketFactory
public static void setDefaultSSLSocketFactory (SSLSocketFactory sf)
Sets the default SSLSocketFactory inherited by new instances of this class.
The socket factories are used when creating sockets for secure https URL connections.
| Parameters | |
|---|---|
| sf | SSLSocketFactory: the default SSL socket factory |
| Throws | |
|---|---|
| IllegalArgumentException | if the SSLSocketFactory parameter is null. |
| SecurityException | if a security manager exists and itscheckSetFactory method does not allow a socket factory to be specified. |
setHostnameVerifier
public void setHostnameVerifier (HostnameVerifier v)
Sets the HostnameVerifier for this instance.
New instances of this class inherit the default static hostname verifier set by [setDefaultHostnameVerifier](/reference/javax/net/ssl/HttpsURLConnection#setDefaultHostnameVerifier%28javax.net.ssl.HostnameVerifier%29). Calls to this method replace this object's HostnameVerifier.
Android's HttpsURLConnection relies on the HostnameVerifier for the entire hostname verification step.
| Parameters | |
|---|---|
| v | HostnameVerifier: the host name verifier |
| Throws | |
|---|---|
| IllegalArgumentException | if the HostnameVerifier parameter is null. |
setSSLSocketFactory
public void setSSLSocketFactory (SSLSocketFactory sf)
Sets the SSLSocketFactory to be used when this instance creates sockets for secure https URL connections.
New instances of this class inherit the default staticSSLSocketFactory set by[setDefaultSSLSocketFactory](/reference/javax/net/ssl/HttpsURLConnection#setDefaultSSLSocketFactory%28javax.net.ssl.SSLSocketFactory%29). Calls to this method replace this object's SSLSocketFactory.
| Parameters | |
|---|---|
| sf | SSLSocketFactory: the SSL socket factory |
| Throws | |
|---|---|
| IllegalArgumentException | if the SSLSocketFactory parameter is null. |
| SecurityException | if a security manager exists and itscheckSetFactory method does not allow a socket factory to be specified. |