TIBCO FTL Publishing Operator

Introduction

The TIBCO Streaming® Operator for TIBCO FTL® allows a Streaming application to publish messages to an FTL endpoint. The operator has two input ports and one output port. The first input port is used to start and stop publishing to the FTL endpoint. The second input port is used to enqueue tuples to the operator containing FTL messages to be published. The output port emits status tuples.

The operator supports a subset of Streaming data types that contains tuples and lists, though lists may not contain elements of type list. Tuple fields of type tuple can be used to send nested FTL messages.

The operator is configured through several properties set in its Properties view in StreamBase Studio.

TIBCO Middleware Dependencies

This operator requires access to the JAR file that implements the TIBCO FTL Java API on your system, and any files referenced by that JAR file. The FTL adapter was tested with FTL version 6.0, and is compatible with higher versions as well. To make the TIBCO FTL Java API available to the adapter, you must supply a maven dependency for it -- specifically, to FTL's ${FTL_HOME}/lib/tibftl.jar.

The tibftl.jar file, in turn, relies on various native libraries such as tibftljni.dll on Windows and tibftljni.so on Linux. As with tibftl.jar, these native libraries are supplied as part of your TIBCO FTL installation and are not shipped with TIBCO Streaming. Make sure to edit your src/main/configurations/engine.conf and make changes to reflect your current setup, to include an externalNativeLibraryPath directive that points to your FTL installation's ${FTL_HOME}/bin directory. Please see the FTL sample application for an example configuration.

Operator Properties

Property Description
FTL Control Operator Name The name of the FTL Control operator instance that will be managing the connection to the FTL realm server to be used by this Subscriber. If this Control instance is not located in the current fragment, its fully-qualified name should be used. All FTL operator instances using a given instance of the Control operator to manage their realm connection will share this connection.
Endpoint Name The FTL endpoint, which abstracts the transport details.
Buffer Size To enable batching of tuples sent from the operator, enter a non-zero size of a buffer to maintain in number of tuples. The default is zero, which disables buffering and sends one tuple at a time.
Flush Interval (mS) When using a non-zero buffer size, enter an integer number of milliseconds to specify how often to flush the buffer and send its accumulated tuples.
Start On Connection If enabled, when the associated Control operator successfully establishes a connection to the FTL realm, a publisher to the configured endpoint will be automatically created and started. Otherwise, the operator will wait for a Start command to start the publisher.
Log Level Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level is used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE.
FTL Library Log Level The log level used by the FTL library. Multiple FTL operator instances share the most verbose level configured in any operator.

Using the Operator in a Streaming Application

This section discusses how to use the TIBCO FTL Publishing Operator in a Streaming application. The publishing operator has two input ports and one output port to communicate with the surrounding application.

The TIBCO FTL Publishing Operator's ports are used as follows:

  • PublishControl: This input port receives tuples used to start and stop publishing to the endpoint. The Control port has the following schema:

    • Command, string: Contains one of the following commands:

      • Start

      • Stop

  • PublishIn: Tuples enqueued on this input port cause the operator to publish FTL messages, one per tuple. The port's schema is derived from the output port of the upstream operator and can contain a subset of Streaming data types, including lists and nested tuples to include nested messages in the outgoing FTL message. Tuple fields are mapped to FTL message fields by name. List fields may contain only double, long, string, timestamp, and double elements. Fields containing null in the tuple are discarded; no corresponding field is placed in the FTL message.

    In processing outgoing FTL messages, the operator converts to Streaming data types to FTL data types. As shown in the table below, each Streaming type has a single corresponding FTL type. When an attempt to perform an invalid conversion occurs, a one-time warning for the field is displayed and the corresponding FTL message field is not included in the message.

    Streaming Type FTL Type
    boolean LONG, with a value of 0 (FALSE) or 1 (TRUE).
    list<boolean> LONG_ARRAY, with values of 0 (FALSE) or 1 (TRUE).
    blob OPAQUE
    double DOUBLE
    list<double> DOUBLE_ARRAY
    long LONG
    list<long> LONG_ARRAY
    string STRING
    list<string> STRING_ARRAY
    timestamp DATETIME
    list<timestamp> DATETIME_ARRAY
    tuple MESSAGE
    list<tuple> MESSAGE_ARRAY
  • PublishStatus: This output port emits status, information, and error tuples. The Status port has the following schema:

    • Status, string: Describes the type of event that occurred. Possible values include: Connected, Disconnected, Success, Error.

    • Time, timestamp: The time at which this status occurred.

    • Info, list(tuple): A list of name-value pair tuples containing any additional information for the event.

Add an instance of the operator to a new Streaming application as follows:

  1. In StreamBase Studio, create a project, and create an EventFlow application file to host the operator.

  2. Drag an instance of the TIBCO FTL Publishing Operator from the Operators and Adapters drawer in the Palette view to the canvas.

  3. Connect an input streams to the operator's two input port and an output stream to its output port.

  4. Configure the schema of the PublishControl input stream with a Command field.

  5. Configure the schema of the PublishIn input stream with the fields to be including in published FTL messages.

  6. Select the operator icon, and in the Properties view, select the Operator Properties tab and fill in any desired properties.

Typechecking and Error Handling

The TIBCO FTL Publishing Output operator uses typecheck messages to help you configure the operator in your Streaming application. In particular, the operator generates typecheck messages when a required property has not been specified, the control input schema is missing a required field, or an input or output schema contains unsupported Streaming data types.

The operator generates messages on the status port during runtime under various conditions, including:

  • The operator starts, or fails to start, the publisher to the configured endpoint.

  • An FTL message is acknowledged.

  • The operator fails to process an outgoing FTL message.

Suspend and Resume Behavior

When suspended, the TIBCO FTL Publishing Operator stops its publisher and stops processing outgoing FTL messages.

When resumed, once the Control operator has successfully reconnected to the realm and if the Publisher's Start On Connection property is enabled, the operator restarts the publisher and resumes processing outgoing FTL messages. Otherwise it will wait for a Start command on its Command port before publishing again.