Summary: Protected Ctors | Methods | Inherited Methods | [Expand All]

public abstract class

SSLSocket

extends Socket

java.lang.Object
↳	java.net.Socket
	↳	javax.net.ssl.SSLSocket

Class Overview

The extension of Socket providing secure protocols like SSL (Secure Socket Layer") or TLS (Transport Layer Security).

Summary

Protected Constructors
	SSLSocket() Only to be used by subclasses.
	SSLSocket(String host, int port) Only to be used by subclasses.
	SSLSocket(InetAddress address, int port) Only to be used by subclasses.
	SSLSocket(String host, int port, InetAddress clientAddress, int clientPort) Only to be used by subclasses.
	SSLSocket(InetAddress address, int port, InetAddress clientAddress, int clientPort) Only to be used by subclasses.

Public Methods
abstract void	addHandshakeCompletedListener(HandshakeCompletedListener listener) Registers the specified listener to receive notification on completion of a handshake on this connection.
abstract boolean	getEnableSessionCreation() Returns whether new SSL sessions may be created by this socket or if existing sessions must be reused.
abstract String[]	getEnabledCipherSuites() Returns the names of the enabled cipher suites.
abstract String[]	getEnabledProtocols() Returns the names of the enabled protocols.
abstract boolean	getNeedClientAuth() Returns true if the server socket should require client authentication.
SSLParameters	getSSLParameters() Returns a new SSLParameters based on this SSLSocket's current cipher suites, protocols, and client authentication settings.
abstract SSLSession	getSession() Returns the `SSLSession` for this connection.
abstract String[]	getSupportedCipherSuites() Returns the names of the supported cipher suites.
abstract String[]	getSupportedProtocols() Returns the names of the supported protocols.
abstract boolean	getUseClientMode() Returns true if this connection will act in client mode when handshaking.
abstract boolean	getWantClientAuth() Returns true if the server should request client authentication.
abstract void	removeHandshakeCompletedListener(HandshakeCompletedListener listener) Removes the specified handshake completion listener.
abstract void	setEnableSessionCreation(boolean flag) Sets whether new SSL sessions may be created by this socket or if existing sessions must be reused.
abstract void	setEnabledCipherSuites(String[] suites) Sets the names of the cipher suites to be enabled.
abstract void	setEnabledProtocols(String[] protocols) Sets the names of the protocols to be enabled.
abstract void	setNeedClientAuth(boolean need) Sets whether the server should require client authentication.
void	setSSLParameters(SSLParameters p) Sets various SSL handshake parameters based on the SSLParameter argument.
abstract void	setUseClientMode(boolean mode) Sets whether this connection should act in client mode when handshaking.
abstract void	setWantClientAuth(boolean want) Sets whether the server should request client authentication.
void	shutdownInput() Unsupported for SSL because reading from an SSL socket may require writing to the network.
void	shutdownOutput() Unsupported for SSL because writing to an SSL socket may require reading from the network.
abstract void	startHandshake() Starts a new SSL handshake on this connection.

[Expand]

Inherited Methods

From class java.net.Socket

void	bind(SocketAddress localAddr) Binds this socket to the given local host address and port specified by the SocketAddress `localAddr`.
synchronized void	close() Closes the socket.
void	connect(SocketAddress remoteAddr, int timeout) Connects this socket to the given remote host address and port specified by the SocketAddress `remoteAddr` with the specified timeout.
void	connect(SocketAddress remoteAddr) Connects this socket to the given remote host address and port specified by the SocketAddress `remoteAddr`.
SocketChannel	getChannel() Returns this socket's `SocketChannel`, if one exists.
InetAddress	getInetAddress() Returns the IP address of the target host this socket is connected to, or null if this socket is not yet connected.
InputStream	getInputStream() Returns an input stream to read data from this socket.
boolean	getKeepAlive() Returns this socket's `SO_KEEPALIVE` setting.
InetAddress	getLocalAddress() Returns the local IP address this socket is bound to, or `InetAddress.ANY` if the socket is unbound.
int	getLocalPort() Returns the local port this socket is bound to, or -1 if the socket is unbound.
SocketAddress	getLocalSocketAddress() Returns the local address and port of this socket as a SocketAddress or null if the socket is unbound.
boolean	getOOBInline() Returns this socket's `SO_OOBINLINE` setting.
OutputStream	getOutputStream() Returns an output stream to write data into this socket.
int	getPort() Returns the port number of the target host this socket is connected to, or 0 if this socket is not yet connected.
synchronized int	getReceiveBufferSize() Returns this socket's `receive buffer size`.
SocketAddress	getRemoteSocketAddress() Returns the remote address and port of this socket as a `SocketAddress` or null if the socket is not connected.
boolean	getReuseAddress() Returns this socket's `SO_REUSEADDR` setting.
synchronized int	getSendBufferSize() Returns this socket's `send buffer size`.
int	getSoLinger() Returns this socket's `linger` timeout in seconds, or -1 for no linger (i.e.
synchronized int	getSoTimeout() Returns this socket's `receive timeout`.
boolean	getTcpNoDelay() Returns this socket's `SocketOptions#TCP_NODELAY` setting.
int	getTrafficClass() Returns this socket's setting.
boolean	isBound() Returns whether this socket is bound to a local address and port.
boolean	isClosed() Returns whether this socket is closed.
boolean	isConnected() Returns whether this socket is connected to a remote host.
boolean	isInputShutdown() Returns whether the incoming channel of the socket has already been closed.
boolean	isOutputShutdown() Returns whether the outgoing channel of the socket has already been closed.
void	sendUrgentData(int value) Sends the given single byte data which is represented by the lowest octet of `value` as "TCP urgent data".
void	setKeepAlive(boolean keepAlive) Sets this socket's `SO_KEEPALIVE` option.
void	setOOBInline(boolean oobinline) Sets this socket's `SO_OOBINLINE` option.
void	setPerformancePreferences(int connectionTime, int latency, int bandwidth) Sets performance preferences for connectionTime, latency and bandwidth.
synchronized void	setReceiveBufferSize(int size) Sets this socket's `receive buffer size`.
void	setReuseAddress(boolean reuse) Sets this socket's `SO_REUSEADDR` option.
synchronized void	setSendBufferSize(int size) Sets this socket's `send buffer size`.
void	setSoLinger(boolean on, int timeout) Sets this socket's `linger` timeout in seconds.
synchronized void	setSoTimeout(int timeout) Sets this socket's `read timeout` in milliseconds.
synchronized static void	setSocketImplFactory(SocketImplFactory fac) Sets the internal factory for creating socket implementations.
void	setTcpNoDelay(boolean on) Sets this socket's `TCP_NODELAY` option.
void	setTrafficClass(int value) Sets this socket's `IP_TOS` value for every packet sent by this socket.
void	shutdownInput() Closes the input stream of this socket.
void	shutdownOutput() Closes the output stream of this socket.
String	toString() Returns a `String` containing a concise, human-readable description of the socket.

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() 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() 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.

Protected Constructors

protected SSLSocket ()

Since: API Level 1

Only to be used by subclasses.

Creates a TCP socket.

protected SSLSocket (String host, int port)

Since: API Level 1

Only to be used by subclasses.

Creates a TCP socket connection to the specified host at the specified port.

Parameters

host	the host name to connect to.
port	the port number to connect to.

Throws

IOException	if creating the socket fails.
UnknownHostException	if the specified host is not known.

protected SSLSocket (InetAddress address, int port)

Since: API Level 1

Only to be used by subclasses.

Creates a TCP socket connection to the specified address at the specified port.

Parameters

address	the address to connect to.
port	the port number to connect to.

Throws

IOException	if creating the socket fails.

protected SSLSocket (String host, int port, InetAddress clientAddress, int clientPort)

Since: API Level 1

Only to be used by subclasses.

Creates a TCP socket connection to the specified host at the specified port with the client side bound to the specified address and port.

Parameters

host	the host name to connect to.
port	the port number to connect to.
clientAddress	the client address to bind to
clientPort	the client port number to bind to.

Throws

IOException	if creating the socket fails.
UnknownHostException	if the specified host is not known.

protected SSLSocket (InetAddress address, int port, InetAddress clientAddress, int clientPort)

Since: API Level 1

Only to be used by subclasses.

Creates a TCP socket connection to the specified address at the specified port with the client side bound to the specified address and port.

Parameters

address	the address to connect to.
port	the port number to connect to.
clientAddress	the client address to bind to.
clientPort	the client port number to bind to.

Throws

IOException	if creating the socket fails.

Public Methods

public abstract void addHandshakeCompletedListener (HandshakeCompletedListener listener)

Since: API Level 1

Registers the specified listener to receive notification on completion of a handshake on this connection.

Parameters

listener	the listener to register.

Throws

IllegalArgumentException	if `listener` is `null`.

public abstract boolean getEnableSessionCreation ()

Since: API Level 1

Returns whether new SSL sessions may be created by this socket or if existing sessions must be reused.

Returns

true if new sessions may be created, otherwise false.

public abstract String[] getEnabledCipherSuites ()

Since: API Level 1

Returns the names of the enabled cipher suites.

public abstract String[] getEnabledProtocols ()

Since: API Level 1

Returns the names of the enabled protocols.

public abstract boolean getNeedClientAuth ()

Since: API Level 1

Returns true if the server socket should require client authentication. This does not apply to sockets in client mode.

public SSLParameters getSSLParameters ()

Since: API Level 9

Returns a new SSLParameters based on this SSLSocket's current cipher suites, protocols, and client authentication settings.

public abstract SSLSession getSession ()

Since: API Level 1

Returns the SSLSession for this connection. If necessary, a handshake will be initiated, in which case this method will block until the handshake has been established. If the handshake fails, an invalid session object will be returned.

Returns

the session object.

public abstract String[] getSupportedCipherSuites ()

Since: API Level 1

Returns the names of the supported cipher suites.

public abstract String[] getSupportedProtocols ()

Since: API Level 1

Returns the names of the supported protocols.

public abstract boolean getUseClientMode ()

Since: API Level 1

Returns true if this connection will act in client mode when handshaking.

public abstract boolean getWantClientAuth ()

Since: API Level 1

Returns true if the server should request client authentication. This does not apply to sockets in client mode.

public abstract void removeHandshakeCompletedListener (HandshakeCompletedListener listener)

Since: API Level 1

Removes the specified handshake completion listener.

Parameters

listener	the listener to remove.

Throws

IllegalArgumentException	if the specified listener is not registered or `null`.

public abstract void setEnableSessionCreation (boolean flag)

Since: API Level 1

Sets whether new SSL sessions may be created by this socket or if existing sessions must be reused. If flag is false and there are no sessions to resume, handshaking will fail.

Parameters

flag	`true` if new sessions may be created.

public abstract void setEnabledCipherSuites (String[] suites)

Since: API Level 1

Sets the names of the cipher suites to be enabled. Only cipher suites returned by getSupportedCipherSuites() are allowed.

Parameters

suites	the names of the to be enabled cipher suites.

Throws

IllegalArgumentException	if one of the cipher suite names is not supported.

public abstract void setEnabledProtocols (String[] protocols)

Since: API Level 1

Sets the names of the protocols to be enabled. Only protocols returned by getSupportedProtocols() are allowed.

Parameters

protocols	the names of the to be enabled protocols.

Throws

IllegalArgumentException	if one of the protocols is not supported.

public abstract void setNeedClientAuth (boolean need)

Since: API Level 1

Sets whether the server should require client authentication. This does not apply to sockets in client mode. Client authentication is one of the following:

authentication required
authentication requested
no authentication needed

This method overrides the setting of setWantClientAuth(boolean).

public void setSSLParameters (SSLParameters p)

Since: API Level 9

Sets various SSL handshake parameters based on the SSLParameter argument. Specifically, sets the SSLSocket's enabled cipher suites if the parameter's cipher suites are non-null. Similarly sets the enabled protocols. If the parameters specify the want or need for client authentication, those requirements are set on the SSLSocket, otherwise both are set to false.

public abstract void setUseClientMode (boolean mode)

Since: API Level 1

Sets whether this connection should act in client mode when handshaking.

Parameters

mode	`true` if this connection should act in client mode, `false` if not.

public abstract void setWantClientAuth (boolean want)

Since: API Level 1

Sets whether the server should request client authentication. Unlike setNeedClientAuth(boolean) this won't stop the negotiation if the client doesn't authenticate. This does not apply to sockets in client mode.The client authentication is one of:

authentication required
authentication requested
no authentication needed

This method overrides the setting of setNeedClientAuth(boolean).

public void shutdownInput ()

Since: API Level 1

Unsupported for SSL because reading from an SSL socket may require writing to the network.

Throws

IOException

public void shutdownOutput ()

Since: API Level 1

Unsupported for SSL because writing to an SSL socket may require reading from the network.

Throws

IOException

public abstract void startHandshake ()

Since: API Level 1

Starts a new SSL handshake on this connection.

Throws

IOException	if an error occurs.

Interfaces

Classes

Enums

Exceptions

SSLSocket

Class Overview

Summary

Protected Constructors

protected SSLSocket ()

protected SSLSocket (String host, int port)

Parameters

Throws

protected SSLSocket (InetAddress address, int port)

Parameters

Throws

protected SSLSocket (String host, int port, InetAddress clientAddress, int clientPort)

Parameters

Throws

protected SSLSocket (InetAddress address, int port, InetAddress clientAddress, int clientPort)

Parameters

Throws

Public Methods

public abstract void addHandshakeCompletedListener (HandshakeCompletedListener listener)

Parameters

Throws

public abstract boolean getEnableSessionCreation ()

Returns

public abstract String[] getEnabledCipherSuites ()

public abstract String[] getEnabledProtocols ()

public abstract boolean getNeedClientAuth ()

public SSLParameters getSSLParameters ()

public abstract SSLSession getSession ()

Returns

public abstract String[] getSupportedCipherSuites ()

public abstract String[] getSupportedProtocols ()

public abstract boolean getUseClientMode ()

public abstract boolean getWantClientAuth ()

public abstract void removeHandshakeCompletedListener (HandshakeCompletedListener listener)

Parameters

Throws

public abstract void setEnableSessionCreation (boolean flag)

Parameters

public abstract void setEnabledCipherSuites (String[] suites)

Parameters

Throws

public abstract void setEnabledProtocols (String[] protocols)

Parameters

Throws

public abstract void setNeedClientAuth (boolean need)

public void setSSLParameters (SSLParameters p)

public abstract void setUseClientMode (boolean mode)

Parameters

public abstract void setWantClientAuth (boolean want)

public void shutdownInput ()

Throws

public void shutdownOutput ()

Throws

public abstract void startHandshake ()

Throws