JavaTM 2 Platform
Std. Ed. v1.4.0

javax.net.ssl
Class HttpsURLConnection

java.lang.Object
  |
  +--java.net.URLConnection
        |
        +--java.net.HttpURLConnection
              |
              +--javax.net.ssl.HttpsURLConnection

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.

Since:
1.4

Field Summary
protected  HostnameVerifier hostnameVerifier
          The hostnameVerifier for this object.
 
Fields inherited from class java.net.HttpURLConnection
HTTP_ACCEPTED, HTTP_BAD_GATEWAY, HTTP_BAD_METHOD, HTTP_BAD_REQUEST, HTTP_CLIENT_TIMEOUT, HTTP_CONFLICT, HTTP_CREATED, HTTP_ENTITY_TOO_LARGE, HTTP_FORBIDDEN, HTTP_GATEWAY_TIMEOUT, HTTP_GONE, HTTP_INTERNAL_ERROR, HTTP_LENGTH_REQUIRED, HTTP_MOVED_PERM, HTTP_MOVED_TEMP, HTTP_MULT_CHOICE, HTTP_NO_CONTENT, HTTP_NOT_ACCEPTABLE, HTTP_NOT_AUTHORITATIVE, HTTP_NOT_FOUND, HTTP_NOT_IMPLEMENTED, HTTP_NOT_MODIFIED, HTTP_OK, HTTP_PARTIAL, HTTP_PAYMENT_REQUIRED, HTTP_PRECON_FAILED, HTTP_PROXY_AUTH, HTTP_REQ_TOO_LONG, HTTP_RESET, HTTP_SEE_OTHER, HTTP_SERVER_ERROR, HTTP_UNAUTHORIZED, HTTP_UNAVAILABLE, HTTP_UNSUPPORTED_TYPE, HTTP_USE_PROXY, HTTP_VERSION, instanceFollowRedirects, method, responseCode, responseMessage
 
Fields inherited from class java.net.URLConnection
allowUserInteraction, connected, doInput, doOutput, ifModifiedSince, url, useCaches
 
Constructor Summary
protected HttpsURLConnection(URL url)
          Creates an HttpsURLConnection using the URL specified.
 
Method Summary
abstract  String getCipherSuite()
          Returns the cipher suite in use on this connection.
static HostnameVerifier getDefaultHostnameVerifier()
          Gets the default HostnameVerifier that it inherited when an instance of this class is created.
static SSLSocketFactory getDefaultSSLSocketFactory()
          Gets the default static SSL socket factory used when creating sockets for secure https URL connections.
 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.
abstract  Certificate[] getServerCertificates()
          Returns the server's certificate chain 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.
static void setDefaultHostnameVerifier(HostnameVerifier v)
          Sets the default HostnameVerifier inherited when an instance of this class is created.
static void setDefaultSSLSocketFactory(SSLSocketFactory sf)
          Sets the default SSL socket factory inherited when an instance of this class is created.
 void setHostnameVerifier(HostnameVerifier v)
          Sets the HostnameVerifier.
 void setSSLSocketFactory(SSLSocketFactory sf)
          Sets the SSL socket factory to be used when creating sockets for secure https URL connections.
 
Methods inherited from class java.net.HttpURLConnection
disconnect, getErrorStream, getFollowRedirects, getHeaderFieldDate, getInstanceFollowRedirects, getPermission, getRequestMethod, getResponseCode, getResponseMessage, setFollowRedirects, setInstanceFollowRedirects, setRequestMethod, usingProxy
 
Methods inherited from class java.net.URLConnection
addRequestProperty, connect, getAllowUserInteraction, getContent, getContent, getContentEncoding, getContentLength, getContentType, getDate, getDefaultAllowUserInteraction, getDefaultRequestProperty, getDefaultUseCaches, getDoInput, getDoOutput, getExpiration, getFileNameMap, getHeaderField, getHeaderField, getHeaderFieldInt, getHeaderFieldKey, getHeaderFields, getIfModifiedSince, getInputStream, getLastModified, getOutputStream, getRequestProperties, getRequestProperty, getURL, getUseCaches, guessContentTypeFromName, guessContentTypeFromStream, setAllowUserInteraction, setContentHandlerFactory, setDefaultAllowUserInteraction, setDefaultRequestProperty, setDefaultUseCaches, setDoInput, setDoOutput, setFileNameMap, setIfModifiedSince, setRequestProperty, setUseCaches, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

hostnameVerifier

protected HostnameVerifier hostnameVerifier
The hostnameVerifier for this object.

Constructor Detail

HttpsURLConnection

protected HttpsURLConnection(URL url)
                      throws IOException
Creates an HttpsURLConnection using the URL specified.

Parameters:
url - the URL
Throws:
IOException - if the connection can't be established
Method Detail

getCipherSuite

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.

getLocalCertificates

public abstract Certificate[] getLocalCertificates()
Returns the certificate(s) that were sent to the server during handshaking.

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.

getServerCertificates

public abstract Certificate[] getServerCertificates()
                                             throws SSLPeerUnverifiedException
Returns the server's certificate chain which was established as part of defining the session.

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.

setDefaultHostnameVerifier

public static void setDefaultHostnameVerifier(HostnameVerifier v)
Sets the default HostnameVerifier inherited when an instance of this class is created.

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

Parameters:
v - the default host name verifier
Throws:
IllegalArgumentException - if the HostnameVerifier parameter is null.
See Also:
getDefaultHostnameVerifier()

getDefaultHostnameVerifier

public static HostnameVerifier getDefaultHostnameVerifier()
Gets the default HostnameVerifier that it inherited when an instance of this class is created.

Returns:
the default host name verifier
See Also:
setDefaultHostnameVerifier(HostnameVerifier)

setHostnameVerifier

public void setHostnameVerifier(HostnameVerifier v)
Sets the HostnameVerifier.

When called on a new instance of this class, this method overrides the default static hostname verifier set by setDefaultHostnameVerifier.

Parameters:
v - the host name verifier
Throws:
IllegalArgumentException - if the HostnameVerifier parameter is null.
See Also:
getHostnameVerifier(), setDefaultHostnameVerifier(HostnameVerifier)

getHostnameVerifier

public HostnameVerifier getHostnameVerifier()
Gets the HostnameVerifier in place on this instance.

Returns:
the host name verifier
See Also:
setHostnameVerifier(HostnameVerifier), setDefaultHostnameVerifier(HostnameVerifier)

setDefaultSSLSocketFactory

public static void setDefaultSSLSocketFactory(SSLSocketFactory sf)
Sets the default SSL socket factory inherited when an instance of this class is created.

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.
See Also:
getDefaultSSLSocketFactory()

getDefaultSSLSocketFactory

public static SSLSocketFactory getDefaultSSLSocketFactory()
Gets the default static SSL socket factory used when creating sockets for secure https URL connections.

Returns:
the default SSLSocketFactory
See Also:
setDefaultSSLSocketFactory(SSLSocketFactory)

setSSLSocketFactory

public void setSSLSocketFactory(SSLSocketFactory sf)
Sets the SSL socket factory to be used when creating sockets for secure https URL connections.

If called on a new instance of this class, this method overrides the default static socket factory set by setDefaultSSLSocketFactory.

Parameters:
sf - the SSL socket factory
Throws:
IllegalArgumentException - if the SSLSocketFactory parameter is null.
See Also:
getSSLSocketFactory()

getSSLSocketFactory

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)

JavaTM 2 Platform
Std. Ed. v1.4.0

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.