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.
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.
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.
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).
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.
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, see the Java In-Process Adapter Interface Project for details.
If you want to install a version of this demo on your local Lightstreamer Server, follow these steps:
- Download Lightstreamer Server (Lightstreamer Server comes with a free non-expiring demo license for 20 connected users) from Lightstreamer Download page, and install it, as explained in the
GETTING_STARTED.TXTfile in the installation home directory. - Get the
deploy.zipfile of the latest release, unzip it, and copy the just unzippedHelloWorldfolder into theadaptersfolder of your Lightstreamer Server installation. - Launch Lightstreamer Server.
- Test the Adapter, launching the Lightstreamer - "Hello World" Tutorial - HTML Client listed in Clients Using This Adapter.
To build your own version of this demo, instead of using the one provided in the deploy.zip file from the Install section above, you have two options: either use Maven (or other build tools) to take care of dependencies and building (recommended) or gather the necessary jars yourself and build it manually. For the sake of simplicity, only the Maven case is detailed here.
You can easily build and run this application using Maven through the pom.xml file located in the root folder of this project. As an alternative, you can use an alternative build tool (e.g. Gradle, Ivy, etc.) by converting the provided pom.xml file.
Assuming Maven is installed and available in your path you can build the demo by running
mvn package- Complete list of "Hello World" Adapter implementations with other technologies
- LiteralBasedProvider Metadata Adapter
- Compatible with Lightstreamer Java In-Process Adapter API version 7.3.0 or newer.
Please post to our support forums any feedback or questions you might have. Thanks!