Hotspot Itch Input Adapter

Contents

Introduction
Adapter Properties
Using the Adapter within a StreamBase Application
Typechecking and Error Handling
Suspend/Resume Behavior
Related Topics

Introduction

The TIBCO StreamBase® Input Adapter for Hotspot ITCH allows a StreamBase application to subscribe to and receive order information from Hotspot ECN book. The adapter is embedded within the StreamBase application.

The adapter sends subscription requests received on its subscription input port to the Hotspot Itch server and asynchronously and continuously receives and converts the resulting response or market update messages into StreamBase tuples, which it sends downstream.

The adapter emits market data tuples on several output ports. The fields that appear in each output port's output schema are predetermined by the adapter and closely correspond to the market and ticker messages received from the Hotspot Itch server. See below for the description of each output port as well as the name, type, and description of each field emitted by each output port.

In general, the philosophy of this adapter is to perform minimal event processing beyond translating each incoming message into an output tuple.

The adapter provides a status output port to convey status and error information to the StreamBase application. For example, when the state of a connection to the Hotspot Itch server changes, a connection status tuple is emitted from the status output port.

Subscriptions are submitted for one or more currency pairs. It is possible to subscribe to all currency pairs by specifying the special currency pair value ALL.

The adapter is configured through several properties set in the adapter's Properties view within StreamBase Studio.

Adapter Properties

Property Description
Host Name The hostname or IP address of the Hotspot Itch server.
Port Number The TCP port number of the Hotspot Itch server.
User Name The user name used to log in to the Hotspot Itch server.
Password The password used to login to the Hotspot Itch server.
Reconnect Interval The time, in seconds, to wait between attempts to reconnect to the Hotspot Itch server after a failed connection attempt or after the connection is lost (a disconnect).
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, and ALL.
Subscribe to Market Data at Startup When enabled, the adapter attempts to subscribe to market data when it starts using the currency pairs from the Initial Market Data Currency Pairs property, rather than waiting for a subscribe tuple. Additional subscriptions can be made after startup by enqueuing subscribe tuples to the adapter.
Initial Market Data Currency Pairs The currency pairs to use when subscribing to market data at startup.
Subscribe to Ticker Data at Startup When enabled, the adapter attempts to subscribe to ticker data when it starts using the currency pairs from the Initial Ticker Data Currency Pairs property, rather than waiting for a subscribe tuple. Additional subscriptions can be made after startup by enqueuing subscribe tuples to the adapter.
Initial Ticker Data Currency Pairs The currency pairs to use when subscribing to ticker data at startup.
Enable Instrument Directory Adds an output port for emitting a tuple containing the list of currency pairs available from the Hotspot Itch server.
Enable Market Snapshot Adds an output port for emitting tuples containing the initial snapshot of the market order state for the set of subscribed currency pairs.
Enable New Order Adds an output port for emitting new-order tuples.
Enable Modify Order Adds an output port for emitting modify-order tuples.
Enable Cancel Order Adds an output port for emitting cancel-order tuples.
Enable Ticker Adds an output port for emitting ticker tuples.

Using the Adapter within a StreamBase Application

This section discusses how to use the Hotspot Itch input adapter within a StreamBase application. As shown in the diagram below depicting the adapter's sample application, the adapter has one input port and up to seven output ports to communicate with the surrounding application.

The Hotspot Itch Input Adapter's ports are used as follows:

  • Subscribe: Tuples enqueued on this port cause the adapter to dynamically subscribe to, or unsubscribe from, market and ticker data after the adapter has started. The schema of the subscribe port is derived from the upstream operator or stream and must have the following fields.

    • isSubscribe, boolean: true or false to subscribe or unsubscribe, respectively. A null value defaults to true (subscribe).

    • isMarketData, boolean: true or false to subscribe/unsubscribe request is for market or ticker data, respectively. A null value defaults to true (market data).

    • currencyPairs, list<string>: The currency pairs to subscribe to or unsubscribe from. The special value ALL may be used to subscribe to or unsubscribe from all currency pairs. A null value (for the tuple field rather than an entry in the list) defaults to ALL.

    Note that these "dynamic" subscriptions can be used in conjunction with initial subscriptions specified through the Initial Market Data Currency Pairs and Initial Ticker Data Currency Pairs adapter properties. For example, if Initial Market Data Currency Pairs contains ALL, and a subscribe tuple is later enqueued with isSubscribe=false, isMarketData=true, and currencyPairs=[EUR/USD, USD/JPY], then the adapter remains subscribed to market data for all currency pairs except EUR/USD and USD/JPY.

    Also note that the adapter rejects dynamic subscribe tuples with "Invalid Currency Pair" status until it receives an InstrumentDirectory message from the Hotspot Itch server.

  • Status: This output port emits status, information, and error tuples. The Status port has the following schema:

    • type, string: Contains one of the following values describing the type of event that occurred:

      • Connection - A connection to the Hotspot Itch server has gone up or down

      • Login - A login request to the Hotspot Itch server has been accepted or rejected

      • Protocol Error - An error notification message has been received from the Hotspot Itch server

      • Subscription - An initial or dynamic subscription has been rejected

      • Suspend/Resume - The adapter has been suspended or resumed

    • object, string: The name of the object related to the event:

      • Connection - The configured Hotspot server host:port value

      • Login - The configured Hotspot User Name for which the login request was accepted or rejected

      • Protocol Error - null

      • Subscription - A string representation of the initial or dynamic subscribe or unsubscribe request that was rejected, such as Subscription{type: 'Initial', isSubscribe: 'true', isMarketData: 'true', currencyPairs: ['EUR/USB']}

      • Suspend/Resume - The adapter's name on the canvas

    • action, string: The action associated with the event

      • Connection - Opened or Closed

      • Login - Logged In or Rejected

      • Protocol Error - Error Notification Packet Received

      • Subscription - Rejected

      • Suspend/Resume - Suspending or Resumed

    • message, string: A human-readable description of the event

  • InstrumentDirectory: After it logs in to the Hotspot Itch server, the adapter emits a tuple on this output port containing the list of valid currency pairs. The InstrumentDirectory port has the following schema:

    • currencyPairs, list<string>: Each list entry contains a currency pair available from the Hotspot Itch server.

  • MarketSnapshot: This output port emits a tuple after a subscribe or unsubscribe request is processed. The tuple conveys the current market data order state for all subscribed currency pairs. The port's schema has a three-level hierarchy, with entries at the top level representing currency pairs, the middle level bid and offer price levels, and the bottom level orders:

    • exchangeId, list<CurrencyPairSchema>: Each entry in this list holds the order state for a specific currency pair and has the following fields:

      • currencyPair, string: The currency pair

      • bidPriceLevels, list<PriceLevelSchema>: Each entry in this list holds a bid price level for a specific currency pair and has the following fields:

        • price, string: The bid price

        • orders, list<OrderSchema>: Each entry in this list holds a bid at a specific price for a specific currency pair and has the following fields:

          • amount, double: The bid size

          • ordersID, string: The ID of the bid

      • offerPriceLevels, list<PriceLevelSchema>: Each entry in this list holds an offer price level for a specific currency pair and has the following fields:

        • price, string: The offer price

        • orders, list<OrderSchema>: Each entry in this list holds an offer at a specific price for a specific currency pair and has the following fields:

          • amount, double: The offer size

          • ordersID, string: The ID of the offer

  • NewOrders: This output port emits a tuple when a new bid or offer is received. The NewOrders port has the following schema:

    • isBuy, boolean: True or false if the order is a bid or offer, respectively

    • currencyPair, string: The currency pair

    • price orderID, string: The ID of the bid or offer

    • price string: The bid or offer price

    • amount, double: The bid or offer size

  • ModifiedOrders: This output port emits a tuple when the size of an existing bid or offer changes. The ModifiedOrders port has the following schema:

    • currencyPair, string: The currency pair

    • price orderID, string: The ID of the existing bid or offer

    • amount, double: The new bid or offer size

  • CancelledOrders: This output port emits a tuple when a bid or offer is cancelled. The CancelledOrders port has the following schema:

    • currencyPair, string: The currency pair

    • price orderID, string: The ID of the existing bid or offer being cancelled

  • Ticker: This output port emits a tuple for each trade of a subscribed currency pair. The Ticker port has the following schema:

    • aggressorIsBuy, boolean: True or false if the aggressor bought or sold, respectively

    • currencyPair, string: The currency pair traded, such as AUD/USD

    • price string: The price that it traded at, such as 0.83736

    • transactionDate, string: The date of the trade, such as 20090807

    • transactionTime, string: The date of the trade, such as 123852

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

  1. Within StreamBase Studio, create a project, including a StreamBase EventFlow diagram, that will host the adapter

  2. Drag an instance of the Hotspot Itch adapter from the Project Adapters drawer in the Palette view to the canvas.

  3. Connect Input and Output streams to the adapter input and output ports. Configure the schema of the input stream as defined in the descriptions of the subscribe port above. The adapter informs you of any missing or extraneous fields, or fields configured with the wrong type.

  4. Select or double-click the adapter icon, and in the Properties view, click the Connection Properties tab and fill in values for the Hotspot Itch server host, port, username, and password. Click the Subscription Properties tab and set up any desired initial subscriptions.

Typechecking and Error Handling

The Hotspot Itch Input adapter generates the following typecheck messages to help you configure the adapter within your StreamBase application:

  • Required fields are missing or configured with the wrong data type, or extraneous fields are present in the subscribe input schema.

  • A Hotspot Itch host or IP address is missing.

  • A Hotspot Itch port number is missing or invalid.

  • A Hotspot Itch user name is missing.

  • One or more invalid currency pairs has been supplied in one of the Subscription Properties.

The adapter emits tuples on the status port during runtime under various conditions:

  • A connection to the Hotspot Itch server opens or closes.

  • An attempt to open a connection to the Hotspot Itch server fails.

  • A login attempt to the Hotspot Itch server succeeds or fails.

  • An error notification message is received from the Hotspot Itch server.

  • An initial or dynamic subscription request is rejected.

  • The adapter is suspended or resumed.

Suspend/Resume Behavior

When suspended, the Hotspot Itch input adapter unsubscribes from all market and ticker data for all currencies and stops emitting tuples.

When resumed, the adapter re-subscribes to the market and ticker data it had been subscribed to at the time of suspension and begins emitting tuples again.

Related Topics