Exegy Input Adapter

Contents

Introduction
Exegy Input Adapter Properties
Adapter Ports
Using the Adapter in a StreamBase Application
Typechecking and Error Handling
Suspend and Resume Behavior
Related Topics

Introduction

The Spotfire Streaming Adapter for Exegy allows a StreamBase application to receive and process real-time market data from the Exegy Ticker Plant.

The adapter supports Level 1 and 2 market data for equities and commodities. It supports key lists, allowing the StreamBase application to define and store customized instrument lists (keylists) on the Exegy Ticker Plant, and to modify existing keylists.

The adapter is embedded in the StreamBase application and has several input and output ports, some of which are always present, and others whose presence is configurable.

The adapter can be configured to connect to the Exegy Ticker Plant when it starts or later, in response to a connect tuple on its Admin input port. The Subscribe and KeyList input ports expose the adapter's core functions. Section Input Ports describes the adapter's input ports in more detail.

Some of the adapter's output ports, such as Status, Dictionary, and KeyListDef, have fixed schemas defined by the adapter, while others, such as Equities, Commodities, and PriceBook, have schemas defined by the user via the adapter's Edit Schema tab. Section Output Ports describes the adapter's output ports in more detail.

The set of StreamBase data types supported by the adapter is dictated by the Exegy dictionary, which can be retrieved by enqueuing a dumpDict tuple to the adapter's Admin input port or by enabling the adapter's Dump Dictionary on Startup property.

The adapter is configured through properties set in the adapter's Properties view in StreamBase Studio. The properties are organized across several tabs and include checkboxes that determine the set of optional input and output ports present, connection parameters for the Exegy Ticker Plant, subscription properties for controlling the subscription rate and maximum available subscriptions, and properties for setting the schemas of various adapter output ports.

Exegy Middleware Dependencies

The Spotfire Streaming Exegy adapter only runs on Linux platforms. While you may use Studio to write your EventFlow applications on any supported platform, in order to run your applications they will need to be deployed to a Linux machine. This is due to the fact that as since version 4.0, the Exegy Client API only provides Java support on Linux.

The Spotfire Streaming Exegy adapter relies on version 4.10.0 or later of the JAR file that implements the Exegy Client API, XCAPI.jar. This file is supplied as part of your Exegy installation and is not included in StreamBase. If you get an error message whose text refers to NoClassDefFoundError: com/exegy/xcapi/XCException, make sure this JAR file is locatable by the adapter on the path specified in the CLASSPATH environment variable.

The Spotfire Streaming Exegy adapter also relies on version 4.10.0 or later of the native library that implements the Exegy Client API, libjnixcapi64.so. This file is supplied as part of your Exegy installation and is not included in Spotfire Streaming. If you get an error message whose text refers to Failed to load Java XCAPI library (jnixcapi64), make sure this file is locatable by the adapter on the path specified in the LD_LIBRARY_PATH environment variable on Linux or in the PATH environment variable on Windows.

The Exegy API implementation described in this section is a product of a third party, and its specifications and file names are subject to change by Exegy. See your Exegy documentation for the latest information.

Exegy Input Adapter 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

Property Description
Price Book Depth

The maximum number of bids and asks present in each tuple emitted on the PriceBook output port. The default value is 5.

Enable Dynamic Key List Definition If enabled (not the default), the adapter includes an input port for configuring and querying key list definitions and an output port for receiving key list definition changes.
Enable Baskets If enabled (not the default), the adapter includes an input port for configuring, subscribing to, and querying baskets and a second input port for setting custom halted prices, and output ports for receiving basket activity and the real-time flow of Net Asset Value (NAV) updates for each active basket.
Enable Order Imbalance If enabled (not the default), the adapter will output order imbalance information on the order imbalance port when received.
Include Basket Pass-Thru Field When set, a field named PassThru is expected in the schema of the Basket input port, and a field of the same type is added to the BasketUpdates and BasketNav output ports. There are no constraints on the PassThru field's type. The value received in this field from the subscription tuple is placed in each output tuple emitted as a result of that subscription.
Dump Dictionary on Startup If enabled (the default), the adapter emits a tuple on its Dictionary output port when it starts.
Include Callback Nanotime If enabled (not the default), the adapter includes an XC_ADAPTER_CALLBACK_NANOTIME field of type long in its Equities, Commodities, and PriceBook output ports that indicates the nanotime at which a message was received from the XCAPI library.
Include Adapter Latency If enabled (not the default), the adapter includes an XC_ADAPTER_LATENCY_NANOS field of type long in its Equities, Commodities, and PriceBook output ports that tracks the number of nanoseconds spent within the adapter processing each incoming message.
Include Ticker Plant Latency If enabled (not the default), the adapter includes an XC_TICKER_PLANT_LATENCY_NANOS field of type long in its Equities, Commodities, and PriceBook output ports that tracks the latency in nanoseconds between the receipt of a message by the ticker plant from the exchange and the receipt of the message by the adapter from the ticker plant.
Include Subscribe Pass-Thru Field When set, a field named PassThru is expected in the schema of the Subscribe input port, and a field of the same type is added to the Equity, PriceBook, and Commodities output ports. There are no constraints on the PassThru field's type. The value received in this field from the subscription tuple is placed in each output tuple emitted as a result of that subscription.
Maximum quote rate The maximum rate, in quotes per second, for 'metered quote delivery' for subscribed equity and commodity symbols if no maximum quote rate is defined in the subscription stream. Valid for Edge-Cache connected applications only. 0 means default (unlimited) Note that setting the field does not change the quote delivery rate in effect for previously existing subscriptions.
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.

Connection Properties Tab

Property Description
Exegy Server Host The host name or IP address of the Exegy Ticker Plant.
Login Username The username used in connecting to the Exegy Ticker Plant.
Login Password The password used in connecting to the Exegy Ticker Plant.
Connect on Startup If enabled (the default), the adapter connects to the Exegy Ticker Plant when it starts. If the adapter is configured to not connect on startup, a connect tuple can be enqueued to the adapter's Admin port to connect to the Exegy Ticker Plant.

Subscription Properties Tab

Property Description
Maximum Subscription Symbols The maximum allowable subscription requests that can be passed to the adapter.
Throttle Subscriptions If enabled (the default), the adapter limits the rate at which subscription requests are passed to the Exegy Ticker Plant based to the value of the Symbols Per Second property.
Symbols Per Second The maximum rate at which subscription requests are passed to the Exegy Ticker Plant. If the rate of incoming subscription tuples exceeds this rate, the adapter throttles the requests by enqueuing them internally and passing them to the Ticker Plant at the specified rate.
Refresh/Snapshot Only - No Updates If enabled (not the default), the adapter does not emit tuples for update events.

Edit Schemas Tab

Use the Edit Schemas tab to specify the schemas for three of this adapter's output ports:

Level 1 Equity Schema

Specifies the schema to appear on the Equities output port.

Level 1 Commodity Schema

Specifies the schema to appear on the Commodities output port.

Price Level Schema

Specifies the schema of the bids and asks fields of the PriceBook output port. The schema of the PriceBook output port is set by the adapter.

For general instructions on using the Edit Schema tab, see the Properties: Edit Schema Tab section of the Defining Input Streams page.

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.

Adapter Ports

The Exegy adapter, when configured with all ports enabled, has three input ports and six output ports to communicate with the surrounding application.

The Exegy Input Adapter's ports are used as follows:

Input Ports

  • Admin: This input port receives tuples used to connect to, and disconnect from, the Exegy Ticker Plant and to retrieve the Exegy data dictionary. The Admin port has the following schema:

    • command, string: Contains the administrative command to execute:

      • connect—connect to the Exegy Ticker Plant.

      • disconnect—disconnect from the Exegy Ticker Plant.

      • dumpDict—emit a tuple on the Dictionary output port containing a list of tuples, one per Exegy field.

  • Subscribe: This input port receives tuples used to subscribe to, and unsubscribe from, Level 1 and 2 market data. The Subscribe port has the following schema:

    • command, string: Contains the subscription command to execute:

      • subscribe—subscribe to market data.

      • unsubscribe—unsubscribe from market data.

    • symbol, string: The Exegy symbol to subscribe to, such as US:N:IBM.

    • subscriptionType, string: The type of subscription:

      • level_one—Level 1 market data.

      • price_book—Level 2 market data.

    • containerType, string: The Exegy container type:

      • equity

      • commodity

    • isAggregated, boolean: True to subscribe to aggregated Level 2 data and false otherwise. Ignored for Level 1 subscriptions.

    • includeImplied, boolean: True to include Level 2 commodity quotes and false otherwise. Ignored for all Level 1 subscriptions and Level 2 equity subscriptions.

    • PassThru, any type: must be present when the Include Subscribe Pass-Thru Field property is enabled. A corresponding field is added to the schema of the Equities, PriceBook, and Commodities output ports. The value received in this field is placed in each tuple emitted as a result of that subscription.

    • maxQuoteRate, int: The maximum rate, in quotes per second, for 'metered quote delivery' for this subscription. 0 or null means use the global Maximum quote rate from the adapters properties.

  • KeyList: This optional input port receives tuples used to create, modify, or retrieve keylists. The KeyList port has the following schema:

    • command, string: Contains the keylist command to execute:

      • refresh—request a tuple containing the contents of the specified keylist be emitted on the KeyListUpdates port.

      • save—create a new keylist or update an existing keylist.

    • key, string: The name of the keylist to retrieve, create, or update.

    • values, list<string>: When creating or updating keylists, the new values associated with the keylist.

Output Ports

  • Status: The adapter emits tuples on this port when significant events occur, such as when the state of the connection to the Exegy Ticket Plant changes, a subscription is processed, or a basket event occurs. The Status port has the following schema:

    • Type, string: The type of event:

      • Connection—the state of the connection to the Exegy Ticket Plant changes.

      • Subscription—a subscription request was processed.

      • Basket—a basket event was received from the Exegy Ticker Plant.

    • Object, string: a string representation of the subscription for Subscription events or the basket name for Basket events.

    • Action, string: Connected or Disconnected for Connection events, Subscribed or SubscribeFailed for Subscription events, and Saved, SaveFailed, Deleted, DeleteFailed, Subscribed, SubscribeFailed, NavSubscribed, or NavSubscribeFailed for Basket events.

    • Message, string: A human-readable description of the event, if applicable.

    • Time, timestamp: The time of the event.

  • Dictionary: The adapter emits a tuple on this port when starting up if its Dump Dictionary on Startup property is enabled and in response to dumpDict tuples received on its Admin port. The Dictionary port has the following schema:

    • dataType, string: The name of the StreamBase data type to use for the field.

    • inLevelOneEquity: True if the field is available for use in Level 1 equity tuples and false otherwise.

    • inLevelOneCommodity: True if the field is available for use in Level 1 commodity tuples and false otherwise.

    • inPriceBookTop: True if the field is available for use in Level 2 tuples and false otherwise.

    • inPriceBookSubLevel: True if the field is available for use in bid and ask subtuples of Level 2 tuples and false otherwise.

  • Equities: The adapter emits a tuple on this optional port when a Level 1 equity event is received. The Equities port schema is derived from the adapter's Level 1 Equity Schema property on the Edit Schema tab. Use the tuple emitted on the Dictionary output port to determine the fields available for the Equities port and their types. If the Add Performance Trace property is set, the adapter adds a XC_ADAPTER_LATENCY_MICROS field to the Equities port that contains the time, in microseconds, to process the Level 1 equity event.

    The XC_MESSAGE_TYPE field, if present, contains one of the following values:

    • 0: Refresh

    • 1: Snapshot

    • 2: Quote

    • 3: Trade

    • 5: Trading action

  • Commodities: The adapter emits a tuple on this optional port when a Level 1 commodity event is received. The Commodities port schema is derived from the adapter's Level 1 Commodity Schema property on the Edit Schema tab. Use the tuple emitted on the Dictionary output port to determine the fields available for the Commodities port and their types. If the Add Performance Trace property is set, the adapter adds a XC_ADAPTER_LATENCY_MICROS field to the Commodities port that contains the time, in microseconds, to process the Level 1 commodity event.

    The XC_MESSAGE_TYPE field, if present, contains one of the following values:

    • 0: Refresh

    • 1: Snapshot

    • 2: Quote

    • 3: Trade

    • 5: Trading action

  • PriceBook: The adapter emits a tuple on this optional port when a Level 2 (price book) event is received. The PriceBook port has the following schema:

    • Symbol, string: the symbol associated with the Level 2 event.

    • XC_MESSAGE_TYPE, int: The type of event:

      • 0: Refresh

      • 1: Snapshot

      • 4: Book update

    • bids, list<tuple>: The list of bids associated with the Level 2 event. Each bid tuple has the schema specified in the Price Level Schema property.

    • asks, list<tuple>: The list of asks associated with the Level 2 event. Each ask tuple has the schema specified in the Price Level Schema property.

    • isAggregated, boolean: True if the price book is aggregated and false otherwise.

    • includeImplied, boolean: True if the price book includes implied quotes and false otherwise.

    • containerType, string: equity or commodity.

    • XC_ADAPTER_LATENCY_MICROS, long: Present in the schema if the Add Performance Trace property is enabled. Contains the time, in microseconds, spent in the adapter processing the Level 2 event.

  • KeyListUpdates: The adapter emits a tuple on this optional port when a keylist is updated or a refresh tuple is enqueued to the KeyList port. The KeyListUpdates port has the following schema:

    • key, string: The keylist name.

    • values, list<string>: The new values associated with the keylist.

Using the Adapter in a StreamBase Application

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

  1. In StreamBase Studio, create a project, and create an EventFlow application file to host the adapter.

  2. Drag the Input Adapter icon from the Operators & Adapters drawer in the Palette view to the canvas. Select the Exegy Input Adapter from the list and click OK.

  3. Select the adapter icon, and in the Properties view, select Adapter Properties, and enable one or more optional ports, if desired.

  4. Select Connection Properties, and enter site-specific values for the Exegy server, login username, and password.

  5. Connect input streams to each adapter input port, and configure the schema of each with the fields described above. The adapter generates a typecheck error if a required field is missing or of the wrong type, or if an unexpected field is present.

  6. Connect output streams to each adapter output port.

  7. Run the application and enqueue a dumpDict command to the Admin port.

  8. Use the resulting tuple emitted by the adapter on the Dictionary port to determine the fields available for the Equities, Commodities, and PriceBook ports.

  9. Stop the application, select the adapter icon, and in the Properties view, select Edit Schemas. Add fields to the Level 1 Equity, Level 1 Commodity, and Price Level Schema properties.

Typechecking and Error Handling

The Exegy Input adapter uses typecheck messages to help you configure the adapter in your StreamBase application. In particular, the adapter generates typecheck messages when:

  • A required field is missing or of the wrong type, or if an unexpected field is present, in an input port schema.

  • Values for the Exegy Server Host, Login Username, or Login Password properties have not been entered.

  • The Maximum Subscription Symbols or Symbols Per Second properties are not within their required ranges.

The adapter emits warnings and errors messages on the status port and/or stderr during runtime under various conditions, including:

  • The Level 1 Equity, Level 1 Equity Commodity, and/or Price Level Schema properties are configured with an invalid Exegy field name.

  • A missing or invalid value is detected in an input tuple, such as an invalid Admin, Subscribe, or Basket command.

  • A Subscribe, Keylist, or Basket command is requested when disconnected from the Exegy Ticker Plant.

  • The Exegy Ticker Plant session disconnects.

  • An error is returned from the Exegy Client API.

  • A Level 1 or 2 event field cannot be processed due to a data type mismatch.

Suspend and Resume Behavior

When suspended, the Exegy Input Adapter stops emitting tuples on its output ports.

When resumed, the adapter begins emitting tuples on its output ports once again.

Related Topics