Instances and Terminals - xylamic/lightrail-pubsub-integration-framework GitHub Wiki

Lightrail Instances

Before any messages can be delivered to or from an application, the application must first get an instance of the Lightrail. The name of the instance should be meaningful to your application and the description provides more detail about what this instance will be used for.

Example C++

// include Lightrail[D].lib

#include <ILightrail.h>
#include <Lightrail.h>

using namespace Xylasoft;

// create the Lightrail instance
ILightrail* client = Lightrail::GetLightrailInstance(L"Name", L"Description");

// setup any callbacks for subscription/response

// start the Lightrail so it can receive messages and send messages
client->StartDeliveries();

// send and receive deliveries

// when you are closing your application, stop the client
client->StopDeliveries();

// when all work is completed, remove the instance
delete client;

Example C#

// include Xylasoft.LightrailNet.dll

using Xylasoft;

// create the Lightrail instance
LightrailClient client = new LightrailClient("Name", "Description");

// setup any callbacks for subscription/response

// start the Lightrail so it can receive messages and send messages
client.StartDeliveries();

// send and receive deliveries

// when you are closing your application, stop the client
client.StopDeliveries();

Once an instance has been established, event callbacks should be registered first. Setting up these event callbacks are discussed in the other sections (subscription/response). When deliveries are “started”, messages can be sent and received. When communication is finished within your application, the instance should be stopped.

Terminals

The Terminal string, similar to a topic, is what allows other Terminals to bind. These strings will be compared and if they match, the message will be transferred from a publishers to a subscriber, or a requester to a responder.

The Terminal string must always begin with a [ and has 'sections' that are separated by >. If a section is empty >> (arrows with nothing between), then it behaves as a wild card and the section does not need to match. The string can end with > or ], where > allows more sections to follow and ] does not.

Example C++

// create the terminal
const ITerminal* terminal = Lightrail::NewTerminal(L"PubTerminal", L"PubDesc",
     L"[Global>Company>Region>Domain>App>Instance>Publish]");

// register the terminal
client->RegisterTerminal(Standpoint::PUBLISHER, terminal);

Example C#

client.RegisterTerminal(TerminalStandpoint.Publisher, "PubTerminal", "PubDesc", 
    "[Global>Company>Region>Domain>App>Instance>Publish]");

Below are some examples of Terminal string and indications of which ones match.

[a>b>c] = [a>b>c]
[a>b> = [a>b>c]
[a>b>c] = [a>
[a>>c] = [a>b>c]
[a>b>c] != [a>b>d]
[a>>c] != [a>b>d]
[a>b>d] != [a>b>c>

To send or receive a message, a "Terminal" must be registered. A Terminal provides the endpoint which a message arrives or leaves from. The name provides context of what information will be transferred and the description provides further details. The Terminal string, similar to a topic, is what allows other Terminals to bind. These strings will be compared and if they match, the message will be transferred from a publishers to a subscriber, or a requester to a responder. The Terminal string must always begin with a [ and has 'sections' that are separated by >. If a section is empty >> (arrows with nothing between), then it behaves as a wild card and the section does not need to match. The string can end with > or ], where > allows more sections to follow and ] does not.

Global - For global delivery context
[Company] - The company name.
[Region] - The regional identifier (location, division, etc).
[Domain] - A lesser group than region.
[Application] - The application type.
[Instance] - The instance of the application, possibly a machine name.
[..MessageType..] - The actual message type and other information (could be several sections).

Even though this format exists, there are no restrictions as what strings are allowed; it is solely at your discretion. As a general rule, the more information that can be embedded in a string, the more flexibility you allow yourself for the future. You can always wildcard-out obvious information in smaller systems, so you can future-proof your system now with no added overhead.