Red Hat Training

A Red Hat training course is available for Red Hat JBoss Web Server

4.2. Implementing WebSocket on Tomcat

Configuring WebSocket on Tomcat requires individual configuration of the following:
  • Configuring write timeout
  • Configuring incoming binary messages
  • Configuring incoming text messages
  • Configuring additional programmatic deployment
  • Configuring callbacks for asynchronous writes
  • Configuring timeout for IO operations while establishing the connections
Configuring write timeout

You can change the write timeout in blocking mode by using the org.apache.tomcat.websocket.BLOCKING_SEND_TIMEOUT property. The property accepts values in milliseconds. The default value is 20000 milliseconds (20 seconds).

Configuring incoming binary messages

To configure incoming binary messages, MessageHandler.Partial must be defined. If MessageHandler.Partial is not defined then incoming binary messages must be buffered so that the entire message is delivered in a single call to MessageHandler.Whole.

The default buffer size for binary messages is 8192 bytes. You can change the buffer size for a web application by changing the value of the servlet context initializing parameter org.apache.tomcat.websocket.binaryBufferSize.
Configuring incoming text messages

To configure incoming text messages, MessageHandler.Partial must be defined. If MessageHandler.Partial is not defined then incoming text messages must be buffered so that the entire message is delivered in a single call to MessageHandler.Whole.

The default buffer size for text messages is 8192 bytes. You can change the buffer size for a web application by changing the value of the servlet context initializing parameter org.apache.tomcat.websocket.textBufferSize.
Configuring additional programmatic deployment

Java WebSocket specification 1.0 does not allow programmatic deployment after the first endpoint has started a WebSocket handshake. However, Tomcat by default allows additional programmatic deployment. Additional programmatic deployment can be done by using the servlet context initialization parameter org.apache.tomcat.websocket.noAddAfterHandshake.

Set the system property org.apache.tomcat.websocket.STRICT_SPEC_COMPLIANCE to true to change the default setting.
Configuring callbacks for asynchronous writes

Callbacks for asynchronous writes need to be performed on a different thread to the thread that initiated the write. The container thread pool is not exposed via the Servlet API. Hence the WebSocket implementation has to provide its own thread pool.

The following servlet context initialization parameters control the thread pool:
  • org.apache.tomcat.websocket.executorCoreSize
    The core size of the executor thread pool. If not set, the default of 0 (zero) is used.
  • org.apache.tomcat.websocket.executorMaxSize
    The maximum permitted size of the executor thread pool. If not set, the default of 10 is used.
  • org.apache.tomcat.websocket.executorKeepAliveTimeSeconds
    The maximum time an idle thread will remain in the executor thread pool until it is terminated. If not specified, the default of 60 seconds is used.
Configuring timeout for IO operations while establishing the connections

The timeout for IO operations while establishing the connections is controlled by userProperties of the provided javax.websocket.ClientEndpointConfig. You can change timeout by changing the org.apache.tomcat.websocket.IO_TIMEOUT_MS property. The property accepts the values in milliseconds. The default value is 5000 (5 seconds).

To connect WebSocket client to secure server endpoints, the client SSL configuration is controlled by userProperties of the provided javax.websocket.ClientEndpointConfig.
The following user properties are supported:
  • org.apache.tomcat.websocket.SSL_CONTEXT
  • org.apache.tomcat.websocket.SSL_PROTOCOLS
  • org.apache.tomcat.websocket.SSL_TRUSTSTORE
  • org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD
The default truststore password is changeit. The org.apache.tomcat.websocket.SSL_TRUSTSTORE and org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD properties are ignored if the org.apache.tomcat.websocket.SSL_CONTEXT property is set.
Report a bug