Contents
The TIBCO Streaming® Subscribing Operator for TIBCO FTL® allows a Streaming application to receive FTL messages by subscribing to an FTL endpoint. The operator is embedded in the Streaming application and has one input port and two output ports. The input port is used to acknowledge received messages and to subscribe and unsubscribe to an endpoint on the FTL realm server. The first output port emits status tuples, while the second emits tuples representing received FTL messages.
The operator relies on the FTL Control operator to create and manage its connection to the FTL realm server. Once a connection is established, the Subscribing operator can subscribe to an endpoint to asynchronously and continuously receive FTL messages and convert them into Streaming tuples, which it sends downstream.
The operator supports a subset of Streaming 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 operator's Properties view.
The operator is configured through several properties set in its Properties view in StreamBase Studio.
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.
| 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. |
| Subscriber Name | The subscriber name to use when subscribing to the endpoint. |
| Durable Name | The durable name of the endpoint. Used for durable connections. |
| Explicit ACK | If enabled, incoming messages must be acknowledged. Also,
if enabled, a string field named MessageID is
expected to be present in the Command port's schema.
|
| Subscribe On Connection | If enabled, when the associated Control operator successfully establishes a connection to the FTL realm, a subscription to the configured endpoint will be automatically created and started. Otherwise, the operator will wait for a Subscribe command to start the subscription. |
| Store Local Message Id Field Name | The name of the field that will be used to contain incoming messages' Store Local id in the output tuple. If not set, this value will npot be included in the output tuple. |
| 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 adapter instances share the most verbose level configured in any instance. |
This section discusses how to use the TIBCO FTL Subscribing Operator in a Streaming application. The Subscriber has one input port and two output ports to communicate with the surrounding application.
The operator's ports are used as follows:
-
SubscribeControl: This input port receives tuples used to acknowledge received messages and to subscribe or unsubscribe from endpoints on the realm server. The Control port has the following schema:
-
Command, string: Contains one of the following commands:
-
Acknowledge
-
Subscribe
-
Unsubscribe
-
-
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 ACKproperty is enabled. This field is ignored unless the Command field's value is toAcknowledge. -
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
SubscribeorUnsubscribe.
-
-
SubscribeStatus: 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.
-
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.
-
-
SubscribeOut: The operator 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 Streaming 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. The FTL architecture does not support the use of boolean fields, but for convenience if the Streaming boolean data type is used in the schema, the corresponding FTL field is assumed to be of type LONG, and a 0 value will be converted to FALSE while any non-zero value will cause the boolean field to be set to TRUE.
In processing incoming FTL messages, the operator converts FTL data types to Streaming data types. As shown in the table below, Each FTL type has a single corresponding Streaming 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 Streaming Type DATETIME timestamp DATETIME_ARRAY list<timestamp> DOUBLE double DOUBLE_ARRAY list<double> LONG long Note
For convenience, Streaming fields of type booleans are also converted from FTL LONGs since FTL has no support for boolean data. An incoming value of 0 will set the boolean to FALSE, while any non-zero value will be converted to TRUE.
LONG_ARRAY list<long> Note
Similarly, Streaming list<boolean> fields are converted from FTL LONG_ARRAYs using the rule described above.
MESSAGE tuple MESSAGE_ARRAY list<tuple> OPAQUE blob STRING string STRING_ARRAY list<string>
Add an instance of the operator to a new Streaming application as follows:
-
In StreamBase Studio, create a project, and create an EventFlow application file to host the operator.
-
Drag an instance of the TIBCO FTL Subscribing Operator from the Operators and Adapters drawer in the Palette view to the canvas.
-
Connect an input stream to the operator's input port and output streams to its two output ports.
-
Configure the schema of input stream with a Command field and, if the Explicit ACK property is enabled, also include a MessageID field.
-
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.
-
Select the operator's icon, and in the Properties view, select the Operator Properties tab and fill in any desired properties.
The TIBCO FTL Subscribing operator uses typecheck messages to help you configure the adapter 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 adapter generates messages on the status port during runtime under various conditions, including:
-
The adapter subscribes, or fails to subscribe, to the endpoint on the realm server.
-
An FTL message is acknowledged.
-
The adapter fails to dispatch an event on its event queue.
-
The adapter fails to process an incoming FTL message.
When suspended, the associated TIBCO Control operator will disconnect from the realm server. Consequently, the Subscribing operator also removes any active subscription from the realm server and stops processing incoming FTL messages.
When resumed, the Control operator will attempt to reconnect to the realm. If reconnection is successful, and if the Subscriber's Subscribe On Connect property is enabled, the Subscriber and resumes processing incoming FTL messages.