com.dkfqs.tools.websocket

Class WebSocketClient

java.lang.Object

com.dkfqs.tools.websocket.WebSocketClient

public class WebSocketClient
extends java.lang.Object

A powerful WebSocket client that supports the measurement of extended performance data to address server bottlenecks.

Response times (performance data) are measured about:

• Opening the WebSocket connection to the server (TCP/IP connect time, SSL handshake time, HTTP request time, HTTP response time).
• TCP/IP processing times for sending and receiving text frames.
• TCP/IP processing times for sending and receiving binary frames.
• TCP/IP processing times for sending and receiving ping frames.
• TCP/IP processing times for sending and receiving pong frames.

Overall summary counters (performance data) are measured at realtime about:

• The total number of sent frames
• The total sum of sent bytes - overall sent frames
• The total sum of sent payloads (in bytes) - overall sent frames
• The total number of received frames
• The total sum of received bytes - overall received frames
• The total sum of received payloads (in bytes) - overall received frames

In addition, the WebSocket client supports to monitor at realtime the number of pending frames which are awaiting to be send to the server (send frame backlog).

The WebSocket client supports to set, or rather to override, the following timeouts:

• Opening the WebSocket connection to the server timeout.
• Sending a WebSocket frame to the server timeout - report an error and close the WebSocket connection if the send timeout is exceeded.

In case if the opening a WebSocket connection to the server fails, detail error information is provided at which internal protocol level the failure has occurred.

Note for encrypted wss connections: The verification of the SSL server certificate is disabled by default. Therefore this client is also able to connect to servers which contain invalid or untrusted certificates. To override this behavior, you can set an own trust managers by using the method setTrustManagers(TrustManager[]).

Other features:

• TLS Authentication with a client certificate is supported (for example by using a certificate in PKCS#12 file-format)
• Sending WebSocket frames by using multiple threads is supported.

See Also:

DEFAULT_CONNECT_TIMEOUT_MILLIS, DEFAULT_FRAME_SEND_TIMEOUT_MILLIS, setTLSClientAuthenticationKeyManagers(KeyManager[]), setTrustManagers(TrustManager[])

Field Summary

Fields

Modifier and Type	Field and Description
static int	CONNECT_STEP_CLOSED WebSocket internal state: Previously opened websocket now closed.
static int	CONNECT_STEP_HTTP_RECEIVE_UPGRADE_RESPONSE WebSocket internal state: Receiving the HTTP upgrade response from server.
static int	CONNECT_STEP_HTTP_SEND_UPGRADE_REQUEST WebSocket internal state: Sending the HTTP upgrade request to server.
static int	CONNECT_STEP_HTTP_VERIFY_UPGRADE_RESPONSE WebSocket internal state: Verifying the HTTP upgrade server response.
static int	CONNECT_STEP_NO_STEP WebSocket internal state: The connect() method was not called.
static int	CONNECT_STEP_OPEN WebSocket internal state: WebSocket open to server.
static int	CONNECT_STEP_PREPARE WebSocket internal state: Preparing the connection to server.
static int	CONNECT_STEP_SSL_HANDSHAKE WebSocket internal state: Performing the SSL handshake with server.
static int	CONNECT_STEP_TCP_CONNECT WebSocket internal state: Establishing the TCP/IP connection to server
static int	DEFAULT_CONNECT_TIMEOUT_MILLIS The default value for the socket connect timeout in milliseconds.
static long	DEFAULT_FRAME_SEND_TIMEOUT_MILLIS The default value for the frame send timeout in milliseconds.
static java.lang.String	DEFAULT_TLS_PROTOCOL_VERSION The default TLS protocol version for encrypted wss connections.
static java.lang.String	PROTOCOL_WS The unencrypted 'ws' protocol.
static java.lang.String	PROTOCOL_WSS The encrypted 'wss' protocol.

Constructor Summary

Constructors

Constructor and Description
WebSocketClient(java.lang.String serverHost, int serverPort, java.lang.String urlPath, WebSocketClientListenerInterface clientListener) Create a new, unconnected WebSocket client.

Method Summary

Modifier and Type	Method and Description
void	addHttpBasicAuthentication(java.lang.String username, java.lang.String password) Add HTTP Basic Authentication credentials to the WebSocket upgrade request.
void	addHttpCookie(java.lang.String cookieName, java.lang.String cookieValue) Add a HTTP cookie to the WebSocket upgrade request.
void	addHttpHeaderField(java.lang.String httpHeaderField) Add an additional HTTP header field to the WebSocket upgrade request.
WebSocketClientContext	connect() Connect the WebSocket to the server.
static java.lang.String	currentConnectStepToString(int connectStep) Get the text representation of the current internal state of the WebSocket connection.
void	disconnect() Disconnect the WebSocket from the server without sending a close frame and free all internal resources.
void	disconnect(long serverConfirmCloseMillis) Disconnect the WebSocket from the server and free all internal resources.
int	getConnectTimeoutMillis() Get the value for the socket connect timeout.
int	getCurrentConnectStep() Get the current internal state of the WebSocket connection - which provides additional information if establishing a WebSocket connection to the server fails.
long	getFrameSendTimeoutMillis() Get the value for the frame send timeout.
long	getHttpUpgradeRequestTime() Get the HTTP upgrade request send time, inclusive flushing the HTTP request at network level.
long	getHttpUpgradeResponseTime() Get the HTTP upgrade response receive time, started after the HTTP upgrade request was send and flushed, until the complete HTTP response header ws received.
long	getNumberOfPendingFramesToSend() Get the number of currently pending frames to send (performance data).
java.lang.String	getProtocol() Get the protocol (ws or wss).
java.util.ArrayList<java.lang.String>	getRequestHeader() Get the list of the HTTP upgrade request header fields.
java.util.ArrayList<java.lang.String>	getResponseHeader() Get the list of the HTTP upgrade response header fields.
long	getSslHandshakeTime() Get the SSL handshake time to the server (after the TCP/IP connection was established).
long	getTcpIpConnectTime() Get the TCP/IP connect time for opening the network connection to the server.
javax.net.ssl.KeyManager[]	getTLSClientAuthenticationKeyManagers() Get the TLS client authentication credential (derived from a client certificate).
java.lang.String	getTLSProtocolVersion() Get the TLS protocol version (which is used for encrypted wss connections only).
long	getTotalBytesReceived() Get the total number of bytes which has received till now - overall frames (performance data).
long	getTotalBytesSent() Get the total number of bytes which has sent till now - overall frames (performance data).
long	getTotalFramesReceived() Get the total number of frames which has received till now (performance data).
long	getTotalFramesSent() Get the total number of frames which has sent till now (performance data).
long	getTotalPayloadReceived() Get the total sum of payload in bytes which has received till now - overall frames (performance data).
long	getTotalPayloadSent() Get the total sum of payload in bytes which has sent till now - overall frames (performance data).
long	getWebSocketOpenTime() Get the total time used to open the WebSocket to the server.
void	printDebug(java.lang.String message) Print debug information to stdout.
void	setConnectTimeoutMillis(int connectTimeoutMillis) Override the default value for the socket connect timeout.
void	setDebugToStdout() Enable that debug information is written to stdout.
void	setFrameSendTimeoutMillis(long frameSendTimeoutMillis) Override the default value for the frame send timeout.
void	setHttpOrigin(java.lang.String httpOrigin) Set the value of the HTTP origin header field.
void	setProtocol(java.lang.String protocol) Set the protocol (ws or wss).
void	setTLSClientAuthenticationKeyManagers(javax.net.ssl.KeyManager[] tlsClientAuthenticationKeyManagers) Set a TLS client authentication credential (derived from a client certificate).
void	setTLSProtocolVersion(java.lang.String tlsProtocolVersion) Override the default value for the TLS protocol version (which is used for encrypted wss connections only).
void	setTrustManagers(javax.net.ssl.TrustManager[] trustManagers) Set a specific trust manager for the TLS (wss) protocol.

Methods inherited from class java.lang.Object

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

Field Detail

PROTOCOL_WS

public static final java.lang.String PROTOCOL_WS

The unencrypted 'ws' protocol.

See Also:

Constant Field Values

PROTOCOL_WSS

public static final java.lang.String PROTOCOL_WSS

The encrypted 'wss' protocol.

See Also:

Constant Field Values

CONNECT_STEP_NO_STEP

public static final int CONNECT_STEP_NO_STEP

WebSocket internal state: The connect() method was not called.

See Also:

connect(), Constant Field Values

CONNECT_STEP_PREPARE

public static final int CONNECT_STEP_PREPARE

WebSocket internal state: Preparing the connection to server.

See Also:

Constant Field Values

CONNECT_STEP_TCP_CONNECT

public static final int CONNECT_STEP_TCP_CONNECT

WebSocket internal state: Establishing the TCP/IP connection to server

See Also:

Constant Field Values

CONNECT_STEP_SSL_HANDSHAKE

public static final int CONNECT_STEP_SSL_HANDSHAKE

WebSocket internal state: Performing the SSL handshake with server.

See Also:

Constant Field Values

CONNECT_STEP_HTTP_SEND_UPGRADE_REQUEST

public static final int CONNECT_STEP_HTTP_SEND_UPGRADE_REQUEST

WebSocket internal state: Sending the HTTP upgrade request to server.

See Also:

Constant Field Values

CONNECT_STEP_HTTP_RECEIVE_UPGRADE_RESPONSE

public static final int CONNECT_STEP_HTTP_RECEIVE_UPGRADE_RESPONSE

WebSocket internal state: Receiving the HTTP upgrade response from server.

See Also:

Constant Field Values

CONNECT_STEP_HTTP_VERIFY_UPGRADE_RESPONSE

public static final int CONNECT_STEP_HTTP_VERIFY_UPGRADE_RESPONSE

WebSocket internal state: Verifying the HTTP upgrade server response.

See Also:

Constant Field Values

CONNECT_STEP_OPEN

public static final int CONNECT_STEP_OPEN

WebSocket internal state: WebSocket open to server.

See Also:

Constant Field Values

CONNECT_STEP_CLOSED

public static final int CONNECT_STEP_CLOSED

WebSocket internal state: Previously opened websocket now closed.

See Also:

Constant Field Values

DEFAULT_TLS_PROTOCOL_VERSION

public static final java.lang.String DEFAULT_TLS_PROTOCOL_VERSION

The default TLS protocol version for encrypted wss connections.

See Also:

Constant Field Values

DEFAULT_CONNECT_TIMEOUT_MILLIS

public static final int DEFAULT_CONNECT_TIMEOUT_MILLIS

The default value for the socket connect timeout in milliseconds.

See Also:

Constant Field Values

DEFAULT_FRAME_SEND_TIMEOUT_MILLIS

public static final long DEFAULT_FRAME_SEND_TIMEOUT_MILLIS

The default value for the frame send timeout in milliseconds.

See Also:

Constant Field Values

Constructor Detail

WebSocketClient

public WebSocketClient(java.lang.String serverHost,
                       int serverPort,
                       java.lang.String urlPath,
                       WebSocketClientListenerInterface clientListener)

Create a new, unconnected WebSocket client.

Parameters:

serverHost - the server name or IP address

serverPort - the TLS port of the server

urlPath - the URL path, example: /product/websocket-handling

clientListener - the client listener, which has to be implemented by the caller of this class

See Also:

setProtocol(String), setConnectTimeoutMillis(int), setFrameSendTimeoutMillis(long), connect(), WebSocketClientContext.sendTextFrame(String), WebSocketClientContext.sendBinaryFrame(byte[]), disconnect(long)

Method Detail

setProtocol

public void setProtocol(java.lang.String protocol)

Set the protocol (ws or wss). By default wss is used.

Parameters:

protocol - the protocol (ws or wss)

See Also:

PROTOCOL_WS, PROTOCOL_WSS

getProtocol

public java.lang.String getProtocol()

Get the protocol (ws or wss).

Returns:

the protocol (ws or wss)

See Also:

PROTOCOL_WS, PROTOCOL_WSS

setTLSProtocolVersion

public void setTLSProtocolVersion(java.lang.String tlsProtocolVersion)

Override the default value for the TLS protocol version (which is used for encrypted wss connections only).

Parameters:

tlsProtocolVersion - the TLS protocol version. Supported values are:

• TLSv1
• TLSv1.1
• TLSv1.2
• TLSv1.3

See Also:

DEFAULT_TLS_PROTOCOL_VERSION

getTLSProtocolVersion

public java.lang.String getTLSProtocolVersion()

Get the TLS protocol version (which is used for encrypted wss connections only).

Returns:

the TLS protocol version

setTLSClientAuthenticationKeyManagers

public void setTLSClientAuthenticationKeyManagers(javax.net.ssl.KeyManager[] tlsClientAuthenticationKeyManagers)

Set a TLS client authentication credential (derived from a client certificate).

Parameters:

tlsClientAuthenticationKeyManagers - the TLS client authentication credential

See Also:

LoadPKCS12Certificate, LoadPKCS12Certificate.getKeyManagers()

getTLSClientAuthenticationKeyManagers

public javax.net.ssl.KeyManager[] getTLSClientAuthenticationKeyManagers()

Get the TLS client authentication credential (derived from a client certificate).

Returns:

the TLS client authentication credential, or null if no TLS client authentication credential was set.

See Also:

setTLSClientAuthenticationKeyManagers(KeyManager[])

setTrustManagers

public void setTrustManagers(javax.net.ssl.TrustManager[] trustManagers)

Set a specific trust manager for the TLS (wss) protocol.

Parameters:

trustManagers - the sources of peer authentication trust decisions

setConnectTimeoutMillis

public void setConnectTimeoutMillis(int connectTimeoutMillis)

Override the default value for the socket connect timeout.

Parameters:

connectTimeoutMillis - the applied socket connect timeout in milliseconds

See Also:

DEFAULT_CONNECT_TIMEOUT_MILLIS

getConnectTimeoutMillis

public int getConnectTimeoutMillis()

Get the value for the socket connect timeout.

Returns:

the value for the socket connect timeout in milliseconds

setFrameSendTimeoutMillis

public void setFrameSendTimeoutMillis(long frameSendTimeoutMillis)

Override the default value for the frame send timeout. This method can be called at any time.

Note: The 'frame send timeout' is applied only when the outgoing TCP/IP packet queue of the operating system is full, which means that sending further outbound data is blocked by the receiving server at TCP/IP protocol level. Therefore 'frame send timeouts' are often not instantly detected.

Parameters:

frameSendTimeoutMillis - the applied frame send timeout in milliseconds

See Also:

DEFAULT_FRAME_SEND_TIMEOUT_MILLIS

getFrameSendTimeoutMillis

public long getFrameSendTimeoutMillis()

Get the value for the frame send timeout.

Returns:

the value for the frame send timeout in milliseconds

setHttpOrigin

public void setHttpOrigin(java.lang.String httpOrigin)

Set the value of the HTTP origin header field.

Parameters:

httpOrigin - the value of the HTTP origin header field

addHttpBasicAuthentication

public void addHttpBasicAuthentication(java.lang.String username,
                                       java.lang.String password)

Add HTTP Basic Authentication credentials to the WebSocket upgrade request.

Parameters:

username - the username

password - the password

addHttpCookie

public void addHttpCookie(java.lang.String cookieName,
                          java.lang.String cookieValue)

Add a HTTP cookie to the WebSocket upgrade request. This method can be called multiple times.

Parameters:

cookieName - the name of the cookie to add

cookieValue - the value of the cookie to add

addHttpHeaderField

public void addHttpHeaderField(java.lang.String httpHeaderField)

Add an additional HTTP header field to the WebSocket upgrade request. This method can be called multiple times.

Parameters:

httpHeaderField - the HTTP header field to add. Example: "Referer: http://en.wikipedia.org/wiki/Main_Page"

setDebugToStdout

public void setDebugToStdout()

Enable that debug information is written to stdout.

connect

public WebSocketClientContext connect()
                               throws java.security.NoSuchAlgorithmException,
                                      java.security.KeyManagementException,
                                      java.io.IOException,
                                      WebSocketClientConnectException

Connect the WebSocket to the server.

Returns:

the WebSocket client context

Throws:

java.security.NoSuchAlgorithmException - if the TLS V1.2 protocol is not supported

java.security.KeyManagementException - if the SSL/TLS context cannot initialized

java.io.IOException - if an IO error occurs

WebSocketClientConnectException - if the HTTP upgrade request did fail or when a WebSocket connect timout occurred.

getRequestHeader

public java.util.ArrayList<java.lang.String> getRequestHeader()

Get the list of the HTTP upgrade request header fields.

Returns:

the list of the HTTP upgrade request header fields, or null if connect() was not previously called

See Also:

connect()

getResponseHeader

public java.util.ArrayList<java.lang.String> getResponseHeader()

Get the list of the HTTP upgrade response header fields.

Returns:

the list of the HTTP upgrade response header fields, or null if no HTTP response was received

disconnect

public void disconnect()
                throws java.io.IOException

Disconnect the WebSocket from the server without sending a close frame and free all internal resources.

Throws:

java.io.IOException - if somewhat fails

disconnect

public void disconnect(long serverConfirmCloseMillis)
                throws java.io.IOException,
                       java.lang.InterruptedException

Disconnect the WebSocket from the server and free all internal resources. If needed, this method sends also a close frame to the server.

Parameters:

serverConfirmCloseMillis - the wait time to receive the close frame confirmation from the server

Throws:

java.io.IOException - if somewhat fails

java.lang.InterruptedException - if the current thread is interrupted

printDebug

public void printDebug(java.lang.String message)

Print debug information to stdout. This method does nothing if debug to stdout is not enabled.

Parameters:

message - the debug message

See Also:

setDebugToStdout()

getTcpIpConnectTime

public long getTcpIpConnectTime()

Get the TCP/IP connect time for opening the network connection to the server.

Returns:

the TCP/IP connect time for opening the network connection to the server in milliseconds, or -1 if no such data is available

getSslHandshakeTime

public long getSslHandshakeTime()

Get the SSL handshake time to the server (after the TCP/IP connection was established).

Returns:

the SSL handshake time to the server in milliseconds, or -1 if the unencrypted 'ws://' protocol is set, or also -1 if no such data is available

getHttpUpgradeRequestTime

public long getHttpUpgradeRequestTime()

Get the HTTP upgrade request send time, inclusive flushing the HTTP request at network level.

Returns:

the HTTP upgrade request send time in milliseconds, or -1 if no such data is available

getHttpUpgradeResponseTime

public long getHttpUpgradeResponseTime()

Get the HTTP upgrade response receive time, started after the HTTP upgrade request was send and flushed, until the complete HTTP response header ws received.

Returns:

the HTTP upgrade response receive time in milliseconds, or -1 if no such data is available

getWebSocketOpenTime

public long getWebSocketOpenTime()

Get the total time used to open the WebSocket to the server.
This method returns only a valid value if the WebSocket connection was successful established to the server.
The return value is the sum of getTcpIpConnectTime() + [optional getSslHandshakeTime()] + getHttpUpgradeRequestTime() + getHttpUpgradeResponseTime().

Returns:

the total time used to open the WebSocket to the server in milliseconds, or -1 if no such data is available

See Also:

getTcpIpConnectTime(), getSslHandshakeTime(), getHttpUpgradeRequestTime(), getHttpUpgradeResponseTime()

getCurrentConnectStep

public int getCurrentConnectStep()

Get the current internal state of the WebSocket connection - which provides additional information if establishing a WebSocket connection to the server fails.

Returns:

the current internal state of the WebSocket connection

See Also:

CONNECT_STEP_NO_STEP, CONNECT_STEP_PREPARE, CONNECT_STEP_TCP_CONNECT, CONNECT_STEP_SSL_HANDSHAKE, CONNECT_STEP_HTTP_SEND_UPGRADE_REQUEST, CONNECT_STEP_HTTP_RECEIVE_UPGRADE_RESPONSE, CONNECT_STEP_HTTP_VERIFY_UPGRADE_RESPONSE, CONNECT_STEP_OPEN, CONNECT_STEP_CLOSED, currentConnectStepToString(int)

currentConnectStepToString

public static java.lang.String currentConnectStepToString(int connectStep)

Get the text representation of the current internal state of the WebSocket connection.

Parameters:

connectStep - the current internal state of the WebSocket connection

Returns:

the text representation of the current internal state of the WebSocket connection, or '???' if the value of the passed current internal state is invalid.

See Also:

getCurrentConnectStep()

getNumberOfPendingFramesToSend

public long getNumberOfPendingFramesToSend()

Get the number of currently pending frames to send (performance data).

Returns:

the number of currently pending frames to send, or -1 if no such information is available

getTotalFramesSent

public long getTotalFramesSent()

Get the total number of frames which has sent till now (performance data).

Returns:

Get the total number of frames which has sent till now, or -1 if no such information is available

getTotalBytesSent

public long getTotalBytesSent()

Get the total number of bytes which has sent till now - overall frames (performance data).

Returns:

the total number of bytes which has sent till now, or -1 if no such information is available

getTotalPayloadSent

public long getTotalPayloadSent()

Get the total sum of payload in bytes which has sent till now - overall frames (performance data).

Returns:

the total sum of payload in bytes which has sent till now, or -1 if no such information is available

getTotalFramesReceived

public long getTotalFramesReceived()

Get the total number of frames which has received till now (performance data).

Returns:

the total number of frames which has received till now or -1 if no such information is available

getTotalBytesReceived

public long getTotalBytesReceived()

Get the total number of bytes which has received till now - overall frames (performance data).

Returns:

the total number of bytes which has received till now, or -1 if no such information is available

getTotalPayloadReceived

public long getTotalPayloadReceived()

Get the total sum of payload in bytes which has received till now - overall frames (performance data).

Returns:

the total sum of payload in bytes which has received till now, or -1 if no such information is available