Package com.tccc.kos.commons.web.client

Class WebsocketClient

java.lang.Object
com.tccc.kos.commons.web.client.WebsocketClient
All Implemented Interfaces:
AttributeAware
public class WebsocketClient extends Object implements AttributeAware
Websocket client with support for automatic reconnects using exponential backoff. This is useful for applications that expect to be connected to a remote host and don't want to deal with the connection management. The client also supports changing the endpoint to connect to while the client is running.

By default the client is configured for single connection mode. A call to start() will only perform a single connection attempt. In this mode the user can call start() on failure / close to attempt another connection. By setting the reconnect flag to true, a single call to start() will cause the client to continuously connect to the configured endpoint.

Lifecycle events for the connection are available by attaching a connection listener. All messages received from the client will be forwarded to the configured message handler.

Since:
1.0
Version:
2022-09-28

  • Constructor Details

    • WebsocketClient

      public WebsocketClient()
      Create a new websocket client.

  • Method Details

    • setMsgHandler

      public WebsocketClient setMsgHandler(WebsocketMsgHandler msgHandler)
      Set the message handler to receive incoming messages.
      Parameters:
      msgHandler - the message handler

    • setEndpoint

      public WebsocketClient setEndpoint(WebsocketEndpoint endpoint)
      Set the endpoint. Setting this while a websocket is open will close the websocket. If the reconnect flag is true then the new endpoint will be used on the next connection attempt.

    • start

      public WebsocketClient start()
      Start the client which will cause it to try to connect to the currently configured endpoint if there is one. The client will automatically reconnect until stopped or the endpoint is set to null.

    • stop

      public void stop()
      Stop the client. Any connection currently open will be closed.

    • isRunning

      public boolean isRunning()
      Return true if the client is currently running as a result of calling start() . If no endpoint is set, the connection attempt will block until either and endpoing is set or stop() is called. If and endpoint is set, a connection attempt will be made to the endpoint. If reconnect is false, only a single connection attempt will be made. If true, the client will attempt to reconnect to the endpoint using a backoff algorithm until stop() is called.

    • isConnected

      public boolean isConnected()
      Return true if the websocket is currently connected.

    • setReconnect

      public WebsocketClient setReconnect(boolean reconnect)
      Set reconnect flag. When set to true the client will attempt to reconnect as long as the client is running. When set to false, only a single connect attempt will be made for each call to start() .

    • isReconnect

      public boolean isReconnect()
      Return the reconnect flag. If true, the client will automatically reconnect to the endpoint until stop() is called or the endpoint is set to null.

    • disablePing

      public WebsocketClient disablePing()
      Disable ping timeout checks on the websocket connection. This is useful when connecting to a server that doesn't support ping such as when connecting to the chrome web browser.

    • getConnection

      public WebsocketConnection getConnection()
      Return the active connection if there is one.

    • setAttribute

      public void setAttribute(Object name, Object val)
      Set an attribute to the client which will be added to any connections created by this client. Does not impact any existing connections.
      Specified by:
      setAttribute in interface AttributeAware
      Parameters:
      name - the attribute name
      val - the attribute value

    • removeAttribute

      public Object removeAttribute(Object name)
      Remove an attribute from the client. Does not impact any existing connections.
      Specified by:
      removeAttribute in interface AttributeAware
      Parameters:
      name - the attribute name
      Returns:
      the value of the attribute being removed, or null if it didn't exist

    • getAttribute

      public Object getAttribute(Object name)
      Return an attribute set on the client.
      Specified by:
      getAttribute in interface AttributeAware
      Parameters:
      name - the attribute name
      Returns:
      the value of the attribute, or null if it doesn't exist

    • addListener

      public WebsocketClient addListener(WebsocketConnectionListener listener)
      Add a connection listener to the client.
      Parameters:
      listener - the listener to add

    • removeListener

      public WebsocketClient removeListener(WebsocketConnectionListener listener)
      Remove a connection listener from the client.
      Parameters:
      listener - the listener to remove

    • sendMessage

      public boolean sendMessage(String msg)
      Send a message to the websocket connection. Returns true if the message was sent, false if there is no connection to send the message.
      Parameters:
      msg - the message to send

    • setMinSuccessfulConnectTimeMS

      public WebsocketClient setMinSuccessfulConnectTimeMS(long ms)
      Set the minimum time a connection must be connected before a disconnect is considered a failure. For example, if a server connects but then immediately disconnects (such as if a proxy terminates the websocket but then fails to connect to the server behind the proxy) then the connection was really a failure so the backoff algorithm should throttle connections. Default value is 20000.

    • setRetryDelayBaseTimeMS

      public WebsocketClient setRetryDelayBaseTimeMS(long ms)
      Set the base delay time for a reconnect. This will be the starting delay for every connect attempt before throttling is added. Default value is 1000.

    • setRetryDelayPerFailureTimeMS

      public WebsocketClient setRetryDelayPerFailureTimeMS(long ms)
      Set the delay to add to the base retry time when there are connection failures. This will be multiplied by the square of the failure count. Default value is 500;

    • setMaxFailureCount

      public WebsocketClient setMaxFailureCount(int count)
      Set the max failure count when computing the reconnect delay. Since the backoff algorithm uses the square of the failure count, the delays can grow very large very quickly. This caps the delay related to failure count. Default value is 100. Using default values, this will result in a max delay of about 1.4 hours from failure related backoff.

    • setRetryDelayMaxTimeMS

      public WebsocketClient setRetryDelayMaxTimeMS(long ms)
      Set the max retry delay. This ensures that failure based backoff doesn't grow past this upper threshold. Default value is 2 hours.

    • setMaxFailedConnects

      public WebsocketClient setMaxFailedConnects(int maxFailedConnects)
      Set the max number of failed connects before stopping the client.

    • getMinSuccessfulConnectTimeMS

      public long getMinSuccessfulConnectTimeMS()

    • getRetryDelayBaseTimeMS

      public long getRetryDelayBaseTimeMS()

    • getRetryDelayPerFailureTimeMS

      public long getRetryDelayPerFailureTimeMS()

    • getRetryDelayMaxTimeMS

      public long getRetryDelayMaxTimeMS()

    • getMaxFailureCount

      public int getMaxFailureCount()

    • getMaxFailedConnects

      public int getMaxFailedConnects()

    • getEndpoint

      public WebsocketEndpoint getEndpoint()

    • getMsgHandler

      public WebsocketMsgHandler getMsgHandler()