HttpsURLConnection

AI-generated Key Takeaways

• HttpsURLConnection extends HttpURLConnection to provide HTTPS-specific features, such as secure connections via HostnameVerifier and SSLSocketFactory.

• It supports server hostname verification against the certificate through HostnameVerifier and secure socket creation using SSLSocketFactory.

• Default implementations for HostnameVerifier and SSLSocketFactory are provided, with options to customize them globally or per instance.

• HttpsURLConnection inherits various constants, fields, and methods from HttpURLConnection and URLConnection, including HTTP status codes and request/response handling.

• It offers specific methods to manage secure connections, such as retrieving the cipher suite, managing certificates, and handling SSL socket factories, as well as methods inherited from HttpURLConnection for general HTTP handling.

public abstract class HttpsURLConnection extends 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 and SSLSocketFactory. 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) before connecting.

Inherited Constant Summary

From class java.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 is deprecated. 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.

Field Summary

protected HostnameVerifier

hostnameVerifier

The hostnameVerifier for this object.

Inherited Field Summary

From class java.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.
protected String	method	The HTTP method (GET,POST,PUT,etc.).
protected int	responseCode	An int representing the three digit HTTP Status-Code.
protected String	responseMessage	The HTTP response message.

From class java.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.
protected URL	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 Constructor Summary

HttpsURLConnection(URL url) Creates an HttpsURLConnection using the URL specified.

Public Method Summary

abstract String	getCipherSuite() Returns the cipher suite in use on this connection.
static HostnameVerifier	getDefaultHostnameVerifier() Gets the default HostnameVerifier that is inherited by new instances of this class.
static SSLSocketFactory	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.
abstract Certificate[]	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.
abstract Certificate[]	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 Method Summary

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 n^th 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 n^th header field.
boolean	getInstanceFollowRedirects() Returns the value of this HttpURLConnection's instanceFollowRedirects 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: GET POST HEAD OPTIONS PUT DELETE TRACE 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.
static String	getDefaultRequestProperty(String key) This method is deprecated. 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's useCaches flag.
boolean	getDoInput() Returns the value of this URLConnection's doInput flag.
boolean	getDoOutput() Returns the value of this URLConnection's doOutput flag.
long	getExpiration() Returns the value of the expires header field.
synchronized static FileNameMap	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 n^th 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 n^th 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's useCaches field.
static String	guessContentTypeFromName(String fname) Tries to determine the content type of an object, based on the specified "file" component of a URL.
static String	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.
synchronized static void	setContentHandlerFactory(ContentHandlerFactory fac) Sets the ContentHandlerFactory of an application.
static void	setDefaultAllowUserInteraction(boolean defaultallowuserinteraction) Sets the default value of the allowUserInteraction field for all future URLConnection objects to the specified value.
static void	setDefaultRequestProperty(String key, String value) This method is deprecated. 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 this URLConnection to the specified value.
void	setDoOutput(boolean dooutput) Sets the value of the doOutput field for this URLConnection 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 this URLConnection 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) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
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(long timeout, 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 timeout) 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() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object.

Fields

protected HostnameVerifier hostnameVerifier

The hostnameVerifier for this object.

Protected Constructors

protected HttpsURLConnection (URL url)

Creates an HttpsURLConnection using the URL specified.

Parameters

url	the URL

Public Methods

public abstract String getCipherSuite ()

Returns the cipher suite in use on this connection.

Returns

• the cipher suite

Throws

IllegalStateException	if this method is called before the connection has been established.

public static HostnameVerifier getDefaultHostnameVerifier ()

Gets the default HostnameVerifier that is inherited by new instances of this class.

Returns

• the default host name verifier

See Also

• setDefaultHostnameVerifier(HostnameVerifier)

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

• the default SSLSocketFactory

See Also

• setDefaultSSLSocketFactory(SSLSocketFactory)

public HostnameVerifier getHostnameVerifier ()

Gets the HostnameVerifier in place on this instance.

Returns

• the host name verifier

See Also

• setHostnameVerifier(HostnameVerifier)
• setDefaultHostnameVerifier(HostnameVerifier)

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

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

See Also

• 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

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

See Also

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

• the server's principal. Returns an X500Principal of the end-entity certiticate for X509-based cipher suites, and KerberosPrincipal for Kerberos cipher suites.

Throws

SSLPeerUnverifiedException	if the peer was not verified
IllegalStateException	if this method is called before the connection has been established.

See Also

• getServerCertificates()
• getLocalPrincipal()

public SSLSocketFactory getSSLSocketFactory ()

Gets the SSL socket factory to be used when creating sockets for secure https URL connections.

Returns

• the SSLSocketFactory

See Also

• setSSLSocketFactory(SSLSocketFactory)

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

• an ordered array of server certificates, with the peer's own certificate first followed by any certificate authorities.

Throws

SSLPeerUnverifiedException	if the peer is not verified.
IllegalStateException	if this method is called before the connection has been established.

See Also

• getPeerPrincipal()

public static void setDefaultHostnameVerifier (HostnameVerifier v)

Sets the default HostnameVerifier inherited by a new instance of this class.

If this method is not called, the default HostnameVerifier assumes the connection should not be permitted.

Parameters

v	the default host name verifier

Throws

IllegalArgumentException	if the HostnameVerifier parameter is null.
SecurityException	if a security manager exists and its checkPermission method does not allow SSLPermission("setHostnameVerifier")

See Also

• getDefaultHostnameVerifier()

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	the default SSL socket factory

Throws

IllegalArgumentException	if the SSLSocketFactory parameter is null.
SecurityException	if a security manager exists and its checkSetFactory method does not allow a socket factory to be specified.

See Also

• getDefaultSSLSocketFactory()

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. Calls to this method replace this object's HostnameVerifier.

Parameters

v	the host name verifier

Throws

IllegalArgumentException	if the HostnameVerifier parameter is null.

See Also

• getHostnameVerifier()
• setDefaultHostnameVerifier(HostnameVerifier)

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 static SSLSocketFactory set by setDefaultSSLSocketFactory. Calls to this method replace this object's SSLSocketFactory.

Parameters

sf	the SSL socket factory

Throws

IllegalArgumentException	if the SSLSocketFactory parameter is null.

See Also

• getSSLSocketFactory()