Tomcat WebSocket specific configuration

Tomcat provides a number of Tomcat specific configuration options for WebSocket. It is anticipated that these will be absorbed into the WebSocket specification over time.

The write timeout used when sending WebSocket messages in blocking mode defaults to 20000 milliseconds (20 seconds). This may be changed by setting the property org.apache.tomcat.websocket.BLOCKING_SEND_TIMEOUTin the user properties collection attached to the WebSocket session. The value assigned to this property should be a Long and represents the timeout to use in milliseconds. For an infinite timeout, use -1.

If the application does not define a MessageHandler.Partial for incoming binary messages, any incoming binary messages must be buffered so the entire message can be delivered in a single call to the registeredMessageHandler.Whole for binary messages. The default buffer size for binary messages is 8192 bytes. This may be changed for a web application by setting the servlet context initialization parameterorg.apache.tomcat.websocket.binaryBufferSize to the desired value in bytes.

If the application does not define a MessageHandler.Partial for incoming text messages, any incoming text messages must be buffered so the entire message can be delivered in a single call to the registeredMessageHandler.Whole for text messages. The default buffer size for text messages is 8192 bytes. This may be changed for a web application by setting the servlet context initialization parameterorg.apache.tomcat.websocket.textBufferSize to the desired value in bytes.

The Java WebSocket specification 1.0 does not permit programmatic deployment after the first endpoint has started a WebSocket handshake. By default, Tomcat continues to permit additional programmatic deployment. This behavior is controlled by the org.apache.tomcat.websocket.noAddAfterHandshake servlet context initialization parameter. The default may be changed by setting theorg.apache.tomcat.websocket.STRICT_SPEC_COMPLIANCE system property to true but any explicit setting on the servlet context will always take priority.

The Java WebSocket 1.0 specification requires that callbacks for asynchronous writes are performed on a different thread to the thread that initiated the write. Since the container thread pool is not exposed via the Servlet API, the WebSocket implementation has to provide its own thread pool. This thread pool is controlled by the following servlet context initialization parameters:

• apache.tomcat.websocket.executorCoreSize: The core size of the executor thread pool. If not set, the default of 0 (zero) is used.

• apache.tomcat.websocket.executorMaxSize: The maximum permitted size of the executor thread pool. If not set, the default of 10 is used.

• 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.

When using the WebSocket client to connect to server endpoints, the timeout for IO operations while establishing the connection is controlled by the userProperties of the provided javax.websocket.ClientEndpointConfig. The property is org.apache.tomcat.websocket.IO_TIMEOUT_MS and is the timeout as a String in milliseconds. The default is 5000 (5 seconds).

When using the WebSocket client to connect to secure server endpoints, the client SSL configuration is controlled by the userProperties of the provided javax.websocket.ClientEndpointConfig. The following user properties are supported:

• apache.tomcat.websocket.SSL_CONTEXT
• apache.tomcat.websocket.SSL_PROTOCOLS
• apache.tomcat.websocket.SSL_TRUSTSTORE
• apache.tomcat.websocket.SSL_TRUSTSTORE_PWD

The default truststore password is changeit.

If the org.apache.tomcat.websocket.SSL_CONTEXT property is set then theorg.apache.tomcat.websocket.SSL_TRUSTSTORE and org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWDproperties will be ignored.