Search Results

TIBCO eFTL™ Java Quick Start

Contents

Getting Started

This quick start guide provides basic instructions for writing TIBCO eFTL applications in Java for TIBCO Cloud™ Messaging.

Building and running samples

Follow the steps below to build and run the Java samples:

  • Unzip eftl-java-samples.zip
  • Change directories into eftl-java-samples/
  • Build project: gradle build
  • Use -f option to specify the configuration file.
  • Run samples: gradle EftlProducer:run --args="-f <full-path-to>/tcm-config.yaml"

Description of sample applications

Producer

The producer demonstrates connecting an eFTL Java application to Cloud Messaging and publishing eFTL messages:

usage: EftlProducer [-c <count>] [-dest <destination>] [-f <config-file>] [-h] [-i <interval>] [-id <client-id>][-t timeout>]
 -c,--count <count>          the number of messages to send before exiting
 -dest <destination>         the destination field value
 -f,--config <config-file>   the path to a configuration yaml
 -h,--help                   this usage
 -i,--interval <interval>    the interval between sends (milliseconds)
 -id <client-id>             client identifier
 -t,--timeout <timeout>      the duration before exiting (seconds)

Consumer

The consumer demonstrates connecting an eFTL Java application to Cloud Messaging, creating a subscription, and receiving eFTL messages:

usage: EftlConsumer [-c <count>] [-client_ack] [-dest <destination>] [-durable_name <durable-name>] [-durable_type <durable-type>]
    [-f <config-file>] [-h] [-id <client-id>] [-t <timeout>]
 -c,--count <count>             the number of messages to receive before exiting
 -client_ack                    enable explicit client acknowledgements
 -dest <destination>            the destination field value
 -durable_name <durable-name>   durable name
 -durable_type <durable-type>   one of default, shared or last-value durable types
 -f,--config <config-file>      the path to a configuration yaml
 -h,--help                      this usage
 -id <client-id>                client identifier
 -t,--timeout <timeout>         the duration before exiting (seconds)

Run the consumer and producer at the same time to demonstrate real-time messaging. To demonstrate persistence, stop the consumer, run the producer, and restart the consumer using the same durable name. For default durables, you will also need to supply the same client id each time.

Using the eFTL SDK

For Java programs, include the eFTL Client Java library JAR file tibeftl.jar in your CLASSPATH.

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.

Client Identifiers

You must provide a unique identifier for your client if you want it to receive any messages missed while disconnected. Only one application can connect with a given client id at any given time. If a second application connects with a client id already in use by another application, the first application will disconnect.

Connection Example

final Properties props = new Properties();
// set the password to tcm_authentication_key
props.setProperty(EFTL.PROPERTY_PASSWORD, "<tcm_authentication_key>");

// provide a unique client identifier
props.setProperty(EFTL.PROPERTY_CLIENT_ID, "abc123");

// connect to TIBCO Cloud Messaging
EFTL.connect("<eftl_url>",
             props, new ConnectionListener() {
                @ Override
                public void onConnect(Connection connection) {
                    System.out.printf("connected\n");
                }
                @ Override
                public void onDisconnect(Connection connection, int code, String reason) {
                    System.out.printf("disconnected: %s\n", reason);
                }
                @Override
                public void onReconnect(Connection connection) {
                    System.out.printf("reconnected\n");
                }
                @Override
                public void onError(Connection connection, int code, String reason)
                {
                    System.out.printf("error: %s\n", reason);
                }
            });

onConnect callback

The onConnect callback is invoked once the connection to TIBCO Cloud Messaging is established. The Connection object passed to the onConnect callback can be used for subscribing to messages and publishing messages.

onDisconnect callback

If the connection cannot be established, or is lost, the onDisconnect callback is invoked.

onReconnect callback

The onReconnect callback is invoked when the client successfully reconnects to TIBCO Cloud Messaging.

onError callback

The onError callback is invoked when TIBCO Cloud Messaging sends an error to the client.

Publishing Messages

Clients can publish messages after they are connected to TIBCO Cloud Messaging. To publish messages, use the connection returned in the onConnect callback.

// Create a message
// Fields and arrays of type string, numeric, date, and sub-messages are used in messages.
connection.publish(message, null);
final Message message = connection.createMessage();
message.setString("event", "hello");
message.setString("text": "Hello, World!");

// To be notified if the publish was successful or if an error occurred, callbacks can be provided.

// Publish a message to TIBCO Cloud Messaging
connection.publish(message, new CompletionListener() {
   @Override
   public void onCompletion(Message message) {
      System.out.printf("publish success\n");
   }
   @Override
   public void onError(Message message, int code, String reason) {
      System.out.printf("publish error: %s\n", reason);
   }
});

Receiving Messages

After clients are connected to TIBCO Cloud Messaging, they can create one or more subscriptions to receive messages of interest. You can subscribe to messages by matching the message fields of interest. Use the connection returned in the onConnect callback to register subscriptions.

// Create a subscription in TIBCO Cloud Messaging
//
// This subscription matches all published messages that contain a
// field named `event` with a value of `hello`
//
// This subscription also sets the durable name to "hello" which allows
// the client to receive messages that were published while disconnected
//
connection.subscribe("{\"event\":\"hello\"}", "hello",
    new SubscriptionListener() {
        @Override
        public void onMessage(Message[] messages) {
            for (Message message : messages) {
                System.out.printf("message received: %s", message.getString("text"));
            }
        }
        @Override
        public void onSubscribe(String subscription) {
            System.out.printf("subscribed");
        }
        public void onError(String subscription, int code, String reason) {
            System.out.printf("subscription error: %s\n", reason);
        }
    });

Matcher field

The matcher field specifies the messages that are to be received by matching their content. In this case, the subscription receives all published messages containing a field named event whose value is hello.

Durable field

The durable field is the unique subscription name used by TIBCO Cloud Messaging to store messages for the client when the client is not connected.

onMessage callback

The onMessage callback is invoked when the content of a published message matches the subscription’s matcher.

onError callback

The onError callback is invoked when an error occurs while registering the subscription, typically because of an invalid matcher or invalid durable.