Pages

Saturday, April 04, 2009

Lightstreamer : A tutorial for java Adapters and Flex clients : Part 2

I know i am posting this second part pretty late, but can't help, have loads of work at hand. So, here goes the next part of the Lightstreamer tutorial which explains the Flex part. Remember, the flex client swc is available only if you download the evaluation version of the Lightstreamer. This is not packaged with the Moderato version.

This tutorial will explain how to use the native AS3 Flex client lib to subscribe data from the Adapter that I present in the previous post. Strictly speaking, this post will just provide a beginning to LS, we have developed a complete framework on the Flex side which is being used by around 9 modules transparently with out the knowledge of existence of LS. Well, I will not and I am not supposed to provide any more details about it.

Change the port at which the LS server runs. Edit the $LS_HOME/conf/lightstreamer_conf.xml. Change <port>8080</port> to <port>8787</port> in the HTTP server configuration present. Restart the server.

Step 1:

Use the LSClient to connect to the LS server which has the adapter deployed.
var lsClient:LSClient = new LSClient(); 
lsClient.addEventListener(StatusChangeEvent.STATUS_CHANGE,onLSStatusChange); // The LS sends status changes. The method onLSStatusChange handles it.

var connectionInfo:ConnectionInfo = new ConnectionInfo();
connectionInfo.setServer("localhost");// Place where the server is running
connectionInfo.setAdapter("MyJavaAdapter"); // This is the name of the adapter we configured in the adapters.xml
connectionInfo.setControlPort("8787");// The port we configured above.
connectionInfo.setPort("8787");// The port we configured above.
connectionInfo.setControlProtocol("http");// The protocol to use http or https. For quotes data, http is preferred.
connectionInfo.setProtocol("http");

var connectionPolicy:ConnectionPolicy = new ConnectionPolicy(); //These are more configurations, as needed by the application.
connectionPolicy.setTimeoutForStalled(2);
connectionPolicy.setTimeoutForReconnect(15);
connectionPolicy.setRetryTimeout(5);

//Connect to Lightstreamer Server
try {
lsClient.openConnection(connectionInfo,connectionPolicy);
} catch(e:Error) {
Alert.show(e.message);
}

public function onLSStatusChange(event:StatusChangeEvent):void{
trace(event.previousStatus + " => " + event.status);
//The status can change as below. You can display a popup or some indicators to the user showing what is happening.
/* "DISCONNECTED" => "CONNECTING"
"CONNECTING" => "STREAMING"
"STREAMING" => "CONNECTING"
"STALLED" => "CONNECTING"
"CONNECTING" => "POLLING"
/*
}

Step 2:
Subscribe to the data. You can use Visual or NonVisual table. We use only the NonVisual table. ok, I am sure you did not understand what is a table. In a simple term, a table contains rows and columns. In LS term, the columns are the items you subscribe for. For e.g. LastPrice. The rows are the items you subscribe. For E.g. Quote data for IBM. So, each row is a unique subscription for the items present as columns. Non-Visual table is not a component that will be displayed on the UI. You handle the display yourself. I feel this is more flexible and powerful than Visual Table.
var nonVisualTable:NonVisualTable = new NonVisualTable(new Array("IBM"),new Array("LastAsk","LastBid","LastPrice","Symbol"),"MERGE"); 
nonVisualTable.setDataAdapter("MYJAVAADAPTER");
nonVisualTable.setSnapshotRequired(false);
nonVisualTable.addEventListener(NonVisualItemUpdateEvent.NON_VISUAL_ITEM_UPDATE,handleUpdate);
nonVisualTable.setRequestedMaxFrequency(1);
lsClient.subscribeTable(nonVisualTable);

Ok, here I will explain some terms.
The last param in the constructor arg of NonVisualTable is the management mode. There are 4 types, namely, RAW, DISTINCT, MERGE and COMMAND. You can look at documentation for detailed explanation of all these.
In simple terms, if your data is constantly changing like quotes, and LS sends only those data that have changed. The data that is not changed is not sent and its state is maintained as previous. i.e the last unchanged value. This type of management of data is called MERGE mode.
If you need the data as being generated, i.e each of the data should be pushed to the front end, like news data, then you use the DISTINCT mode.
RAW mode is similar to Distinct. Each and every data is sent to the client. I am not so sure, but the only difference the document says is, in case of DISTINCT not all the events be sent to the client.
COMMAND is more complicated and has better performance, please read the documentation for it. I have used MERGE and DISTINCT mode till now successfully.

The DataAdapter is the one you configured in adapters.xml, in our case "MYJAVAADAPTER".
You can request a snapshot if the data-adapter supports one.

The requested max frequency limits the updates I get from the LS server. I do not need more than 1 update per item per second. So, its 1 in my case. Make sure you use this with MERGE mode only.

handleUpdate gets the updates from the LS. It is given below. The code is self explanatory.
public function handleUpdate(event:NonVisualItemUpdateEvent):void{ 
var eventType:String = event.item; //This provides the update event name, in our case IBM.
trace(extractFieldData(event,"LastAsk"));
trace(extractFieldData(event,"LastBid"));
trace(extractFieldData(event,"LastPrice"));
}
private function extractFieldData(event:NonVisualItemUpdateEvent,field:*):String {
var value:String;
if (event.isFieldChanged(field)) {
value = event.getFieldValue(field);
} else {
value = event.getOldFieldValue(field);
}
return value;
}

Step 3: When all done, please un-subscribe the table.
lsClient.unsubscribeTable(nonVisualTable); 

This is all you need to get going on the Flex side with LS. We started from here and you wont believe where we have reached. The LS forums is really really helpful. Please post any queries there, I have always got sensible and useful replies. Try going through the lightstreamer_conf.xml, there are a lot of things you can configure there. Any developer with some experience will understand it. If you need more help, just go to the forums.

This will end the Lightstreamer tutorials from my side. Try this technology, am sure you will love it...