search

Lightstreamer / Lightstreamer-example-HelloWorld-adapter-dotnet

"Hello World" tutorial for Lightstreamer .NET Adapter API
Apache License 2.0
5 stars 3 forks source link

readme

Lightstreamer - "Hello World" Tutorial - .NET Adapter

This project, of the "Hello World with Lightstreamer" series, will focus on a .NET port of the Java Data Adapter illustrated in Lightstreamer - "Hello World" Tutorial - Java Adapter. In particular, both a C# version and a Visual Basic version of the Data Adapter will be shown.

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

Details

First, please take a look at the previous installment Lightstreamer - "Hello World" Tutorial - HTML Client, which provides some background and the general description of the application. Notice that the front-end will be exactly the same. We created a very simple HTML page that subscribes to the "greetings" Item, using the "HELLOWORLD" Adapter. Now, we will replace the "HELLOWORLD" Adapter implementation based on Java with C# and Visual Basic equivalents. On the client side, nothing will change, as server-side Adapters can be transparently switched and changed, as long as they respect the same interfaces. Thanks to this decoupling provided by Lightstreamer Server, we could even do something different. For example, we could keep the Java Adapter on the server side and use node.js, instead of HTML, on the client side. Or, we could use the C# Adapter on the server side and use Java, instead of HMTL or node.js, on the client side. Basically, all the combinations of languages and technologies on the client side and on the server side are supported.

Please refer to General Concepts for more details about Lightstreamer Adapters.

.NET Interfaces

Lightstreamer Server exposes native Java Adapter interfaces. The .NET interfaces are added through the Lightstreamer Adapter Remoting Infrastructure (ARI).

The Architecture of Adapter Remoting Infrastructure for .NET.

General architecture

ARI is simply made up of two Proxy Adapters and a Network Protocol. The two Proxy Adapters, one implementing the Data Adapter interface and the other implementing the Metadata Adapter interface, are meant to be plugged into Lightstreamer Kernel.

Basically, the Proxy Data Adapter exposes the Data Adapter interface through TCP sockets. In other words, it offers a Network Protocol, which any remote counterpart can implement to behave as a Lightstreamer Data Adapter. This means you can write a remote Data Adapter in any language, provided that you have access to plain TCP sockets. But, if your remote Data Adapter is based on certain languages/technologies (such as Java, .NET, and Node.js), you can forget about direct socket programming, and leverage a ready-made library that exposes a higher level interface. Now, you will simply have to implement this higher level interface.

In this specific example we will leverage the Lightstreamer .NET Standard Adapter API library. So, let's recap... the Proxy Data Adapter converts from a Java interface to TCP sockets, and the .NET Standard library converts from TCP sockets to a .NET interface.
The full API references for the languages covered in this tutorial are available from .NET Standard API reference for Adapters.

Dig the Code

The C# Data Adapter

(Skip this section if you are only interested in The Visual Basic Data Adapter.)

The C# Data Adapter consists of two classes: the DataAdapterLauncher contains the application's Main and initializes the DataProviderServer (the provided piece of code that implements the Network Protocol); the HelloWorldAdapter implements the actual Adapter interface.

DataAdapterLauncher

The DataAdapterLauncher creates a DataProviderServer instance and assigns a HelloWorldAdapter instance to it. Then, it creates a TCP client socket on TCP port 6661. Then it assigns the stream of the socket to both the RequestStream and ReplyStream properties of the DataProviderServer. As we said, after creating this socket, you don't have to bother with reading and writing, as these operations are automatically handled by the DataProviderServer.

Finally, the DataProviderServer is started.

HelloWorldAdapter

The HelloWorldAdapter class implements the IDataProvider interface (which is the .NET remote equivalent of the Java DataProvider interface).

Implement the SetListener method to receive a reference to the server's listener that you will use to inject events.

Then, implement the Subscribe method. When the "greetings" item is subscribed to by the first user, the 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, the Adapter is notified through the Unsubscribe call. In this case, we stop the publisher thread for that item. If a new user re-subscribes to "greetings", the Subscribe method is called again. As already mentioned in the previous installment, this approach avoids consuming processing power for items no one is currently interested in.

The Run method is executed within the thread started by Subscribe. Its code is very simple. We create a Hashtable containing a message (alternating "Hello" and "World") and the current timestamp. Then we inject the Hashtable into the server through the listener. We wait for a random time between 1 and 3 seconds, and we are ready to generate a new event.

The Visual Basic Data Adapter

Now let's work with Visual Basic instead of C#.

It consists of two modules: the DataAdapterLauncher, which contains the application's Main and initializes the DataProviderServer (the provided piece of code that implements the Network Protocol); The HelloWorldAdapter that implements the actual Adapter interface.

DataAdapterLauncher

The DataAdapterLauncher.vb creates a DataProviderServer instance and assigns a HelloWorldAdapter instance to it. Then, it creates a TCP client socket on TCP port 6661. Then it assigns the stream of the socket to both the RequestStream and ReplyStream properties of the DataProviderServer. As we said, after creating this socket, you don't have to bother with reading and writing, as these operations are automatically handled by the DataProviderServer.

Finally, the DataProviderServer is started.

HelloWorldAdapter

The HelloWorldAdapter class implements the IDataProvider interface (which is the .NET remote equivalent of the Java DataProvider interface).

Implement the SetListener subroutine to receive a reference to the server's listener that you will use to inject events.

Then, implement the Subscribe subroutine. When the "greetings" item is subscribed to by the first user, the Adapter receives that subroutine call and starts a thread that will generate the real-time data. If more users subscribe to the "greetings" item, the Subscribe subroutine is not called anymore. When the last user unsubscribes from this item, the Adapter is notified through the Unsubscribe call. In this case, we stop the publisher thread for that item. If a new user re-subscribes to "greetings", the Subscribe subroutine is called again.

The Run subroutine is executed within the thread started by Subscribe. Its code is very simple. We create a Hashtable containing a message (alternating "Hello" and "World") and the current timestamp. Then we inject the Hashtable into the server through the listener. We wait for a random time between 1 and 3 seconds, and we are ready to generate a new event.

The Adapter Set Configuration

For this demo, we just use a Proxy Data Adapter, while instead, as Metadata Adapter, we use the LiteralBasedProvider, a simple full implementation of a Metadata Adapter, already provided by Lightstreamer server. This Adapter pair will be referenced by the clients as "PROXY_HELLOWORLD". The adapters.xml file looks like:

<?xml version="1.0"?>

<adapters_conf id="PROXY_HELLOWORLD">

  <metadata_provider>
    <adapter_class>com.lightstreamer.adapters.metadata.LiteralBasedProvider</adapter_class>
  </metadata_provider>

  <data_provider>
    <adapter_class>PROXY_FOR_REMOTE_ADAPTER</adapter_class>
    <classloader>log-enabled</classloader>
    <param name="request_reply_port">6661</param>
  </data_provider>

</adapters_conf>

NOTE: not all configuration options of a Proxy Adapter are exposed by the file suggested above.
You can easily expand your configurations using the generic template for basic and robust Proxy Adapters as a reference.

Install

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

Build

Build The C# Data Adapter

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

Build The Visual Basic Data Adapter

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

See Also

Clients Using This Adapter

Related Projects

Lightstreamer Compatibility Notes

Final Notes

For more information, please visit our website and post to our support forums any feedback or question you might have. Thanks!