The Apache Tomcat Servlet/JSP Container

Apache Tomcat 7

Version 7.0.47, Oct 18 2013
Apache Logo

Links

User Guide

Reference

Apache Tomcat Development

WebSocket How-To

Table of Contents
Overview

Tomcat provides support for WebSocket as defined by RFC 6455.

Application development

Tomcat implements the Java WebSocket 1.0 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.

Tomcat WebSocket specific configuration

The JSR-356 Java WebSocket 1.0 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.

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.

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.

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.

Comments

Notice: This comments section collects your suggestions on improving documentation for Apache Tomcat.

If you have trouble and need help, read Find Help page and ask your question on the tomcat-users mailing list. Do not ask such questions here. This is not a Q&A section.

The Apache Comments System is explained here. Comments may be removed by our moderators if they are either implemented or considered invalid/off-topic.


Copyright © 1999-2013, Apache Software Foundation