com.neovisionaries.ws.client

Class WebSocketFactory

java.lang.Object

com.neovisionaries.ws.client.WebSocketFactory

public class WebSocketFactory
extends Object

Factory to create WebSocket instances.

Constructor Summary

Constructors

Constructor and Description
WebSocketFactory() Constructor.
WebSocketFactory(WebSocketFactory other) Copy constructor.

Method Summary

Modifier and Type	Method and Description
WebSocket	createSocket(String uri) Create a WebSocket.
WebSocket	createSocket(String uri, int timeout) Create a WebSocket.
WebSocket	createSocket(URI uri) Create a WebSocket.
WebSocket	createSocket(URI uri, int timeout) Create a WebSocket.
WebSocket	createSocket(URL url) Create a WebSocket.
WebSocket	createSocket(URL url, int timeout) Create a WebSocket.
int	getConnectionTimeout() Get the timeout value in milliseconds for socket connection.
int	getDualStackFallbackDelay() Get the dual stack fallback delay in milliseconds that will be applied when establishing a socket connection.
DualStackMode	getDualStackMode() Get the dual stack mode that will be applied when establishing a socket connection.
ProxySettings	getProxySettings() Get the proxy settings.
String[]	getServerNames() Get server names for SNI (Server Name Indication).
SocketFactory	getSocketFactory() Get the socket factory that has been set by setSocketFactory(SocketFactory).
int	getSocketTimeout() Get the timeout value in milliseconds for socket read and write operations.
SSLContext	getSSLContext() Get the SSL context that has been set by setSSLContext(SSLContext).
SSLSocketFactory	getSSLSocketFactory() Get the SSL socket factory that has been set by setSSLSocketFactory(SSLSocketFactory).
boolean	getVerifyHostname() Get the flag which indicates whether the hostname in the server's certificate should be verified or not.
WebSocketFactory	setConnectionTimeout(int timeout) Set the timeout value in milliseconds for socket connection.
WebSocketFactory	setDualStackFallbackDelay(int delay) Set the dual stack fallback delay in milliseconds that will be applied when establishing a socket connection.
WebSocketFactory	setDualStackMode(DualStackMode mode) Set the dual stack mode that will be applied when establishing a socket connection.
WebSocketFactory	setServerName(String serverName) Set a server name for SNI (Server Name Indication).
WebSocketFactory	setServerNames(String[] serverNames) Set server names for SNI (Server Name Indication).
WebSocketFactory	setSocketFactory(SocketFactory factory) Set a socket factory.
WebSocketFactory	setSocketTimeout(int timeout) Set the timeout value in milliseconds for socket read and write operations.
WebSocketFactory	setSSLContext(SSLContext context) Set an SSL context to get a socket factory.
WebSocketFactory	setSSLSocketFactory(SSLSocketFactory factory) Set an SSL socket factory.
WebSocketFactory	setVerifyHostname(boolean verifyHostname) Set the flag which indicates whether the hostname in the server's certificate should be verified or not.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WebSocketFactory

public WebSocketFactory()

Constructor.

WebSocketFactory

public WebSocketFactory(WebSocketFactory other)

Copy constructor.

Parameters:

other - A WebSocketFactory instance to copy.

Throws:

IllegalArgumentException - If the given WebSocketFactory instance is null.

Since:

2.10

Method Detail

getSocketFactory

public SocketFactory getSocketFactory()

Get the socket factory that has been set by setSocketFactory(SocketFactory).

Returns:

The socket factory.

setSocketFactory

public WebSocketFactory setSocketFactory(SocketFactory factory)

Set a socket factory. See createSocket(URI) for details.

Parameters:

factory - A socket factory.

Returns:

this instance.

getSSLSocketFactory

public SSLSocketFactory getSSLSocketFactory()

Get the SSL socket factory that has been set by setSSLSocketFactory(SSLSocketFactory).

Returns:

The SSL socket factory.

setSSLSocketFactory

public WebSocketFactory setSSLSocketFactory(SSLSocketFactory factory)

Set an SSL socket factory. See createSocket(URI) for details.

Parameters:

factory - An SSL socket factory.

Returns:

this instance.

getSSLContext

public SSLContext getSSLContext()

Get the SSL context that has been set by setSSLContext(SSLContext).

Returns:

The SSL context.

setSSLContext

public WebSocketFactory setSSLContext(SSLContext context)

Set an SSL context to get a socket factory. See createSocket(URI) for details.

Parameters:

context - An SSL context.

Returns:

this instance.

getProxySettings

public ProxySettings getProxySettings()

Get the proxy settings.

Returns:

The proxy settings.

Since:

1.3

See Also:

ProxySettings

getConnectionTimeout

public int getConnectionTimeout()

Get the timeout value in milliseconds for socket connection. The default value is 0 and it means an infinite timeout.

When a createSocket method which does not have timeout argument is called, the value returned by this method is used as a timeout value for socket connection.

Returns:

The connection timeout value in milliseconds.

Since:

1.10

setConnectionTimeout

public WebSocketFactory setConnectionTimeout(int timeout)

Set the timeout value in milliseconds for socket connection. A timeout of zero is interpreted as an infinite timeout.

Parameters:

timeout - The connection timeout value in milliseconds.

Returns:

this object.

Throws:

IllegalArgumentException - The given timeout value is negative.

Since:

1.10

getSocketTimeout

public int getSocketTimeout()

Get the timeout value in milliseconds for socket read and write operations. The default value is 0 and it means an infinite timeout.

This can be changed later with getSocket().setSoTimeout(int).

Returns:

The socket timeout value in milliseconds.

Since:

2.14

See Also:

Socket.setSoTimeout(int)

setSocketTimeout

public WebSocketFactory setSocketTimeout(int timeout)

Set the timeout value in milliseconds for socket read and write operations. A timeout of zero is interpreted as an infinite timeout.

This can be changed later with getSocket().setSoTimeout(int).

Parameters:

timeout - The socket timeout value in milliseconds.

Returns:

this object.

Throws:

IllegalArgumentException - The given timeout value is negative.

Since:

2.14

See Also:

Socket.setSoTimeout(int)

getDualStackMode

public DualStackMode getDualStackMode()

Get the dual stack mode that will be applied when establishing a socket connection. The default value is DualStackMode.BOTH.

A hostname may resolve to an arbitrary amount of IPv4 and IPv6 addresses. This controls which IP address families will be used when establishing a connection. Note that IPv6 will be preferred, if activated.

Returns:

The dual stack mode.

setDualStackMode

public WebSocketFactory setDualStackMode(DualStackMode mode)

Set the dual stack mode that will be applied when establishing a socket connection.

Parameters:

mode - The dual stack mode to be applied.

Returns:

this object.

getDualStackFallbackDelay

public int getDualStackFallbackDelay()

Get the dual stack fallback delay in milliseconds that will be applied when establishing a socket connection.

A hostname may resolve to an arbitrary amount of IPv4 and IPv6 addresses. This controls the maximum amount of time that may pass between attempts to establish a socket connection to an IP addresses before trying the next one. Note that the previous attempt will not be aborted. The connections will race until one has been established.

Returns:

The dual stack fallback delay in milliseconds.

setDualStackFallbackDelay

public WebSocketFactory setDualStackFallbackDelay(int delay)

Set the dual stack fallback delay in milliseconds that will be applied when establishing a socket connection.

Parameters:

delay - The dual stack fallback delay in milliseconds.

Returns:

this object.

getVerifyHostname

public boolean getVerifyHostname()

Get the flag which indicates whether the hostname in the server's certificate should be verified or not. The default value is true. See the description of setVerifyHostname(boolean) to understand what this boolean flag means.

Returns:

true if hostname verification is enabled.

Since:

2.3

setVerifyHostname

public WebSocketFactory setVerifyHostname(boolean verifyHostname)

Set the flag which indicates whether the hostname in the server's certificate should be verified or not. The default value is true.

Manual hostname verification has been enabled since the version 2.1. Because the verification is executed manually after Socket.connect(SocketAddress, int) succeeds, the hostname verification is always executed even if you has passed an SSLContext which naively accepts any server certificate (e.g. NaiveSSLContext). However, this behavior is not desirable in some cases and you may want to disable the hostname verification. This setter method exists for the purpose and you can disable hostname verification by passing false to this method.

Parameters:

verifyHostname - true to enable hostname verification. false to disable hostname verification.

Returns:

this object.

Since:

2.3

getServerNames

public String[] getServerNames()

Get server names for SNI (Server Name Indication).

Returns:

List of host names.

Since:

2.4

setServerNames

public WebSocketFactory setServerNames(String[] serverNames)

Set server names for SNI (Server Name Indication). If setServerNames(List<SNIServerName>) method of SSLParameters class is available in the underlying system, the method is called to set up server names for SNI (Server Name Indication).

Parameters:

serverNames - List of host names.

Returns:

this object.

Since:

2.4

setServerName

public WebSocketFactory setServerName(String serverName)

Set a server name for SNI (Server Name Indication). This method internally creates a String array of size 1 which contains the given serverName and calls setServerNames(String[]).

Parameters:

serverName - A host name.

Returns:

this object.

Since:

2.4

createSocket

public WebSocket createSocket(String uri)
                       throws IOException

Create a WebSocket.

This method is an alias of createSocket(uri, getConnectionTimeout()).

Parameters:

uri - The URI of the WebSocket endpoint on the server side.

Returns:

A WebSocket.

Throws:

IllegalArgumentException - The given URI is null or violates RFC 2396.

IOException - Failed to create a socket. Or, HTTP proxy handshake or SSL handshake failed.

createSocket

public WebSocket createSocket(String uri,
                              int timeout)
                       throws IOException

Create a WebSocket.

This method is an alias of createSocket(URI.create(uri), timeout).

Parameters:

uri - The URI of the WebSocket endpoint on the server side.

timeout - The timeout value in milliseconds for socket connection. A timeout of zero is interpreted as an infinite timeout.

Returns:

A WebSocket.

Throws:

IllegalArgumentException - The given URI is null or violates RFC 2396, or the given timeout value is negative.

IOException - Failed to create a socket. Or, HTTP proxy handshake or SSL handshake failed.

Since:

1.10

createSocket

public WebSocket createSocket(URL url)
                       throws IOException

Create a WebSocket.

This method is an alias of createSocket(url, getConnectionTimeout()).

Parameters:

url - The URL of the WebSocket endpoint on the server side.

Returns:

A WebSocket.

Throws:

IllegalArgumentException - The given URL is null or failed to be converted into a URI.

IOException - Failed to create a socket. Or, HTTP proxy handshake or SSL handshake failed.

createSocket

public WebSocket createSocket(URL url,
                              int timeout)
                       throws IOException

Create a WebSocket.

This method is an alias of createSocket(url.toURI(), timeout).

Parameters:

url - The URL of the WebSocket endpoint on the server side.

timeout - The timeout value in milliseconds for socket connection.

Returns:

A WebSocket.

Throws:

IllegalArgumentException - The given URL is null or failed to be converted into a URI, or the given timeout value is negative.

IOException - Failed to create a socket. Or, HTTP proxy handshake or SSL handshake failed.

Since:

1.10

createSocket

public WebSocket createSocket(URI uri)
                       throws IOException

Create a WebSocket. This method is an alias of createSocket(uri, getConnectionTimeout()).

A socket factory (= a SocketFactory instance) to create a raw socket (= a Socket instance) is determined as described below.

1. If the scheme of the URI is either wss or https,
   1. If an SSLContext instance has been set by setSSLContext(SSLContext), the value returned from SSLContext.getSocketFactory() method of the instance is used.
   2. Otherwise, if an SSLSocketFactory instance has been set by setSSLSocketFactory(SSLSocketFactory), the instance is used.
   3. Otherwise, the value returned from SSLSocketFactory.getDefault() is used.
2. Otherwise (= the scheme of the URI is either ws or http),
   1. If a SocketFactory instance has been set by setSocketFactory(SocketFactory), the instance is used.
   2. Otherwise, the value returned from SocketFactory.getDefault() is used.

Parameters:

uri - The URI of the WebSocket endpoint on the server side. The scheme part of the URI must be one of ws, wss, http and https (case-insensitive).

Returns:

A WebSocket.

Throws:

IllegalArgumentException - The given URI is null or violates RFC 2396.

IOException - Failed to create a socket.

createSocket

public WebSocket createSocket(URI uri,
                              int timeout)
                       throws IOException

Create a WebSocket.

A socket factory (= a SocketFactory instance) to create a raw socket (= a Socket instance) is determined as described below.

1. If the scheme of the URI is either wss or https,
   1. If an SSLContext instance has been set by setSSLContext(SSLContext), the value returned from SSLContext.getSocketFactory() method of the instance is used.
   2. Otherwise, if an SSLSocketFactory instance has been set by setSSLSocketFactory(SSLSocketFactory), the instance is used.
   3. Otherwise, the value returned from SSLSocketFactory.getDefault() is used.
2. Otherwise (= the scheme of the URI is either ws or http),
   1. If a SocketFactory instance has been set by setSocketFactory(SocketFactory), the instance is used.
   2. Otherwise, the value returned from SocketFactory.getDefault() is used.

Parameters:

uri - The URI of the WebSocket endpoint on the server side. The scheme part of the URI must be one of ws, wss, http and https (case-insensitive).

timeout - The timeout value in milliseconds for socket connection.

Returns:

A WebSocket.

Throws:

IllegalArgumentException - The given URI is null or violates RFC 2396, or the given timeout value is negative.

IOException - Failed to create a socket.

Since:

1.10