public abstract class

HttpsURLConnection

extends HttpURLConnection

java.lang.Object
↳	java.net.URLConnection
	↳	java.net.HttpURLConnection
		↳	javax.net.ssl.HttpsURLConnection

Known Direct Subclasses

HttpsURLConnectionImpl

Class Overview

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.

Summary

[Expand]

Inherited Constants

From class java.net.HttpURLConnection

Fields
protected HostnameVerifier	hostnameVerifier	The `hostnameVerifier` for this object.

[Expand]

Inherited Fields

From class java.net.HttpURLConnection

From class java.net.URLConnection

Protected Constructors
	HttpsURLConnection(URL url) Creates an `HttpsURLConnection` using the URL specified.

Public Methods
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.

[Expand]

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 `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 permission object representing the permission necessary to make the connection represented by this object.
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.
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.
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() Loads filename map (a mimetable) from a data file.
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.
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) 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.
final Class<?>	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() Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.
final void	wait(long timeout, int nanos) Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
final void	wait(long timeout) Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.

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

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

public HostnameVerifier getHostnameVerifier ()

Gets the HostnameVerifier in place on this instance.

Returns

the host name verifier

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.

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.

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.

public SSLSocketFactory getSSLSocketFactory ()

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

Returns

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

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")`

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.

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.

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.

Interfaces

Classes

Enums

Exceptions

HttpsURLConnection

Class Overview

Summary

Fields

protected HostnameVerifier hostnameVerifier

Protected Constructors

protected HttpsURLConnection (URL url)

Parameters

Public Methods

public abstract String getCipherSuite ()

Returns

Throws

public static HostnameVerifier getDefaultHostnameVerifier ()

Returns

See Also

public static SSLSocketFactory getDefaultSSLSocketFactory ()

Returns

See Also

public HostnameVerifier getHostnameVerifier ()

Returns

See Also

public abstract Certificate[] getLocalCertificates ()

Returns

Throws

See Also

public Principal getLocalPrincipal ()

Returns

Throws

See Also

public Principal getPeerPrincipal ()

Returns

Throws

See Also

public SSLSocketFactory getSSLSocketFactory ()

Returns

See Also

public abstract Certificate[] getServerCertificates ()

Returns

Throws

See Also

public static void setDefaultHostnameVerifier (HostnameVerifier v)

Parameters

Throws

See Also

public static void setDefaultSSLSocketFactory (SSLSocketFactory sf)

Parameters

Throws

See Also

public void setHostnameVerifier (HostnameVerifier v)

Parameters

Throws

See Also

public void setSSLSocketFactory (SSLSocketFactory sf)

Parameters

Throws

See Also