# Apache Tomcat 7

Version 7.0.107, Nov 18 2020

Links

- Docs Home
- FAQ
- User Comments

User Guide

- 1) Introduction
- 2) Setup
- 3) First webapp
- 4) Deployer
- 5) Manager
- 6) Host Manager
- 7) Realms and AAA
- 8) Security Manager
- 9) JNDI Resources
- 10) JDBC DataSources
- 11) Classloading
- 12) JSPs
- 13) SSL/TLS
- 14) SSI
- 15) CGI
- 16) Proxy Support
- 17) MBeans Descriptors
- 18) Default Servlet
- 19) Clustering
- 20) Load Balancer
- 21) Connectors
- 22) Monitoring and Management
- 23) Logging
- 24) APR/Native
- 25) Virtual Hosting
- 26) Advanced IO
- 27) Additional Components
- 28) Mavenized
- 29) Security Considerations
- 30) Windows Service
- 31) Windows Authentication
- 32) Tomcat's JDBC Pool
- 33) WebSocket

Reference

- Release Notes
- Configuration
- Tomcat Javadocs
- Servlet Javadocs
- JSP 2.2 Javadocs
- EL 2.2 Javadocs
- WebSocket 1.1 Javadocs
- Common Annotations 1.1 Javadocs
- JK 1.2 Documentation

Apache Tomcat Development

- Building
- Changelog
- Status
- Developers
- Architecture
- Tribes

# WebSocket How-To

Table of Contents

> - Overview
> - Application development
> - Production usage
> - Tomcat WebSocket specific configuration
> - Deprecated proprietary API

Overview

> Tomcat provides support for WebSocket as defined by RFC 6455.

Application development

> Tomcat implements the Java WebSocket 1.1 API defined by JSR-356.

> There are several example applications that demonstrate how the WebSocket API can be used. You will need to look at both the client side HTML and the server side code.

Production usage

> Although the WebSocket implementation does work with any of the HTTP connectors, it is not recommended to the WebSocket with the BIO HTTP connector as the typical uses of WebSocket (large numbers of mostly idle connections) is not a good fit for the HTTP BIO connector which requires that one thread is allocated per connection regardless of whether or not the connection is idle.

> It has been reported (56304) that Linux can take large numbers of minutes to report dropped connections. When using WebSocket with the BIO HTTP connector this can result in threads blocking on writes for this period. This is likely to be undesirable. The time taken for the connection to be reported as dropped can be reduced by using the kernel network parameter `/proc/sys/net/ipv4/tcp_retries2`. Alternatively, one of the other HTTP connectors may be used as they utilise non-blocking IO enabling Tomcat to implement its own timeout mechanism to handle these cases.

Tomcat WebSocket specific configuration

> The JSR-356 Java WebSocket 1.1 implementation is only available when Tomcat is running on Java 7 or later.

> 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_TIMEOUT` in 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`.

> In addition to the `Session.setMaxIdleTimeout(long)` method which is part of the Java WebSocket API, Tomcat provides greater control of the timing out the session due to lack of activity. Setting the property `org.apache.tomcat.websocket.READ_IDLE_TIMEOUT_MS` in the user properties collection attached to the WebSocket session will trigger a session timeout if no WebSocket message is received for the specified number of milliseconds. Setting the property `org.apache.tomcat.websocket.WRITE_IDLE_TIMEOUT_MS` will trigger a session timeout if no WebSocket message is sent for the specified number of milliseconds. These can be used separately or together, with or without `Session.setMaxIdleTimeout(long)`. If the associated property is not specified, the read and/or write idle timeout will be applied.

> 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 registered `MessageHandler.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 parameter `org.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 registered `MessageHandler.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 parameter `org.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 the `org.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:

> - `org.apache.tomcat.websocket.executorCoreSize`: The core size of the executor thread pool. If not set, the default of 0 (zero) is used. Note that the maximum permitted size of the executor thread pool is hard coded to `Integer.MAX_VALUE` which effectively means it is unlimited.
> - `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.

> 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:

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

> If the `org.apache.tomcat.websocket.SSL_CONTEXT` property is set then the `org.apache.tomcat.websocket.SSL_TRUSTSTORE` and `org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD` properties will be ignored.

> For secure server end points, host name verification is enabled by default. To bypass this verification (not recommended), it is necessary to provide a custom `SSLContext` via the `org.apache.tomcat.websocket.SSL_CONTEXT` user property. The custom `SSLContext` must be configured with a custom `TrustManager` that extends `javax.net.ssl.X509ExtendedTrustManager`. The desired verification (or lack of verification) can then be controlled by appropriate implementations of the individual abstract methods.

> When using the WebSocket client to connect to server endpoints, the number of HTTP redirects that the client will follow is controlled by the `userProperties` of the provided `javax.websocket.ClientEndpointConfig`. The property is org.apache.tomcat.websocket.MAX_REDIRECTIONS. The default value is 20. Redirection support can be disabled by configuring a value of zero.

Deprecated proprietary API

> Prior to the development of JRS-356, Tomcat provided a proprietary WebSocket API. This API has been deprecated in Tomcat 7 and will be removed in Tomcat 8. There is unlikely to be any further development of this proprietary API apart from bug fixes.

> For information on this API, please see the Javadoc for the `org.apache.catalina.websocket` package. The Javadoc pages are not included with Tomcat binary distributions. To view them locally you would have to download and install "Full documentation" distribution, or build it from sources. You can also read this on the Apache Tomcat web site. Start with the `WebSocketServlet` class.

> There are also several example applications that demonstrate how the WebSocket API can be used. You'll need to look at both the client side HTML and the server side code.

Copyright © 1999-2020, Apache Software Foundation