Contents
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. An optional control port can also be used to control the connection to Tibrv.
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.
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 Rendezvous
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.
This section describes the properties you can set for this adapter, using the various tabs of the Properties view in StreamBase Studio.
Name: Use this required field to specify or change the name of this instance of this component, which must be unique in the current EventFlow module. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.
Adapter: A read-only field that shows the formal name of the adapter.
Class name: Shows the fully qualified class name that implements the functionality of this adapter. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.
Start options: This field provides a link to the Cluster Aware tab, where you configure the conditions under which this adapter starts.
Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.
Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.
| 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. |
| Convert Underscore Numeric To Numeric | If enabled, any field which starts with an underscore and then a numeric will be publish as a field name with the underscore removed.\nFor example _123 would be simply published to a field named123. |
| 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:
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.
|
| Enable Control Port | If enabled, the adapter will enable an input port for controlling connection |
| Auto Connect At Startup | If enabled, the adapter will automatically try to connect at startup |
| Auto Reconnect | If enabled the adapter will automatically try reconnect if a failure occurs |
| Auto Reconnect Wait | The number of milliseconds to wait after a failed connection attempt before trying to connect again |
| 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. |
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 |
Use the settings in this tab to allow this operator or adapter to start and stop based on conditions that occur at runtime in a cluster with more than one node. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with TIBCO Streaming releases before 10.5.0, leave the Cluster start policy control in its default setting, Start with module.
Cluster awareness is an advanced topic that requires an understanding of StreamBase Runtime architecture features, including clusters, quorums, availability zones, and partitions. See Cluster Awareness Tab Settings on the Using Cluster Awareness page for instructions on configuring this tab.
Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.
Caution
Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.
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:
-
Control (input): If enabled, this input port receives tuples used to connect and disconnect. The control port has the following schema:
-
Command, string: The command to send to the operator 'Connect' or 'Disconnect'.
-
-
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:
-
In StreamBase Studio, create a project, and create an EventFlow application file to host the adapter.
-
Drag an instance of the TIBCO Rendezvous Publishing 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 Tibrv messages to be published.
-
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.
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.
When suspended, the TIBCO Rendezvous Subscribing Output Adapter disconnects and stops processing input tuples.
When resumed, the adapter connects and begins processing input tuples once again.