Embedding the jWebSocket Server into Tomcat Web Applications

For Tomcat web applications the jWebSocket Server is provided in two jars, jWebSocketServer-Bundle-<version>.jar and jWebSocketTomcatEngine-<version>.jar files. It contains all the core jWebSocket classes, libraries, plug-ins and filters. You can get this file from the bundles section in the download area.

To use jWebSocket in Tomcat WebApps unpack the archive and copy the jWebSocketServer-Bundle-<version>.jar into the lib folder of your existing Tomcat 7.0.35+ installation. Tomcat will then automatically load jWebSocket and provide its capabilities to all deployed web applications.

Please check that the %JWEBSOCKET_HOME% environment variable refers to the jWebSocket Server root folder in order to re-use existing jWebSocket services or default configuration files.

To start and stop the jWebSocket Server in your web app you require to configure the jWebSocket Tomcat Engine context listener. The context listener method contextInitialized is invoked by Tomcat's servlet engine once the web application has started e.g. when it is deployed the first time or re-started. The contextDestroyed method is called when the web application terminates, e.g. when it is stopped or undeployed.

Also to integrate the Tomcat session management with jWebSocket server you should register a session listener.

The following example demonstrates how to configure you application (WEB-INF/web.xml) for jWebSocket integration:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
    <display-name>jWebSocket Web Application Demo</display-name>
    <context-param>
        <param-name>jws_config</param-name>
        <param-value>${WEB_APP_HOME}WEB-INF/jWebSocket.xml</param-value>
    </context-param>
    <listener>
        <description>Context listener used to start and stop the jWebSocket application server.</description>
        <listener-class>org.jwebsocket.tomcat.ContextListener</listener-class>
    </listener>
    <listener>
        <description>Session management listener</description>
        <listener-class>org.jwebsocket.tomcat.listener.SessionListener</listener-class>
    </listener>
    <servlet>
        <servlet-name>jWebSocket</servlet-name>
        <servlet-class>org.jwebsocket.tomcat.TomcatServlet</servlet-class>
    </servlet>
    ...

The Tomcat engine ContextListener support 3 possible optionaparams:

  1. jws_config: Overrides file path to main configuration file "jWebSocket.xml".
  2. jws_bootstrap: Overrides file path to global jWebSocket Spring IOC configuration file "bootstrap.xml".
  3. jws_home: Overrides JWEBSOCKET_HOME path. For web apps that wants to have independent jWebSocket configurations, this param is suggested. Usage:
...
<context-param>
  <param-name>jws_home</param-name>
  <param-value>${WEB_APP_HOME}WEB-INF/</param-value>
</context-param>
...

Please see https://jwebsocket.org/downloads/jwebsocket-bundles "jWebSocket Web Application Demo" demo for more details.

TomcatEngine configuration
Another step required to embed jWebSocket into Tomcat, is to setup the TomcatEngine in the config file $JWEBSOCKET_HOME/conf/jWebSocket.xml engines section. 
Required configuration example (notice that engine ports requires 0 value):
 
...
<engines>
 <!-- Tomcat Engine Configuration -->
 <engine>
   <name>org.jwebsocket.tomcat.TomcatEngine</name>
   <id>tomcat0</id>
   <jar>jWebSocketTomcatEngine-1.0.jar</jar>
   <!-- keystore file with in ${JWEBSOCKET_HOME}conf -->
   <keystore>${JWEBSOCKET_HOME}conf/jWebSocket.ks</keystore>
   <!-- password to access keystore file -->
   <password>jWebSocket</password>
   <!-- The jWebSocket TomcatEngine can either work in embedded mode 
    or in standard web app mode. In standard wep app mode the 
    jWebSocket Tomcat engine listens on same port like
    Tomcats's http. The http protocol is upgraded to use WebSockets.
    The http/websocket port can be configured via the Tomcat
    configuration in the server.xml configuration file.
   -->
   <!-- set both port settings to "0" (null) if running Tomcat
    Servlet Container for Web Apps and embed jWebSocket library.
    This uses the settings from server.xml, wraps the existing
    Tomcat WebSocket servlet and does NOT instantiate a separate
    embedded engine at run time within jWebSocket.
   -->
   <port>0</port>
   <sslport>0</sslport>
   <!-- these domains are accepted by the engine listening
    on the above mentioned port -->
   <domains>
     <domain>*</domain>
   </domains>
   <!-- default session timeout (minutes) -->
   <timeout>1</timeout>		
   <!-- The default jWebSocket server web-app context. The context can be configured 
    through the files:
    - ${JWEBSOCKET_HOME}/conf/TomcatEngine/conf/context.xml 
    - ${JWEBSOCKET_HOME}/conf/TomcatEngine/conf/web.xml 
   -->
   <context>/jWebSocket</context>
   <!--
    maximum size of the data packet that the engine will read,
    if the frame size is larger than this the connection will be closed.
   -->
   <maxframesize>1048840</maxframesize>
   <!-- maximun number of connections allowed by this engine -->
   <maxconnections>10000</maxconnections>
   <!-- on max connections reached strategy -->
   <!-- close, reject --> 
   <onmaxconnections>reject</onmaxconnections>
   <settings>
     <!-- directory that contains the public web folder path -->
     <setting key="document_root">${JWEBSOCKET_HOME}web/</setting>
     <!-- max threads property value for each tomcat connector -->
     <setting key="max_threads">200</setting>
   </settings>
  </engine>
<engines>
...
 
When jWebSocket runs embedded in Tomcat, almost all the TomcatEngine configurations are discarded since jWebSocket assume the parent Tomcat Web server instance.

The bridge between Tomcat and jWebSocket Server

The jWebSocket tomcat engine uses a WebSocket servlet to process the web app WebSocket messages. The servlet configutation is required:

...
<servlet>
    <servlet-name>jWebSocket</servlet-name>
    <servlet-class>org.jwebsocket.tomcat.TomcatServlet</servlet-class>
</servlet>
...

Comet support in Tomcat

The jWebSocket Tomcat Engine also supports the Tomcat Comet support. To enable Comet in your jWebSocket apps, you must enable the following servlet:

...
<servlet>
    <servlet-name>jWebSocketComet</servlet-name>
    <servlet-class>org.jwebsocket.tomcat.comet.CometServlet</servlet-class>
</servlet>
...

The web apps in order to support Comet requires to do the following.
  1. Import the jWebSocketComet.js file located in res/js/
  2. Execute the following code at the beggining of your script:
if(!jws.browserSupportsWebSockets()){
    jws.enableCometSupportForWebSockets();
}

Implementing WebSocket functionality

To implement your own WebSocket functionality you usually create plug-ins as described here. In the sample above the SamplePlugIn is instantiated and added to the plug-in chain of the TokenServer.

Publications

Learn more about WebSockets in general, get background information and gain deeper insight!

Join jWebSocket

Wether developer, designer or translator – join the jWebSocket team and grow together with our success!

Copyright © 2013 Innotrade GmbH. All rights reserved.