Search Results

TIBCO FTL® C# Quick Start

Contents

Getting Started

This quick start guide provides basic instructions for writing TIBCO FTL applications in C# for TIBCO Cloud™ Messaging.

Follow the steps below to use the sample applications:

Building and running samples

Follow the steps below to build and run the C# samples:

  • On Linux and macOS, add the <ftl>/<version>/lib to LD_LIBRARY_PATH.
  • On Windows, add <ftl>\<version>\lib to your PATH.
  • Unzip ftl-dotnet-samples.zip
  • Copy a tcm-config.yaml configuration file into the current working directory.
  • Run sample: dotnet run --project ftl-dotnet-samples/ftlconsumer
  • Run sample: dotnet run --project ftl-dotnet-samples/ftlproducer

Description of sample applications

Producer

The producer demonstrates connecting an FTL C# application to Cloud Messaging and publishing FTL messages.

Consumer

The consumer demonstrates connecting an FTL C# application to Cloud Messaging, creating a subscription, and receiving FTL messages.

Run the consumer and producer at the same time to demonstrate real-time messaging. Stop the consumer, run the producer, and restart the consumer to demonstrate persistence.

Using the FTL SDK

To use the FTL SDK include the library and any third-party dependencies in your source files: using TIBCO.FTL;

Connecting to TIBCO Cloud Messaging

The client configuration file contains all the information client applications need to securely connect to TIBCO Cloud Messaging. Generate the client configuration file using the roles REST API or user interface. Generate as many configuration files as needed for each Role.

Note: TIBCO Cloud Messaging samples require a client configuration file to run.

TIBCO FTL Server Validation

TIBCO FTL applications cannot use their host’s certificate pool to automatically validate TIBCO Cloud Messaging servers. For server verification to work, TIBCO FTL applications must supply the value of ftl_certificate as the server certificate when connecting to TIBCO Cloud Messaging. The value of ftl_certificate can be found in the configuration file.

Connection Example

ITibProperties realmProps = FTL.CreateProperties();

realmProps.Set(FTL.REALM_PROPERTY_STRING_CLIENT_LABEL, "tcmdemopub.cs");
realmProps.Set(FTL.REALM_PROPERTY_STRING_USERNAME, options["tcm_authentication_id"]);
realmProps.Set(FTL.REALM_PROPERTY_STRING_USERPASSWORD, options["tcm_authentication_key"]);
realmProps.Set(FTL.REALM_PROPERTY_LONG_TRUST_TYPE, FTL.REALM_PROPERTY_HTTPS_CONNECTION_USE_SPECIFIED_TRUST_STRING);

string ftlCert = options["ftl_certificate"];
ftlCert = ftlCert.Replace("\\n", "\n");
realmProps.Set(FTL.REALM_PROPERTY_STRING_TRUST_PEM_STRING, ftlCert);

realm = FTL.ConnectToRealmServer(options["ftl_url"], options["ftl_application"], realmProps);

Publishing a message

Before a message can be published, the publisher must be created on the previously-created realm. Specify the endpoint onto which the messages will be published. In this example we are using the “default” endpoint.

IPublisher pub = null;
pub = realm.CreatePublisher("default");

In order to send a message, the message object must first be created via a call to realm.CreateMessage. Specify the format name. Here the format demo_tcm is used. TCM only supports dynamic formats.

msg = realm.CreateMessage("demo_tcm");

A newly-created message is empty - it contains no fields. The next step is to add one or more fields to the message. msg.SetString adds a string field. In this example a string field named demo_tcm is added, with the value “message seq”.

String content = String.Format("message {0}", seq);
msg.SetString("demo_tcm", content);

Once the message is complete, it can be sent via pub.Send(). Specify the message to be sent.

pub.Send(msg);

Subscribing and receiving messages

For messages to be delivered to a client application, three things are required:

  • An event queue.
  • A subscriber object on an endpoint.
  • The created subscriber object must be added to an event queue to dispatch the received messages.

Event Queue

Before the subscriber object can be added to an event queue, the event queue must exist:

queue = realm.CreateEventQueue();

Subscriber

Create the subscriber object by specifying the endpoint name, an optional content matcher, and an optional properties object:

sub = realm.CreateSubscriber("default", contentMatcher, subscriberProps);

The last step is to add the subscriber object to the event queue. This allows the event queue to dispatch messages sent to that subscriber:

queue.AddSubscriber(sub, this);

Endpoints

TIBCO Cloud Messaging only supports a fixed set of endpoints: default, shared, last-value and map. Each endpoint is associated with a durable type of the same name. If your application does not need persistence use the default endpoint.

Content Matcher

A content matcher is used to limit which messages are delivered to a client application based on the content of the message. The string passed to realm.CreateContentMatcher() contains JSON which specifies the field name in the message, and the required value of that field. In this case, {"demo_tcm":true} matches any message which contains the field demo_tcm.

contentMatcher = realm.CreateContentMatcher("{\"demo_tcm\":true}");

Subscriber Properties

A shared durable essentially acts like a queue. Messages are stored in the persistent server, and apportioned among active subscribers to the durable in a round-robin fashion. Each subscriber must specify the same durable name. The durable name is defined by properties specified when the subscriber is created. If your application does not need persistence do not supply a durable name.

subscriberProps = FTL.CreateProperties();
subscriberProps.Set(FTL.SUBSCRIBER_PROPERTY_STRING_DURABLE_NAME, "tcmdemosub.cs");

Dispatching

Begin dispatching messages

Console.WriteLine("Waiting for message(s)");
while (!finished)
{
    queue.Dispatch();
}

Message Callback

A message callback must have the signature MessagesReceived(IMessage[], int, IEventQueue) and be a method of a class which implements ISubscriberListener:

public void MessagesReceived(IMessage[] messages, ref int count, IEventQueue eventQueue)
{
    int i;
    for (i = 0; i < count; i++)
    {
        Console.WriteLine("Received " + (IMessage)messages[i]);
    }
}

Subscribing to Notifications

In some situation, FTL must notify a client application of a condition which cannot be delivered through an event queue. Register a notification handler which is invoked when an administrative action occurs which requires the client application to be notified:

realm.SetNotificationHandler(this);

A notification handler callback must have the signature ONotification(RealmNotificationType, string) and be a method of a class which implements INotificationHandler:

public void OnNotification(RealmNotificationType type, string reason)
{
    if (type == RealmNotificationType.CLIENT_DISABLED)
    {
        System.Console.WriteLine("Application administratively disabled: " + reason);
        finished = true;
    }
    else
    {
        System.Console.WriteLine("Notification type " + type + ": " + reason);
    }
}

Cleanup

Once objects are no longer needed, they should be disposed of - and generally in reverse order of creation.

Publisher

msg.Dispose();
pub.Dispose()
realm.Dispose();
realmProps.Dispose();

Subscriber

contentMatcher.Dispose();
queue.RemoveSubscriber(sub);
queue.Dispose();
sub.Dispose();
realm.Dispose();

To permanently destroy a durable subscription, including any messages stored by TIBCO Cloud Messaging for that durable, first close the subscription and then call unsubscribe using the realm object. Supply the unsubscribe call with the endpoint name and durable name used to create the durable subscription.

sub.Dispose();
realm.Unsubscribe("default", "tcmdemosub.cs");