Contents
This topic describes how to use the Real-Time Payment Protocol (RTPP) operators to act as either a client or server in an RTPP conversation, and explains how to configure the operators' Properties views.[1]
The RTPP connectivity solution is implemented as a suite of global Java operators that allow a Spotfire Streaming application to connect to an RTPP client or server, and exchange messages with that counterparty. The adapter conforms to version 1.1 of the RTPP protocol, and fully supports the following products:
-
Wireless Server Broker (WSB)
-
Multimedia Messaging Center (MMSC)
-
Unified Messaging (UM)
-
Short Message Service Center (SMSC)
-
Global User Agent (GUA)
The RTPP operators are members of the Java Adapter group in the Palette view in StreamBase Studio. Select the operators from the Insert an Operator or Adapter dialog. Invoke the dialog with one of the following methods:
-
Drag the Adapters, Java Operators token from the Operators and Adapters drawer of the Palette view to the canvas.
-
Click in the canvas where you want to place the operator, and invoke the keyboard shortcut
O V
-
From the top-level menu, invoke
> > .
From the Insert an Operator or Adapter
dialog, type RTPP
in the filter text box to
narrow the choices in the list below it, then select one of the
following operators and double-click or press
:
-
RTPP Client Control, which is used to control or report on the client's current connection state to the configured server. For example, a command can be sent to this operator to initiate a connection to the server, and when that connection is established, a status tuple will be emitted to inform the application of the successful connection. At this point the Client Input and Client Output operators linked to the same connection definition (by virtue of having it specified in their Adapter Configuration property) can begin performing operations.
-
RTPP Client Input, which is used to receive RTPP messages from the configured server and emit them as tuples to the application's downstream logic.
-
RTPP Client Output, which is used to send RTPP messages to the configured server.
-
RTPP Server Control, which is used to control or report on the server's current state. For example, a command can be sent to this operator to start listening for incoming client connections.
-
RTPP Server Input, which is used to receive RTPP messages from the connected clients and emit them as tuples to the application's downstream logic.
-
RTPP Server Output, which is used to send RTPP messages to connected client.
The different RTPP Client operators can be made to share a
connection to the server (and and conversely, RTPP Server operators can be
made to share the same connections to clients), provided they are
configured to do so. Each operator lists the connection configurations
available in corresponding combo box settings (see Properties: Operator Properties Tab). The lists are specified
in a dedicated section of the application's adapter configuration file.
The following example is the RTPP.conf
file used in
the RTPP
sample:
name = "RTPP.conf" type = "com.tibco.ep.streambase.configuration.adapter" version = "1.0.0" configuration = { // An adapter group type defines a collection of EventFlow adapter configurations, // indexed by adapter type. AdapterGroup = { // A collection of EventFlow adapter configurations, indexed by adapter type. // This key is required and must contain at least one configuration. adapters = { // The root section for the configurations for the RTPP adapters. rtpp-adapters = { // Section list. This key is optional and has no default value. sections = [ // A configuration for a named section for this adapter. { // Section name. The value does not have to be unique; that is, you can have // multiple sections with the same name in the same array of sections. This key // is required. name = "rtpp-connection" // Section property bag. All values must be strings. This key is optional // and has no default value. settings = { id = "RTPPSampleClient" host = "127.0.0.1" port= "51234" connect-on-startup = "true" enable-automatic-reconnection = "true" reconnection-attempts = "3" // Anything < 1 means infinite retries reconnection-attempt-interval = "3000" // In ms echo-interval = "50000" // In ms // This directs the adapter to convert RTPP parameters of type OCTETSTRING // to a Base64-endoded, TIBCO Streaming type STRING instead of BLOB. Defaults to "true". treat-octetstring-as-base64string = "true" // This determines how the TransactionID header field is represented: // "HexString" -- Default. A String field containing the hex representation of the 16 bytes of the ID (e.g. '10203040506070809000A0B0C0D0E0F0') // "Base64String" -- A String field containing the base64 conversion of the 16 bytes of the ID // "Blob" -- A Blob field containing the raw 16 bytes of the ID transaction-id-handling = "HexString" // When set to true, this will add message receipt timestamp fields to the Input adapters' results port. Default to "false". add-receipt-timestamps = "false" //message-buffer-size = "65536" // In bytes } } // A configuration for a second named section for this adapter. { name = "rtpp-connection" settings = { id = "RTPPSampleServer" port = "51234" connect-on-startup = "true" idle-connection-timeout = "60000" // In ms // This directs the adapter to convert RTPP parameters of type OCTETSTRING // to a Base64-endoded, TIBCO Streaming type STRING instead of BLOB. Defaults to "true". treat-octetstring-as-base64string = "true" // This determines how the TransactionID header field is represented: // "HexString" -- Default. A String field containing the hex representation of the 16 bytes of the ID (e.g. '10203040506070809000A0B0C0D0E0F0') // "Base64String" -- A String field containing the base64 conversion of the 16 bytes of the ID // "Blob" -- A Blob field containing the raw 16 bytes of the ID transaction-id-handling = "HexString" // When set to true, this will add message receipt timestamp fields to the Input adapters' results port. Default to "false". add-receipt-timestamps = "false" //message-buffer-size = "65536" // In bytes } } ] } } } }
In each section named rtpp-connection
, the value
of the id
setting identifies this particular section
(in other words, this particular connection definition) and will be listed
in the Operator Properties tab's Adapter
Configuration drop-down setting in each operator's Properties
view. Multiple operators can be made to share a single connection by using
the same value for this Adapter Configuration
setting.
A best practice is to define your connections before placing operator instances on the canvas, so that the list is already available in the Properties view and the operators can be configured right away.
This section describes the shared adapter configuration block
found in the HOCON
file.
If a value is not present, the default is used. Those values listed without a default are required unless otherwise noted.
Property | Type | Default | Client? | Server? | Description |
---|---|---|---|---|---|
id | string | yes | yes | ALWAYS REQUIRED. This is the ID that will appear in the adapter's Adapter Configuration drop-down. | |
host | string | yes | no | ALWAYS REQUIRED. The host name or IP address of the server to which to connect. | |
port | integer | yes | yes | ALWAYS REQUIRED. For clients, port number to use to connect to server. For servers, local port on which to listen for incoming connection requests from clients. | |
connect-on-startup | boolean | true | yes | yes | For clients, whether to attempt to connect to server automatically when application starts. For servers, whether to start listening for incoming client connections automatically when application starts. |
enable-automatic-reconnection | boolean | true | yes | no | Whether to attempt to reconnect to server when the connection is lost, or when the previous connection attempt failed. The number of attempts and interval between attempts is controlled by the next two settings below. |
reconnection-attempts | integer | 3 | yes | no | The number of times to attempts reconnection. Ignored
when enable-automatic-reconnection =
"false" .
|
reconnection-attempt-interval | integer | 5000 | yes | no | The number of milliseconds to wait between reconnection
attempts. Ignored when enable-automatic-reconnection =
"false" .
|
echo-interval | integer | 25000 | yes | no | The number of milliseconds between Echo Request messages sent to the server to keep the connection alive (which is a function handled automatically by the Client adapter). This number should be set to a slightly lower value than the server's idle-connection-timeout policy to avoid disconnections from the server due to inactivity. |
idle-connection-timeout | integer | 30000 | no | yes | The number of milliseconds of inactivity on a given client connection before considering it stale and disconnecting. |
message-buffer-size | integer | 65536 | yes | yes | The maximum size (in bytes) an RTPP PDU message is expected to use. |
treat-octetstring-as-base64string | boolean | true | yes | yes | Whether to convert RTPP parameters of type OCTETSTRING to (and from) a Base64-encoded Streaming type STRING (when set to "true") or raw BLOB (when set to "false"). |
This section describes the properties you can set for an RTPP operator, 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. The name must be unique within the current EventFlow module. The name can contain alphanumeric characters, underscores, and escaped special characters. Special characters can be escaped as described in Identifier Naming Rules. The first character must be alphabetic or an underscore.
Operator: A read-only field that shows the formal name of the operator.
Class name: Shows the fully qualified class name that implements the functionality of this operator. 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 operator starts.
Enable Error Output Port: Select this checkbox 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 purpose and function of the component. In the EventFlow Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.
This section describes the properties on the Operator Properties tab in the Properties view for all RTPP Adapter operators. Enter all text fields as string literals, not as expressions.
All the RTPP Adapter operators share a common set of properties:
- RTPP Configuration
-
The Editor, used for adapter configuration.
button is a shortcut to the StreamBase Configuration File - Connection Definition
-
Specifies the ID of the configuration section describing the connection parameters used by this operator. The Connection Definition drop-down list of each operator will contain a list of available definitions from which to choose, as specified in the adapter configuration file (see Adapter Configuration). This setting is required.
- Log Level
-
Use this to set the operator to produce more or less verbose console output, independent of the
STREAMBASE_LOG_LEVEL
global setting. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE.
Use the settings in this tab to enable this operator or adapter for runtime start and stop conditions in a multi-node cluster. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with 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.
The Client Control and Server Control operators have one input port, used to receive commands describing an operation to be performed (such as Connect or Disconnect). The schema for these input ports is the same for both operators, but supported commands differ:
Field Name | Field Type | Description |
---|---|---|
command | string | REQUIRED. Specifies the command to execute.
For the Client Control operator, the available commands are:
For the Server Control operator, the available commands are:
|
Similarly, the Client Output and Server Output operators have one input port, used to receive tuples describing RTPP messages to be sent to a counterparty. The schema for these input ports is the same for both operators:
Field Name | Field Type | Description | |
---|---|---|---|
MajorVersion | integer | OPTIONAL. When present, its value is expected to be null or 1. | |
MinorVersion | integer | OPTIONAL. When present, its value is expected to be null or 1. | |
OpCode | int | CONDITIONALLY REQUIRED. Contains the operation code of
this RTPP message. Either this field or
OpCodeAsString must be specified. Must be
one of:
|
|
OpCodeAsString | string | CONDITIONALLY REQUIRED. Contains the operation code of
this RTPP message. Either this field or
OpCode must be specified. Must be one
of:
|
|
TransactionID | string or blob, depending on the value of the
transaction-id-handling configuration
setting
|
Uniquely identifies the transaction related to this
message. Note that neither the Client or Server Output
operators make any attempt to validate the content of this
field beyond the required 32-character length constraint when
using transaction-id-handling='HexString'
or the 16-byte length of the blob field when using
transaction-id-handling='Blob' .
For clients, if this value is left null a reasonably unique random value will be provided. For servers, this value
must be specified for outgoing messages
and match that of the initiating request message received from
the client. Note that the RTPP protocol specification
stipulates that a transaction consists in exactly one request
from the client followed by exactly one reply from the server.
So for a given server, an incoming message's
|
|
BILLINGCORRID | string | Billing correlation ID | |
CONTEXTID | string | Context ID | |
INBAND | string | In-band billing information | |
INFO | string | Informational field | |
OPERATION | long | Billing event identification | |
OPTIME | long | Operation time, expressed in seconds since Unix Epoch (01/01/1970, 00:00:00 UTC) | |
PREPAID | boolean | Whether the applicable subscriber is registered as a prepaid subscriber | |
STATUSCODE | long | Transaction status code | |
STATUSMSG | string | Transaction status message | |
TARIFFCODE | long | Tariff code associated with this transaction | |
WSB | tuple | Contains all fields specifically related to Wireless Service Broker messages. The schema for this sub-tuple can be examined by looking at an instance of the Client or Server Input adapter's first input port. | |
MMSC | tuple | Contains all fields specifically related to Multimedia Messaging Center messages. The schema for this sub-tuple can be examined by looking at an instance of the Client or Server Input adapter's first input port. | |
UM | tuple | Contains all fields specifically related to Unified Messaging messages. The schema for this sub-tuple can be examined by looking at an instance of the Client or Server Input adapter's first input port. | |
SMSC | tuple | Contains all fields specifically related to Short Message Service Centre messages. The schema for this sub-tuple can be examined by looking at an instance of the Client or Server Input adapter's first input port. | |
GUA | tuple | Contains all fields specifically related to Global User Agent messages. The schema for this sub-tuple can be examined by looking at an instance of the Client or Server Input adapter's first input port. |
Every operator (Client and Server Control, Input and Output) have a Status output port used to issue various informational and error messages:
Field Name | Field Type | Description |
---|---|---|
Status | string | Describes this event (Connected ,
Disconnected , Success ,
Error , and so on).
|
Time | timestamp | The time at which this status tuple was generated. |
Info | list<tuple> | Contains any additional information pertaining to this
event. Each tuple has two fields, Name and
Value to describe one informational
entry.
|
In addition to the Status port described above, these operators
each also present an output port used to relay RTPP messages as they are
received from a counterparty. The schema for this port is identical to
the input port of Client and Server Output Operators (see Client Output and Server Output Operators), with the optional addition
of two utility fields that will contain the receipt time of the message.
These fields will only be added to the schema if the
add-receipt-timestamps
configuration setting is set
to true
.
Field Name | Field Type | Description |
---|---|---|
MessageReceiptTime | timestamp | The time at which this RTPP message was received by the Input adapter. |
MessageReceiptTimeNano | long | The time at which this RTPP message was received by the
Input adapter, in high-resolution format returned by Java's
System.nanoTime() call.
|
In addition to the Status port described above, these operators each also present an output port used to relay RTPP messages that were successfully sent to a counterparty (sending failures will not be reported via this port but rather via the operator's Status port). The schema for this port is identical to the input port of Client and Server Output Operators (see Client Output and Server Output Operators).
The table below lists all the RTPP data types and their translation to a corresponding Spotfire Streaming data type.
Note
RTPP types listed with an asterisk designate types currently not in use anywhere in the currently-supported telephony products (WSB, MMSC, UM, SMSC and GUA) but are included here for completeness.
RTPP Type | Spotfire Streaming Type |
---|---|
STRING, UTFSTRING | string |
INT8*, UINT8*, INT16*, UINT16*, INT32, UINT32, INT64*, UINT64* | long |
BOOLEAN | boolean |
OCTETSTRING | If the adapter's configuration specifies
treat-octetstring-as-base64string = "true"
then string, otherwise blob.
|
DATE* | timestamp |
ID* | blob |
The adapter offers a few convenience Java functions available to
EventFlow via the use of the calljava()
function,
to facilitate conversions to and from byte-array-based fields --
specifically the TransactionID
header field, and
SMSC's SMSMSGID
and SMSVAMCUDH
fields which are both of RTTP type OCTETSTRING.
-
com.streambase.sb.adapter.rtpp.RTPP.hexStringToBlob(String hexString)
-- Converts a field of type String containing a hex-encoded value to a field of type Blob. For example, the function callcalljava('com.streambase.sb.adapter.rtpp.RTPP', 'hexStringToBlob', '01A2CF') as blob
will return a Blob field containing the byte array { 0x01, 0xA2, 0xCF }. -
com.streambase.sb.adapter.rtpp.RTPP.blobToHexString(Blob bytes) --
Converts a Blob field to a String field containing its hex-encoded equivalent representation. For example, calling this function with a Blob field containing the byte array { 0x01, 0xA2, 0xCF } will return a String value of "01A2CF". -
com.streambase.sb.adapter.rtpp.RTPP.base64StringToBlob(String base64String)
-- Converts a field of type String containing a base64-encoded value to a field of type Blob. -
com.streambase.sb.adapter.rtpp.RTPP.blobToBase64String(Blob bytes)
-- Converts a field of type Blob to a String containing its base64-encoded value.
The Spotfire Streaming installation comes with a sample demonstrating the use of this adapter. To load the sample in Streaming Studio, select Messaging Adapters category for an entry called RTPP Adapter.
> and look under the