RTPP Adapter

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]

Introduction

The RTPP connectivity solution is implemented as a suite of global Java operators that allow a TIBCO 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)

Placing RTPP Operators on the Canvas

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 Insert>Operator>Java.

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

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

Adapter Configuration

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.

Shared Adapter Configuration Options

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").

Properties View Settings

This section describes the properties you can set for an RTPP operator, using the various tabs of the Properties view in StreamBase Studio.

Properties: General Tab

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.

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 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.

Properties: Operator Properties Tab

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.

Common Properties

All the RTPP Adapter operators share a common set of properties:

RTPP Configuration

The Edit button is a shortcut to the StreamBase Configuration File Editor, used for adapter configuration.

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.

Cluster Aware Tab

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.

Properties: Concurrency 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.

Input Ports

Client Control and Server Control Operators

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:

  • Connect: Instructs the client to attempt connecting to the configured server

  • Disconnect: Instructs the client to disconnect from the server

  • Status: Reports on the current connection status via a tuple on the operator's status output port

For the Server Control operator, the available commands are:

  • Start: Instructs the server to start listening for incoming client connections on the configured port

  • Stop: Instruct the server to stop listening for incoming client connections

  • Status: Reports on the current listening status via a tuple on the operator's status output port

Client Output and Server Output Operators

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:
  • 0x0001 (Debit Request)

  • 0x8001 (Debit Response)

  • 0x0002 (Credit Request)

  • 0x8002 (Credit Response)

  • 0x0003 (Echo Request) -- As the adapter automatically and transparently manages the sending and receiving of keep-alive Echo messages, there should be no need to send these.

  • 0x8003 (Echo Response) -- As the adapter automatically and transparently manages the sending and receiving of keep-alive Echo messages, there should be no need to send these.

OpCodeAsString string CONDITIONALLY REQUIRED. Contains the operation code of this RTPP message. Either this field or OpCode must be specified. Must be one of:
  • DEBIT_REQ (Debit Request)

  • DEBIT_RESP (Debit Response)

  • CREDIT_REQ (Credit Request)

  • CREDIT_RESP (Credit Response)

  • ECHO_REQ (Echo Request) -- As the adapter automatically and transparently manages the sending and receiving of keep-alive Echo messages, there should be no need to send these.

  • ECHO_RESP (Echo Response) -- As the adapter automatically and transparently manages the sending and receiving of keep-alive Echo messages, there should be no need to send these.

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 TransactionID value must be used exactly once to reply to the request it represents.

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.

Client Input and Server Input Operators

These operators have no input ports.

Output Ports

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.

Client and Server Input Operators Results Port

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.

Client and Server Output Operators Results Port

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).

Data Type Mappings

The table below lists all the RTPP data types and their translation to a corresponding TIBCO 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 TIBCO 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

Blob Conversion Functions

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 call calljava('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.

RTPP Adapter Sample

The TIBCO Streaming installation comes with a sample demonstrating the use of this adapter. To load the sample in Streaming Studio, select File>Import Samples and Community Content and look under the Messaging Adapters category for an entry called RTPP Adapter.



[1] The RTPP protocol was initially developed by LogicaCMG, now part of the CGI Group.