- Index

< Previous |  | Next >

# TIBCO FTL Map Adapters

## Introduction

The TIBCO StreamBase® Adapters for TIBCO FTL® map operations allow a StreamBase application to perform various operations on FTL maps, including getting and setting messages, iterating through a map's messages and removing messages from a map.

- TIBCO StreamBase® Map Get Operator For TIBCO FTL, which allows a StreamBase application to retrieve a message with a specific key from a specified FTL map.

- TIBCO StreamBase® Map Iterate Operator For TIBCO FTL, which allows a StreamBase application to add a message with a specific key to a specified FTL map.

- TIBCO StreamBase® Map Remove Operator For TIBCO FTL, which allows a StreamBase application to retrieve all messages from a specified FTL map in one operation.

- TIBCO StreamBase® Map Set Operator For TIBCO FTL, which allows a StreamBase application to remove a message with a specific key from a specified FTL map.

These adapters connect to the FTL realm server on start-up, and can additionally be disconnected and reconnected via their Control input port.

The adapters support a subset of StreamBase data types that contains tuples and lists, though lists may not contain elements of type list.

The adapters are configured through several properties set in their 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.

### TIBCO FTL Version

Note that TIBCO FTL has introduced support for Maps in version 4.2, so you will need to have this or a more recent version installed in order to effectively use these adapters.

## Adapter Properties

All four adapters have the following 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.
Endpoint Name | The FTL endpoint, which abstracts the transport details.
Remove Map On Disconnect | When checked, this causes the adapter to remove the map from the FTL realm before disconnecting from it.
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.

Some of the adapters also offer additional properties:

### MapGet, MapIterate

Property | Description
--- | ---
Edit Schema Tab | These adapters have an additional tab named "Edit Schema", where the expected schema of incoming FTL messages must be specified.

### MapSet

Property | Description
--- | ---
Message Formats Tab | Use this tab to specify the names of the message formats used by the adapter. Top-level Message Format describes the name of the FTL message, and the Nested Message Formats list specifies the format names of any nested messages (i.e. fields of type Message).

## Input Ports

Each of the four FTL Map adapters have at least one input port, with schemas described in this section.

### MapGet Adapter

This adapter only has one input port, which receives various commands described in this section. The port has the following schema:

Field Name | Field Type | Description
--- | --- | ---
Command | string | The name of the operation to be performed. Valid values are: `Connect`: Triggers a connection attempt to the FTL realm. Other fields in the tuple are ignored. `Disconnect`: Disconnects from the FTL realm if already connected. Other fields in the tuple are ignored. `Get`: Retrieve the message with the specified key from the specified FTL map. If the message exists in the map it will be converted to a StreamBase tuple and emitted to the adapter's Result output port. Otherwise a tuple with its FTLMapName and FTLKeyName fields set to null will be emitted in its place, to indicate the message was not found in the map.
FTLMapName | string | Name of the FTL map from which to retrieve the message (used by the `Get` commmand). If the map doesn't exist, it will be automatically created before executing the operation.
FTLKeyName | string | Key of the message to fetch in the FTL map (used by the `Get` commmand).

### MapIterate Adapter

This adapter only has one input port, which receives various commands described in this section. The port has the following schema:

Field Name | Field Type | Description
--- | --- | ---
Command | string | The name of the operation to be performed. Valid values are: `Connect`: Triggers a connection attempt to the FTL realm. Other fields in the tuple are ignored. `Disconnect`: Disconnects from the FTL realm if already connected. Other fields in the tuple are ignored. `Iterate`: Retrieve all messages currently contained in the specified FTL map. Each message will be emitted on the adapter's Result output port, followed by an empty tuple with its FTLMapName and FTLKeyName fields set to null to indicate the end of the list.
FTLMapName | string | Name of the FTL map from which to retrieve the messages (used by the `Iterate` commmand). If the map doesn't exist, it will be automatically created before executing the operation.
FTLLockMap | boolean | If set to `true`, the FTL map will be locked during the operation to avoid contention from other adapters.

### MapRemove Adapter

This adapter only has one input port, which receives various commands described in this section. The port has the following schema:

Field Name | Field Type | Description
--- | --- | ---
Command | string | The name of the operation to be performed. Valid values are: `Connect`: Triggers a connection attempt to the FTL realm. Other fields in the tuple are ignored. `Disconnect`: Disconnects from the FTL realm if already connected. Other fields in the tuple are ignored. `Remove`: Remove the message with the specified key from the specified FTL map.
FTLMapName | string | Name of the FTL map from which to remove the message (used by the `Remove` commmand). If the map doesn't exist, it will be automatically created before executing the operation.
FTLKeyName | string | Key of the message to remove from the FTL map (used by the `Remove` commmand).
FTLLockMap | string | If set to `true`, the FTL map will be locked during the operation to avoid contention from other adapters.

### MapSet Adapter

This adapter has two input ports, one which receives various commands (described in this section), and one which receives tuples to be placed in the FTL map as messages.

The Command port has the following schema:

Field Name | Field Type | Description
--- | --- | ---
Command | string | The name of the operation to be performed. Valid values are: `Connect`: Triggers a connection attempt to the FTL realm. Other fields in the tuple are ignored. `Disconnect`: Disconnects from the FTL realm if already connected. Other fields in the tuple are ignored.
FTLMapName | string | Name of the FTL map from which to retrieve the message (used by the `Get` commmand). If the map doesn't exist, it will be automatically created before executing the operation.
FTLKeyName | string | Key of the message to fetch in the FTL map (used by the `Get` commmand).

The second input port, used to set messages in an FTL map, expects its schema to have at least the following fields:

Field Name | Field Type | Description
--- | --- | ---
FTLMapName | string | Name of the FTL map on which to set the message. If the map doesn't exist, it will be automatically created before executing the operation.
FTLKeyName | string | Key to assign to the message in the FTL map.

All other fields will be treated as values to be set on the outgoing FTL message.

## Output Ports

Each of the four FTL Map adapters have at least one output port, to issue status, information and error tuples. The schema for this port is the same for all four adapters and is as follows:

Field Name | Field Type | Description
--- | --- | ---
type | string | Describes 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 Map Get: an error occurred during a Get operation Map Set: an error occurred during a Set operation Map Iterate: an error occurred during an Iterate operation Map Remove: an error occurred during a Remove operation
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 explaining the event.
inputTuple | tuple | The tuple enqueued to the control port that led to the event, or null if the event was not related to processing an input tuple.

In addition to this status output port, some adapters also have other output port as described in the follwing subsections.

### MapGet Adapter

This adapter has a second output port to emit incoming FTL messages as tuples.

When it receives a `Get` command, the MapGet adapter emits a tuple on its second output port representing the FTL message it retrieved from the map. 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 addition to the fields specified on the Edit Schemas tab, each tuple will also have two extra fields set automatically to indicate the map it came from and the key it was assigned in the map:

Field Name | Field Type | Description
--- | --- | ---
FTLMapName | string | Name of the FTL map from which this tuple was retrieved. If no message was found in the FTL map with the `FTLKeyName` specified in the `Get` command, this field will be set to null.
FTLKeyName | string | Key of the message in the FTL map. If no message was found in the FTL map with the `FTLKeyName` specified in the `Get` command, this field will be set to null.

### MapIterate Adapter

This adapter has a second output port to emit incoming FTL messages as tuples.

When it receives an `Iterate` command, the MapIterate adapter emits a tuple on its second output port for each FTL message contained in the specified map, ending with a marker tuple that has null values in its FTLMapName and FTLKeyName fields to indicate the end of the iteration process.

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 addition to the fields specified on the Edit Schemas tab, each tuple will also have two extra fields set automatically to indicate the map it came from and the key it was assigned in the map:

Field Name | Field Type | Description
--- | --- | ---
FTLMapName | string | Name of the FTL map from which this tuple was retrieved, or `null` if this is the end of the iteration operation.
FTLKeyName | string | Key of the message in the FTL map, or `null` if this is the end of the iteration operation.

## Data Type Conversion

In processing incoming FTL messages, the adapters convert FTL data types to StreamBase data types (or vice-versa). 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 (or in the case of StreamBase-to-FTL conversions, the FTL field is omitted from the message).

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>

## 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 Subscribing Input Adapter

  TIBCO FTL Publishing Output Adapter