Table of Contents
This chapter describes the concepts, functions, and configurations of the WebSocket container.
The WebSocket container is included in the web engine and one exists for every web context. To use the WebSocket container, the <websocket> setting must be configured in jeus-web-dd.xml.
The WebSocket container provided by JEUS complies with JSR 356 and Java API for WebSocket. Thus, the server's WebSocket service must be written according to the API defined by the relevant standard. But, this document does not include detailed information about WebSocket RFC6455 and Java API for WebSocket standards.
1. Since the HTML5 WebSocket API is a client library, it is irrelevant to WebtoB and JEUS.
2. The Java API for WebSocket is included in Java EE 7. When developing with references to the Java EE 6 API classes, the WebSocket API cannot be referenced. In this case, the 'lib/system/javaee.jar' file must be set to the classpath. The javax.websocket package is included in the classpath.
The basic functions of the WebSocket container are to deploy WebSocket Server Endpoint objects included in the web context and connect a WebSocket Handshake request from the client to a Server Endpoint object that it maps to. Once a client and a WebSocket container are connected, WebSocket sessions are created and the life cycle of the session objects are also managed.
The role of a service developer is to implement a WebSocket Server Endpoint class(javax.websocket.Endpoint) and a configuration class(javax.websocket.server.ServerApplicationConfig), and package them into the web application.
The following are the constraints for using WebSocket containers in JEUS 7.
Only available for the HTTP listeners. Thus, it is recommended to use then with the reverse proxy function of WebtoB 4.1.8 or later. Detailed information about WebSocket support in the WebtoB reverse proxy function, refer to the WebtoB guide.
The <websocket> configuration must be added to jeus-web-dd.xml.
The client API provided by the Java API for WebSocket standard is not supported. The client API needs Java SE 7. Since JEUS 7 is based on Java EE 6 and is compiled using Java SE 6, the client API cannot be provided. Calling a method that is in the client API will trigger a java.lang.UnsupportedOperationException.
The client APIs are javax.websocket.WebSocketContainer#connectToServer() methods.
This chapter describes the additional functions of the WebSocket container.
A WebSocket container provides space in memory for storing data per WebSocket session. The map object(hereafter UserProperties) obtained by calling the javax.websocket.Session.getUserProperties() API contains the data.
Assume that WebSocket applications(web context including the WebSocket Server Endpoint) are deployed to two different servers. If data are saved in the UserProperties by using the WebSocket and the server is abnormally terminated, all data will be lost. However, if the data are backed up on another server, the UserProperties can be recovered by connecting the WebSocket to the backup server even if the server is abnormally terminated. From the user perspective, the WebSocket service can be used seamlessly. This is called WebSocket Session Failover or Distributed WebSocket Session.
The following conditions must be met in order to use this function.
WebSocket Session Failover operates based on the HTTP session service. A WebSocket application must be deployed to the HTTP session cluster. For detailed information about HTTP session cluster, refer to JEUS Session Management Guide. "2.6. Clustering" and JEUS Session Management Guide. "2.8. Session Clustering".
The following must be added to the jeus-web-dd.xml configuration file of the WebSocket application.
<websocket>
<distributed-session enabled="true"/>
</websocket>
In general, the WebSocket Session and HTTP Session are not integrated for use.
Data in the UserProperties object must be serializable.
WebSocket connection is initiated by an HTTP request. The cookie header of the WebSocket Handshake request must include the JSESSIONID. The HTTP session that the JSESSIONID points to must be created in the web context that the server endpoint belongs to.
For instance, when the JSP that calls the HTML5 WebSocket API is called, the HTTP session is created to send JESSIONID to the cookie header. When HTML5 WebSocket JavaScript is executed in the web browser, the WebSocket Handshake request is sent to JEUS. The cookie header must be included in the request header. WebSocket Session Failover cannot be used If a WebSocket Client, which does not support this, is used.
[Reference]
Currently, FireFox 30.0 attaches the cookie header to the WebSocket Handshake request when HTML5 WebSocket API is used.
GET /service/chat HTTP/1.1 Connection: keep-alive, Upgrade Cookie: JSESSIONID=FheDy8e0bOTPO7KNqdeJ7Eps8j51CaQqcRWHvpYo9mdVw1BCSwlwrFiyrclsolkr.amV1czcvc2VydmVyMg== Sec-WebSocket-Key: Csv/FCQo1g1eZfqMtPd8+g== Sec-WebSocket-Version: 13 Upgrade: websocket User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:30.0) Gecko/20100101 Firefox/30.0 FirePHP/0.7.4
When this function is used with the WebtoB reverse proxy, the session routing must be configured in the reverse proxy configuration. For detailed information, refer to the WebtoB guide.
Note the following when using this function.
The HTTP session's timeout and the WebSocket session's timeout are not related. Especially in the case of a WebSocket session, since it is dependent on the HTTP session, the HTTP session properties cannot be modified from the WebSocket container level. When serializable data are added(put) to the UserProperties object, depending on the circumstances the HTTP session can time out first which prevents failover from occurring. HTTP session's timeout must be adjusted appropriately taking such situations into consideration.
If the HTTP session times out when adding(put) serializable data to the UserProperties, a WARNING level message will be logged.
The UserProperties of WebSocket sessions are not shared between different web contexts.
Configure the WebSocket container settings in jeus-web-dd.xml of each web application.
[Example 6.1] Web Context Configuration File: <<jeus-web-dd.xml>>
<jeus-web-dd xmlns="http://www.tmaxsoft.com/xml/ns/jeus" version="7.0">
<websocket>
<max-incoming-binary-message-buffer-size>8192</max-incoming-binary-message-buffer-size>
<max-incoming-text-message-buffer-size>8192</max-incoming-text-message-buffer-size>
<max-session-idle-timeout-in-millis>1800000</max-session-idle-timeout-in-millis>
<monitoring-period-in-millis>300000</monitoring-period-in-millis>
<blocking-send-timeout-in-millis>10000</blocking-send-timeout-in-millis>
<async-send-timeout-in-millis>30000</async-send-timeout-in-millis>
</websocket>
</jeus-web-dd>
The following describes each configuration tag.
| Tag | Description |
|---|---|
<max-incoming-binary-message- buffer-size> | Maximum size of the buffer used for binary messages transmitted from the client. If the message size is larger than this value, the 1009 error occurs and the WebSocket session is closed. |
<max-incoming-text-message- buffer-size> | Maximum size of the buffer used for text messages transmitted from the client. If the message size is larger than this value, the 1009 error occurs and the WebSocket session is closed. |
<max-session-idle-timeout- in-millis> | Timeout for closing idle WebSocket sessions. If the value is larger than zero and smaller than 1000, it is set to 1000. (Default value: 30 minutes (1800000ms)) |
| <monitoring-period-in-millis> | Cycle for checking the WebSocket session timeout. If the value is smaller than 1000, it is set to 1000. (Default value: 5 minutes(300000ms)) |
| <blocking-send-timeout-in-millis> | Timeout for waiting for a synchronous send. Applied when using javax.websocket.RemoteEndpoint.Basic. (Default: 10 seconds) |
| <async-send-timeout-in-millis> | Timeout for waiting for messages awaiting to be sent asynchronously. The server session where the timeout occurred is closed instead of canceling each timed out messages. Applied when using javax.websocket.RemoteEndpoint.Async. |
| <websocket-executor> | Thread pool related settings used by the WebSocket container. This is usually used to process asynchronous sends. |
| <distributed-session> | WebSocket Session Failover related settings depending on what is defined in the javax.websocket.Session.getUserProperties() method. To use WebSocket Session Failover, the enabled attribute must be set to 'true'. |