TIBCO FTL Control Operator

Contents

Introduction
Operator Properties
Using the Operator in a Streaming Application
Typechecking and Error Handling
Suspend and Resume Behavior
Related Topics

Introduction

The TIBCO Streaming® Control Operator for TIBCO FTL® allows a Streaming application to control the connection to an FTL Realm server, and to manage FTL groups within that server. Other Streaming operators for FTL (Subscriber, Publisher, Map Get, Map Set, Map Iterate and Map Remove) use this connection by specifying the Control operator's instance name in their Control Operator Name property. All such operators will share the same connection.

The operator is embedded in the Streaming application and has one input port and one output port. The input port is used to connect to, and disconnect from, the FTL realm server as well join and leave FTL groups, and get the current group status of this connection. The output port emits status tuples related to those operations.

The operator connects to the FTL realm server on start-up if configured to do so via its Connect On Startup property, or await a Connect command on its Command port to do so otherwise.

The operator 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 name and client label, as well as any authentication credentials.

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
Connect on Startup If enabled, the operator connects to the realm server when it starts.
Realm Server URLs A pipe-delimited ("|") list of realm server URLs to which to connect (such as http://localhost:8080|http://localhost:8181). Should the first server in the list become unavailable, the operator will automatically try to connect to the next one in the list, and so on.
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.
Client Label The FTL client label to use to identify this connection.
Inline Mode Whether to use Inline Mode, which improves performance by reducing inbound latency.
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.
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 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 Control Operator in a Streaming application. The operator has one input port and one output port to communicate with the surrounding application.

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

  • SubscribeControl: This input port receives tuples used to connect to, or disconnect from, the realm server as well as control membership to FTL groups. The Control port has the following schema:

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

      • Connect

      • Disconnect

      • JoinGroup

      • LeaveGroup

      • GetJoinedGroupNames

    • GroupID, string: Identifier of the group to join or leave (used by the JoinGroup and LeaveGroup commands).

    • IsObserver, boolean: Whether to join the group as a member (false) or an observer (true) (used by the JoinGroup command).

    • GroupMemberDescriptor, string: JSON string to use as a group member descriptor (used by the JoinGroup command).

    • GroupActivationInterval, double: Number of milliseconds to use as an activation interval (used by the JoinGroup command).

  • 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.

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 Control Operator from the Operators and Adapters drawer in the Palette view to the canvas.

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

  4. Configure the schema of input stream with a Command field and, if membership to groups is desired, GroupID, IsObserver, GroupMemberDescriptor and GroupActivationInterval fields.

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

Typechecking and Error Handling

The TIBCO FTL Control 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 or the control input schema is missing a required field.

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

  • The operator connects, or fails to connect, to the realm server.

  • The operator is administratively disabled by the realm server.

  • The operator receives an advisory message.

  • The operator fails to dispatch an event on its event queue.

Suspend and Resume Behavior

When suspended, the TIBCO FTL Control Operator disconnects from the realm server.

When resumed, the operator re-connects to the realm server if it had been connected before being suspended.

Related Topics