jWebSocket Headquarter

Innotrade GmbH

An Vieslapp 29

52134 Herzogenrath


Publications – Overview

Real-time Cross-Platform Communication with WebSockets


The variety of stationary and mobile devices requires cross-platform communication concepts for interactive apps and real-time data exchange. This article shows what models are appropriate for their needs.

Alexander Schulze, Rolando Santamaría Masó, Translation: Predrag Stojadinovic


Whether online gaming, online collaboration, streaming, monitoring or just a chat: The need for communication in the Internet grows as the number of devices - and with them the demand for safety, volume and speed. Interaction replaced information and instead of traditional client/server mechanisms, a more convenient and standardized way of data exchange is now needed – not only between client and server, but also between the various clients today. Hence, getting busy with WebSockets is almost inevitable. Mostly it's about

  • to improve and expand existing Web Apps,
  • to develop new native apps, stationary or mobile, or
  • to develop new Web apps, of course, cross-platform and cross-browser compatible.

In this article we present several models for communication with WebSockets in heterogeneous environments. Let's take a closer look, however, at the various requirement profiles.

Expand existing Apps

For already established web applications it is a key requirement to easily expand it and accelerate it using WebSockets. New WebSocket features must not only be convenient to deal with within existing business logic, but also be able to easily integrate into existing server environments.

In particular, for vendors of enterprise apps that have been developed over many years, protecting their investments is of great importance. Here the focus lies on improvements of existing services and for Real-Time Add-ons.

The answer is a library that developers can easily embed in their solution. Since functions such as authentication or database access are in most cases likely to already be implemented, here it rather depends on clear and easy embeddable Communication APIs. The underlying WebSocket solution should also be open for a gradual migration process.

WebSockets for Native Apps

If one prefers specific solutions for particular device dependent features – which are not yet achievable by HTML5 – one might decide to develop native apps instead of web apps.

Therefore, due to the variety of different operating systems like Android, iOS, Windows Mobile, BlackBerry, Symbian or Bada for small and medium-sized companies it is often a challenge to create native apps for mass markets.

But once this decision is made, due to the standardization by the IETF and the W3C, WebSockets are a safe basis to interconnect native platform specific apps and web apps.

Various programming languages such as Java SE, ME, Objective C, .Net / Silverlight, or C# as well as the fragmentation of various platforms are a cause for increased expenses. In addition, there are necessary live hardware tests to consider. And thus small teams of developers are limited to just a small variety of platforms.

To provide the necessary flexibility that is required in today's equipment turnover and the rapidly changing market, any WebSocket Framework must support as many platforms as possible - in the spirit of mobile interoperability.

HTML5 web apps development

A developer gladly decides to create a web app if he does not rely on special device-specific features.

Indeed, it is also required to consider different display formats and abstraction. However, cross-platform prototypes can be realized a lot faster.

Whether you see the abstraction of a single web UI by using a framework, for example jQuery Mobile or Sencha Touch , as an advantage in the sense of corporate identity or as a disadvantage in terms of a possibly non-compliant platform UI, is up to you to decide.

It is important that Web Apps practically work on all stationary and mobile browsers. What previously was transmitted using XMLHttpRequest will in the future be taken over by the slimmer and TCP-based WebSockets.

Based on the advantages of WebSockets it can be expected that they will gradually replace traditional mechanisms such as Comet. However, in order to be a real HTTP-alternative, it is required to be more than just the replacement of the basic communication technology.

Thus, in addition to pure data exchange the used WebSocket framework should provide further capabilities, for example for authentication, and also allow shared access to objects, remote procedure calls or databases.

Server implementations

If we look at the server-side WebSocket implementations, we can see that these can be divided roughly into the following categories:

  • WebSocket Libraries
  • Standalone Server
  • Servlet Container
  • Application Server

If you already run an implemented web application on an application server like GlassFish or servlet containers like Tomcat or Jetty, you will want to use WebSocket functions in order to avoid redundancies – as soon as these are supported.

At present, server’s activity is limited in terms of WebSockets in the rudimentary exchange of data packets. Higher-level protocols or even specific features such as file or database access do not usually fall within the scope of such a Web server.

A suitable WebSocket framework in this case is simply integrated into the existing application. It uses the WebSocket features of the underlying server and provides additional functions and interfaces to existing logic.

If you work with a Web server such as Apache and do not require access to server-side business logic, then a parallel autonomous WebSocket server is a practical approach.

The Framework should either be used on its own WebSocket Server or integrated in one, which is best suitable for your needs. In addition, it is useful when the framework provides a certain amount of server side standard features. These include not only file or a table sharing, but also skills such as Remote Procedure Calls (RPCs), mail services or shared objects. A plug-in approach for this is presented in the course of this article.

jWebSocket Engine Model

An example of a WebSocket framework is jWebSocket . It considers all server-side WebSocket implementations as so-called engines. An engine can be replaced at any time and no changes to the application are necessary.

Engines manage the physical connections to the clients via so-called connectors. We will examine these later in the article.

jWebSocket can be integrated as a library into an existing web application and then use the functions provided the underlying server. One example of such a combination is jWebSocket in a GlassFish application.

Likewise, jWebSocket can be operated as a standalone system and expanded with its own business logic. In this way, for example, an existing implementation like Netty from JBoss, can be used or in future node.js as well. If necessary, the included TCP engine can be used.

Jetty with jWebSocket is the most flexible combination. Jetty can be used as an autonomous web server and as a servlet container but also as a module in your own applications. In cooperation with jWebSocket you will have all options open.

It is noteworthy that Jetty can already accept http:// and ws:// requests on a single port without problems as well as support SSL for WebSockets (wss://). This avoids conflicts with proxies and firewalls.

Until its final adoption some changes to the protocol WebSocket are still expected. Reasons for this are the proper handling of proxies and the safeguarding against attacks. An important argument in the development of the WebSocket technology is to pay attention to create a clean abstraction at an early stage.


In the WebSocket protocol there exist no rules for content or processing. Hence, all participants in a WebSocket network must agree, therefore, to a common language to communicate with.

In order to be able to use custom protocols, besides standard formats such as JSON or XML, such as for example Socket-IO , it is necessary to abstract the data packets. In jWebSocket this is realized with the so-called tokens. These are abstract, hierarchical data objects with an API that provides access methods to the contents of the token.

Token Processors

So-called Token Processors convert incoming and outgoing data packets into tokens. Thus, neither the application has to worry about the internal format of the token, nor is the overall system limited to a particular data format.

As Token Processors negotiate the data format individually for each client and the server works internally only with the abstract tokens, all clients can communicate with each other using completely different formats and sub-protocols.

If in a network data packets need to be exchanged in a certain preferred format, then optimized token implementations should be used.

If for example, in browser apps mainly JSON packages are exchanged, then it makes sense to manage tokens internally as JSON objects. Then there is less conversion effort. In jWebSocket there are native Map, JSON and XML implementations.

The server performance will be increased proportionally.

Data formats in tokens

To ensure that all clients can reliably handle the exchanged packets on various operating systems and in various programming languages, the tokens contain only fields with a limited set of abstract data types: integer, string, float, boolean, list and map. Hierarchical structures can be represented using list and map.

Time and date values are enclosed in strings in ISO8601-Format (UTC [+Time zone]) in order to avoid incompatibilities.


In an application listeners listen to incoming data packets and can also answer. Listeners are the means of choice when certain WebSocket functionality is to be added fast to an existing application.

For this, simply add the jWebSocketServerBundle.jar to your application. That way you will already have a built-in WebSocket server. The server is then controlled using the start and stop methods.

TokenServer lServer = JWebSocketFactory.getServer();
lServer.addListener(new DemoListener());

A listener is a new class that implements the default listener interface. It contains the processToken function for receiving and sendToken to send messages. As shown in the listing above, the listener will be registered only once on the server and afterwards the tokens are processed.

public void processToken(
  WebSocketTokenEvent aEvent,
  Token aToken) {

  String lNS = aToken.getNS();
  String lType = aToken.getType();

  if (lType != null && "my.namespace".equals(lNS)) {
    Token lResponse = aEvent.createResponse(aToken);
    if ("getInfo".equals(lType)) {
      lResponse.setString("version", JWebSocketServerConstants.VERSION_STR);
      lResponse.setString("copyright", JWebSocketCommonConstants.COPYRIGHT);
    } else {
      lResponse.setInteger("code", -1);
        "Token type '" + lType + "' not supported in namespace '" + lNS + "'.");

Listeners are useful there where specific logic of an application should be deployed over WebSockets to clients.


When it comes, however, to extending not the application itself but rather the server with some additional services, then it can be extended accordingly using plug-ins. Typically, this scenario is chosen, if a WebSocket server will run like a web server as a separate instance – i.e. not embedded in an application.

Plug-ins are individual modules that are in the form of separate .jars added to the server. All clients, assuming appropriate permissions, can share the services in a plug-in.

Some examples from the jWebSocket Plug-in Portfolio are:

  • JDBC Plug-in for abstract and native SQL queries and updates
  • RPC Plug-in for remote procedure calls from client to server (C2S), client to client (C2C) and server-to-Client (S2C)
  • SharedObjects plug-in for the common, synchronized access to key data objects for online collaboration and online gaming
  • Streaming Plug-in for its own and third-party real-time streaming services
  • XMPP/Jabber-compatible plug-in for chats
  • Twitter plug-in to use the Twitter service via WebSockets mit Support der Twitter Streams
  • Statistic, admin and test plug-ins, and many more

Each plug-in has an individual and unique name space, so that always a unique addressing of different services on a server is possible.

Similar to a listener, a plug-in is also implemented by a new class that implements the plug-in interface.

Within the plug-ins the system can react to different events, such as beginning and end of a client connection or incoming data packets.

Also, a plug-in can send out messages to a specific client or broadcast to multiple clients.

Connector Attributes

Using Attributes per connector broadcasts can be filtered by any criteria. An attribute room for a connector, for example, can make a chat app that only visitors of a particular area will receive a text message.

However, this kind of filtering has a disadvantage, because for each filtered broadcast the current attributes of all connected clients will be evaluated – a negative aspect for performance. A better alternative is to use Channels, which we will discuss later in this article.

WebSocket Apps

While plug-ins are associated with shared services implemented through server-side extensions WebSocket Apps rather are closed functional units whose functions are hidden to the public. Of course, apps can access the methods of installed plug-ins.

WebSocket Apps can implement their own internal filters, however, they also are subject to the control of global filters, created by the administrator. This ensures that for instance in a file-sharing or mailing app, a global filter can also check content for viruses.

The jWebSocket Framework is published under the open source Apache 2.0 License, which allows you to offer your own apps for free or commercially – without the requirement to disclose your own source code.


The server has the least features and is still the most important central component in a WebSocket Framework.

On the one hand, it manages the selected engine with its physical connectors to the clients. On the other hand, it manages filters, listeners, and plug-ins. Its core functions are receiving, sending to a single client and broadcasting of messages to some or all clients.

In essence, therefore, the server has a mediating role between the clients and the individual processing instances.

The data packets from engines and connectors, which come in using individually chosen formats, are initially abstracted by token processors into standard tokens and then passed to the filter chain. If they pass through successfully, the server then passes the token to listeners, plug-ins and apps, in other words through to the actual business logic.


The server components have a particular purpose in a cluster. Here, they handle the routing of tokens between the various server nodes. These are also connected to each other via the WebSocket protocol, which makes the implementation of the backbones extraordinarily simple.

Each server node has its own Client-/Session-Cache and knows exactly which client is connected to which node. Connect and disconnect broadcasts synchronize the caches, optimizing the routing in addition.


Since the WebSocket protocol, at the time of writing this article (Hybi Draft # 04), besides the same-origin policy and the SSL-encryption offered no mechanisms for authorization or validation of messages, therefore the self-sufficient filters are an essential part of the security concept for WebSocket applications.

A server administrator can install inbound and/or outbound filters to ensure that both incoming packets with questionable content are rejected and questionable outgoing packets are suppressed.

If the filters are supposed to work as global security instances independent of plug-ins or listeners, then they are added to the server as a separate .jar’s.

In the communication chain, the inbound filters will execute before any packet processing and the outbound filters before the final dispatch to the clients.

Similarly, filters can be used, instead from a .jar, from within an application, for example for the validation of data packets. In this case, a new class simply implements the filter interface with two simple methods.

public class SampleFilter
  extends TokenFilter {

  public void processTokenIn(FilterResponse aResponse,WebSocketConnector aConnector,Token aToken) {

    TokenServer lServer = getServer();
    String lUsername = lServer.getUsername(aConnector);

    if ("locked".equals(lUsername)) {
      Token lToken = lServer.createAccessDenied(aToken);
      lServer.sendToken(aConnector, lToken);
  public void processTokenOut(FilterResponse aResponse, WebSocketConnector aSource,
  	WebSocketConnector aTarget,Token aToken) {

The example shows, how it is checked whether a user is blocked, and an incoming token is therefore rejected. For the outgoing token, the procedure is identical.


Broadcasts are quite inefficient, especially in environments with multiple applications on one server. For network-wide broadcasts the packets are sent to all clients, including to those that are not associated with a specific application. Even if the packets are then discarded because of their namespace, this unnecessarily wastes resources.

In fact, using connector attributes for filtered broadcasts avoids unnecessary packets on the network. However, on the server an application has to evaluate the attributes of all the connectors per each message to their individual clients. So, operation of many applications on one server results in a loss of performance.

The channels model avoids this overhead and allows several applications in a WebSocket network to each have their own independent communication channels.

As part of the used Publish/Subscribe mechanism the application shall initially create one or more channels. The clients sign up to these (subscribe) and then receive the (publish) messages sent on these channels only.

The server manages a list of all registered clients for each channel. A broadcast to all recipients of a channel thus can be performed very efficiently.

Depending on the application a client logs on to one or more channels and can then send and listen on each of them.

For security reasons, each channel is optionally protected by Access/Secret key combinations and in both send and receive directions it is separately authorized.

Channels, therefore, represent a safe and high-performance communications model, both when multiple applications run independently of each other and if an application has multiple logical functions, such as chat rooms or on-line collaboration on various topics.


WebSockets are a bidirectional communications protocol, which raises the question why a client actually accesses services only in one direction on the server. Or else, why cannot the client present itself – at least for inactivity – its own services to the network?

One can argue that in a WebSocket network, in principle, all nodes should have equal rights – even if the client claims the privilege of the connection initialization.

Clients, which provide their own service, are called Service Nodes. A client service can be provided on every imaginable machine on a browser, as a desktop app or even as a mobile app.

Their biggest advantage is that a WebSocket network can be expanded at any time to any service, without changing the server or restarting it. They release their API and make their services known to the network.

Clients as Service Nodes should not be perceived as user systems only. They can just as well relieve an existing server in an intranet or provide additional convenient services via the server to the outside.

Service nodes are also useful for testing new services without endangering the server or for distributing multiple versions of a service on multiple physical systems.

The administrator of a WebSocket server may for security purposes allow only external, only internal or only pre-configured service nodes. For security reasons, optional Access/Secret-Keys protect the server environment against unauthorized external nodes from providing questionable services.


Another highly flexible communication model for WebSockets is offered with events. The workflow on event driven programming is characterized by triggering events and subsequent reactions, the processing of the events.

Here we come to the use of the observable pattern. This defines a 1:N relation between the so-called Observables and the Observer objects. If an Observable object's status changes all related Observers will be informed automatically.

Unlike the previous client/server mechanisms, events work on each node on the same principle. The WebSockets are simply a two-way communication medium, regardless of who has previously made the connection. The nodes are equal by definition.

The classic request/response procedures and other distinction required by server and client logic are so passé.

Additional advantages of this model are the loose coupling of different components, the low dependencies between the objects and the straightforward program structure.

In order to transmit the events between all involved nodes, the events are encapsulated in tokens. The namespace of the token makes sure that the event is identified as such.

Each node in a WebSocket network can both trigger events, thus contain observable objects, and also process events, i.e. implement an Observer.

Although events in the network will only be transferred as data packets, they are, in contrast to the abstract token, concrete objects with their own methods.

Event Plug-Ins

The first obvious new feature in the event plug-ins compared to its token variation with the process token method, are the additional methods for the treatment of the events. For example, for events, which at login and logout have to deal with a user, the system plug-in contains the following methods:

public void processEvent(
  Logon aEvent, 

public void processEvent(
  Logoff aEvent,

Event API

Another useful feature of WebSocket events is that they - like WSDL in Web services - can publish their interface.

The WebSocket Event API (WSEA) even allows the clients to generate the event classes completely automatically. Hence, the vendor of a plug-in does not need to provide the implementations for the various programming languages.

The following listing shows an example of how the logon and logoff events, like a WSEA record, in JSON looks like:

  "logon": {
    "outgoingArgsValidation": [
      {"optional": false,
       "name": "username",
       "type": "string"},
      {"optional": false,
       "name": "roles",
       "type": "array"}
    "isSecurityEnabled": false,
    "roles": [],
    "cacheTime": 0,
    "incomingArgsValidation": [
      {"optional":f alse,
       "name": "username",
       "type": "string"},
      {"optional": false,
       "name": "password",
       "type": "string"}
    "type": "auth.logon",
    "isCacheEnabled": false
    "isSecurityEnabled": true,
    "roles": ["USER"],
    "cacheTime": 0,
    "type": "auth.logoff",
    "isCacheEnabled": false

Event Filter

For security purposes the events run through the filter chain, just like tokens, so that unauthorized or faulty incoming and outgoing events can be blocked.

A generic Validator filter as an autonomous body ensures, for example, that events with invalid arguments, do not even reach their Observer. Through the public API of each event this generic approach is very easy to implement. A security filter checks whether an authenticated user has the required role to trigger an event and rejects it if necessary.

Last but not least for performance improvements a Cache-Filter checks for a certain event if response is already stored and returns the result for the cache instead of requesting it again.

The reading of the Event API is one plausible example of a cache-enabled event. Also a cache with expiration date can effectively improve the performance of database events.

public class AuthPlugIn
  extends EventPlugIn {
  public void processEvent(
    Logon aEvent,
    WebSocketResponseEvent aResponseEvent) {
    // Argumente ermitteln
    String username = aEvent.getArgs().getString("username");
    String password = aEvent.getArgs().getString("password");
    // Authentifizierung
    // Antwort Event generieren
    aResponseEvent.getArgs().setList("roles", roles);
    aResponseEvent.getArgs().setInt("returnCode", 0);
  public void processEvent(
    Logoff aEvent,
    WebSocketResponseEvent aResponseEvent) {

In JavaScript, the event plug-in automatically generates the following code from the server using the published API at run-time.

generator = new

authPlugIn = generator.generate(

Triggering of events, as well as waiting for an answer, turns out to be very easy.

  args: {
    username: "username",
    password: "password"
  OnSuccess: function( aResponseEvent ) {
    // logon was successful 

The event model for WebSockets can be used on the same principle for all platforms and programming languages. Such implementations will be available very soon.


WebSocket connections are generally produced from a server to a client. Still, with WebSockets the server cannot establish a connection to a client by itself. Also, two clients cannot connect to each other directly via WebSockets. A private communication between two clients is always done via the server. Direct P2P connections are not specified in the WebSocket protocol.

Comet or Flash Fallback?

If you decide to build a browser app with real-time or push functionality based on WebSockets, until these are not yet comprehensively implemented on all browsers, you should think about a fallback. This may be Comet or alternatively a Flash plug-in.

Comet requires that appropriate HTTP push technology is available on the server and that these are also implemented on the client. Despite the possible abstraction that makes the communication substructure for the application transparent, on both sides additional effort and code redundancy comes up. Moreover, with Comet, the advantages of lower protocol overhead and better use of resources are destroyed.

When using the Flash plug-in , all the advantages of Web Sockets can be used. The server does not need a second engine and no significant abstraction is necessary on the client because the API of the Flash plug-in is identical to the WebSocket object of JavaScript and is very easily embedded when needed using simple JS code. Since many Web sites already require a Flash Player, it is already installed on most clients. This assures a high availability.

One problem remains, however. Only on the iPhone browser Flash is not (yet) supported. So here you have to wait until the mobile Safari provides WebSockets support again.

WebSockets in the Browser

In JavaScript the WebSocket object takes over the communication with the server. In jWebSocket a full JavaScript implementation, including tokens, channels and events is available.

The following screenshot shows an example of a simple chat demo with a BlackBerry.

Chat Demo in the Browser

WebSockets for native Apps

If you decide to create native apps, you can take full advantage of the respective device-specific features. In terms of communication among various devices you must remember, however, that almost always individual development expenses incure for each platform.

The analysis of differences between platforms would fill a whole article, but here we do at least provide a rough overview.


Apps for iPhone and iPad are programmed in Objective-C. In contrast to the more standardized Java, Apple chose higher Tool-turnover, with XCode, which is a stable and extensive development environment for iOS.

Contained herein is the Cocoa framework. It provides the classes CFSocket and CFStream, which already basically support UDP and TCP. However, but it is recommended to use the CocoaAsyncSocket Project – a powerful simplified wrapper around the Cocoa-based classes, which simplifies the implementation of the TCP protocol significantly.

The WebSocket implementation in the jWebSocket Framework is, as with Android, implemented with only rudimentary functions for packet exchange and token handling. The open source TouchJSON Library provides this service for good processing of JSON packets.

iPhone Fundamentals App


Google provides its own Java VM called Dalvik VM for Android. It supports Java 1.5 standard and thus annotations and collections – a significant development advantage compared to older devices that only support Java ME and therefore only Java 1.3. An extensive API to access device-specific functions is also included.

The developer should be aware that it is not easy to include .jar libraries from third party manufacturers into an Android project. Byte code generated by Dalvik VM is optimized for minimal memory usage, which while very compact, is unfortunately incompatible with the J2SE byte code. Therefore, for your cross-platform projects choose only libraries that are either delivered in source code or compiled directly for Android.

There is a complete WebSocket client for Android included in the jWebSocket framework. In order to keep the code widely identical for mobile and stationary devices and to minimize maintenance efforts only well documented open source libraries are used.

The Screenshot shows the Fundamental WebSocket App for Android.

Android Fundamentals App

Java ME

Symbian and BlackBerry Smart phones are programmed in Java ME. Even though their market share is gradually decreasing due to the success of iPhone and iPad as well as Android based devices, if you decide to develop a cross-platform portable app you can at least not entirely ignore the BlackBerry.

Java ME follows the Java 1.3 standard. Frequently used Java classes, such as collections, are missing altogether. Others, like the socket classes are implemented differently.

The missing Collections framework may be well compensated by the use of Javolution Library. The JSON2 Library provides compatibility in communication. For the WebSocket implementation with TCP sockets simply the appropriate adjustments are required. Bottom line is that even the Java ME based platforms can quite comfortably connect with a WebSocket network.

A JME client for Symbian and BlackBerry is also included in the jWebSocket framework.


SDK development tools are available for Java ME. Sun (now Oracle) provides the Wireless Toolkit (WTK) and the Java Micro Edition (JME) for a long time already, both are integrated in all major IDEs such as NetBeans, Eclipse and IntelliJ or can at least be added as plug-ins.

Those who seek a good template for a Java ME WebSocket client will find them in the jWebSocket framework – which contains both the study with documented source code as well as a directly executable demo app.

The following screenshot shows the fundamental jWebSocket demo with Java ME:

Symbian/JME Fundamentals App

Black Berry

The manufacturer Research In Motion (RIM) provides a JDE for the development of your own BlackBerry Apps. This includes emulators for the various devices, but unfortunately can only be used under MS Windows.

To connect an emulator to the Internet, you need to install another component called MDS Service. This service acts as a proxy between the emulator and the host operating system. Without these, neither HTTP nor WebSocket connection is possible.

But if one has taken care of these hurdles, then the connection of a BlackBerry to a WebSocket network has no more obstacles. The screenshot shows the fundamental jWebSocket demo on a BlackBerry 9700:

BlackBerry Fundamentals App


In this article we have presented various models with which you can use WebSockets as a secure and real-time communications platform for your native or browser-based apps.

There was not enough space so that platforms such as Windows Mobile or Samsung's Bada had to remain unmentioned. We will do this in one of the next articles. We will also show other examples of how to create WebSockets specific services on the Internet and use them on various platforms.

It keeps being exciting.

Copyright © 2013 Innotrade GmbH. All rights reserved.