First steps with jWebSocket – open source Java framework for WebSockets – installation and running samples

This month, In have been delving into Push architectures for the Web, looking into WebSockets among several other things. WebSockets, a fairly new standard (!) evolved along with HTML 5, specifies a communication protocol that provides an alternative to classic HTTP communication. WebSocket based interaction has lower overhead and – more importantly – is bi-directional which means that push from server to client is really supported (and not just emulated through poll, long poll or streaming responses as is currently the case in comet push style frameworks).

All modern browsers provide support for the WebSocket specification – meaning they can communicate based on the WebSocket protocol (ws:// and wss:// in addition to http:// and https://) and they implement the WebSocket client side (JavaScript) APIs. These API are well defined – http://dev.w3.org/html5/websockets/ – and seem to be truly standard across all browsers.

The WebSocket server side is at this moment not very well defined. Other than the fact that the communication over ws:// and wss:// should be handled by a server, not much has been decided about the server side of WebSockets. Currently, WebSockets is not supported in classic JEE servers although such support seems imminent with JEE 7 through the Servlet 3.1 specification (JSR 340, http://jcp.org/en/jsr/summary?id=340; also read http://antwerkz.com/websockets-and-java-ee/ on how WebSockets my be included in the Servlet API). Initial support for WebSockets has been shown in Jetty and GlassFish, with other JEE containers undoubtedly following suit in next 18 months or so. In the meanwhile, several stand alone WebSocket servers have been released, including Kaazing (a commercial offering which I mentioned in two earlier articles: https://technology.amis.nl/blog/14755/get-going-with-kaazing-websocket-gateway-html5-edition-installing-locally-and-running-demos and https://technology.amis.nl/blog/14777/push-based-synchronized-slideshow-web-application-implemented-using-websockets-and-kaazing-websocket-gateway) and jWebSocket (an open source offering – http://jwebsocket.org/), that I will introduce in this article.

These WebSocket servers are capable of handling WebSocket interaction with a variety of clients – well, the server should not have to care about the type of client but only about the communication. How the WebSocket server should relay WebSocket messages received from a client to a back end service is not well defined, at least not in a standardized way. Vice versa: how back end services can deliver their push messages and events – chat message, JMS message, mail reception, RSS entry, Tweet, database update, business event … – to the WebSocket server for onward routing to interested clients is not covered by an existing standard either. Even integration of WebSocket interaction into regular JEE Web Applications is very much in question. Kaazing spokesmen even suggested that perhaps WebSocket communication provides the foundation for a whole new type of application in which traditional JEE application servers are no longer needed (see: http://www.businesswire.com/news/home/20111019005426/en).

Well, before going to deep into these discussions, let’s take a look at how we can get the jWebSocket server going to at least run a few demo application on our local machine (or at least my local environment).

Step one is downloading the jWebSocket distribution. I downloaded zip-file http://jwebsocket.googlecode.com/files/jWebSocketServer-1.0-nb20105.zip and extracted it to my local c:\temp directory (on Windows 7) – (~26.7 MB).

Furthermore: The jWebSocket Server is based on pure Java technology. Ensure that you have the Java Runtime Environment (JRE) 1.6 or higher installed and that the JAVA_HOME environment variable refers to the root folder of this Java installation. For my Windows environment I also hadd to add the path to java.exe to the PATH environment variable.

The environment variable JWEBSOCKET_HOME needs to be set, referring to the directory where the jWebSocket archive was exploded and specifically to the directory that includes the bin directory. In my case: C:\temp\jWebSocketServer-1.0b1\jWebSocket-1.0.

To start the stand alone jWebSocket server, run the jWebSocketServer.bat batch in the bin folder either from the command shell or the Windows Explorer.

A console window appears:

The configuration for jWebSocket is done through the file jWebSocket.xml in the conf directory. This file includes engines, servers, plug-ins, filter, rights, roles and users as well as logging.

The server is ready and we can try to run the demos that ship with jWebSocket. Well, that is if we download and install these samples.

The download page for jWebSocket has a second download link – in addition to Server – for Client. This download is a zip-file of just over 8Mb that contains a substantial number of samples that communicate with the locally installed jWebSocket server over the WebSocket protocol.

I have extracted the download client zip file into the directory that also contains the jWebSocket server home. The exploded directory structure is shown below.

Many of these samples are simple, static HTML documents that perform WebSocket interaction from JavaScript.

Let’s run the hello_world demo:

The static html file hello_world.htm is opened in the browser. In this case I have clicked on Login – to create the communication channel with the jWebSocket server. Then I typed a message – Let me tell you a story – and clicked on broadcast. Finally I clicked on GetTime. The communication taking place over WebSockets is illustrated in the log window.

There is an easy way to verify whether the browser does indeed communicate with the jWebSocket server, through the use of the Java Client GUI that is shipped with the jWebSocket server:

The GUI opens.

I click Connect, type a message – My message to you – and click on Broadcast:

In the browser client, a message is received when the client connects. Subsequently, the message is received. Another message is sent from the browser – Let me tell you another story. That message is received in the Java Client as can be seen in the image above.

This demo shows how a Java Client through the client APIs does web socket communication with the jWebSocket server and how its messages are pushed to the HTML/JavaScript web client.

Another fun demo is the canvas demo (demos\canvas\canvas.htm):

This page is opened in two different browser windows. When the user starts painting in one of the canvases – I did so in the canvas on the bottom right -, events are communicated via WebSockets to the server and from there to the jWebSocket server and the other clients. The browser clients process these messages by synchronizing the other canvases with the one painted on:\

Note that jWebSocket ships with a wide variety of samples – demonstrating many ways of using WebSockets and the jWebSocket server on conjunction for example with JMS, XMPP, Mail, JDBC, and many more.

I am looking forward to further explorations with jWebSocket.

Resources

jWebSocket.org – http://jwebsocket.org/ with documentation, how to documents, downloads etc.

blog article on how to get going with jWebSocket – http://blog.jwebsocket.org/2010/05/22/jwebsocket-step-by-step-part-1/

Documentation on integrating jWebSocket into existing Java Web Applications running on JEE Servlet Containers – https://www.jwebsocket.com/quickguide/qg_appserver.htm

http://java.sg/category/websockets/ – blog on jWebSockets and Tomcat – in progess