"Hello World" tutorial for Lightstreamer Java Adapter API
Java
Switch branches/tags
Nothing to show
Clone or download
Permalink
Failed to load latest commit information.
lib Fix compile lib dependencies Jul 10, 2014
src Standardize copyright notes. Oct 26, 2015
.gitattributes First commit Aug 9, 2013
.gitignore First commit Aug 9, 2013
LICENSE First commit Aug 9, 2013
README.md Fix Github query string for searches Oct 10, 2017
adapter-logo.png Add adapter logo png Jun 11, 2014

README.md

Lightstreamer - "Hello World" Tutorial - Java Adapter

The demos of the "Hello World with Lightstreamer" series are very basic examples where we push the alternated strings "Hello" and "World", followed by the current timestamp, from the server to the browser.

This project contains the source code and all the resources needed to install the Java Data Adapter for the "Hello World" Tutorial.

As an example of Clients Using This Adapter, you may refer to the Lightstreamer - "Hello World" Tutorial - HTML Client and view the corresponding Live Demo.

Details

Lightstreamer is made up of a Server and a set of Client libraries. Lightstreamer's job is to push real-time data over the Web in both directions (from the server to the clients and from the clients to the server). To do that, it uses a set of techniques refined and tuned over the last 13 years, including HTTP Streaming, Comet, and WebSockets.

Let's keep the "Hello World" demo very basic: we want to push the alternated strings "Hello" and "World", followed by the current timestamp, from the server to the browser. The demo is based on two components: the HTML front-end (on the client side) of which full details you can find at Lightstreamer - "Hello World" Tutorial - HTML Client, and the Data Adapter (on the server side) detailed in this project.

Data Model

In the Lightstreamer framework, you subscribe to Items. An item is made up of a number of fields whose values change over time. Here are some examples of possible items:

  • An item in Lightstreamer could represent an item on eBay, say, a pair of "Nike Air Jordan" shoes. The Item name would be "NIKE-AIR-JORDAN-XX3-XXIII-23-PREMIER-Limited-sz-10". Some fields would be: current_bid, total_bids, and high_bidder. When a field changes, the new value is pushed to the browser and displayed in real-time.
  • An item could represent a weather probe. The Item name would be, for example, "Mt_Everest_Probe.1" (this probe was left by MIT after the 1998 Everest Expedition). Some fields would be: temperature, barometric_pressure, and light_level.
  • In finance market data dissemination, an item often represents a stock quote. The item name would be, for example, "TIBX.O" (TIBCO Software Inc. on Nasdaq). Some fields would be: TRDPRC_1, TRDTIM_1, BID, and ASK.

That said, how can we represent our very complex Hello World messages? Of course, through an item... The item name will be greetings. It will have two fields: message and timestamp.

Dig the Code

We need to create the server-side code that will pass the data to the Lightstreamer Server, which, in turn, will pass it to the front-end. This is done by writing a Data Adapter, a plug-in module that injects data into the Server. Let's choose Java to write our Data Adapter (the other current options would be to use .NET or to work at the TCP socket level, but we are adding more).

The Data Adapter

First, we need to implement the SmartDataProvider interface:

public class HelloWorldDataAdapter implements SmartDataProvider {

We will be passed a reference to a listener that we will use to inject the real-time events:

private ItemEventListener listener;

public void setListener(ItemEventListener listener) {
   this.listener = listener;
}

Then we must be ready to accept subscription requests:

public void subscribe(String itemName, Object itemHandle, boolean needsIterator)
     throws SubscriptionException, FailureException {
   if (itemName.equals("greetings")) {
      gt = new GreetingsThread(itemHandle);
      gt.start();
   }
}

When the greetings item is subscribed to by the first user, our Adapter receives that method call and starts a thread that will generate the real-time data. If more users subscribe to the "greetings" item, the subscribe method is not called anymore. When the last user unsubscribes from this item, our Adapter is notified through the unsubscribe call:

public void unsubscribe(String itemName)
     throws SubscriptionException, FailureException {
   if (itemName.equals("greetings") && gt != null) {
      gt.go = false;
   }
}

We can stop publishing data for that item. If a new user re-subscribes to "greetings", the subscribe method will be called again. This approach avoids consuming processing power for items no one is currently interested in.

Now, let's see what the GreetingsThread does. Its run method is pretty straightforward:

public void run() {
   int c = 0;
   Random rand = new Random();
   while(go) {
      Map data = new HashMap();
      data.put("message", c % 2 == 0 ? "Hello" : "World");
      data.put("timestamp", new Date().toString());
      listener.smartUpdate(itemHandle, data, false);
      c++;
      try {
         Thread.sleep(1000 + rand.nextInt(2000));
      } catch (InterruptedException e) {
      }
   }
}

We create a HashMap containing the message (alternating "Hello" and "World") and the current timestamp. Then we inject the HashMap into the Lightstreamer Server through the listener (and the itemHandle we were passed at subscription time). We do a random pause between 1 and 3 seconds, and we are ready to generate a new event.

The full source code of this Data Adapter is shown in the HelloWorldDataAdapter.java source file of this project. This example is really very basic and exploits only a minor portion of the features offered by the Lightstreamer API. To delve a bit more into the API used above, you can take a look at the online API references: Java In-Process Adapter API Reference.

The Adapter Set Configuration

This Adapter Set Name is configured and will be referenced by the clients as HELLOWORLD. This demo implements just the Data Adapter, while instead, as Metadata Adapter, we use the LiteralBasedProvider, a simple full implementation of a Metadata Adapter, already provided by Lightstreamer server. A Metadata Adapter is responsible for managing authentication, authorization, and quality of service, but for this demo, we don't need any custom behavior.

The adapters.xml file for this demo should look like:

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

NOTE: not all configuration options of an Adapter Set are exposed by the file suggested above. You can easily expand your configurations using the generic template, DOCS-SDKs/sdk_adapter_java_inprocess/doc/adapter_conf_template/adapters.xml, as a reference.

Install

If you want to install a version of this demo in your local Lightstreamer Server, follow these steps:

Build

To build your own version of HelloWorldDataAdapter.jar, instead of using the one provided in the deploy.zip file from the Install section above, follow these steps:

  • Download this project.
  • Get the ls-adapter-interface.jar file from DOCS-SDKs/sdk_adapter_java_inprocess/lib within your Lightstreamer Server installation, and copy it into the lib folder.
  • Build the java source file. Here is an example for that:
 > mkdir tmp_classes
 > javac -classpath lib/ls-adapter-interface.jar -d tmp_classes -sourcepath src src/HelloWorldDataAdapter.java
 > jar cvf HelloWorldDataAdapter.jar -C tmp_classes .
  • Copy the just compiled HelloWorldDataAdapter.jar in the adapters/HelloWorld/lib folder of your Lightstreamer Server installation.

In case you want to use Eclipse for developing & running your own Adapter Set, please follow the instructions provided in this thread of our Java Adaper API support forum.

See Also

Clients Using This Adapter

Related Projects

Lightstreamer Compatibility Notes

  • Compatible with Lightstreamer Java In-Process Adapter API version 5.1 or newer.

Final Notes

Please post to our support forums any feedback or question you might have. Thanks!