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.
Handshake
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.
Streaming
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:
ws://host:port[/path1[/path2]][;arg1=value1[&arg2=value2]]
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.
siva, and 5 others are discussing. 
Seb is discussing. 
chris campos, 
Steve 3:56 am on October 19, 2010 Permalink |
Thank you!
Steve 5:45 am on October 19, 2010 Permalink |
Hello Puran, thanks again for making this available. I have tried out your posting and have not had success in ‘firing’ the plugin, hope you can help.
First, some notes:
a) I belive the main class for the eclipse project is not org.jwebsocket.console.JWebSocketServer (as posted above) but org.jwebsocket.console.JWebSocket
b) the posted snippet for the override xml has a spurious bit of html in line #2: that needs to be removed
c) the posted snippet of your Eclipse project lists two java files: HelloWorldPlugin.java and RandomData.java; however the downloaded project contains: HelloWorldPlugin.java and CustomInitializer.java?
I was able to build and run the project after making the change to what the main class should be and the engine seems to fire up just fine. Here is the console output:
jWebSocket Ver. 0.9.0.0503 beta
(C) 2010 jWebSocket.org by Innotrade GmbH, Germany, Herzogenrath
Distributed under GNU GPL License Version 3.0 (http://www.gnu.org/licenses/gpl-3.0.html)
JWEBSOCKET_HOME variable not set, using default configuration...
2010-10-19 16:01:41,202 DEBUG - SecurityFactory: Initializing demo rights, roles and users...
2010-10-19 16:01:41,207 INFO - SecurityFactory: Default rights, roles and users initialized.
Engine tcp listening on port 8787, default (sub)prot json, default session timeout: 120000, log-level: debug
2010-10-19 16:01:41,210 DEBUG - TCPEngine: Starting TCP engine...
2010-10-19 16:01:41,228 INFO - TCPEngine: TCP engine started.
2010-10-19 16:01:41,239 DEBUG - SystemFilter: Instantiating system filter...
2010-10-19 16:01:41,239 DEBUG - TokenFilterChain: Adding token filter systemFilter...
2010-10-19 16:01:41,242 DEBUG - SystemPlugIn: Instantiating system plug-in...
2010-10-19 16:01:41,243 DEBUG - RPCPlugIn: Instantiating rpc plug-in...
2010-10-19 16:01:41,244 DEBUG - StreamingPlugIn: Instantiating streaming plug-in...
2010-10-19 16:01:41,248 DEBUG - FlashBridgePlugIn: Starting flash bridge...
2010-10-19 16:01:41,249 INFO - FlashBridgePlugIn: flash bridge started.
2010-10-19 16:01:41,250 DEBUG - JWebSocket: Starting token server...
2010-10-19 16:01:41,250 INFO - TokenServer: Token server started.
2010-10-19 16:01:41,253 DEBUG - TimeStream$TimerThread: Starting time stream...
2010-10-19 16:01:41,254 DEBUG - MonitorStream$MonitorProcess: Starting monitor stream...
2010-10-19 16:01:41,254 DEBUG - JWebSocket: Starting custom server...
Which is good, but I haven't been able to successfully add the 'HelloWorldPlugin' to the plugin chain (as you can see in the above there are no messages corresponding to:
System.out.println("Engine Started on Hello World Plugin");
and the like (I've added a few log4j debug statements of my own)
Here is what I added to your project's jWebSocket.xml file (in ):
com.plugins.HelloWorldPlugin
jws.custom
com.plugins.custom
jWebSocketCustom-0.10.jar
ts0
Do you have any suggestions as to where I have gone wrong with this? I am guessing I haven't configured the override xml file properly. Or possibly, when running the -config wasn't done right (although I tried to follow your post exactly in terms of providing the full path to the file: -config /Users/stevexm/Documents/workspace/JWebSocketApp/conf/jWebSocket-override.xml
Thanks in advance, Steve M
purans 3:09 am on October 20, 2010 Permalink |
Hi Steve,
sorry for that i got trick by the same file name and uploaded the old zip package.. i have replaced with the new one and i tested it myself in eclipse and it works!!
I am not sure about JWebSocket.java, because we only have org.jwebsocket.console.JWebSocketServer as the main class now i think it’s because of the old jar .. i remember we used to have that name before..
try this one, it will work now.
Fernando 7:08 am on October 20, 2010 Permalink
Follow up of my previous comment:
UTF-8
UTF-8
best regards,
Fernando
Steve 6:30 am on October 21, 2010 Permalink
Many thanks for the quick turn-around…much appreciated!
siva 8:47 pm on August 22, 2011 Permalink
Hi Purans! Thanks for the posting. However, I have two things in my eclipse.
1. Complete source code that is set with JWEBSOCKET_HOME.
2. I download this source code and integrated with eclipse as separate project.
When I run your server side plugin example, I got an error
>>
WebSocketException during jWebSocket Server startup: Either JWEBSOCKET_HOME variable is not set or jWebSocket.xml file does neither exist at %JWEBSOCKET_HOME%/conf nor at %CLASSPATH%/conf.
>> Pls can you tell me where is problem?
Thanks again
guest 3:02 pm on November 8, 2010 Permalink |
Thanks for good guide.
but, i have no idea…
———————————-
and in the arguments tab provide the -config argument value as the full path of your jWebSocket.xml file as
-config [MY-PATH]/jWebSocket-override.xml
———————————-
where can i set that line?
1. Run as -> Run Configuration
2. Arguments Tab
Program arguments?, VM arguments? where?
when run my application, eclipse displays below line in console…
———————————-
WebSocketException during jWebSocket Server startup: Either JWEBSOCKET_HOME variable is not set or jWebSocket.xml file does neither exist at %JWEBSOCKET_HOME%/conf nor at %CLASSPATH%/conf.
help me, plz…
Lukasz 1:30 pm on January 22, 2011 Permalink |
Hello im trying to make my own plugin, but im using netbeans. I’ve managed to configure and run the project but there is a problem with proper path to config file.
I did it like that:
-config /Users/lukasz/jWebSocket.xml
but when im trying to run the project it says:
Log files per default in jWebSocket.log if not overwritten in jWebSocket.xml.
WebSocketException during jWebSocket Server startup: Either JWEBSOCKET_HOME variable is not set or jWebSocket.xml file does neither exist at %JWEBSOCKET_HOME%/conf nor at %CLASSPATH%/conf.
BUILD SUCCESSFUL (total time: 0 seconds)
What i did wrong ?
Lakiesha 3:26 am on August 24, 2011 Permalink |
Wait, I cannot fathom it being so starightofwrrad.
jWebSocket 4:54 pm on September 8, 2011 Permalink |
There is a video tutorial available on our site which explains in details how to import the jWebSocket maven project into Eclipse.
Please refer to our Documentation section, click developer guide and select “Eclipse”.
Thanks,
Alex