First, a quick recap of the previous installments:

1. “Hello World” with Lightstreamer: An introduction to Lightstreamer’s data model, Web Client API, and Java Data Adapters API.
2. “Hello World”
   for .NET with Lightstreamer: The .NET API version of the Data Adapter used in the “Hello World” application, showing both a C# and a Visual Basic port.
3. “Hello World” for Sockets with Lightstreamer: The TCP-socket-based version of the Data Adapter, suitable for implementation in other languages (PHP, Python, Perl, etc).

Basically, Lightstreamer Server can be seen as a “technology hub” for data push, where you can mix different technologies on the client-side and on the server-side to exchange real-time messages.

In this article, we will delve into the “Flex on the client-side, Java on the server-side” scenario.

In particular, Simone Fabiano will show you how to push binary ActionScript objects directly to your Flex application in real-time, using AMF. Action Message Format is used for serializing binary ActionScript objects in order to transmit them over the wire.

As you may recall form the first installment, Lightstreamer data push model is based on items made up of fields. A client can subscribe to many items, each with its own schema (a set of fields). Each field is usually a text string with an arbitrary length (from a few characters to large data structures, perhaps based on XML, JSON, etc.). With this new Lightstreamer feature, you can now put a full AMF object into any field and have it pushed from the server to the client in real binary format (with no re-encondings).

The Flex Client library for Lightstreamer has been used for one of the major dealing platforms in the finance field and has undergone many cycles of improvements to make it completely production resilient. We were asked to add native support for AMF objects to improve the performance when streaming complex data structures. So now you can push both text-based items and object-based items to the same Flex application.

When approaching the Lightstreamer data model, it is important to choose the right trade-off between using fine-grained fields and coarse objects. You could map each individual atomic piece of information to a Lightstreamer field, thus using many fields and items, or you could map all your data to a single field of a single item. This applies to both text-based fields (where you can encode coarse objects via JSON, XML, etc.) and object-based fields (via AMF). Usually, going for fine-grained fields is better, because you let Lightstreamer know more about your data structure, so that it will be able to apply optimization mechanisms, like conflation and delta delivery. On the other hand, if you go for huge opaque objects, Lightstreamer will be used more as a blind pipe. But in both cases, you will still benefit from other features, like bandwidth allocation and dynamic throttling. All intermediate scenarios are possible too.

In the tutorial below, Simone will use a single field containing an AMF object derived from a JavaBean. To encode a JavaBean as an AMF object, several ready-made libraries exist. Here we will leverage BlazeDS.

AMF Lightstreamer Tutorial

by Simone Fabiano, Software Engineer at Lightstreamer

Alessandro asked me to write a simple “Hello World” example to show how to use AMF with our new Flex client library (docs). We will create a JavaBean on the server-side and then use it on the client-side.

For this tutorial, I’m assuming you have already read the Basic Hello World example, or that you are already familiar with Lightstreamer concepts.

On the client, the result of this tutorial will be quite similar to the one obtained with the original Hello World by Alessandro, but in Flex: we’ll get a string alternating some different values (Hello AMF World) and a timestamp. On the server-side, data will be encapsulated into a JavaBean containing a String and a Date instance. This bean will be translated into a byte array and then injected into the Lightstreamer kernel as a single field, instead of being spread over different fields as simple strings (as the original adapter does). Here lies the power of AMF, as you will be able to push even complex JavaBeans to your Flex clients with ease.

Gather Stuff

• First of all you’ll need a browser, a Flash player, and a JDK: hopefully you already have those
• You’ll need Lightstreamer Server 3.6 (Presto or Vivace) and Lightstreamer Flex Client 2.0. You can download them from the Lightstreamer web site.
• You’ll have to compile a Flex application, so you’ll need either the Flex Builder or the Flex SDK (the example works with Flex 3 and Flex 4; use Flex 4 only if you’re going to use it with the Flex Builder, otherwise you may have problems with the mxmlc
• The conversion from Java beans to an AMF-compatible byte array is performed by a couple of the BlazeDS libraries. Download BlazeDS (binary distribution) and extract flex-messaging-common.jar and flex-messaging-core.jar from it (the downloaded zip contains a .war file, open it with an archive manager and locate the needed libraries under “WEB-INF/lib/”).

Let’s Code the Front-End(s)

The front-end of our application will be a simple .mxml file compiled into a .swf. Open your text editor and start writing a mxml file (notice the creationComplete event):

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
   creationComplete="init()">

Then add a TextArea instance (myTextArea), where we’ll put the updates:

<mx:TextArea width="693" height="56" id="myTextArea"
   fontSize="25" fontWeight="bold" text="loading..."/>

Now to Actionscript… We need an init method to initialize our client and subscribe to our table. We’ll also configure a DateFormatter instance to print nice-looking dates.

public function init():void {
  dateFormatter.formatString = "MM/DD/YY J:NN:SS"; 
 
  var cInfo:ConnectionInfo = new ConnectionInfo();
  cInfo.server = "localhost";
  cInfo.adapterSet = "AMFHELLOWORLD";
 
  var client:LSClient = new LSClient();
 
  var nonVisualTable:NonVisualTable =
     new NonVisualTable(["greetings"],["AMF_field"],"MERGE",true);
  nonVisualTable.addEventListener(
    NonVisualItemUpdateEvent.NON_VISUAL_ITEM_UPDATE,onChange);
  client.subscribeTable(nonVisualTable);
 
  client.openConnection(cInfo);
}

The ConnectionInfo instance defines how we connect to the server and the adapter set that will handle our requests. In this case we’ll deploy our application on tje Lightstreamer internal web server so the server has to be set to “localhost”. The adapter set in use will be called “AMFHELLOWORLD”.

The LSClient instance is the core of the Lightstreamer Flex client library. It handles the connection to the server and the subscription/unsubscription of tables.

The NonVisualTable represents the subscription we’re going to make. It is a mono-item (”greetings”) and mono-field (”AMF_field”) MERGE subscription. The fourth parameter in the constructors tells the server that we’re looking for binary data, namely AMF.

Next, we need the onChange callback to handle the updates and show them on screen. We’ll just extract the single field and, since it’s a Bean, expand it, format the date an put everything on the TextArea previously created:

public function onChange(evt:NonVisualItemUpdateEvent):void {
  if (evt.isFieldChanged("AMF_field")) {
    var obj:* = evt.getFieldValue("AMF_field");
    myTextArea.text = dateFormatter.format(obj.now) + " " + obj.hello;
  }
}

Download the complete source of the Flex client:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
  creationComplete="init()">
 
  <mx:TextArea width="693" height="56" id="myTextArea" 
    fontSize="25" fontWeight="bold" text="loading..."/>
 
  <mx:Script><![CDATA[
    import mx.formatters.DateFormatter;
    import com.lightstreamer.as_client.ConnectionInfo;
    import com.lightstreamer.as_client.LSClient;
    import com.lightstreamer.as_client.NonVisualTable;
    import com.lightstreamer.as_client.events.NonVisualItemUpdateEvent;
 
    public var dateFormatter:DateFormatter = new DateFormatter();
 
    public function init():void {
      dateFormatter.formatString = "MM/DD/YY J:NN:SS"; 
 
      var cInfo:ConnectionInfo = new ConnectionInfo();
      cInfo.server = "localhost";
      cInfo.adapterSet = "AMFHELLOWORLD";
 
      var client:LSClient = new LSClient();
 
      var nonVisualTable:NonVisualTable = 
        new NonVisualTable(["greetings"],
         ["AMF_field"],"MERGE",true);
      nonVisualTable.addEventListener(
        NonVisualItemUpdateEvent.NON_VISUAL_ITEM_UPDATE,
        onChange);
      client.subscribeTable(nonVisualTable);
 
      client.openConnection(cInfo);
    }
 
    public function onChange(evt:NonVisualItemUpdateEvent):void {
      if (evt.isFieldChanged("AMF_field")) {
        var obj:* = evt.getFieldValue("AMF_field");
        myTextArea.text = 
          dateFormatter.format(obj.now) + " " + obj.hello;
      }
    }    
 
  ]]>
  </mx:Script>
</mx:Application>

If you prefer a DataGrid in place of the TextArea, don’t worry, the substitution is really easy. First we replace the TextArea with a DataGrid (myDataGrid) with two columns. Each column is associated to a property of the bean sent by the server, so “AMF_field” represents the entire bean (the field of our subscription) and “AMF_field.hello” represents the “hello” property of the bean. We add a labelFunction to one of the columns so that we’ll be able to format the received date.

<mx:DataGrid width="479" x="447.5" height="91" id="helloView" y="12" >
  <mx:columns>
    <mx:DataGridColumn dataField="AMF_field.now" 
      headerText="Time" labelFunction="formatDate" />
    <mx:DataGridColumn dataField="AMF_field.hello" headerText="Hello"/>
  </mx:columns>
</mx:DataGrid>

Then, we need something to be bound with the DataGrid. Luckily enough, our VisualTable class extends the ArrayCollection native class. so that it can be bound to a DataGrid to update the view automagically. We have to put our VisualTable in the global space so that we can declare the [Bindable] metadata on it.

[Bindable] public var myTable:VisualTable;

Finally, we have to initialize this table. The code is very similar to the one used to initialize the NonVisualTable, but we don’t need to add any event handlers. Instead, we bind our VisualTable and the DataGrid assigning our Bindable VisualTable to the “dataProvider” property of the DataGrid.

var myTable:VisualTable =
  new VisualTable(["greetings"],["AMF_field"],"MERGE",true);
helloView.dataProvider = myTable;

Download the complete modified source of the Flex client:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
  creationComplete="init()">
 
 <mx:DataGrid width="479" x="447.5" height="91" id="helloView" y="12" >
  <mx:columns>
    <mx:DataGridColumn dataField="AMF_field.now" 
      headerText="Time" labelFunction="formatDate" />
    <mx:DataGridColumn dataField="AMF_field.hello" headerText="Hello"/>
  </mx:columns>
 </mx:DataGrid>
 
 <mx:Script> <![CDATA[
	import mx.formatters.DateFormatter;
	import com.lightstreamer.as_client.VisualTable;
	import com.lightstreamer.as_client.ConnectionInfo;
	import com.lightstreamer.as_client.LSClient;
 
	public var dateFormatter:DateFormatter = new DateFormatter();
 
	[Bindable]
	public var myTable:VisualTable;
 
	public function init():void {
		dateFormatter.formatString = "MM/DD/YY J:NN:SS"; 
 
		var cInfo:ConnectionInfo = new ConnectionInfo();
		cInfo.server = "localhost";
		cInfo.adapterSet = "AMFHELLOWORLD";
 
		var client:LSClient = new LSClient();
 
		var myTable:VisualTable = 
		  new VisualTable(["greetings"], 
		    ["AMF_field"],"MERGE",true);
		helloView.dataProvider = myTable;
		client.subscribeTable(myTable);
 
		client.openConnection(cInfo);
	}
 
	public function formatDate(item:Object,
          column:DataGridColumn):String {
		return dateFormatter.format(item.AMF_field.now);
	}
 ]]></mx:Script>
</mx:Application>

The mxml file, as is, is quite useless, so, save it as “AMFHelloWorld.mxml” and compile it into a swf file using the Flex SDK:

FLEX_SDK_HOME/bin/mxmlc AMFHelloWorld.mxml 
  -output AMFHelloWorld.swf 
  -library-path+=
    LS_HOME/DOCS-SDKs/sdk_client_flash_flex(native_as)
    /lib/Lightstreamer_as_client.swc

Note that if you’re using a 64-bit JVM you may have some issues running mxmlc; use a 32-bit JVM (mxmlc makes use of the JAVA_HOME environment variable to choose the JVM).

Server-Side

Now it’s time to write the adapter. We’ll reuse most of the code of the first Hello World. We’ll add a static property and a static utility method to the class we’ve renamed into “AMFHelloWorld”.

private static SerializationContext context = 
  SerializationContext.getSerializationContext();
 
public static byte[] toAMF(Object bean) { 
  ByteArrayOutputStream baos = new ByteArrayOutputStream();
  Amf3Output output = new Amf3Output(context);
  output.setOutputStream(baos);
  try {
    output.writeObject(bean);
    output.flush();
    output.close();
  } catch (IOException e1) {
    e1.printStackTrace();
  }
  return baos.toByteArray();
}

The toAMF method receives an Object instance and converts it into an AMF byte array using the Amf3Output class. You can find a list of the conversions performed to switch from Java to AMF in the ActionMessageOutput class javadoc.

In this case we’re going to use a Java bean. Note that the AMF3Output class javadoc is currently not linked/listed on BlazeDS classes list (they forgot?). You can reach it anyway, at the logical directory.

Once the conversion method is in place, we can add the bean we want to send to the clients. We will prepare a simple bean containing only two properties, a String and a Date:

public class HelloBean implements java.io.Serializable {
 
  private static final long serialVersionUID = 7965747352089964767L;
  private String hello;
  private Date now;
 
  public HelloBean() {
  }
 
  public String getHello() {
    return hello;
  }
 
  public void setHello(String hello) {
    this.hello = hello;
  }
 
  public Date getNow() {
    return now;
  }
 
  public void setNow(Date now) {
    this.now = now;
  }
}

Finally, we will replace the run method of the GreetingThread inner class with a different implementation that handles our bean:

public void run() {
  int c = 0;
  Random rand = new Random();
  HelloBean testBean = new HelloBean();
  while(go) {
    Map<String,byte[]> data = new HashMap<String,byte[]>();
 
    testBean.setHello(c % 3 == 0 ? "Hello" : c % 3 == 1 ? "AMF" : "World");
    testBean.setNow(new Date());
 
    data.put("AMF_field", toAMF(testBean));
 
    listener.smartUpdate(itemHandle, data, false);
    c++;
    try {
        Thread.sleep(1000 + rand.nextInt(2000));
    } catch (InterruptedException e) {
    }
  }
}

As you can see, there’s nothing extremely complicated here, we just convert the instance of our bean through the toAMF method and inject it in a Map as if it was a simple String. Then, in turn, the Map is injected into the Lightstreamer kernel to make its way to the clients.

Download the complete Java Adapter source:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.IOException;
 
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.Random;
 
import com.lightstreamer.interfaces.data.DataProviderException;
import com.lightstreamer.interfaces.data.FailureException;
import com.lightstreamer.interfaces.data.ItemEventListener;
import com.lightstreamer.interfaces.data.SmartDataProvider;
import com.lightstreamer.interfaces.data.SubscriptionException;
 
import flex.messaging.io.SerializationContext;
import flex.messaging.io.amf.Amf3Output;
 
 
public class AMFHelloWorld implements SmartDataProvider {
  private ItemEventListener listener;
  private volatile GreetingsThread gt;
 
  public void init(Map params, File configDir) 
    throws DataProviderException {
  }
 
  public boolean isSnapshotAvailable(String itemName) 
    throws SubscriptionException {
    return false;
  }
 
  public void setListener(ItemEventListener listener) {
    this.listener = listener;
  }
 
  public void subscribe(String itemName, 
    Object itemHandle, boolean needsIterator) 
        throws SubscriptionException, FailureException {
    if (itemName.equals("greetings")) {
      gt = new GreetingsThread(itemHandle);
      gt.start();
    }
  }
 
  public void subscribe(String itemName, 
    boolean needsIterator)
        throws SubscriptionException, FailureException {
  }
 
  public void unsubscribe(String itemName) 
    throws SubscriptionException,
        FailureException {
    if (itemName.equals("greetings") && gt != null) {
      gt.go = false;
    }
  }
 
  private static SerializationContext context = 
    SerializationContext.getSerializationContext();
 
  public static byte[] toAMF(Object bean) { 
    ByteArrayOutputStream baos = new ByteArrayOutputStream();
    Amf3Output output = new Amf3Output(context);
    output.setOutputStream(baos);
    try {
      output.writeObject(bean);
      output.flush();
      output.close();
    } catch (IOException e1) {
      e1.printStackTrace();
    }
    return baos.toByteArray();
  }
 
  class GreetingsThread extends Thread {
 
    private final Object itemHandle;
 
    public volatile boolean go = true;
 
    public GreetingsThread(Object itemHandle) {
      this.itemHandle = itemHandle;
    }
 
    public void run() {
      int c = 0;
      Random rand = new Random();
      HelloBean testBean = new HelloBean();
      while(go) {
        Map<String,byte[]> data = 
          new HashMap<String,byte[]>();
 
        testBean.setHello(c % 3 == 0 ? 
          "Hello" : c % 3 == 1 ? "AMF" : "World");
        testBean.setNow(new Date());
 
        data.put("AMF_field", toAMF(testBean));
 
        listener.smartUpdate(itemHandle, data, false);
        c++;
        try {
            Thread.sleep(1000 + rand.nextInt(2000));
        } catch (InterruptedException e) {
        }
      }
    }
 
  }
 
  public class HelloBean implements java.io.Serializable {
 
  private static final long serialVersionUID = 
    7965747352089964767L;
    private String hello;
    private Date now;
 
    public HelloBean() {
    }
 
    public String getHello() {
      return hello;
    }
 
    public void setHello(String hello) {
      this.hello = hello;
    }
 
    public Date getNow() {
      return now;
    }
 
    public void setNow(Date now) {
      this.now = now;
    }
  }
}

Deploy the Adapter

Now just compile the .java file as you would compile any other java application. Remember to add to the classpath the “ls-adapter-interface.jar” file (from LS_HOME/DOCS-SDKs/sdk_adapter_java/lib), “flex-messaging-common.jar” and “flex-messaging-core.jar” (from BlazeDS). You will obtain three class files: AMFHelloWorld.class, AMFHelloWorld$HelloBean.class and AMFHelloWorld$GreetingsThread.class. Now create an “AMFHelloWorld” folder under “LS_HOME/adapters” and a “classes” folder inside it: put the .class files there.

Finally, create an adapters.xml file under the LS_HOME/adapters/AMFHelloWorld folder:

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0"?>
 
<adapters_conf id="AMFHELLOWORLD">
  <metadata_provider>
    <adapter_class>
      com.lightstreamer.adapters.metadata.LiteralBasedProvider
    </adapter_class>
  </metadata_provider>
  <data_provider>
    <adapter_class>AMFHelloWorld</adapter_class>
  </data_provider>
</adapters_conf>

As anticipated, while assembling the client we’re going to use “AMFHELLOWORLD” as the adapter set name, while we’ll use the classic LiteralBasedProvider as our Metadata Adapter and our brand new AMFHelloWorld class as our Data Adapter.

Deploy the Client

The client is made up only by the compiled swf file, so grab that file and put it under the “LS_HOME/pages” folder, that’s all.

Run!

Start the Lightstreamer server and point your browser to:
http://localhost:8080/AMFHelloWorld.swf
Enjoy

Final Notes

You’ve seen how to push Objects instead of Strings from a Lightstreamer server to a Flex client. You can exploit this technique to push complex data structures, but obviously, doing so you’ll lose some of the optimizations offered by Lightstreamer protocol. For example, the merging algorithm (of the MERGE mode) is applied to the entire bean instead of being applied to each single field, so that every time a property within the bean changes, the entire bean is pushed to the client, not only the changed value. As with anything regarding engineering you’ll have to choose the trade-off that optimizes properly for your application.

Please also consider that the Flex client library in this tutorial is not available with the Moderato version of Lightstreamer Server, so you may want to use a trial license for Lightstreamer Presto/Vivace to experiment with it.

Simple Chat

Chat is the "helloworld" application of web-2.0 and a simple WebSocket chat room is included with the jetty-7 which now supports WebSockets. The source of the simple chat can be seen in svn for the client-side and server-side. The key part of the client-side is to establish a WebSocket connection:

join: function(name) {
	this._username=name;
	var location = document.location.toString().replace('http:','ws:');
	this._ws=new WebSocket(location);
	this._ws.onopen=this._onopen;
	this._ws.onmessage=this._onmessage;
	this._ws.onclose=this._onclose;
},

It is then possible for the client to send a chat message to the server:

_send: function(user,message){
	user=user.replace(':','_');
	if (this._ws){
		this._ws.send(user+':'+message);
	}
},

and to receive a chat message from the server and to display it:

_onmessage: function(m) {
	if (m.data){
		var c=m.data.indexOf(':');
		var from=m.data.substring(0,c)
			.replace('<','&lt;')
			.replace('>','&gt;');
		var text=m.data.substring(c+1)
			.replace('<','&lt;')
			.replace('>','&gt;');
		var chat=$('chat');
		var spanFrom = document.createElement('span');
		spanFrom.className='from';
		spanFrom.innerHTML=from+':&nbsp;';
		var spanText = document.createElement('span');
		spanText.className='text';
		spanText.innerHTML=text;
		var lineBreak = document.createElement('br');
		chat.appendChild(spanFrom);
		chat.appendChild(spanText);
		chat.appendChild(lineBreak);
		chat.scrollTop = chat.scrollHeight - chat.clientHeight;   
	}
},

For the server-side, we simply accept incoming connections as members:

public void onConnect(Outbound outbound){
	_outbound=outbound;
	_members.add(this);
}

and then for all messages received, we send them to all members:

public void onMessage(byte frame, String data){
	for (ChatWebSocket member : _members){
		try{
			member._outbound.sendMessage(frame,data);
		}
		catch(IOException e){
			Log.warn(e);
		}
	}
}

So we are done, right?  We have a working chat room - let’s deploy it and we’ll be the next Google GChat!! Unfortunately, reality is not that simple and this chat room is a long way short of the kinds of functionality that you expect from a chat room - even a simple one.

Not So Simple Chat

On Close?

With a chat room, the standard use-case is that once you establish your presence in the room and it remains until you explicitly leave the room. In the context of webchat, that means that you can send receive a chat message until you close the browser or navigate away from the page. Unfortunately the simple chat example does not implement this semantic because the WebSocket protocol allows for an idle timeout of the connection. So if nothing is said in the chat room for a short while then the WebSocket connection will be closed, either by the client, the server or even an intermediary. The application will be notified of this event by the onClose method being called.

So how should the chat room handle onClose? The obvious thing to do is for the client to simply call join again and open a new connection back to the server:

_onclose: function() {
	this._ws=null;
	this.join(this.username);
}

This indeed maintains the user’s presence in the chat room, but is far from an ideal solution since every few idle minutes the user will leave the room and rejoin. For the short period between connections, they will miss any messages sent and will not be able to send any chat themselves.

Keep-Alives

In order to maintain presence, the chat application can send keep-alive messages on the WebSocket to prevent it from being closed due to an idle timeout. However, the application has no idea at all about what the idle timeouts are, so it will have to pick some arbitrary frequent period (e.g. 30s) to send keep-alives and hope that is less than any idle timeout on the path (more or less as long-polling does now). Ideally a future version of WebSocket will support timeout discovery, so it can either tell the application the period for keep-alive messages or it could even send the keep-alives on behalf of the application.

Unfortunately keep-alives don’t avoid the need for onClose to initiate new WebSockets, because the internet is not a perfect place and especially with wifi and mobile clients, sometimes connections just drop. It is a standard part of HTTP that if a connection closes while being used, the GET requests are retried on new connections, so users are mostly insulated from transient connection failures. A WebSocket chat room needs to work with the same assumption and even with keep-alives, it needs to be prepared to reopen a connection when onClose is called.

Queues

With keep-alives, the WebSocket chat connection should be mostly be a long-lived entity, with only the occasional reconnect due to transient network problems or server restarts. Occasional loss of presence might not be seen to be a problem, unless you’re the dude that just typed a long chat message on the tiny keyboard of your vodafone360 app or instead of chat you are playing on chess.com and you don’t want to abandon a game due to transient network issues. So for any reasonable level of quality of service, the application is going to need to "pave over" any small gaps in connectivity by providing some kind of message queue in both client and server. If a message is sent during the period of time that there is no WebSocket connection, it needs to be queued until such time as the new connection is established.

Timeouts

Unfortunately, some failures are not transient and sometimes a new connection will not be established. We can’t allow queues to grow forever and pretend that a user is present long after their connection is gone. Thus both ends of the chat application will also need timeouts and the user will not be seen to have left the chat room until they have no connection for the period of the timeout or until an explicit leaving message is received.

Ideally a future version of WebSocket will support an orderly close message so the application can distinguish between a network failure (and keep the user’s presence for a time) and an orderly close as the user leaves the page (and remove the user’s present).

Message Retries

Even with message queues, there is a race condition that makes it difficult to completely close the gaps between connections. If the onClose method is called very soon after a message is sent, then the application has no way to know if that close event happened before or after the message was delivered. If quality of service is important, then the application currently has no option but to have some kind of per message or periodic acknowledgment of message delivery. Ideally a future version of WebSocket will support orderly close, so that delivery can be known for non-failed connections and a complication of acknowledgments can be avoided unless the highest quality of service is required.

Backoff

With onClose handling, keep-alives, message queues, timeouts and retries, we finally will have a chat room that can maintain a user’s presence while they remain on the web page. But unfortunately the chat room is still not complete, because it needs to handle errors and non-transient failures. Some of the circumstances that need to be avoided include:

• If the chat server is shut down, the client application is notified of this simply by a call to onClose rather than an onOpen call. In this case, onClose should not just reopen the connection as a 100% CPU busy loop with result. Instead the chat application has to infer that there was a connection problem and to at least pause a short while before trying again - potentially with a retry backoff algorithm to reduce retries over time. Ideally a future version of WebSocket will allow more access to connection errors, as the handling of no-route-to-host may be entirely different to handling of a 401 unauthorized response from the server.
• If the user types a large chat message, then the WebSocket frame sent may exceed some resource level on the client, server or intermediary. Currently the WebSocket response to such resource issues is to simply close the connection. Unfortunately for the chat application, this may look like a transient network failure (coming after a successful onOpen call), so it may just reopen the connection and naively retry sending the message, which will again exceed the max message size and we can lather, rinse and repeat! Again it is important that any automatic retries performed by the application will be limited by a backoff timeout and/or max retries. Ideally a future version of WebSocket will be able to send an error status as something distinct from a network failure or idle timeout, so the application will know not to retry errors.

Does it have to be so hard?

The above scenario is not the only way that a robust chat room could be developed. With some compromises on quality of service and some good user interface design, it would certainly be possible to build a chat room with less complex usage of a WebSocket. However, the design decisions represented by the above scenario are not unreasonable even for chat and certainly are applicable to applications needing a better QoS that most chat rooms.

What this blog illustrates is that there is no silver bullet and that WebSocket will not solve many of the complexities that need to be addressed when developing robust Comet web applications. Hopefully some features such as keep-alives, timeout negotiation, orderly close and error notification can be build into a future version of WebSocket, but it is not the role of WebSocket to provide the more advanced handling of queues, timeouts, reconnections, retries and backoffs. If you wish to have a high quality of service, then either your application or the framework that it uses will need to deal with these features.

cometD with WebSocket

cometD version 2 will soon be released with support for WebSocket as an alternative transport to the currently supported JSON long-polling and JSONP callback-polling. cometD supports all the features discussed in this blog and makes them available transparently to browsers with or without WebSocket support. We are hopeful that WebSocket usage will be able to give us even better throughput and latency for cometD than the already impressive results achieved with long-polling.

Although building a demo is quite trivial, building a stock ticker that has useful functionality quickly raises a number of questions, many of which have been directed to me at Frozen Mountain. One question in particular has been directed to me multiple times, and is more of a design question: what’s the best way to implement a stock ticker using Comet?

Note: for the purposes of this article, I’m going to assume we’re working with a Comet server built on the Bayeux protocol, such as WebSync or Jetty).

The Problem

The “best way to implement a stock ticker” is rather ambiguous, so let’s take a moment and first define our scenario clearly so we know what the problem really entails.

Let’s work with a fairly common scenario. Assume each user has a “portfolio” of stocks, each stock containing between 10 and 50 points of data (such as min price, max price, current value, etc). Each user also had the ability to show or hide certain data points. Since we’re talking about 10-50 data points per stock, and we obviously want to avoid sending 5x the amount of necessary data, we want to send each user only the exact set of information they require.

At First Glance

If you just take this problem at face value without digging into the details, one approach jumps out pretty quickly. The data set is unique per user, so just send each user their own set of data! This approach would look something like this:

• Create a unique channel for the user
• Build a custom “portfolio” object for each user
• Change the serialization of that object to only include the properties selected by the user
• For every user, when new data arrives, check to see if the new data matches the list of properties the user cares about, and if so, send it to them

While this approach would (somewhat) work, it has a couple fairly notable disadvantages:

• State must be maintained for each user on the server, increasing memory usage substantially
• A lot of additional checking needs to be done to determine if the data should be sent
• The stock data gets tied directly to a specific user

Our first disadvantage, maintaining state, can be resolved with more hardware and persistent storage. Obviously, if we can eliminate the need to maintain state for thousands of users, we reduce the application complexity, remove the need for persistent storage (in case of a soft application reset), and we’re going to need a lot less hardware. Pretty straightforward.

Our second disadvantage, additional data checking, is less important, but still a hassle. When the data is sent, it has to be checked to make sure it’s in the list of data this user cares about. If the sum total of the data is nothing, then the request doesn’t actually need to be sent at all. Not impossible by any stretch of the imagination, but annoying. And software should never be annoying.

Our third disadvantage with this approach, the tight coupling of data to individual users, is a little more interesting. Typically, to get data streaming, the data is published from a separate process - a windows service, linux/unix daemon, whatever. This process contains no information about the web users, and is just managing the data. That means we need to make an adjustment to either the process (to make it aware of the users by using a common storage mechanism, such as a database) or the web application (to make it pre-process the data, such as in WebSync’s “BeforePublish” event, and push the data to the individual users). Neither of these options sound like ideal, and both would still require the web application to be stateful.

So with all these issues, where does that leave us? If we analyze the problems with our “first glance” approach, it becomes obvious that the what we’re looking for is a solution that is both 1) stateless and 2) loosely coupled between the data and users.

Now that we’ve agreed on that…let’s locate that solution!

Channel Mania

Let’s re-state our problem a little, now that we’ve gotten a little more in-depth. Basically, we need to have a way for any user to be able to access live changes for any, all, or none of the data points. If we think about this in terms of the Bayeux protocol, what we’re really saying is that each data point needs its own channel.

That means no more per-user channels, which in turn means our application can be stateless, which also implies that we can keep our publishing of data separate from our consuming of the data. Ok, interesting. Of course, this solution immediately raises some questions as well.

First, isn’t creating a channel for every data point a lot of extra overhead? Well, there are two places where we really have to care about overhead: the server process that’s managing all the messages and the size of the actual message itself. The message size can be easily managed by keeping channel length small, so that’s not a big problem. The server processing of the messages is actually a very interesting discussion…

While I can’t speak for certain about implementations of the Bayeux protocol other than WebSync, I believe our implementation may be similar to many others in this particular aspect. WebSync makes using multiple channels a very efficient method of message distribution. In fact, WebSync only actually creates a channel when at least one user subscribes to it, and destroys it once the last subscription to that channel is gone. What that means is that publishing a message to 10,000 channels when users are only subscribed to 5 channels results in 9,995 messages immediately getting discarded, which is the fastest possible operation that can be performed. So we’re ok on server overhead too.

Final Result

Now we’ve answered our two main objections to this solution: we can keep message sizes small, and having lots and lots of channels is actually a very good thing for efficient message distribution. We’ve also noted that this solution allows us to reach our goals of statelessness and clean separation of tasks between the publishing and consuming of data. So, as a result, we end up with all kinds of channels, each of which might look something like:

"/ticker/GOOG/max"
"/ticker/GOOG/min"
"/ticker/GOOG/current"

So the only question that remains is how to actually subscribe to all these channels without creating a ton of additional requests? Well guess what - the Bayeux protocol accounts for this very scenario. When you make a subscribe request, you can subscribe to multiple channels in a single shot:

client.subscribe({
  channels: [
      "/ticker/GOOG/max",
      "/ticker/GOOG/min",
      "/ticker/GOOG/avg"
  ],
  onReceive: function(args){
      // handle the incoming data...args.channel will describe the 
      // channel, so if we need to we can update specific table 
      // columns, rows, etc.
  }
});

Another interesting aspect of this approach is that it is highly extensible. We’re now able to work with 2D data (stocks => rows, data points => columns) but we can extend our approach out to 3D data with another path portion on the channel such as "/ticker/GOOG/{date}/avg", and start displaying data in a cube instead of a table!

Man, now I want to make a 3D stock ticker…

We encourage all the Lightstreamer users to upgrade to the latest version, to take benefit of the many improvements and new features released.

I will summarize some of the major changes below.

Let’s start with brand new APIs. An official and broadly tested Silverlight client library is now available. A simple example, with full source code, is provided within the new SDK. It is visible online too.

The Flex client library is now at version 2.0. It has undergone a lot of improvements from all perspectives (features, reliability, and performance), derived from on-the-field experience (Lightstreamer Flex has been adopted by a major financial trading application). The push of native objects encoded with Action Message Format (AMF) is now fully supported. If you have complex data structure to push, rather than tabular data, it may be easier and faster to directly process real-time ActionScript objects.

The new JavaScript client library, now at version 4.4, has been deeply refactored, to make it cleaner and lighter. The results are very good, with a new library that is actually smaller and faster. Many internal mechanisms have been improved, including the connection sharing system, the network protocol, and the namespace management. An efficient and reliable backward channel has been implemented, which makes it possible to push messages from the client to the server with advanced features, such as delivery notification and automatic batching.

Both the .NET and Java SE client libraries now support Stream-Sense (the ability to automatically switch between streaming and polling) and mocking interfaces.

The Lightstreamer Server version 3.6 has a brand new threading model.  We have separated the management of external requests into subtasks related with request parsing, authentication, authorization/execution and subscription. Each subtask is then separated into lower level subtasks devoted to individual tables or items. Hence, compound client requests are now managed in parallel. Furthermore, all subscription requests to the Data Adapter are performed in parallel and asynchronously with respect to the client requests. On the network side, we have made NIO (the Java-based socket management mechanisms) even more scalable, by introducing multiple selectors.

As for the Adapter Remoting Infrastructure, now version 1.3, support for disconnected remote Metadata Adapters has been introduced, through the brand new RobustNetworkedMetadataProvider.

I suggest going through the detailed release notes, to learn about all of the enhancements.

The Spanish Lottery

The best prize is big, but the probability to win this reward, “el Gordo” (”the biggest”), is disappointing, 1/165.750.000, if you just buy one ticket (”décimo”) for 20 euros (around $28 USD).

While I would prefer to waste this money in a casino game where the probability to win is not so low, it is very difficult to escape from this well established and popular tradition (beyond gambling).

The raffle is itself a show because nobody knows when the number with “el gordo” is going to be chosen from a hopper containing all of numbers because concurrently another hopper contains the prizes (containing the big ones and many small prizes). Because many more numbers are taken out randomly with minor prizes, the show takes several hours.

An introduction to the Spanish gambling culture is not the objective of this article, the subject is of course Comet.

Several million people follow this Christmas special event over the radio, television and of course the Internet, especially online newspapers. Are these newspapers using a Comet technique to notify users in real-time when the best prizes are known?

The Experiment

I have watched the most important Spanish online newspapers (elpais.com, elmundo.es, abc.es, 20minutos.es, elperiodico.com, cadenaser.com) to check if the number with “el Gordo” is shown in real-time (listening to the radio is an effective way to know when this occurs). When it comes to technology, Spanish online newspapers are very advanced and have no reason to envy any other international newspaper.

In spite of this, the answer to the question is… NO!!

No newspaper was using any kind of Comet technology or even simple Ajax polling. They all are using a typical full page reload using a timer or a refresh meta tag, typically with an interval of 10 – 15 minutes. This interval is too large and is definitively not real-time in this case.

When “el Gordo” was removed from the hopper, people listening to the radio, usually at work (yes, listening to the radio is usually tolerated this day), compulsively reloaded their preferred online newspaper to check the exact number, because this number, obviously, was not shown in their outdated web page. Consequence: some of these newspaper web sites were stalled for a while.

Can Comet help the Spanish Gambling Culture?

Do not take this question too seriously. This “experiment” is an excuse, based on a concrete and real example, to speculate about how Comet technologies can be introduced to online newspapers or similar web sites with expected, but unpredictable, spikes in traffic.

Comet in Online Newspapers

People like to keep open the main page of their preferred online newspaper to check any change. The main page of an online newspaper is usually (ever?) updated using a simple full page refresh with a JavaScript timer or a refresh meta tag directive.

Full reload of the newspaper’s main page is especially ugly for users and expensive for the server because it contains a substantial amounts of information. Reloading completely takes time, bandwidth and server resources to rebuild the web page because usually newspapers make use of template processors and sometimes querying databases, as with any typical web application.

Online newspapers are designed for the desktop using JavaScript and large screens. Usually there are alternative mobile versions, but most of them do not use JavaScript.

Excluding from this analysis mobile based versions, newspapers make some use of JavaScript and DHTML because web site designers know that virtually 100% of visitors are using modern browsers like Internet Explorer 6+, or those derived from Gecko (FireFox, Mozilla, Camino…) or WebKit (Safari, Chrome). All of these browsers of course have support for Ajax.

We know there are several non-Ajax techniques for Comet, like the forever page, forever frame or script tag long-polling. These techniques are not as clean as Ajax-based alternatives, so I will limit this analysis to Ajax polling and long-polling techniques for this article.

Ajax polling and long-polling can improve the real-time experience of online newspaper readers without excluding users for technological reasons (users with very old browsers are in fact already excluded).

Before trying to add Comet to the news publishing world, one limitation is very important to take into consideration: because most online newspapers are free for users and financed by advertisements, we cannot expense much server power and memory per user because this revenue model only scales with million of readers with a very small cost per user. Web applications for online newspapers are basically stateless. Bandwidth is not a problem because any Comet technique used is a bandwidth saver and usually Comet is a power saver too, but this cannot be said for memory consumption with Comet connection usage.

Comet (Ajax polling or long polling) could be used on two levels:

1. To provide an almost real-time updating service of something specific
2. As a replacement of the old-fashioned full page reload technique

Specific Real-Time Services Based on Comet

The Spanish Christmas Lottery is a very good example of a specific service that could be done with Comet. This event is short in duration and occurs over a reasonably small time frame, so it is worth the effort to spend a bit more server power (it depends on the Comet technique used and the update interval).

For instance, using Ajax polling with an interval of one minute or less, the server can send to the client new reward numbers in almost real-time. The return of most of Ajax requests will be empty (almost no server power and bandwidth used) and will help to avoid the issue of compulsive user reload. What is more expensive: X requests with empty responses, or one request with a useless full page reload? It depends on X and how much a full page reload costs.

Long polling can be more bandwidth effective and can offer the user instant notification, but the server cost can increase because it needs more server resources (connections and memory).

Other similar use cases are notification events of breaking news or during sports games.

The ItsNat Approach

Using ItsNat, this can be easily achieved using an Ajax timer (polling).

On the server, because the dynamic zone is small, most of the server DOM will be declared as static, cached as text (DOM serialized as markup) and shared between all users reducing to the minimum the server memory used per user (client page). ItsNat caching is very important because the memory used by a user must be very small to keep the business need of low small cost per user.

Another alternative is having a fully-static server-side DOM (hence fully cached and shared between users) and dynamic changes served from server as JavaScript code (calling ItsNatDocument.addCodeToSend(String)) to the client to render the dynamic zone usually with the help of a JavaScript framework. In spite of ItsNat, this case is a client-centric solution and ItsNat can be replaced with another technology on the server and toolkits like Dojo can provide Ajax polling.

Replacing the Full Page Reload Technique with Comet

This problem is, by far, more complex.

With Comet, the web page would change partially and only if necessary, avoiding full reloads, reducing server power and bandwidth. However, adding Comet may be analyzed with care because in this context one important piece of this puzzle is server memory. The web application of a newspaper is basically stateless, there is not very much personalization and all users usually see the same content. Adding too much state to the server can increment the server costs (as said before in a service financed with ads), that is to say the web application must remain mainly stateless.

Investigating strategies:

A) Client-centric Approach:

In this kind of problem a JavaScript framework with Comet capabilities like Dojo seems to shine because “the application” is brought to the client and only the strictly necessary user data lives in the server because the client is responsible to keep track of visual rendering and state. For instance the server can instruct the client using Comet (polling or long polling) to render new news, to change the ads showed and so on.

But in this case, what is the application? The main page of a newspaper is an interesting example of a highly flexible web application where data and visual appearance are changing frequently. Sometimes these changes are unpredictable when something very important occurs.

Partially updating this kind of page in an unpredictable “application” is hard to drive and code using JavaScript, because the client code may be outdated, and new code should be injected replacing the old code (the client needs to be “reprogrammed”).

Maybe the most effective action in this case is to notify the client for a full page reload (for instance sending a window.location.reload(true)). So the promise of no full reload is not fulfilled in all cases.

B) Server-centric Approach:

Usually Ajax based server-centric frameworks keep track of the visual state in the server, any change in data model is rendered and the client is updated accordingly. If any part of the web page can change, the page is fully dynamic and must be fully saved in the server. This visual state can use too much memory (maybe valid in any typical web application but not for a newspaper). ItsNat is no different because it uses DOM to save this state in server and in theory any part of the page can change (no caching).

Another problem: if any part of the web page can change, how do you modify the visual state within the server memory programmatically without discarding the current state? In theory ItsNat can fully change the page in server and in client with no reload, so an interesting approach would be to change the original file template and automatically update the DOM tree of the live page with changes. This is an interesting approach to investigate.

The easier solution in ItsNat is to update the file template in server accordingly, notify the server of this change and with a long-polling event, or when the client queries the server to detect any new change (Ajax polling), the server will send a window.location.reload(true) JavaScript instruction or similar to fully update the page. In this case the visual state in the server is almost useless because the page is fully reloaded when something important changes, and the partial update requisite is not fulfilled. So again the promise of no full page reload is not fulfilled.

Conclusion

A newspaper is not a typical predictable and fixed web application. Comet (Ajax polling or long-polling) can be used to partially update some concrete and predictable parts of the web page with client or server-centric strategies, and the cost per user may be acceptable.

If the visual structure of the page randomly changes the most effective strategy is a full reload because the “application” has changed and the visual state saved in server and in client is no longer valid and is very hard to update partially. In this case Comet (polling and maybe long-polling) can be used to detect when the page must be fully reloaded, saving significant bandwidth and server power, but the promise of partial rendering of any part of the page is not fulfilled, so typical Ajax approaches, both client and server-centric may be too inflexible and/or consume too much memory.

This article speculates about how to introduce Comet in the main page of online newspapers, this problem is relatively new and open to ideas and experiences.

What do you think?
What kind of strategy would you choose?

The problem selected is to calculate the PI number through Gregory-Leibniz series. This calculation takes significant time if you want high precision.

The objective of the article is monitoring via the web this server thread with no user interaction, periodically obtaining the estimated value and of course asynchronously notifying to the end user when the calculation has finished. As a bonus, the user can start and stop the server thread through web buttons.

The article has two parts/approaches:

1) In the first part the “polling” technique is used (through the use of a meta refresh directive) alongside Ajax to query the thread state, conventional page navigation technology to start and stop the thread and global variables to hold the thread and calculation states. No specific web framework is used (just servlets and JSPs).

2) The second part uses Comet (long-polling) provided by the ItsNat framework. In this case the application is a single page interface and the thread is only attached to the user’s page. In this case a CometNotifier object provided by ItsNat is “attached” to the web page and to the calculator thread.

Note: the original article has an annoying visual problem, to read it I recommend using MSIE 6 (yes in this case a non-W3C CSS compliant browser is great) or Firefox disabling styles (View/Page Style/No Style).

I’m not a big fan of the WebSocket protocol, as evidenced by my blog on how to improve WebSocket, the BWTP proposal and/or the IETF Hybi mailing list. But Chrome and Firefox will soon be supporting WebSocket, so WebSocket (for better or for worse) will soon be available in the wild.

So if you can’t beat them, join them. Having failed to convince others to create a better protocol, I’m now determined for Jetty to provide the best implementation of the protocol and to become the server of choice for WebSocket Comet development, deployment ( and experimenting with improving the protocol).

Jetty’s async IO architecture is ideally suited to providing a very scalable implementation of WebSocket that is well integrated with standard server-side java application environments. Thus Jetty-7.0.1 now includes a WebSocket server. Feedback welcome!

The CometD project ships the following libraries to develop comet web applications:

* A JavaScript library, with bindings for the well known Dojo and jQuery toolkits
* A Java client library, to be used, for example, in rich Java clients such as Swing applications
* A Java server library, to be used to implement the logic behind you application

The Bayeux protocol is considered complete as well. The Python and Perl versions of the cometD server are not yet production quality, and the project is seeking contributors to help get those servers improved.

Maven users will enjoy the simplicity of getting up and running:

$ mvn archetype:generate -DarchetypeCatalog=http://cometd.org
...
$ mvn install jetty:run

The cometD 1.0 announcement blog has more details, and there’s also a lengthy article on cometD features and extensions.

The project includes a server and a JavaScript framework that is a derivative of MooTools (though it of course works with Dojo, jQuery, and other JavaScript toolkits). APE uses a pub/sub model with its own protocol, and states that it currently scales to more than 100,000 concurrent users. It has some similarities to Orbited in its approach of many other protocols and TCPSockets.

Probably the most interesting point from the performance tests was the conclusion that WebSocket does not yet address compression which can impact overall bandwidth sent across the wire, leading HTML5 lead Hixie to comment that if people want compression, it will be added to the next version as an option.