Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / 6266f996613ae5631b7288523f895b36e30fe5af / . / tomcat-cas / webapps / docs / web-socket-howto.html
blob: 8a121f51a638ba8b455d777813fdf6160f5d0189 [file] [log] [blame]
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1<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">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4</style><style type="text/css">
5code {background-color:rgb(224,255,255);padding:0 0.1em;}
6code.attributeName, code.propertyName {background-color:transparent;}
7
8
9table {
10 border-collapse: collapse;
11 text-align: left;
12}
13table *:not(table) {
14 /* Prevent border-collapsing for table child elements like <div> */
15 border-collapse: separate;
16}
17
18th {
19 text-align: left;
20}
21
22
23div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
24 background-color: transparent;
25}
26div.codeBox {
27 overflow: auto;
28 margin: 1em 0;
29}
30div.codeBox pre {
31 margin: 0;
32 padding: 4px;
33 border: 1px solid #999;
34 border-radius: 5px;
35 background-color: #eff8ff;
36 display: table; /* To prevent <pre>s from taking the complete available width. */
37 /*
38 When it is officially supported, use the following CSS instead of display: table
39 to prevent big <pre>s from exceeding the browser window:
40 max-width: available;
41 width: min-content;
42 */
43}
44
45div.codeBox pre.wrap {
46 white-space: pre-wrap;
47}
48
49
50table.defaultTable tr, table.detail-table tr {
51 border: 1px solid #CCC;
52}
53
54table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
55 background-color: #FAFBFF;
56}
57
58table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
59 background-color: #EEEFFF;
60}
61
62table.defaultTable th, table.detail-table th {
63 background-color: #88b;
64 color: #fff;
65}
66
67table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
68 padding: 5px 8px;
69}
70
71
72p.notice {
73 border: 1px solid rgb(255, 0, 0);
74 background-color: rgb(238, 238, 238);
75 color: rgb(0, 51, 102);
76 padding: 0.5em;
77 margin: 1em 2em 1em 1em;
78}
79</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="
80 The Apache Tomcat Servlet/JSP Container
81 " 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>
82<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>
83</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>
84<p>Tomcat provides support for WebSocket as defined by
85 <a href="http://tools.ietf.org/html/rfc6455">RFC 6455</a>.</p>
86</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>
87<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>
88
89<p>There are several example applications that demonstrate how the WebSocket API
90 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/">
91 HTML</a> and the server side <a href="http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/examples/WEB-INF/classes/websocket/">
92 code</a>.</p>
93</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>
94<p>Although the WebSocket implementation does work with any of the HTTP
95connectors, it is not recommended to the WebSocket with the BIO HTTP connector
96as the typical uses of WebSocket (large numbers of mostly idle connections) is
97not a good fit for the HTTP BIO connector which requires that one thread is
98allocated per connection regardless of whether or not the connection is idle.
99</p>
100
101<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
102minutes to report dropped connections. When using WebSocket with the BIO HTTP
103connector this can result in threads blocking on writes for this period. This is
104likely to be undesirable. The time taken for the connection to be reported as
105dropped can be reduced by using the kernel network parameter
106<code>/proc/sys/net/ipv4/tcp_retries2</code>. Alternatively, one of the other
107HTTP connectors may be used as they utilise non-blocking IO enabling Tomcat to
108implement its own timeout mechanism to handle these cases.</p>
109</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>
110<p>The JSR-356 Java WebSocket 1.1 implementation is only available when Tomcat
111 is running on Java 7 or later.</p>
112
113<p>Tomcat provides a number of Tomcat specific configuration options for
114 WebSocket. It is anticipated that these will be absorbed into the WebSocket
115 specification over time.</p>
116
117<p>The write timeout used when sending WebSocket messages in blocking mode
118 defaults to 20000 milliseconds (20 seconds). This may be changed by setting
119 the property <code>org.apache.tomcat.websocket.BLOCKING_SEND_TIMEOUT</code>
120 in the user properties collection attached to the WebSocket session. The
121 value assigned to this property should be a <code>Long</code> and represents
122 the timeout to use in milliseconds. For an infinite timeout, use
123 <code>-1</code>.</p>
124
125<p>If the application does not define a <code>MessageHandler.Partial</code> for
126 incoming binary messages, any incoming binary messages must be buffered so
127 the entire message can be delivered in a single call to the registered
128 <code>MessageHandler.Whole</code> for binary messages. The default buffer
129 size for binary messages is 8192 bytes. This may be changed for a web
130 application by setting the servlet context initialization parameter
131 <code>org.apache.tomcat.websocket.binaryBufferSize</code> to the desired
132 value in bytes.</p>
133
134<p>If the application does not define a <code>MessageHandler.Partial</code> for
135 incoming text messages, any incoming text messages must be buffered so the
136 entire message can be delivered in a single call to the registered
137 <code>MessageHandler.Whole</code> for text messages. The default buffer size
138 for text messages is 8192 bytes. This may be changed for a web application by
139 setting the servlet context initialization parameter
140 <code>org.apache.tomcat.websocket.textBufferSize</code> to the desired value
141 in bytes.</p>
142
143<p>The Java WebSocket specification 1.0 does not permit programmatic deployment
144 after the first endpoint has started a WebSocket handshake. By default,
145 Tomcat continues to permit additional programmatic deployment. This
146 behavior is controlled by the
147 <code>org.apache.tomcat.websocket.noAddAfterHandshake</code> servlet context
148 initialization parameter. The default may be changed by setting the
149 <code>org.apache.tomcat.websocket.STRICT_SPEC_COMPLIANCE</code> system
150 property to <code>true</code> but any explicit setting on the servlet context
151 will always take priority.</p>
152
153<p>The Java WebSocket 1.0 specification requires that callbacks for
154 asynchronous writes are performed on a different thread to the thread that
155 initiated the write. Since the container thread pool is not exposed via the
156 Servlet API, the WebSocket implementation has to provide its own thread pool.
157 This thread pool is controlled by the following servlet context
158 initialization parameters:</p>
159 <ul>
160 <li><code>org.apache.tomcat.websocket.executorCoreSize</code>: The core
161 size of the executor thread pool. If not set, the default of 0 (zero)
162 is used. Note that the maximum permitted size of the executor thread
163 pool is hard coded to <code>Integer.MAX_VALUE</code> which effectively
164 means it is unlimited.</li>
165 <li><code>org.apache.tomcat.websocket.executorKeepAliveTimeSeconds</code>:
166 The maximum time an idle thread will remain in the executor thread pool
167 until it is terminated. If not specified, the default of 60 seconds is
168 used.</li>
169 </ul>
170
171<p>When using the WebSocket client to connect to server endpoints, the timeout
172 for IO operations while establishing the connection is controlled by the
173 <code>userProperties</code> of the provided
174 <code>javax.websocket.ClientEndpointConfig</code>. The property is
175 <code>org.apache.tomcat.websocket.IO_TIMEOUT_MS</code> and is the
176 timeout as a <code>String</code> in milliseconds. The default is 5000 (5
177 seconds).</p>
178
179<p>When using the WebSocket client to connect to secure server endpoints, the
180 client SSL configuration is controlled by the <code>userProperties</code>
181 of the provided <code>javax.websocket.ClientEndpointConfig</code>. The
182 following user properties are supported:</p>
183 <ul>
184 <li><code>org.apache.tomcat.websocket.SSL_CONTEXT</code></li>
185 <li><code>org.apache.tomcat.websocket.SSL_PROTOCOLS</code></li>
186 <li><code>org.apache.tomcat.websocket.SSL_TRUSTSTORE</code></li>
187 <li><code>org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD</code></li>
188 </ul>
189 <p>The default truststore password is <code>changeit</code>.</p>
190 <p>If the <code>org.apache.tomcat.websocket.SSL_CONTEXT</code> property is
191 set then the <code>org.apache.tomcat.websocket.SSL_TRUSTSTORE</code> and
192 <code>org.apache.tomcat.websocket.SSL_TRUSTSTORE_PWD</code> properties
193 will be ignored.</p>
194</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>
195
196<p>Prior to the development of JRS-356, Tomcat provided a proprietary WebSocket
197 API. This API has been deprecated in Tomcat 7 and will be removed in Tomcat
198 8. There is unlikely to be any further development of this proprietary API
199 apart from bug fixes.</p>
200
201<p>For information on this API, please see the Javadoc for the
202 <a href="api/index.html?org/apache/catalina/websocket/package-summary.html">
203 <code>org.apache.catalina.websocket</code></a> package. The Javadoc
204 pages are not included with Tomcat binary distributions. To view them
205 locally you would have to download and install "Full documentation"
206 distribution, or build it from sources. You can
207 also read this on the Apache Tomcat web site. Start with the
208 <a href="api/index.html?org/apache/catalina/websocket/WebSocketServlet.html">
209 <code>WebSocketServlet</code></a> class.</p>
210
211<p>There are also several example applications that demonstrate how the
212 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/">
213 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/">
214 code</a>.</p>
215</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
216 on improving documentation for Apache Tomcat.<br><br>
217 If you have trouble and need help, read
218 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
219 and ask your question on the tomcat-users
220 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
221 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
222 The Apache Comments System is explained <a href="./comments.html">here</a>.
223 Comments may be removed by our moderators if they are either
224 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
225 var comments_shortname = 'tomcat';
226 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/web-socket-howto.html';
227 (function(w, d) {
228 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
229 d.write('<div id="comments_thread"><\/div>');
230 var s = d.createElement('script');
231 s.type = 'text/javascript';
232 s.async = true;
233 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
234 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
235 }
236 else {
237 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
238 }
239 })(window, document);
240 //--><!]]></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>
241 Copyright &copy; 1999-2017, Apache Software Foundation
242 </em></font></div></td></tr></table></body></html>