TREP-RT Publishing Output Adapter

Contents

Introduction
Setting Properties
Data Model
Adapter Ports
Adding the Adapter to 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 Publishing (the TREP-RT Publishing Adapter) allows a StreamBase application to publish market data to Thomson Reuters RMDS 6 servers. The Thomson Reuters TREP-RT Publishing 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 following Thomson Reuters message models:

  • MarketPrice

  • MarketByOrder

  • MarketByPrice

  • MarketMaker

The MarketPrice model consists of a flat set of key/value pairs. The adapter publishes a MarketPrice refresh or update message for each tuple received on its publish input port.

The other three models are hierarchical, containing an arbitrary number of orders, each consisting of a fixed set of key/value pairs. For these models, the adapter collects multiple refresh tuples per item, each representing an order, and publishes a single refresh message with it receives the last refresh tuple (RefreshComplete=true) for the item. The adapter then publish a single update message for each update tuple received on its publish input port.

The adapter publishes only in response to requests from subscribing clients. The adapter notifies the StreamBase application of new subscription requests by emitting tuples on its event port when clients subscribe to, and unsubscribe from, items.

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 Reuters service name and message model used by the adapter instance, the RFA session name, an optional RFA configuration file, and the names of the Reuters field and enumeration dictionary files.

The optional RFA configuration (preferences) file defines RFA namespaces, sessions, and connections. It can be created using the StreamBase RFA/Java Configuration Wizard provided with StreamBase Studio or 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 publishing 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 Publishing Output adapter.

Property Description
Publish Service Name The Reuters publish service name to be used by this instance of the adapter.
Message Model The Thomson Reuters Message Model to be used by this instance of the adapter: MarketPrice, MarketByOrder, MarketByPrice, and MarketMaker.
RFA Configuration File The name of the RFA configuration (preferences) file. This file may not be required if the preferences from another RFA publishing 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 (::).
Field Dictionary File The file name of the field data dictionary which is used to validate the schema of the publish input port and to respond to dictionary download requests from subscribing clients that are directly connected to the publishing adapter.
Enumeration Dictionary File The file name of the enumeration data dictionary, which is used to validate and translate enumeration fields being published as string values and to respond to dictionary download requests from subscribing clients that are directly connected to the publishing adapter.
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, MARKET_PRICE, MARKET_BY_ORDER, MARKET_BY_PRICE, and MARKET_MAKER. Thus, for example, to see all MarketPrice and MarketByOrder OMM messages received, set this property to MARKET_PRICE|MARKET_BY_ORDER and set Display Reuters Messages Received to true.
Output Info Query as List When set the output of the Info Query stream will be a single tuple for each query info input tuple. The output tuple will be a list having one entry for each subscription, dictionary, or dump item. Each subscription, dictionary, or dump item will be a list of info strings.
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.

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 publish refresh and update messages contains all the fields that can be present in an image (refresh). The application indicates in a metadata field whether the adapter should publish a refresh or update. The adapter publishes all non-null tuple fields in update messages. It generates warning messages when a refresh tuple contain null fields.

No Image Caching in Adapter

With the exception of collecting multiple refresh tuples in preparing to publish a single OMM refresh message, the adapter does not cache image (refresh) records. Image caching is assumed to be a function of the StreamBase application.

Subscribing Client Aggregation

The adapter aggregates multiple subscribing clients and presents them as a single client to the StreamBase application. Thus, for example, if two clients subscribe to a specific item, only one subscribe event for that item is sent to the StreamBase application. When the second client subscribes to the item, an image event is sent to the StreamBase application. The StreamBase application is expected to respond by enqueuing the image (refresh) tuple(s) for the item, which the adapter uses to build and send a refresh message to the second client. The adapter subsequently sends updates to both subscribing clients.

Similarly, the adapter sends an unsubscribe event to the StreamBase application only when the last client subscribed to a specific item unsubscribes.

Nested Tuples and Publish Field Names

The adapter uses nested tuples in the schema of its publish input port to organize metadata, market data, and, for the hierarchical message models, summary fields. The adapter requires the following well-know field names for the top-level fields, each of which is of type tuple: MetaData, MarketData, and SummaryData. The MetaData tuple field has the following set of well-known sub-field names: MessageType, Item, StreamState, DataState, StatusCode, StatusText, RefreshComplete, Action, and Key. The sub-field names of the MarketData and SummaryData fields 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 publish 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. This includes cases in which a StreamBase string field is longer than the corresponding OMM field.

StreamBase Type Valid OMM Types
BLOB BUFFER, OPAQUE_BUFFER
DOUBLE FLOAT, DOUBLE, REAL, 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 published as either strings or integers. In either case, the value is validated at runtime. If an invalid value is detected, an invalid user input event is emitted and the publish tuple is discarded without being published. 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 publish OMM REAL fields and the deprecated REAL32 (PRICE) 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 publish a REAL32 or type long to publish 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 publish 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 two input ports 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 will typically be connected to internal StreamBase operators.

The Thomson Reuters TREP-RT Publishing adapter's ports are used as follows:

  • PublishIn (input): Tuples enqueued on this port cause the adapter to publish OMM refresh and update messages. The adapter informs the StreamBase application when it should publish through tuples emitted on its event port.

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

      • MessageType, string: contains one of the following values that specifies the type of message being published: REFRESH, UPDATE, or STATUS

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

      • StreamState string: contains one of the following values to specify the stream state of the item: UNSPECIFIED, OPEN, NONSTREAMING, CLOSED_RECOVER, CLOSED, or REDIRECT.

      • DataState string: contains one of the following values to specify the date state of the item: UNSPECIFIED, OK, or SUSPECT.

      • StatusCode, string: contains one of the following values to specify the status of the item: NONE, NOT_FOUND, TIMEOUT, NOT_ENTITLED, INVALID_ARGUMENT, USAGE_ERROR, PREEMPTED, JIT_CONFLATION_STARTED, REALTIME_RESUMED, FAILOVER_STARTED, FAILOVER_COMPLETED, GAP_DETECTED, NO_RESOURCES, TOO_MANY_ITEMS, ALREADY_OPEN, SOURCE_UNKNOWN, or NOT_OPEN.

      • StatusText, string: contains a human-readable description of a item's current status.

      • RefreshComplete, boolean, hierarchical message models only: set to true if this is the last refresh message for the current item and false otherwise.

      • Action, string, hierarchical message models only: contains one of the following values specifying the action to take for the specific order: ADD, UPDATE, or DELETE.

      • Key, string, hierarchical message models only: a value that uniquely identifies an order for an item.

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

    • SummaryData, tuple, hierarchical message models only: consists of one or more sub-fields containing summary data to publish. Summary data is constant for all the orders for a specific item and is therefore published in refresh messages but not in updates.

  • InfoQueryIn (input): Tuples enqueued on this port request information from the adapter. The adapter provides the requested information by emitting tuples on its InfoQueryOut port. The InfoQueryIn port has the following fields:

    • Command, string: accepts a command specifying the type of metadata being requested. Valid commands include:

      • ListSubscriptions: returns the current set of subscriptions, including active subscriptions and requests for snapshots.

      • DumpDictionary: returns the contents of the loaded field dictionary.

    • Param, string: accepts a command-specific parameter value, which is currently unused.

    • Tag, string: this value is echoed in each tuple emitted from the information query output port in response to a command, allowing responses to be matched with commands.

  • Events (output): The adapter emits tuples from this port when significant events occur, such as when a new subscribing client session is created, when a subscription or snapshot is received, or when the adapter is suspended or resumed. The schema for this port has the following fields:

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

      • ClientSession

      • Login

      • Dictionary

      • Item

      • UserInput

      • Suspend/Resume

    • Object, string: returns an event type-specific value, such as the item being subscribed to or the user input that was rejected.

    • Action, string: returns an action associated with the event Type and Object, such as Snapshot, Subscribe, or Unsubscribe for item events.

    • Info, string: Returns a human-readable description of the event.

  • InfoQueryOut (output): The adapter emits tuples on this port in response to information query commands. The InfoQueryOut port has the following schema:

    When Output Info Query as List IS NOT checked:

    • Done, bool: Set to false for all but the last tuple emitted in response to a specific command. The final (marker) tuple has Done set to true and all other fields set to null.

    • Command, string: returns the command value specified in the corresponding information query request tuple.

    • Param, string: returns the parameter value specified in the corresponding information query request tuple.

    • Tag, string: returns the tag value specified in the corresponding information query request tuple.

    • Info1-Info5, string: returns one or more command-specific values. The description of the InfoQueryIn stream above lists the information returned for each command.

    When Output Info Query as List IS checked:

    • Command, string: returns the command value specified in the corresponding information query request tuple.

    • Param, string: returns the parameter value specified in the corresponding information query request tuple.

    • Tag, string: returns the tag value specified in the corresponding information query request tuple.

    • Info, List<List<String>>: returns a list of lists of command-specific values. The description of the InfoQueryIn stream above lists the information returned for each command.

Adding the Adapter to 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-pub. Edit this file and change the portNumber parameter if you want the publisher to listen on a different TCP port number. 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 SBProviderNamespace and SBProviderSession, 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-pub.

  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 Publish and double-click or press OK.

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

  7. Enter the service name the adapter should publish under.

  8. Select a Reuters Message Model from the dropdown.

  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 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 SBProviderNamespace::SBProviderSession.

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

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

  13. The last three adapter properties—Display OMM Messages Sent and Received, and OMM Message Display Filter—are used for debugging and should typically be left with their default, empty values.

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

  15. Configure the schemas of the two input ports. (The schemas of the Events and InfoQueryOut output ports are set automatically by the adapter.) The fields required in the two input schemas are specified above in the descriptions of the PublishIn and InfoQueryIn ports. 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 PublishIn 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, MarketData, and SummaryData fields, and select these new types in Edit Schema tab of the stream feeding the adapter's PublishIn port.

Typechecking and Error Handling

The Thomson Reuters TREP-RT publishing 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:

  • A Reuters Message Model has not been selected from the dropdown.

  • 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 two input schemas is missing or is of the wrong type or size.

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

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

  • A value published 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.

  • A tuple is published for an item for which no subscription or snapshot request has been received.

  • An information query input tuple contains a null, empty or unrecognized command.

  • Two instances of the adapter configured to listen on the same port are run simultaneously.

  • An OMM message passed to the Reuters API results in a publish 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