Hello All, because of the lot of questions asked by our users in jwebsocket forum regarding server side plugin development, i would like to list the simple eclipse based java project that uses jWebSocket and other jars as well as custom configuration to write a jWebSocket custom plugin in a separate small eclipse project. This also applies to any other IDE with few minor differences.

Download all the jWebSocket jars from our repository http://code.google.com/p/jwebsocket/downloads/detail?name=jWebSocketServer-0.10.zip&can=2&q= and all the dependency jars, if you are so impatient below is the snapshot of my eclipse project with hello world plugin.

So the above snapshot is the simple java project, which has jwebsocket and other libraries. Only thing that needs attention is jWebSocket.xml file in the conf folder, which is what we used to override the xml file that comes with jWebSocketServer.jar. In your conf/jWebSocket.xml jar you have to define your custom plugin say


NOTE that even though we are not using jar for our custom plugin you still have to specify it because of the known issue in jWebSocket.

Now to start the jWebSocket server you have to specify the jWebSocket main class in eclipse, From the eclipse menu select:

Run ->Run Configurations, then select Java Application which more or less looks like the snapshot below.

Specify the main class as org.jwebsocket.console.JWebSocketServer and in the arguments tab provide the -config argument value as the full path of your jWebSocket.xml file as

-config /Users/puran/project/JWebSocketApp/conf/jWebSocket-override.xml

After that you can select Run->Your application configuration name above.

Here is the sample eclipse project which you can download and get started easily http://code.google.com/p/jwebsocket/downloads/detail?name=JWebSocketApp.zip&can=2&q=

I hope this will be helpful. Feel free to ask any questions or comments.

jWebSocket can be used as a maven dependency if you are using it in maven projects.

First define the repository in your pom.xml file as:

  <name>jWebSocket Repository</name>

And define the dependencies for jWebSocket modules:


This is it!! Also to run the server with default configuration file. Use maven exec

mvn exec:java

It should start the jWebSocket server with the default configuration. If you want to override the xml configuration with yours you can use -config xml_file_path, argument

An Overview by Alexander Schulze
Translation from German by Predrag Stojadinović

jWebSocket instead of XHR und Comet?

Starting with Chrome version 4.0.249, Google delivered the first browser that supported HTML5 WebSockets based on the W3C and IETF standards, Safari 5 catched up and other browsers will follow quite quickly. In contrast to XHR and Comet, WebSockets are bidirectional and resource-saving and are perfectly suited for server-to-client streaming (S2C) and client-to-Client Communication (C2C) – such as a ticker, chat, online collaboration, or even gaming applications. jWebSocket provides this new technology as an open source library that can be easily integrated into any application, together with an extensive documentation and all of this is available under the LGPL license.

jWebSocket is a full-duplex high-speed communications solution for the HTML5 Web. This consists of a native Java WebSocket server and a JavaScript WebSocket client without the need for any special plugins. Additional Java clients for desktop applications, such as Swing, as well as Java ME are already available. An Android client is currently under development. The project is completely open source and is released under the GNU LGPL License 3.0. jWebSocket is designed to run in as many environments as possible. Thus, the pure Java server both runs as a stand-alone service or can be integrated as a library in any web application under Tomcat, JBoss, Jetty or GlassFish web servers. On the server side there is only one JAR to be included and on the client side, a single JavaScript file is enough.

jWebSocket includes the WebSocket-protocol implementation, a session management with authentication, a security factory with authorization and access control as well as timeout control and keep-alive. In addition, there are processors for various formats such as JSON, CSV or XML, a streaming API with links to external data pumps, remote procedure calls (RPC) and a flexible plug-in concept for your own WebSocket business logic. Extensible filters provide security and comprehensive control over the data flow. For enterprise applications, multiple WebSocket servers can be connected to a cluster.

Benefits of WebSockets

Benefits and advantages of the WebSocket communication are clear: the use of TCP rather than HTTP removes not only the known AJAX, Comet and XHR request/response mechanism overhead but, apart from the initial handshake, the entire HTTP overhead as well. This leads to shorter latencies and higher bandwidth. While with HTTP, one channel is used to receive data while a second one is used to send data, with WebSockets there is a truly full-duplex communication on a single TCP socket. Therefore, a WebSocket server can manage twice as many simultaneous connections as the existing alternative approaches. On the client side, the jWebSocket JavaScript class provides simple and HTML5 standard events for processing incoming data packets and handling opening and closing of connections. Complicated browser-specific polling and/or buffering mechanisms are completely omitted.

So far (as of June 2010), WebSockets are available in Google’s Chrome browser since version 4.0.249 and 5+ and indirectly by using the Chrome Frame plugin in Internet Explorer versions 6, 7 and 8. Safari is based on the WebKit engine just like Chrome, and with Safari 5 Apple catched up in the race. Opera 10 supports HTML 5 extensively, only WebSockets are missing. Mozilla plans to support WebSockets in one of the next upcoming Firefox versions. However, due to the immense advantages of WebSockets, probably none of the major browser vendors will skip the implementation of WebSockets. For all browsers that do not natively support WebSockets, jWebSocket provides a FlashBridge which is completely transparent to the application. A WebSocket-based chat example application is available at jWebSocket.org.


As with the known XMLHttpRequest, the WebSocket client also needs to connect to the server first. And also like a web server a WebSocket server cannot inititate a connection to a client by himself. However, unlike the HTTP specification, after a proper handshake exchange, the connection remains opened in both directions. Instead of the http protocol, the client initiates a connection via the new ws protocol (ws://domain.tld:port/path;arguments).

Once the TCP socket connection is established, the client sends a header in the form:

GET <path> HTTP/1.1
Upgrade: WebSocket
Connection: Upgrade
Host: {hostname}:{port}
Origin: http://{host}[:{port}]
[Sec-WebSocket-Key1: {secure key1}*]
[Sec-WebSocket-Key2: {secure key2}*]

[8 bytes generated security key3 *]

Whereupon, the server completes the handshake as follows:

HTTP/1.1 101 WebSocket Protocol Handshake
Upgrade: WebSocket
Connection: Upgrade
[Sec-*]WebSocket-Origin: http://{hostname}[:{port}]
[Sec-*]WebSocket-Location: ws://{hostname}:{port}/

[16 bytes generated MD5 sum*]

* In terms of Sec-WebSocket Handshake fields please refer to http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76.

Once the client accepts the handshake the two parties can exchange data bidirectionally over a single socket-channel. Although, one may argue about the reasons why any such WebSocket “protocol” was defined and why not simply use an unregulated socket connection between the browser client and the server. First and foremost, there are security reasons, so that we securely can control cross-domain requests.

Tokens – Communication and data formats

Once the TCP connection is established, client and server can basically exchange any data packets, either text or binary. As of mid of June 2010 the binary format is not yet ultimately specified, but it is abstracted already by jWebSocket. jWebSocket provides on both client and server side low-level classes that allow the implementation of a completely proprietary protocol. Usually, the packages must be interpreted on both sides in order to understand questions and answers. Therefore in jWebSocket the overlying layer protocol known as tokens was implemented. These are objects – simple or complex – with fields and their values. The tokes can be sent in JSON, CSV or XML formats. For the CSV format it has to be taken into account that this line based format supports only “flat” objects, e.g. objects with simple data types, and no complex data structures.

Request/Response with WebSockets

Even though with WebSockets the known HTTP request/response mechanism is missing, the client requests still must be answered sometimes by the server. For example, the sender of a message is expecting a reply to see if the message was received and processed. Further, commands require some result to be returned or at least an error message. Even in the case of server exceptions the client should be informed in order to react appropriately.

In contrast to XHR, messages sent with WebSockets are always answered asynchronously, because JavaScript in this case does not support any blocking calls. The response to a request is received by the client through the onmessage event of the WebSocket class. Due to the multi-threaded implementation of the server, the requests can either be processed sequentially or in parallel within their own thread. In the first case, this means that the server first processes and answers a message completely before the next message is taken from the pool. In this case, then, the sequence of responses corresponds to the sequence of requests. In the second case, a separate thread is instantiated for each request, which means that the results can arrive in a different order back to the client than the order in which they were sent. In order for the client to properly sort and understand the received answers, each sent token is assigned a unique token ID. This is all properly handled by the library.

One-Way Token

Particularly in streaming applications, the client is not required to confirm to the server the arrival of every data packet. In addition, the client also requires no response from the server on a close message when the page is exited. These cases, where the sender does not expect any response from the recipient, are supported in jWebSocket with the so-called one-way tokens.

First launch and integration into your own applications

After the files are downloaded, there is an executable JAR for a standalone server as well as a complete demo site. This provides an immediate feeling of success without the need for any web server or other installations. If you need the jWebSocket server to run as a service, there is a ready to use Java service for both 32bit and 64bit environments. This is a great solution for production systems. In the same way, the jWebSocketServer.jar can easily be integrated into any existing web application, e.g. based on Tomcat. Many examples with full source code are available for download on jWebSocket.org. Through custom plug-ins, anyone can quite easily extend the existing functionality of the jWebSocket library. A frequently visited forum provides support in case of questions or suggestions for improvement.

Developing Plug-ins

The jWebSocket core provides only the basic functionality – besides the protocol-handling, among other things, there is also the interpretation and generation of the JSON, XML or CSV tokens. The implementation of the actual application logic is done using plug-ins. Many plug-ins are already developed and included in the jWebSocket library. Among these are the System Plug-In, which provides the functionality for authentication and also session management and timout controls and the RPC plug-in provides remote procedure calls functionality. There is also the streaming plug-in for streaming functionality and last but not least the FlashBridge plug-in to provide WebSocket functionality for cross-browser-compatibility. Developers can easily modify these existing plug-ins or can simply create their own plug-ins. A blank template plug-in and a demo template are available for this purpose. The API is very simple and limited to only a few methods which are used to intercept and answer any incoming token.

The jWebSocket model allows for many plug-ins to be chained together and to delegate tokens to each other as needed. This allows larger teams to work on the same project and in the end easily build together their individual plug-ins in the overall project.


For streaming applications, there are two essential types of data distribution to be distinguished: one-way and multi-data streams. While in financial market or news tickers, the mission is to broadcast one or more either self-generated or third-party supplied data streams simultaneously one-way from the server to multiple clients, for online collaboration and online games it is rather important to spread events on the various Clients as quickly as possible to all other clients, which from the server’s perspective is a bidirectional communication.

jWebSocket provides the ability to manage multiple streams on the server, to which a client can easily register. For internal or external one-way data flows, an API is ready to link arbitrary streams to the server to be distributed to the registered clients.

For online collaboration and games, the clients themselves provide the data for the pumps or the server-side streams. Streams provide a queue in a separate thread, which receives all incoming messages and queues them to be broadcasted to the registered clients. The demo packages contains a timestream which simply broadcasts the current time to all clients by using the jWebSocket streaming API. You also can check it out that on the jWebSocket web site.

Connection Control and Keep-Alive

Usually WebSocket clients will be disconnected from the server after a certain communication inactivity – this is an essential mechanism for the server to release ports that are no longer used by crashed or inactive clients. For applications where the user basically only receives the data – e.g. for news or financial market tickers – such a session timeout may be impractical. For such applications, jWebSocket provides a keep-alive mechanism in order to ping the server at configurable intervals. This tells the server that the browser is still there and to keep the connection. The client may, in the same way, check if the server is still online. In case of network failures, the client can restore the connection automatically, without any data loss in the observed stream.

URL parameters

Similarly to the HTTP Clients, the jWebSocket Client can pass parameters to the server on connection through the connection URL. The URL is of the form: ws://host:port[/path;arguments]. The additional content after the port number is not specified by the WebSocket protocol. The jWebSocket library provides this URL arguments functionality by respecting the well known HTTP protocol format:


For your own purpose it is of course possible to simply use your own format and pass whatever data you wish and then interpret the entire connection URL in your application.

The jWebSocket server uses this methodology, for example, to temporarily select the data format (JSON, CSV or XML) until all browsers do support the [Sec-]WebSocket-Protocol to specify the desired sub-protocol in the handshake. Since the very first token, after the connection is established, must be of a certain format, the URL parameter is currently the way for the client to communicate the desired token format to the server. Since the server internally manages the tokens as objects, the clients can connect and use different data formats and still properly communicate with each other.

Remote Procedure Calls

Because of their faster response behavior in contrast to XHR, WebSockets offer a better basis for the so called remote procedure calls (RPC), the ability for the clients to make calls to the server methods. The existing jWebSocket RPC plug-in already offers an easy way from the client to access methods of shared Java classes on the server with the same arguments and to receive the results. On jWebSocket.org you will find an example of how an MD5 checksum is calculated on the server from an arbitrary string and returned to the client via RPC. Of course, the included SecurityFactory provides you a fine granulated control of who is allowed to run which remote procedure.

Conclusion and outlook

Certainly WebSockets will not replace the established Web 2.0 concepts tomorrow. Also ws:// will not replace http://, but enrich it. For every kind of previously servlet based communications and streaming applications the TCP WebSockets will prevail against HTTP-based approaches such as comet and polling. jWebSocket allows you to speed-up your applications step-by-step and makes porting calculatable and predictable.

For enterprise applications, the jWebSocket team is already working on a cluster solution which is already taken into account by the model. Tokens will be routed across multiple nodes of a cluster, which theoretically allows implementation of clusters of any size. There is an extensive documentation available, as well as complete demo applications and the full Java and JavaScript source code. And these can all be downloaded free of charge. Since the library is Open Source, any contributions are welcome. The jWebSocket library is distributed under the LGPL License at http://jwebsocket.org.

Alexander Schulze

Founder of the project jWebSocket, IT consultant and trainer for IT professionals.
He is a speaker at various conferences and author of several articles and books and
provides advise to companies relating database, communication and web technologies.

This is the first part of the series of articles that i will write to cover the basics of jWebSocket Project, so that the users or developers can download the project and start using it either with the default features that comes with jWebSocket or with customized functionality on top of jWebSocket platform. Project jWebSocket is an open source Java and JavaScript implementation of the HTML 5 WebSocket protocol with a huge set of extensions. You can find more details about the architecture and different server concepts on our site http://jwebsocket.org. The aim of this article is to focus more on how to use it and get started and understand the various nitty gritty of jWebSocket usage.

So, how do i set it up quickly and run it?? Well, if you cannot wait at all then we have few demos in our product site that you can try without even bothering to set it up in your machine. But, if you want to try the thick and thing here are steps to follow:

Download the latest zip file jWebSocketServer-0.9.0.zip from here for the server and jWebSocketClient-0.9.0.zip from here. After you download and extract it you will see the folder structure like this.
jWebSocket Folder Structure
As you can see there are basically 4 folders
  • bin  – contains the batch file to run the server
  • conf – contains the configuration file ‘jWebSocket.xml‘, I will discuss more about it later.
  • libs – this folder contains all the jar files of different modules in jWebSocket, bundle jar and war for web application.
  • logs – folder that contains log settings.
Similarly for client, you will see the demos html file and javascript files. Now we have two options or modes to run jWebSocket

1. Standalone Server – Whichever mode you want to use, first set the environment variable JWEBSOCKET_HOME to the base location of your jWebSocket-0.9.0 folder(eg: /Users/puran/jWebSocket-0.9.0). To run as stand alone server, simply execute the batch/script file  from the bin directory of the jWebSocket folder. If every thing is honky dory your stand alone server should start successfully at port 8787. My Console looks something like this.

Now to test our stand alone jWebSocket server open any of the demo html files from jWebSocketClient-0.9.0 package you downloaded above. For example if I open file like file:///Users/puran/projects/jwebsockets/jWebSocket/jWebSocketClient-0.9.0/demos/chat/chat.htm then you should be able to login to the chat window as shown below.

2. jWebSocket embedded in Web Application – This option allows you to run jWebSocket Server as an web application in your Tomcat server so that it’s easier to integrate with other web applications.To do this simply copy the jWebSocketAppSrvDemo-0.9.0.war file from JWEBSOCKET_HOME/libs folder to the webapp folder of your tomcat installation. Now copy the jar file jWebSocketServer-Bundle-0.9.0.jar from the same libs folder to the lib folder of your tomcat. This single bundle jar bundles all the required libraries to run jWebSocket. Now at this moment we will not change any configuration whatsoever and just run with the default settings and configuration. Start your tomcat server and point your browser to http://localhost:8080/jWebSocketAppSrvDemo-0.9.0/. If everything is setup properly then you should see the home page with few demos.
So in this very first part we tried to get a quickstart run of jWebSocket. In the second part which will write shortly we will try to understand little bit more about our javascript client library and write our own simple client application that uses the default functionality of jWebSocket server. I hope all of you will find this article helpful in understanding very basics of jWebSocket. Please feel free to send feedbacks or any comments you have in mind.

Hello, we finally got rid of the JavaScript “eval” function by replacing it by either a new native JSON object or automatically embedding the json.org JSON library for browsers that don’t support the JSON class yet. jWebSocket now supports the full JSON capabilities on all common browsers. Nightly build v0.8.5.422 available at http://code.google.com/p/jwebsocket/source/browse/#svn/trunk/jWebSocketExecutables.

Dear jWebSocket developers and users – lots of enhancements and extensions available

in the latest jWebSocket release v0.8.5 we introduced the jWebSocket.xml configuration file. jWebSocket now reads users, rights and roles on startup. It will be extended to configure engines, servers and plug-ins as well. We also improved the streaming functionality. jWebSocket now supports multiple streams. In addition to the timestream demo we now provide a rudimentary monitor stream to track various system parameters.
We introduced the SecurityFactory class for access control. The JavaScript Client has been minimized to 12kb (41kb unzipped) and the code was checked and verified by JSLint.com. The new simplified logon method combines open and login in a single call and log files use buffered IO which significantly increases performance. We extended the Java Docs and introduced first JS Doc for jWebSocket JavaScript Client.

Let us know what you miss most. Best Regards, Alex, a.schulze@jwebsocket.org


Get every new post delivered to your Inbox.