tomcat-uid/webapps/docs/web-socket-howto.html - UniIdentify/tomcat - Gitiles

 <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 (7.0.77) - WebSocket How-To</title><style type="text/css" media="print">
     .noPrint {display: none;}
     td#mainBody {width: 100%;}
 </style><style type="text/css">
 code {background-color:rgb(224,255,255);padding:0 0.1em;}
 code.attributeName, code.propertyName {background-color:transparent;}


 table {
   border-collapse: collapse;
   text-align: left;
 }
 table *:not(table) {
   /* Prevent border-collapsing for table child elements like <div> */
   border-collapse: separate;
 }

 th {
   text-align: left;
 }


 div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
   background-color: transparent;
 }
 div.codeBox {
   overflow: auto;
   margin: 1em 0;
 }
 div.codeBox pre {
   margin: 0;
   padding: 4px;
   border: 1px solid #999;
   border-radius: 5px;
   background-color: #eff8ff;
   display: table; /* To prevent <pre>s from taking the complete available width. */
   /*
   When it is officially supported, use the following CSS instead of display: table
   to prevent big <pre>s from exceeding the browser window:
   max-width: available;
   width: min-content;
   */
 }

 div.codeBox pre.wrap {
   white-space: pre-wrap;
 }


 table.defaultTable tr, table.detail-table tr {
     border: 1px solid #CCC;
 }

 table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
     background-color: #FAFBFF;
 }

 table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
     background-color: #EEEFFF;
 }

 table.defaultTable th, table.detail-table th {
   background-color: #88b;
   color: #fff;
 }

 table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
   padding: 5px 8px;
 }


 p.notice {
     border: 1px solid rgb(255, 0, 0);
     background-color: rgb(238, 238, 238);
     color: rgb(0, 51, 102);
     padding: 0.5em;
     margin: 1em 2em 1em 1em;
 }
 </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="
       The Apache Tomcat Servlet/JSP Container
     " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.77, Mar 28 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL/TLS</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">16) MBeans Descriptors</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.2 Javadocs</a></li><li><a href="elapi/index.html">EL 2.2 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>WebSocket How-To</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
 <ul><li><a href="#Overview">Overview</a></li><li><a href="#Application_development">Application development</a></li><li><a href="#Production_usage">Production usage</a></li><li><a href="#Tomcat_WebSocket_specific_configuration">Tomcat WebSocket specific configuration</a></li><li><a href="#Deprecated_proprietary_API">Deprecated proprietary API</a></li></ul>
 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>
 <p>Tomcat provides support for WebSocket as defined by
    <a href="http://tools.ietf.org/html/rfc6455">RFC 6455</a>.</p>
 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Application development"><!--()--></a><a name="Application_development"><strong>Application development</strong></a></font></td></tr><tr><td><blockquote>
 <p>Tomcat implements the Java WebSocket 1.1 API defined by <a href="http://www.jcp.org/en/jsr/detail?id=356">JSR-356</a>.</p>

 <p>There are several example applications that demonstrate how the WebSocket API
    can be used. You will need to look at both the client side <a href="http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/examples/websocket/">
    HTML</a> and the server side <a href="http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/examples/WEB-INF/classes/websocket/">
    code</a>.</p>
 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Production usage"><!--()--></a><a name="Production_usage"><strong>Production usage</strong></a></font></td></tr><tr><td><blockquote>
 <p>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.
 </p>

 <p>It has been reported (<a href="http://bz.apache.org/bugzilla/show_bug.cgi?id=56304">56304</a>) 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
 <code>/proc/sys/net/ipv4/tcp_retries2</code>. 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.</p>
 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Tomcat WebSocket specific configuration"><!--()--></a><a name="Tomcat_WebSocket_specific_configuration"><strong>Tomcat WebSocket specific configuration</strong></a></font></td></tr><tr><td><blockquote>
 <p>The JSR-356 Java WebSocket 1.1 implementation is only available when Tomcat
    is running on Java 7 or later.</p>

 <p>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.</p>

 <p>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 <code>org.apache.tomcat.websocket.BLOCKING_SEND_TIMEOUT</code>
    in the user properties collection attached to the WebSocket session. The
    value assigned to this property should be a <code>Long</code> and represents
    the timeout to use in milliseconds. For an infinite timeout, use
    <code>-1</code>.</p>

 <p>If the application does not define a <code>MessageHandler.Partial</code> 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
    <code>MessageHandler.Whole</code> 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
    <code>org.apache.tomcat.websocket.binaryBufferSize</code> to the desired
    value in bytes.</p>

 <p>If the application does not define a <code>MessageHandler.Partial</code> 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
    <code>MessageHandler.Whole</code> 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
    <code>org.apache.tomcat.websocket.textBufferSize</code> to the desired value
    in bytes.</p>

 <p>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
    <code>org.apache.tomcat.websocket.noAddAfterHandshake</code> servlet context
    initialization parameter. The default may be changed by setting the
    <code>org.apache.tomcat.websocket.STRICT_SPEC_COMPLIANCE</code> system
    property to <code>true</code> but any explicit setting on the servlet context
    will always take priority.</p>

 <p>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:</p>
    <ul>
      <li><code>org.apache.tomcat.websocket.executorCoreSize</code>: 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 <code>Integer.MAX_VALUE</code> which effectively
          means it is unlimited.</li>
      <li><code>org.apache.tomcat.websocket.executorKeepAliveTimeSeconds</code>:
          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.</li>
    </ul>

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

 <p>When using the WebSocket client to connect to secure server endpoints, the
    client SSL configuration is controlled by the <code>userProperties</code>
    of the provided <code>javax.websocket.ClientEndpointConfig</code>. The
    following user properties are supported:</p>
    <ul>
      <li><code>org.apache.tomcat.websocket.SSL_CONTEXT</code></li>
      <li><code>org.apache.tomcat.websocket.SSL_PROTOCOLS</code></li>
      <li><code>org.apache.tomcat.websocket.SSL_TRUSTSTORE</code></li>
      <li><code>org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD</code></li>
    </ul>
    <p>The default truststore password is <code>changeit</code>.</p>
    <p>If the <code>org.apache.tomcat.websocket.SSL_CONTEXT</code> property is
       set then the <code>org.apache.tomcat.websocket.SSL_TRUSTSTORE</code> and
       <code>org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD</code> properties
       will be ignored.</p>
 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deprecated proprietary API"><!--()--></a><a name="Deprecated_proprietary_API"><strong>Deprecated proprietary API</strong></a></font></td></tr><tr><td><blockquote>

 <p>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.</p>

 <p>For information on this API, please see the Javadoc for the
    <a href="api/index.html?org/apache/catalina/websocket/package-summary.html">
    <code>org.apache.catalina.websocket</code></a> 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
    <a href="api/index.html?org/apache/catalina/websocket/WebSocketServlet.html">
    <code>WebSocketServlet</code></a> class.</p>

 <p>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 <a href="http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/examples/websocket-deprecated/">
    HTML</a> and the server side <a href="http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/examples/WEB-INF/classes/websocket/tc7/">
    code</a>.</p>
 </blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
               on improving documentation for Apache Tomcat.<br><br>
               If you have trouble and need help, read
               <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
               and ask your question on the tomcat-users
               <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
               Do not ask such questions here. This is not a Q&amp;A section.<br><br>
               The Apache Comments System is explained <a href="./comments.html">here</a>.
               Comments may be removed by our moderators if they are either
               implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
               var comments_shortname = 'tomcat';
               var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/web-socket-howto.html';
               (function(w, d) {
                   if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
                       d.write('<div id="comments_thread"><\/div>');
                       var s = d.createElement('script');
                       s.type = 'text/javascript';
                       s.async = true;
                       s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
                       (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
                   }
                   else {
                       d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
                   }
               })(window, document);
               //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
         Copyright &copy; 1999-2017, Apache Software Foundation
         </em></font></div></td></tr></table></body></html>
	<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 (7.0.77) - WebSocket How-To</title><style type="text/css" media="print">
	.noPrint {display: none;}
	td#mainBody {width: 100%;}
	</style><style type="text/css">
	code {background-color:rgb(224,255,255);padding:0 0.1em;}
	code.attributeName, code.propertyName {background-color:transparent;}


	table {
	border-collapse: collapse;
	text-align: left;
	}
	table *:not(table) {
	/* Prevent border-collapsing for table child elements like <div> */
	border-collapse: separate;
	}

	th {
	text-align: left;
	}


	div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
	background-color: transparent;
	}
	div.codeBox {
	overflow: auto;
	margin: 1em 0;
	}
	div.codeBox pre {
	margin: 0;
	padding: 4px;
	border: 1px solid #999;
	border-radius: 5px;
	background-color: #eff8ff;
	display: table; /* To prevent <pre>s from taking the complete available width. */
	/*
	When it is officially supported, use the following CSS instead of display: table
	to prevent big <pre>s from exceeding the browser window:
	max-width: available;
	width: min-content;
	*/
	}

	div.codeBox pre.wrap {
	white-space: pre-wrap;
	}


	table.defaultTable tr, table.detail-table tr {
	border: 1px solid #CCC;
	}

	table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
	background-color: #FAFBFF;
	}

	table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
	background-color: #EEEFFF;
	}

	table.defaultTable th, table.detail-table th {
	background-color: #88b;
	color: #fff;
	}

	table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
	padding: 5px 8px;
	}


	p.notice {
	border: 1px solid rgb(255, 0, 0);
	background-color: rgb(238, 238, 238);
	color: rgb(0, 51, 102);
	padding: 0.5em;
	margin: 1em 2em 1em 1em;
	}
	</style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="
	The Apache Tomcat Servlet/JSP Container
	" border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.77, Mar 28 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL/TLS</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">16) MBeans Descriptors</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.2 Javadocs</a></li><li><a href="elapi/index.html">EL 2.2 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>WebSocket How-To</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
	<ul><li><a href="#Overview">Overview</a></li><li><a href="#Application_development">Application development</a></li><li><a href="#Production_usage">Production usage</a></li><li><a href="#Tomcat_WebSocket_specific_configuration">Tomcat WebSocket specific configuration</a></li><li><a href="#Deprecated_proprietary_API">Deprecated proprietary API</a></li></ul>
	</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>
	<p>Tomcat provides support for WebSocket as defined by
	<a href="http://tools.ietf.org/html/rfc6455">RFC 6455</a>.</p>
	</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Application development"><!--()--></a><a name="Application_development"><strong>Application development</strong></a></font></td></tr><tr><td><blockquote>
	<p>Tomcat implements the Java WebSocket 1.1 API defined by <a href="http://www.jcp.org/en/jsr/detail?id=356">JSR-356</a>.</p>

	<p>There are several example applications that demonstrate how the WebSocket API
	can be used. You will need to look at both the client side <a href="http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/examples/websocket/">
	HTML</a> and the server side <a href="http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/examples/WEB-INF/classes/websocket/">
	code</a>.</p>
	</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Production usage"><!--()--></a><a name="Production_usage"><strong>Production usage</strong></a></font></td></tr><tr><td><blockquote>
	<p>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.
	</p>

	<p>It has been reported (<a href="http://bz.apache.org/bugzilla/show_bug.cgi?id=56304">56304</a>) 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
	<code>/proc/sys/net/ipv4/tcp_retries2</code>. 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.</p>
	</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Tomcat WebSocket specific configuration"><!--()--></a><a name="Tomcat_WebSocket_specific_configuration"><strong>Tomcat WebSocket specific configuration</strong></a></font></td></tr><tr><td><blockquote>
	<p>The JSR-356 Java WebSocket 1.1 implementation is only available when Tomcat
	is running on Java 7 or later.</p>

	<p>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.</p>

	<p>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 <code>org.apache.tomcat.websocket.BLOCKING_SEND_TIMEOUT</code>
	in the user properties collection attached to the WebSocket session. The
	value assigned to this property should be a <code>Long</code> and represents
	the timeout to use in milliseconds. For an infinite timeout, use
	<code>-1</code>.</p>

	<p>If the application does not define a <code>MessageHandler.Partial</code> 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
	<code>MessageHandler.Whole</code> 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
	<code>org.apache.tomcat.websocket.binaryBufferSize</code> to the desired
	value in bytes.</p>

	<p>If the application does not define a <code>MessageHandler.Partial</code> 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
	<code>MessageHandler.Whole</code> 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
	<code>org.apache.tomcat.websocket.textBufferSize</code> to the desired value
	in bytes.</p>

	<p>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
	<code>org.apache.tomcat.websocket.noAddAfterHandshake</code> servlet context
	initialization parameter. The default may be changed by setting the
	<code>org.apache.tomcat.websocket.STRICT_SPEC_COMPLIANCE</code> system
	property to <code>true</code> but any explicit setting on the servlet context
	will always take priority.</p>

	<p>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:</p>
	<ul>
	<li><code>org.apache.tomcat.websocket.executorCoreSize</code>: 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 <code>Integer.MAX_VALUE</code> which effectively
	means it is unlimited.</li>
	<li><code>org.apache.tomcat.websocket.executorKeepAliveTimeSeconds</code>:
	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.</li>
	</ul>

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

	<p>When using the WebSocket client to connect to secure server endpoints, the
	client SSL configuration is controlled by the <code>userProperties</code>
	of the provided <code>javax.websocket.ClientEndpointConfig</code>. The
	following user properties are supported:</p>
	<ul>
	<li><code>org.apache.tomcat.websocket.SSL_CONTEXT</code></li>
	<li><code>org.apache.tomcat.websocket.SSL_PROTOCOLS</code></li>
	<li><code>org.apache.tomcat.websocket.SSL_TRUSTSTORE</code></li>
	<li><code>org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD</code></li>
	</ul>
	<p>The default truststore password is <code>changeit</code>.</p>
	<p>If the <code>org.apache.tomcat.websocket.SSL_CONTEXT</code> property is
	set then the <code>org.apache.tomcat.websocket.SSL_TRUSTSTORE</code> and
	<code>org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD</code> properties
	will be ignored.</p>
	</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Deprecated proprietary API"><!--()--></a><a name="Deprecated_proprietary_API"><strong>Deprecated proprietary API</strong></a></font></td></tr><tr><td><blockquote>

	<p>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.</p>

	<p>For information on this API, please see the Javadoc for the
	<a href="api/index.html?org/apache/catalina/websocket/package-summary.html">
	<code>org.apache.catalina.websocket</code></a> 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
	<a href="api/index.html?org/apache/catalina/websocket/WebSocketServlet.html">
	<code>WebSocketServlet</code></a> class.</p>

	<p>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 <a href="http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/examples/websocket-deprecated/">
	HTML</a> and the server side <a href="http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/examples/WEB-INF/classes/websocket/tc7/">
	code</a>.</p>
	</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
	on improving documentation for Apache Tomcat.<br><br>
	If you have trouble and need help, read
	<a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
	and ask your question on the tomcat-users
	<a href="http://tomcat.apache.org/lists.html">mailing list</a>.
	Do not ask such questions here. This is not a Q&A section.<br><br>
	The Apache Comments System is explained <a href="./comments.html">here</a>.
	Comments may be removed by our moderators if they are either
	implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
	var comments_shortname = 'tomcat';
	var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/web-socket-howto.html';
	(function(w, d) {
	if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
	d.write('<div id="comments_thread"><\/div>');
	var s = d.createElement('script');
	s.type = 'text/javascript';
	s.async = true;
	s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
	(d.getElementsByTagName('head')[0] \|\| d.getElementsByTagName('body')[0]).appendChild(s);
	}
	else {
	d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
	}
	})(window, document);
	//--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
	Copyright © 1999-2017, Apache Software Foundation
	</em></font></div></td></tr></table></body></html>