Tervela Publishing Output Adapter

Introduction

The TIBCO StreamBase® Output Adapter for Tervela allows a StreamBase application to publish Tervela messages to one or more Tervela subjects. The adapter is embedded in the StreamBase application and has an input port that receives tuples to be published as Tervela messages and an output port that emits status tuples. Each tuple enqueued to the adapter's input port causes a single Tervela message to be published.

The adapter supports all StreamBase data types, including tuples and lists, although lists may not contain elements of type list. Tuple fields of type tuple can be used to send nested Tervela messages. The schema of adapter's input port is determined by the output port of the upstream operator.

The adapter is configured through several properties set in the adapter's Properties view in StreamBase Studio. The properties include parameters used to connect to the Tervela server, the input port field containing the topic to publish to, and the default topic value to use if the topic field is null.

Adapter Properties

Property	Description
Username	The username to use in logging in to the Tervela server.
Password	The password to use in logging in to the Tervela server.
TMX Address 1	The host name or IP address of the primary TMX in a fault-tolerant pair.
TMX Address 2	The host name or IP address of the secondary TMX in a fault-tolerant pair, or blank if the primary TMX is not part of a fault-tolerant pair.
Topic Field Name	The name of the input stream field containing the topic value under which to publish the Tervela message. This field is optional if a Default Topic value is specified, which is used if no topic field exists, or its value is null in a specific input tuple.
Default Topic	Contains the topic value under which to publish a Tervela message if no topic field exists, or its value is null in a specific input tuple.
Publish By Field ID	If enabled, the adapter publishes Tervela fields by field ID. The field ID is derived from the StreamBase field name; StreamBase field _123 would be published with an ID of 123. StreamBase fields not of the form `_nnn`, where nnn is a decimal number, are published by name.
Maximum Cache Period	The maximum time in milliseconds for data being published to live.
Enable QOS Notifications	Enables state- and publisher-down QoS notifications to be passed to subscribers.
Allow Partial Publish	Optimizes bandwidth by sending only those fields that have changed, rather than the entire message.
Login Timeout	The time in milliseconds to wait when attempting log in.
Report Missing Tuple Fields	If enabled, the adapter emits a warning and a status tuple when a Tervela message field has no corresponding field in the publish 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, and ALL.

In publishing Tervela messages, the adapter converts StreamBase data types to Tervela data types. Not all possible conversions are valid. When an attempt to perform an invalid conversion occurs, a status tuple indicating the nature of the error is emitted, and the publish tuple is discarded. The following table shows the set of valid conversions.

Tervela Type	StreamBase Type
BOOLEAN	bool
BOOLEAN_ARRAY	list<bool>
BYTE	int
BYTE_ARRAY	blob
DATETIME	timestamp
DATETIME_ARRAY	list<timestamp>
DOUBLE	double
DOUBLE_ARRAY	list<double>
EMBEDDED_MESSAGE	tuple
EMBEDDED_MESSAGE_ARRAY	list<tuple>
FLOAT	double
FLOAT_ARRAY	list<double>
INTEGER	int
INTEGER_ARRAY	list<int>
LONG	long
LONG_ARRAY	list<long>
PRECISION_LONG	tuple{value: long, precision: int}
PRECISION_LONG_ARRAY	list<tuple{value: long, precision: int}>
SHORT	int
SHORT_ARRAY	list<int>
STRING	string
STRING_ARRAY	list<string>

Using the Adapter in a StreamBase Application

This section discusses how to use the Tervela Publishing Output Adapter in a StreamBase application. As shown in the diagram below depicting the adapter's sample application, the publishing adapter has one input and one output port to communicate with the surrounding application.

The Tervela Publishing Output Adapter's ports are used as follows:

Input port, Publish: Tuples enqueued on this input port cause the adapter to publish Tervela messages, one per tuple. The port's schema is derived from the output port of the upstream operator and can contain all StreamBase data types, including lists and (nested) tuples to provide hierarchy in Tervela messages. Tuple fields are mapped to Tervela message fields by name. List fields may contain any element type except a list. Fields containing null in the tuple are discarded; no corresponding field is placed in the Tervela message.
Output port, Status: 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:
  - Login
  - Process Tuple
  - Suspend/Resume
  - Notification
- object, string: the name of the object associated with the event, such as the address of the TMX being logged into, the contents of the publish tuple that wasn't processed successfully, or the name of the adapter that was suspended or resumed.
- action, string: the action associated with the event, such as a login succeeding or adapter suspended or resumed.
- message, string: A human-readable message string

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

In StreamBase Studio, create a project, and create an EventFlow application file to host the adapter.
Drag an instance of the Tervela Output Adapter from the Operators and Adapter drawer in the Palette view to the canvas.
Connect an input and output stream to the adapter's input and output ports, respectively. Configure the schema of input stream with the fields required in the Tervela messages to be published.
Select or double-click the adapter icon to show the Properties view. Select the Adapter Settings tab, and fill in any desired properties. You must specify either Topic Field Name or Default Topic.

Typechecking and Error Handling

The Tervela Publishing Output adapter uses typecheck messages to help you configure the adapter in your StreamBase application. In particular, the adapter generates typecheck messages when no username or TMX address is specified, when two TMX addresses are provided that resolve to the same IP address, or when the configured topic field is not present in the input schema or is not of type string.

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

The adapter creates or fails to log in to the TMX server.
An error occurs in publishing a Tervela message.
The adapter is suspended or resumed.

Suspend and Resume Behavior

When suspended, the Tervela Publishing Output Adapter stops processing input tuples.

When resumed, the adapter begins processing input tuples once again.