Contents
The StreamBase Reuters Subscribing Adapter allows a StreamBase application to receive data from Reuters RMDS, TIB, and Triarch market data systems on an RMDS 5 infrastructure.
Note
Starting with StreamBase 5.1.5, this adapter is deprecated in favor of the StreamBase Reuters RMDS Subscribing Adapter. This adapter supports RMDS 5 only, whereas the Reuters RMDS Subscribing adapter supports both RMDS 5 and RMDS 6. This adapter remains supported for existing projects, but new StreamBase applications should start with the Reuters RMDS Subscribing Adapter.
For the RFA API version used, please see Supported Configurations. This adapter is meant to replace the older StreamBase Reuters SFC subscribing adapter (an external adapter). Unlike the external SFC adapter, the RFA subscribing adapter runs as an embedded adapter within the StreamBase application itself.
To receive data from Reuters Data Feed Direct and RMDS 6 Point-to-Point servers, use the Reuters RMDS Subscribing Input Adapter.
The adapter emits a market data tuple on its primary output stream for each Reuters tick received. This output stream contains several metadata fields that hold the item name, state, and status, along with zero or more Reuters data fields whose names must match those in the data dictionary.
The adapter supports both static and dynamic subscriptions. Static subscriptions are specified as XML elements in the adapter's configuration file and are processed when the adapter starts. Later, items can be subscribed to, or unsubscribed from, by enqueuing tuples to the adapter's dynamic subscription input stream.
The adapter's set of active subscriptions can be retrieved by enqueuing a tuple to a second input stream. When queried, the adapter emits a stream of tuples representing the set of active subscriptions on a second output stream.
Items are addressed in one of two ways: by four-part subject name or by service name/item name pairs. The addressing modes are exposed through both static subscription elements and the dynamic subscription stream.
The adapter is configured through two XML configuration files: one that configures the adapter itself, and a second that configures the RFA infrastructure. These two files are referred to as the adapter and RFA configuration files, respectively. Examples of each are provided with the adapter's sample application.
The name of the adapter configuration file is set as the adapter's single property in the StreamBase application file. The first section of this file chains to the RFA configuration file. Subsequent sections configure the market data output stream, static subscriptions, the dynamic subscription input stream, and the input and output streams used for retrieving the adapter's set of active subscriptions.
The RFA configuration file is typically created using the Reuters RFA/Java Configuration editor and defines RFA namespaces, sessions, connections, and services. It also specifies the source of the data dictionaries (downloaded or local file system) and determines whether entitlements (DACS) are enabled.
Note
This adapter is not provided in the base StreamBase kit, but is available in a separate installation kit. Please contact StreamBase Systems if you are interested in the kit.
| Property | Description |
|---|---|
| Configuration File |
The name of the adapter configuration file, with no path information. When
running the adapter outside of StreamBase Studio, use an
operator-resource-search element within the SBD
configuration file to specify the directory containing the adapter
configuration file.
|
As noted above, two files are used in configuring the adapter: the adapter configuration file and the RFA configuration file.
The adapter configuration file contains five sections, each of which is described below.
The Reuters section contains parameters that allow the adapter to find the RFA configuration file and determine the namespace and session parameters used within it. It also contains authentication information provided to the DACS server when entitlements are enabled.
| Parameter | Description |
|---|---|
| rfa-config-filename | The absolute or relative path of the RFA configuration file. If a relative path is provided, the path is relative to the directory from which the adapter is run. |
| rfa-config-namespace | The namespace used within the RFA configuration file. |
| rfa-session-name | The session name used within the RFA configuration file. |
| username | When entitlements are enabled, the user name to pass to the DACS server. |
| app-id | When entitlements are enabled, the application ID to pass to the DACS server. |
| position | When entitlements are enabled, the position value to pass to the DACS server. |
| use-standard-principal-identity |
Set to true to use standard principal
identities, and false to use tokenized
principal identities.
|
| auto-resubscribe |
Set to true to re-submit all active
subscriptions after a Reuters service down/up event.
|
The market data section allows the adapter to configure the stream used to emit tuples that correspond to Reuters Ticks. The output port number and the names of each of the metadata fields within market data stream are provided in this section. In addition, several parameters control the adapter's behavior when handling update messages and when receiving duplicate subscription requests.
Note
All metadata fields are optional. If a metadata field does not appear in the
adapter's output schema, specify an empty value
attribute in the field's param XML element. For
example:
<param name="item-field" value=""/>
| Parameter | Description |
|---|---|
| port-number | Specifies the output port number of the market data stream. |
| message-type-field |
Provides the name of the metadata field that receives the message type.
For each Reuters tick, this field contains one of the following values:
IMAGE, UPDATE,
UNSOLICITED_IMAGE, CORRECTION, or CLOSING_RUN.
|
| item-field | Provides the name of the metadata field that receives the item name. |
| subject-field | Provides the name of the metadata field that receives the four-part subject name. |
| service-field | Provides the name of the metadata field that receives the Reuters service name. |
| item-state-field |
Provides the name of the metadata field that receives the item state. For
each Reuters tick, this field contains one of the following values:
OK, CLOSED,
CLOSED_RECOVER, STALE, or NO_CHANGE.
|
| item-status-code-field |
Provides the name of the metadata field that receives the item status
code. For each Reuters tick, this field contains one of the following
values: NONE, NO_LICENSE, NO_PERMISSION,
NO_RESOURCES, PauseAck, PauseAck,
PauseNak, PREEMPTED, QUALITY_OF_SERVICE_CHANGE, ResumeAck, or ResumeNak.
|
| item-status-text-field | Provides the name of the metadata field that receives the item status text, which contains a text description of the event or state change. |
| send-unchanged-fields-as-null |
Determines whether fields not present in update messages are populated
with the null or the field's previous value. Valid values are
true or false.
|
| resend-image-on-duplicate-subscribe |
Determines whether an image tuple is emitted when a subscription is
received for an item that has already been subscribed to. Valid values
are true or false.
|
The static subscriptions section is used to have the adapter subscribe to items
during startup. Zero or more subscription
elements are present in this section, each of which subscribes to a specific
item. Items can be addressed by four-part subject or service name/item name
pairs.
| Attribute | Description |
|---|---|
| default-service |
Specifies the Reuters service name to use when a subscription element uses the service name/item
name addressing mode but fails to provide a service attribute.
|
| subscription |
Specifies an item to subscribe to when the adapter starts. Contains
either a subject attribute if
four-part subject addressing is to be used or service and item attributes if service name/item
addressing is to be used. When using service name/item name addressing,
the service attribute need not be
specified if a default-service
attribute is specified for the static-subscriptions element.
|
The dynamic subscriptions section configures the stream used to subscribe to and unsubscribe from items after the adapter starts. A tuple is enqueued to the dynamic subscription stream to subscribe to or unsubscribe from each item. Items can be addressed by four-part subject or service name/item name pair.
| Parameter | Description |
|---|---|
| enabled |
Contains true if dynamic subscriptions are
enabled and false otherwise.
|
| port-number | Contains the input port number of the dynamic subscription stream. |
| subject-addressing-mode-field |
Specifies the name of the boolean field that contains true if the item is being addressed by four-part subject
and false if it is being addressed by
service name/item name pair.
|
| subject-field | Specifies the name of the field that contains the four-part subject when subject addressing mode is being used. |
| service-field | Specifies the name of the field that contains the service name when service name/item name addressing is being used. |
| item-field | Specifies the name of the field that contains the item name when service name/item name addressing is being used. |
| subscribe-field |
Specifies the name of the boolean field that contains true or false if the item
is being subscribed to or unsubscribed from, respectively.
|
| snapshot-field |
Specifies the name of the boolean field that contains true to request an item snapshot. Both the subscribe and
snapshot fields must contain false to
unsubscribe from an item.
|
The active subscription query section configures the input and output streams used to retrieve the adapter's set of active subscriptions. When a tuple is enqueued to the input stream, the adapter emits a sequence of tuples on the output stream, one per active subscription, followed by a null tuple as an end-of-data marker.
| Parameter | Description |
|---|---|
| enabled |
Contains true if active subscription queries
are enabled and false otherwise.
|
| input-port | Contains the input port number of the active subscription query stream. |
| output-port | Contains the output port number of the active subscription response stream. |
| subject-addressing-mode-field |
Specifies the name of the boolean field that receives true if subject addressing mode was used in the
subscription request and false otherwise.
|
| subject-field |
Specifies the name of the field that receives the four-part subject if
subject addressing mode was using in the subscription request and
null otherwise.
|
| service-field |
Specifies the name of the field that receives the service name if
service/item addressing was using in the subscription request and
null otherwise.
|
| item-field |
Specifies the name of the field that receives the item name if
service/item addressing was using in the subscription request and
null otherwise.
|
The optional connection/service/item event stream section configures the output stream used to pass Reuters connection, service, and item events to the StreamBase application. If enabled, a tuple is emitted each time the adapter receives a Reuters connection, service, or item event.
| Parameter | Description |
|---|---|
| enabled |
Contains true if the connection/service/item
event stream is enabled.
|
| port | Contains the output port number of the connection/service/item event stream. |
| event-type-field |
Contains the name of the event stream field that receives the strings
CONNECTION, SERVICE,
or ITEM for connection, service, and item
events, respectively.
|
| name-field | Contains the name of the event stream field that receives the Reuters connection or service name. |
| connection-type-field |
Contains the name of the event stream field that receives the connection
type or null for service and item events. The
connection type field receives one of the following values: SASS3, SSLED, IFP, RV, STIC, STIC_SASS3, or TIBRV.
|
| state-field |
Contains the name of the event stream field that receives the connection,
service, or item state. The event state field receives one of the
following values: UP, DOWN, CLOSED, CLOSED_RECOVER, NO_CHANGE,
OK, or STALE.
|
| status-code-field |
Contains the name of the event stream field that receives the connection,
service, or item status code. The status code field receives one of the
following values: NONE, ACCESS_DENIED, INTERMITTENT_PROBLEMS, NO_LICENSE, NO_PERMISSION,
NO_RESOURCES, PauseAck, PauseNak, PREEMPTED, QUALITY_OF_SERVICE_CHANGE, ResumeAck or ResumeNak.
|
| status-text-field | Contains the name of the event stream field that receives the connection, service, or item status text. |
| item-event-type-field |
Contains the name of field that receives the item event type or
null for non-ITEM events. The item event type
field receives one of the following values: STATUS, GROUP_CHANGE, or
RENAME.
|
| item-name-field |
Contains the name of the event stream field that receives the item name
or null for non-ITEM events.
|
| subject-name-field |
Contains the name of the event stream field that receives the subject
name or null for non-ITEM events.
|
| new-item-name-field |
Contains the name of the event stream field that receives the new item
name after a rename event or null for non-ITEM
events.
|
| new-subject-name-field |
Contains the name of the event stream field that receives the new subject
name after a rename event or null for non-ITEM
events.
|
| group-id-field |
Contains the name of the event stream field that receives the group ID or
null for non-ITEM events.
|
The RFA configuration file is typically created using the Reuters RFA/Java Configuration wizard editor and defines RFA namespaces, sessions, connections, and services. Please refer to the Reuters Foundation API Java Edition Session Layer Package Configuration and Logging Guide for instructions on creating this file. A detailed understanding of the Reuters infrastructure at the customer site is also required.
Three parameters in the reuters section of the
adapter configuration file are critical in linking it with the RFA configuration
file: rfa-config-filename, rfa-config-namespace, and rfa-session-name.
This section demonstrates how to use the Reuters subscribing adapter within a StreamBase application. As shown in the diagram below depicting this adapter's sample application, the adapter uses two input ports and two output ports to communicate with the surrounding application. As with other StreamBase adapters and operators, you can optionally enable an Error Output Port, as described in Using Error Ports and Error Streams.
Note
Although in the sample application the adapter's input and output ports are connected directly to externally-visible input and output streams, in more complex applications these ports will be typically be connected to internal StreamBase operators.
The Reuters subscribing adapter's ports are used as follows:
-
DynamicSubscribe (input): Tuples enqueued on this port cause the adapter to subscribe to, or unsubscribe from, items after the adapter has started. Statically subscribed items (those the adapter subscribes to during startup) can later be unsubscribed from using this port. The schema of this input port provides fields allowing items to be addressed either by four-part subject or by service/item name pair.
-
ActiveSubscriptionQuery (input): Each time a tuple is enqueued on this port, the adapter emits a sequence of tuples on the Active Subscriptions output port representing the set of active subscriptions. The adapter ignores this port's input schema, though it must contain at least one field.
-
ReutersTicks (output): This is the adapter's primary output port, on which a tuple is emitted each time a Reuters tick is received. Several metadata fields, whose names are defined in the adapter configuration file, convey the current state of the item. Additional fields, whose names must match those in the Reuters data dictionary, hold Reuters data.
-
Active subscriptions (output): The adapter emits a sequence of tuples on this port each time a tuple is enqueued to the active subscription query input port. The schema of this port contains a single string field with the item name. A final null tuple is emitted as an end-of-data marker.
Add an instance of the adapter to a new StreamBase application as follows:
-
Within StreamBase Studio, create a project, including a StreamBase EventFlow, which will host the adapter.
-
Import into the project the sample adapter and RFA configuration files, reuters-sub.sbconf and rfa-config.xml, which are located in
streambase-install-dir/sample/adapter/embedded/reuters-sub -
From the Global Adapters drawer of the Palette view, drag a ReutersSubscribe component to the canvas.
-
Double-click the adapter icon, and in the Properties view, select the Adapter Settings tab.
-
In the Configuration File drop-down, select the sample adapter configuration file, reuters-sub.sbconf.
-
Connect Input and Output Streams to the adapter's two input and two output ports.
-
Configure the schemas of the two input ports and the adapter's primary output port. (The schema of the secondary output port, ActiveSubscriptions, need not be set explicitly, as it is derived from the contents of the adapter configuration file.)
The field names shown below are derived from the adapter configuration file. Changes made to the configuration file will require corresponding changes to the field names below.
- DynamicSubscribe (input port 0) fields:
-
-
SubjectAddressingMode: bool(4)
-
Subject: string(40)
-
Service: string(20)
-
Item: string(20)
-
Subscribe: bool(4)
-
- ActiveSubscriptionQuery (input port 1) fields:
-
Ping: int(4)
- ReutersTicks (output port 0) fields:
-
Note
The schema of the adapter's primary output port is configured using the Edit Schema tab of the adapter's Properties view. Any metadata fields listed below that are not entered in the Edit Schema tab are automatically added by the adapter. You should enter a metadata field in the Edit Schema tab if you want to override the field's adapter-provided size.
-
MessageType: string(20)
-
Service: string(20)
-
Item: string(20)
-
ItemState: string(20)
-
ItemStatusCode: string(20)
-
ItemStatusText: string(40)
-
Additional Reuters data fields with names matching those in the data dictionary.
-
The Reuters subscribing adapter uses typecheck messages to help you configure the adapter within your StreamBase application. In particular, the adapter generates typecheck messages when one or more required fields in the two input schemas or primary output schema is missing or is of the wrong type or size.
The adapter generates warning and error messages during runtime under various conditions, including:
-
A tuple received on the dynamic subscription port contains invalid data, such as a null subject value when four-part subject addressing is specified.
-
A field from a Reuters tick is truncated to fit in an output tuple's string field. To avoid overrunning log files, truncation warnings are generated just once per tuple field.
-
In processing an active subscription request, an item name is truncated to fit in an output tuple.
-
The adapter fails to start due to an RFA misconfiguration.
-
Messages originating from the RFA infrastructure are passed to the adapter, which displays them unchanged.
When suspended, the subscribing adapter continues to receive Reuters ticks, but no longer emits tuples on its primary output port.
When resumed, the adapter once again starts emitting tuples on its primary output port.