TREP-RT Contribution Output Adapter

Contents

Introduction
Setting Properties
Data Model
Adapter Ports
Using the Adapter in an EventFlow Application
Typechecking and Error Handling
Suspend and Resume Behavior
Related Topics

Introduction

The Spotfire Streaming Adapter for Thomson Reuters Enterprise Platform for Real-Time Contribution (the TREP-RT Contribution Adapter) allows a StreamBase application to contribute market data via off-stream OMM POST messages to a Reuters Posting Provider. Contributed data is then typically published to Reuters subscribers. The Thomson Reuters TREP-RT Contribution Adapter is an embedded adapter that is represented as an icon on the canvas and runs in the same process as the StreamBase application.

This adapter supports the Reuters MarketPrice message model, which consists of a flat set of key/value pairs. The adapter sends a MarketPrice POST message for each tuple received on its input port.

This adapter contains two output ports to convey status and acknowledgements to posted messages. Status tuples are emitted in response to import events such as logging in to a Posting Provider, dictionary (down)loads, and rejected contribution tuples.

The adapter is configured through a collection of properties set in the adapter's Properties view within StreamBase Studio. Properties specify, among other things, the default Reuters service name, the RFA session name, an optional RFA configuration file, whether to download dictionaries from the Posting Provider applications, and the names of the local files when not downloading.

The optional RFA configuration (preferences) file defines RFA namespaces, sessions, and connections. It can be created using the Reuters Configuration Editor included in the Reuters Foundation API—Java Edition SDK. If a preferences file is provided, its contents are imported into the Java preferences database and subsequently accessed by the RFA/Java library. If other RFA contribution applications have been used on the system, it may be possible to reuse the existing preferences, in which case the preferences file name can be left blank.

Setting Properties

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

General Tab

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.

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

Adapter Properties Tab

This section describes the properties on the Adapter Properties tab in the Properties view for the Thomson Reuters TREP-RT Contribution Output adapter.

Property Description
Message Model The Thomson Reuters Message Model to be used by this instance of the adapter. Currently, the only valid value is MarketPrice.
Default Service Name The Reuters service name to use in POST messages if no value is specified in an input tuple's MetaData.Service field.
RFA Configuration File The name of the RFA configuration (preferences) file. This file may not be required if the preferences from another RFA client application are being reused. If specified, the contents of this file is imported into the Java preferences database when the adapter starts.
RFA Session Name The session name within the Java preferences database to use. The session name must include a namespace prefix and a double colon delimiter (::).
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.

DACS Properties Tab

This section describes the properties on the DACS Properties tab in the Properties view for the Thomson Reuters TREP-RT Contribution Output adapter.

Property Description
Username The username value used to enforce entitlements.
Position The position value used to enforce entitlements.
Application ID The application ID value used to enforce entitlements.

Data Dictionaries Tab

This section describes the properties on the Data Dictionaries tab in the Properties view for the Thomson Reuters TREP-RT Contribution Output adapter.

Property Description
Download Data Dictionaries

When set, data dictionaries are downloaded from the Posting Provider application.

Dictionary Download Service

The Thomson Reuters service to use in downloading data dictionaries when more than service is available from the Posting Provider.

Field Dictionary File When not downloading dictionaries, the local file name of the field data dictionary, which is used to validate the schema of the contribution input port.
Enumeration Dictionary File When not downloading dictionaries, the local file name of the enumeration data dictionary, which is used to validate and translate enumeration fields being contributed as string values.

Debugging Tab

This section describes the properties on the Debugging tab in the Properties view for the Thomson Reuters TREP-RT Contribution Output adapter.

Property Description
Display Messages Sent This property is primarily a diagnostic feature. When set, the adapter displays the contents of messages it sends to subscribing clients
Display Messages Received This property is primarily a diagnostic feature. When set, the adapter displays the contents of messages it receives from subscribing clients.
Message Display Filter This property is primarily a diagnostic feature. If blank, every Thomson Reuters message is subject to display based on the setting of the previous two properties. Otherwise, the filter is a set of message model names delimited with the pipe symbol ( | ). Valid values include: LOGIN, DIRECTORY, DICTIONARY, and MARKET_PRICE. Thus, for example, to see all Login and MarketPrice OMM messages received, set this property to LOGIN|MARKET_PRICE and set Display Reuters Messages Received to true.

Cluster Aware Tab

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.

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.

Data Model

Fat Tuple Model

The adapter supports a fat tuple data model. That is, the input port used by the application to sent POST messages contains all the fields that can be contributed. On a per-tuple basis, the adapter includes all non-null tuple fields in the outgoing message.

Nested Tuples and Contribution Field Names

The adapter uses nested tuples in the schema of its input port to organize metadata and market data. The adapter requires the following well-know field names for the top-level fields, each of which is of type tuple: MetaData and MarketData. The MetaData tuple field has the following set of well-known sub-field names: Service, Item, PostId, and SeqNum. The sub-field names of the MarketData field must match those from the Reuters field dictionary.

Data Type Conversion

A primary function of the adapter is to convert the StreamBase data types of incoming contribution tuples to those available in OMM messages. The table below lists the valid StreamBase-to-OMM data type conversions. The adapter aborts during startup if it detects an attempt to perform an invalid conversion.

StreamBase Type Valid OMM Types
BLOB BUFFER, OPAQUE_BUFFER
DOUBLE FLOAT, REAL, DOUBLE, REAL32 (deprecated), REAL64 (deprecated)
INT INT, UINT, FLOAT, DOUBLE, REAL, ENUM, INT32 (deprecated), UINT32 (deprecated), INT64 (deprecated), UINT64 (deprecated), REAL32 (deprecated), REAL64 (deprecated)
LONG INT, UINT, DOUBLE, REAL, INT64 (deprecated), UINT64 (deprecated), REAL64 (deprecated), UINT32 (deprecated)
STRING ASCII_STRING, UTF8_STRING, RMTES_STRING, ENUM
TIMESTAMP DATE, TIME, DATETIME
TUPLE REAL, REAL32 (deprecated), REAL64 (deprecated)

Note: OMM enumeration fields can be contributed as either strings or integers. In either case, the value is validated at runtime. If an invalid value is detected, an invalid user input status tuple is emitted and the contribution tuple is discarded without generating a POST message. Refer to the Reuters enumeration dictionary, enumtype.def, for the set of valid values for each field.

Note: StreamBase tuple fields can be used to contribute to OMM REAL (PRICE) and the deprecated REAL32 and REAL64 fields. The schema of such a tuple field must have exactly two sub-fields. The first field (value) must be of type int to contribute a REAL32 or type long to contribute a REAL or REAL64. The second field (hint) must be of type int and contains the number of digits to the right of the decimal point in the value field. For example, to contribute a price of 1.23, place 123 in the value field and 2 in the hint field.

Adapter Ports

As shown in the EventFlow diagram below, the adapter uses one input port and two output ports to communicate with the surrounding application. As with other Spotfire Streaming adapters and operators, you can optionally enable an Error Output Port, as described in Using Error Ports and Error Streams.

Note

In the diagram below, the adapter's input and output ports are connected directly to externally-visible input and output streams. However, in more complex applications these ports are typically connected to internal StreamBase operators.

The Thomson Reuters TREP-RT contribution Adapter's ports are used as follows:

  • ContributeIn (input): Tuples enqueued on this port cause the adapter to contribute market data by sending OMM POST messages. Note that tuples enqueued on this port will be rejected until the adapter successfully logs in, (down)loads a data dictionary, and uses it to validate the input schema.

    • MetaData, tuple: consists of the following sub-fields that contain metadata related to the tuple being contributed.

      • Service, string: contains the name of the Reuters service to publish to. If null, the service name specified by the Default Service Name property is used.

      • Item, string: specifies the name of the item being contributed to.

      • PostId, long: specifies the ID of the OMM POST message. This field must contain a non-null value to receive an Acknowledge response from the Posting Provider.

      • SeqNum, string: specifies the sequence number placed in the OMM POST message.

    • MarketData, tuple: consists of one or more sub-fields containing market data to publish. The names of the sub-fields must match those from the Reuters field dictionary. The sub-field types must be compatible with the OMM types of the corresponding fields in the data dictionary as specified in the datatype conversion table above.

  • Status (output): The adapter emits tuples from this port when significant events occur, such as when a login succeeds or fails, when a dictionary is (down)loaded, when a contribution tuple is rejected, or when the adapter is suspended or resumed. The schema for this port has the following fields:

    • Type, string: returns one of the following values to convey the type of event:

      • Login

      • Service

      • Dictionary

      • UserInput

      • Suspend/Resume

    • Object, string: returns an event type-specific value, such as the username/position/applicationID used to login, the name of the dictionary that was (down)loaded, or the canvas name of the adapter that was suspended or resumed.

    • Action, string: returns an action associated with the event Type and Object, such as Accepted or Rejected after a login request, Up, Down, or Not accepting requests to convey the state of a detected Reuters service, Loaded, Downloaded, or Failed to load, to indicate results of a dictionary operation, Rejected when a contribution tuple is rejected, or Suspended or Resumed when the adapter is suspended or resumed.

    • Message, string: returns a human-readable description of the event.

    • InputTuple, string: for UserInput events, the contribution tuple that was rejected.

  • AckResponse (output): The adapter emits tuples on this port when the Posting Provider acknowledges a POST message. Note that a POST message must have a post ID to be acknowledged by the Posting Provider. The AckResponse port has the following schema:

    • PostId, long: returns the post ID from the original POST message.

    • SeqNum, long: returns the sequence number from the original POST message.

    • StreamState, string: returns the stream state from the acknowledge message.

    • DataState, string: returns the data state from the acknowledge message

    • StatusCode, string: returns the status code from the acknowledge message

    • StatusText, string: returns the status text from the acknowledge message.

Using the Adapter in an EventFlow Application

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

  1. In StreamBase Studio, create a project, including an empty StreamBase EventFlow Application file, which will host the adapter.

  2. Import into the project the sample RFA configuration file, rfa-config.xml, which is located in streambase-install-dir/sample/adapter/embedded/reuters-rmds-contrib. Edit this file and change the serverList and/or portNumber parameters if you want the connect to a Posting Provider on a different host or port. Take note of the namespace and session names, as they will be used below. In the configuration file included in the sample, these values are SBContributorNamespace and SBContributorSession, respectively.

  3. Import into the project the sample field and enumeration dictionary files, RDMFieldDictionary and enumtype.def which are located in streambase-install-dir/sample/adapter/embedded/reuters-rmds-config.

  4. Select the adapter 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 A

    • From the top-level menu, invoke Insert>Adapter.

  5. From the Insert an Operator or Adapter dialog that opens, select Thomson Reuters TREP-RT Contribution and double-click or press OK.

  6. Double-click the adapter icon, and in the Properties view, select the Adapter Settings tab.

  7. Enter a default Reuters service name to contribute to if none is provied in a contribution tuple.

  8. In the RFA Session Name field, enter the namespace and session names, delimited by a double colon (::) in the RFA Session Name text entry box. For example, enter SBContributorNamespace::SBContributorSession.

  9. In the RFA Configuration File field's drop-down list, select the RFA Configuration File you imported into the project above.

  10. In the DACS Properties tab, enter the username, position, and application ID values appropriate for your site.

  11. In the Data Dictionaries tab, enable data dictionary downloading or provide field and enumeration dictionary names as described below.

  12. In the Field Dictionary File drop-down list, select Reuters Field Dictionary File you imported into the project above.

  13. In the Enumeration Dictionary File drop-down list, select Reuters Enumeration Dictionary File you imported into the project above.

  14. Connect Input and Output Streams to the adapter's input and output ports.

  15. Configure the schemas of the input ports. (The schemas of the Status and AckResponse output ports are set automatically by the adapter.) The fields required in the input schema are specified above in the descriptions of the ContributeIn port. The adapter guides you through this process, displaying Typecheck Errors when an expected field is missing or of the wrong type or length, or if an unexpected field is present in the schema.

    Note that the ContributeIn schema uses nested tuple fields, whose types are selected from the set of available named schemas. Thus, use the Named Schemas tab to create schemas for MetaData and MarketData fields, and select these new types in Edit Schema tab of the stream feeding the adapter's ContributeIn port.

Typechecking and Error Handling

The Thomson Reuters TREP-RT contribution adapter uses typecheck messages to help you configure the adapter within your StreamBase application. In particular, the adapter generates typecheck messages for the following reasons:

  • An invalid RFA configuration file name has been entered.

  • An invalid RFA session name has been entered. Session names must be of the form namespace::session.

  • An invalid field or enumeration dictionary file is specified.

  • One or more required fields in the input schema is missing or is of the wrong type or size.

The adapter generates warning messages during runtime under various conditions, including:

  • A contribution tuple is rejected because the adapter has not successfully logged in, (down)loaded a data dictionary, and used it to validate the input schema.

  • A contribution tuple is received with an invalid value, such as a bad message type, item name, stream state, or enumeration string.

  • A value contributed as a long must be truncated to fit in a unsigned 32-bit OMM field.

  • A value must be truncated to fit in a string field of an outgoing event or information query output tuple.

  • An unexpected or malformed Reuters message is received.

  • An OMM message passed to the Reuters API results in a contribution error.

The adapter shuts down the StreamBase application under the following conditions:

  • A sub-field in the MarketData or SummaryData publish fields does not exist in the Reuters data dictionary or is of the wrong size or type.

Suspend and Resume Behavior

When suspended, the adapter stops processing input tuples and emitting output tuples.

When resumed, the adapter once again starts processing input tuples and emitting tuples.

Related Topics