TIBCO Rendezvous Publishing Output Adapter

Introduction

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

The adapter supports all StreamBase data types, including tuples and lists, though lists may not contain elements of type list. Tuple fields of type tuple can be used to send nested Tibrv 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 Rendezvous daemon, the input port field containing the subject to publish to, and the default subject value to use if the subject field is null.

TIBCO Middleware Dependencies

This adapter requires access to the JAR file that implements the TIBCO Rendezvous Java API on your system, and any files referenced by that JAR file. The StreamBase installation kit includes version 8.1.2 of the tibrvj.jar JAR file. If your site's Rendezvous implementation requires a newer version of that file, copy the file from $TIBRV_HOME/lib to $STREAMBASE_HOME/lib/ext.

The tibrvj.jar file, in turn, relies on the tibrvj.dll and tibrv.dll files for Windows, and for UNIX, on several .so files in /usr/tibco/tibrv/lib. These DLL or .so files are supplied as part of your TIBCO installation, and are not shipped with StreamBase. Make sure these files are locatable by the TIBCO JAR file on the PATH or by means of the TIBRV_HOME environment variable.

If you get an error message whose text refers to Library not found: tibrvj, audit your system for multiple versions of the TIBCO JAR and DLL (or .so) files. For example, on Windows, you might have an older TIBCO release's DLL files in C:\Windows\System32, and a newer set in $TIBRV_HOME\lib. Make sure the StreamBase TIBCO adapter sees a consistent TIBCO implementation, including tibrvj.jar, tibrvj.dll, and tibrv.dll files all from the same TIBCO release.

The TIBCO API implementation described in this section is a product of a third party, and its specifications and file names are subject to change by TIBCO. See your TIBCO documentation for the latest information.

Adapter Properties

Property Description
Service The Rendezvous service name. Leave blank to use the default value of 7500.
Network The network interface. Leave blank to use the primary network interface for the host computer.
Daemon The Rendezvous daemon. Leave blank to use the daemon on the local computer listening on the default port.
Batch Mode If enabled, outgoing messages are sent in batches, increasing throughput at the expense of increased latency.
Subject Field Name The name of the input stream field containing the subject value under which to publish the Tibrv message. This field is optional if a Default Subject value is specified, which is used if no subject field exists, or its value is null in a specific input tuple.
Default Subject Contains the subject value under which to publish a Tibrv message if no subject field exists, or its value is null in a specific input tuple.
Publish By Field ID If enabled, the adapter publishes Tibrv 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.
Include Field Name And ID If enabled, the adapter includes both the field name and ID when publishing a field by ID. The field name is the StreamBase field name with the leading underscore removed.
Publish Type Overrides File The name of a file that can be used to override the default Tibrv type in publishing various StreamBase fields. A template file is delivered with the adapter's OverridePublishTypes.sbapp sample. The file consists of two comma-delimited columns containing a StreamBase field name and Tibrv type. For example:

MySBField,U16

See the Publish Type Overrides Table below for the correspondence between StreamBase types, default Tibrv types, and valid overrides.

Generate Unique Tibrv Field Names When publishing multiple Tibrv fields per StreamBase list field, generate unique Tibrv field names <listfieldname>_0, <listfieldname>_1, etc. Normally, StreamBase list fields are published using the corresponding Tibrv xyzARRAY type, such as MSGARRAY for a StreamBase list of tuples. If the Publish Type Override File is used to publish a StreamBase list field using a non-array Tibrv type, the adapter places multiple Tibrv fields with the StreamBase field name in the Tibrv message unless Generate Unique Tibrv Field Names is enabled, in which case the Tibrv field names are made unique by appending _n to the name, where n represents the index of the element in the StreamBase list.
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.

The following table shows, for each StreamBase type, the default Tibrv type, and the valid override values that can be used to publish the StreamBase field using a non-default Tibrv type.

Publish Type Overrides Table

StreamBase Type Default Tibrv Type Valid Overrides
blob OPAQUE I8ARRAY, U8ARRAY, XML
bool BOOL I8, U8, I16, U16, I32, U32, I64, U64
double F64 F32
int I32 I8, U8, I16, U16, U32, I64, U64
long I64 I8, U8, I16, U16, I32, U32, U64
string STRING XML
timestamp DATETIME
tuple MSG
list<bool> I8ARRAY BOOL, I8, U8, I16, U16, I32, U32, I64, U64, U8ARRAY, I16ARRAY, U16ARRAY, I32ARRAY, U32ARRAY, I64ARRAY, U64ARRAY
list<double> F64ARRAY F32, F64, F32ARRAY
list<int> I32ARRAY I8, U8, I16, U16, I32, U32, I64, U64, I8ARRAY, U8ARRAY, I16ARRAY, U16ARRAY, U32ARRAY, I64ARRAY, U64ARRAY
list<long> I64ARRAY I8, U8, I16, U16, I32, U32, I64, U64, I8ARRAY, U8ARRAY, I16ARRAY, U16ARRAY, I32ARRAY, U32ARRAY, U64ARRAY
list<string> STRINGARRAY STRING, XML
list<tuple> MSGARRAY MSG

Using the Adapter in a StreamBase Application

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

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

  • Tibrv Messages: Tuples enqueued on this input port cause the adapter to publish Tibrv 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 Tibrv messages. Tuple fields are mapped to Tibrv message fields by name. List fields may contain only bool, int, long, and double elements. Fields containing null in the tuple are discarded; no corresponding field is placed in the Tibrv message.

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

      • Transport

      • Process Tuple

      • Suspend/Resume

    • object, string: the name of the object associated with the event, such as the Rendezvous transport parameters (service, network, and daemon), the contents of the tuple that wasn't processed successfully, or the name of the adapter that was suspended/resumed.

    • action, string: the action associated with the event, such as transport created or adapter suspended/resumed.

    • message, string: A human-readable message 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 Rendezvous Publishing Output Adapter from the Operators and Adapter drawer in the Palette view to the canvas.

  3. 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 Tibrv messages to be published.

  4. Select or double-click the adapter icon, and in the Properties view, click Adapter Settings and fill in any desired properties. Either a Subject Field Name or Default Subject must be specified.

Typechecking and Error Handling

The TIBCO Rendezvous Publishing Output adapter uses typecheck messages to help you configure the adapter in your StreamBase application. In particular, the adapter generates typecheck messages when nether a Subject Field Name nor a Default Subject is specified, when a list field in the Tibrv message input port uses an unsupported element type, or the Subject Field 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 create a transport to the Rendezvous daemon during startup.

  • An error occurs in creating or sending a Tibrv message.

  • The adapter is suspended or resumed.

Suspend and Resume Behavior

When suspended, the TIBCO Rendezvous Subscribing Input Adapter stops processing input tuples.

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