- Index

< Previous |  | Next >

# TIBCO FTL Subscribing Input Adapter

## Introduction

The TIBCO StreamBase® Input Adapter for TIBCO FTL® allows a StreamBase application to receive FTL messages. The adapter is embedded in the StreamBase application and has one input port and two output ports. The input port is used to acknowledge received messages and to connect to, and disconnect from, the FTL realm server. The first output port emits status tuples, while the second emits tuples representing received FTL messages.

The adapter connects to the FTL realm server on start-up and asynchronously and continuously receives and converts incoming FTL messages into StreamBase tuples, which it sends downstream.

The adapter supports a subset of StreamBase data types that contains tuples and lists, though lists may not contain elements of type list. The schema of the FTL message output port is set through the Edit Schema tab of the adapter's Properties view.

The adapter is configured through several properties set in its Properties view in StreamBase Studio. The properties include parameters used to connect to the realm server and the application and endpoint names.

### TIBCO Middleware Dependencies

This adapter 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 adapter has been tested with FTL version 3.1, though it will likely work with newer FTL API versions as well. To make the TIBCO FTL Java API available to the adapter, you must supply a maven dependency for it. The FTL sample comes with a launch config which will install the `tibftl.jar` into your local maven repository.

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 StreamBase. Make sure to edit your `src/main/configurations/engine.conf` and make changes to reflect your current setup. Please see the FTL sample application for an example configuration.

## Adapter Properties

Property | Description
--- | ---
Connect on Startup | If enabled, the adapter connects to the realm server when it starts.
Real Server URL | The URL of the real server.
Secondary Real Server URL | The URL of the secondary realm server for fault tolerance.
Username | The realm server username.
Password | The realm server password.
Application Name | The FTL application, which includes a set of endpoints and formats as configured in the realm server.
Application Instance | The FTL application instance.
Enable Secure Connection | Whether to use a trust file to connect securely to the FTL server.
Trust File Name | The full path to the file containing trust information to connect to the server. Only in effect if Enable Secure Connection is checked.
Endpoint Name | The FTL endpoint, which abstracts the transport details.
Subscriber Name | The subscriber name to use when subscribing to the endpoint.
Durable Name | The durable name of the endpoint. Used for durable connections.
Content Matcher | Criteria for selecting the messages of interest, or an empty string to receive all messages.
Explicit ACK | If enabled, incoming messages must be acknowledged.
Message ID Field Name | When Explicit ACK is enabled, this field is included in the messages received schema and contains the ID of the message to acknowledge.
Inline Mode | Whether to use Inline Mode, which improves performance by reducing inbound latency.
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 input and output adapter instances share the most verbose level configured in any adapter.

## Using the Adapter in a StreamBase Application

This section discusses how to use the TIBCO FTL Subscribing Input Adapter in a StreamBase application. As shown in the diagram below (depicting the adapter's sample application), the subscribing adapter has one input port and two output ports to communicate with the surrounding application.

The TIBCO FTL Subscribing Input Adapter's ports are used as follows:

- SubscribeControl: This input port receives tuples used to acknowledge received messages or to connect to, or disconnect from, the realm server. The Control port has the following schema:

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

    - Acknowledge

    - Connect

    - Disconnect

    - SetContentMatcher

  - MessageID, string: Contains the ID of the message being acknowledged, which was contained in a tuple emitted by the adapter on its SubscribeOut port. This field is required if the adapter's `Explicit ACK` property is enabled. The name of this field is configurable through the `Message ID Field Name` property. This field is ignored unless the Command field's value is to `Acknowledge`.

  - ContentMatcher, string: Contains the new value of the content matcher for this subscription. If left null, no content matcher is specified. This field is ignored unless the Command field's value is to `SetContentMatcher`.

    ### Note

    The `SetContentMatcher` command can be used to change the content matcher string set for this subscription. However, since FTL does not allow on-the-fly changes to this setting, the connection is recycled in order for this setting to take effect.

- SubscribeStatus: This output port emits status, information, and error tuples. The Status port has the following schema:

  - type, string: Contains one of the following values describing the type of event that occurred:

    - Administration: the adapter has received notification that it has been administratively disabled

    - Advisory: an advisory message has been received

    - Connect: the adapter has connected or failed to connect to, or disconnected from, the FTL realm server

    - Dispatch: an error occurred dispatching an event on the adapter's event queue

    - Message: an FTL message was successfully acknowledged, or an error occurred processing an incoming FTL message

    - Suspend/Resume: the adapter is being suspended or has been resumed

    - User Input: an input tuple was rejected

  - action, string: the action associated with the event, such as Acknowledged, Connected, Disconnected, Suspended, or Resumed.

  - object, string: the name of the object associated with the event, such as the URL of the realm server, the contents of the FTL message that wasn't processed successfully, or the name of the adapter that was suspended or resumed.

  - message, string: a human-readable message string

  - inputTuple, tuple: the tuple enqueued to the control port that lead to the event, or null if the event was not related to processing an input tuple.

- SubscribeOut: The adapter emits a tuple on its second output port for each FTL message received. The port's schema is derived from the Edit Schema tab of the adapter's property view and can contain a subset of StreamBase data types, including lists and (nested) tuples to accommodate hierarchy in FTL messages. FTL message fields are mapped to tuple fields by case-sensitive name. List fields may contain elements of type double, long, string, timestamp, or tuple.

  In processing incoming FTL messages, the adapter converts FTL data types to StreamBase data types. As shown in the table below, Each FTL type has a single corresponding StreamBase type. When an attempt to perform an invalid conversion occurs, a one-time warning for the field is displayed and the corresponding field in the tuple is set to null.

  FTL Type | StreamBase Type
  --- | ---
  DATETIME | timestamp
  DATETIME_ARRAY | list<timestamp>
  DOUBLE | double
  DOUBLE_ARRAY | list<double>
  LONG | long
  LONG_ARRAY | list<long>
  MESSAGE | tuple
  MESSAGE_ARRAY | list<tuple>
  OPAQUE | blob
  STRING | string
  STRING_ARRAY | list<string>

Add an instance of the adapter to a new StreamBase application as follows:

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

2. Drag an instance of the TIBCO FTL Subscribing Input Adapter from the Operators and Adapter drawer in the Palette view to the canvas.

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

4. Configure the schema of input stream with a Command field and, if the Explicit ACK property is enabled, a MessageID field.

5. Configure the schema of the FTL message output stream (port 2) using the Edit Schema tab of the adapter's property view to match the set of fields expected in the incoming FTL messages.

6. Select the adapter icon, and in the Properties view, select Adapter Settings and fill in any desired properties.

## Typechecking and Error Handling

The TIBCO FTL Subscribing Input adapter uses typecheck messages to help you configure the adapter in your StreamBase application. In particular, the adapter 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 StreamBase data types.

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

- The adapter connects, or fails to connect, to the realm server during start-up.

- An FTL message is acknowledged.

- The adapter is administratively disabled by the realm server.

- The adapter receives an advisory message.

- The adapter fails to dispatch an event on its event queue.

- The adapter fails to process an incoming FTL message.

- The adapter is suspended or resumed.

## Suspend and Resume Behavior

When suspended, the TIBCO FTL Subscribing Input Adapter disconnects from the realm server and stops processing incoming FTL messages.

When resumed, the adapter re-connects to the realm server, if it had been connected before being suspended, and resumes processing incoming FTL messages.

## Related Topics

- TIBCO FTL Publishing Output Adapter

- TIBCO FTL Map Adapters