Wombat MAMA Output Adapter

< Previous		Next >

Introduction

The TIBCO StreamBase® Output Adapter for Wombat MAMA for StreamBase allows StreamBase applications to publish MAMA messages on a user-specified Wombat MAMA source. The adapter receives tuples from a StreamBase application, converts them to MAMA messages and publishes them on a MAMA transport.

The adapter mimics behavior of a Wombat Feed Handler by listening for MAMA client subscriptions on a user-specified MAMA Source. Upon receiving a new symbol subscription from a MAMA client, the adapter sends back a MAMA Init message and every consecutive message for the given symbol. The adapter stores the latest values for every symbol in a cache, and uses that cache to construct an Init message.

If the adapter receives a tuple for which no subscribers exists, it will not publish it further. The adapter knows the set of symbols it has from all the tuples it's received. If a MAMA client subscribes to a symbol not on this list, the adapter will either ignore it, or, if dynamic subscription port is enabled, send a subscription request to the MAMA input adapter. The developer is responsible to link the dynamic subscription output port from the adapter to the dynamic input port of the MAMA input adapter.

The adapter uses a dictionary to convert the tuple to a MAMA message. The dictionary is a MAMA structure that describes each field's name, id and MAMA data type. The adapter can load the dictionary from the Wombat Feed Handler or a local file.

Frequently, the adapter is used together with the MAMA input adapter in a republishing scenario. In this case, the developer should use adapter's Link with a Mama Input Adapter property so the adapters can coordinate their one-time initialization of the underlying MAMA interface.

Another option when running in republishing mode is the use of a passthrough cache as a temporary holding stage for MAMA messages. The MAMA input adapter received a MAMA message and places it in the cache, then sends the tuple to the StreamBase application. Note: the tuple need not have all the fields of the MAMA message, just the ones that the application will be using. After passing through the application, the tuple is sent to the output adapter. The output adapter retrieves the original MAMA message from the passthrough cache and overrides just the fields that have been received on the incoming publish tuple.

Notes

This document assumes familiarity with the MAMA infrastructure. Terms and contexts are used that assume familiarity with the Wombat Universal Feed Handler Suite, and much of the material discussed in the MAMA Developers Guide from Wombat. In addition, the Wombat-specific functionality of the adapter corresponds fairly closely with the functionality implemented in Wombat's mamalisten programs (especially the Java version, com.wombat.mama.examples.MamaListen).

StreamBase does not license or distribute Wombat libraries or other Wombat-provided runtime artifacts. These must be obtained from Wombat and installed prior to installation of the adapter.

The Wombat MAMA Output Adapter releases are built against specific versions of the mamajni.jar file that is targeted for a particular messaging middleware. For information about supported configurations, please contact TIBCO support.

Tip

If your environment already has Wombat Universal Feed Handler, it is recommended that users first get com.wombat.mama.examples.MamaListen to work in the target environment with the data of interest independent of your StreamBase installation before attempting to use the StreamBase Wombat MAMA Output Adapter.

Making the MAMA Middleware Available

As described earlier, the MAMA middleware you will be using is not provided by StreamBase. Before you can run a StreamBase application that uses this adapter, you must obtain an appropriate middleware package from Wombat.

Copy mamajni.jar (found in your Wombat MAMA's lib directory) to $STREAMBASE_HOME/lib/ext.
In the StreamBaseEngine HOCON configuration, add an externalNativeLibraryPath element for the location of your Wombat MAMA native libraries. For example:

Windows:

<library path="C:/MyWombatInstall/bin/dynamic"/>

Linux:

<library path="/opt/my_wombat_install/lib"/>
Set the WOMBAT_PATH environment variable to the path of the mama.properties file on your system.

Adding the Wombat Output Adapter to an EventFlow Application

To add the adapter to an EventFlow application in StreamBase Studio:

Create a new StreamBase project, choosing the option to create an EventFlow application.
Drag the Wombat MAMA Output icon from the Operators and Adapter drawer in the Palette view to the EventFlow canvas.
Click the Wombat adapter's icon to open its Properties view.
Define properties for the Wombat adapter and add any output and output streams required, as described in the next sections.

Configuring Input and Output Streams

In addition to subscription data from the MAMA feed, the Wombat MAMA Output Adapter can be configured to receive control data on up to three input streams, and to emit data on one to four output streams. The use of each stream is predefined for a particular purpose. In an EventFlow application, StreamBase Studio may add or remove streams automatically when you modify the appropriate settings. For more information, see Adapter Properties, which documents all the adapter settings.

Input Streams

By default, just one input stream is enabled, the publish message input stream. If the adapter is running in republishing scenario and using a passthrough cache, another input stream for discarded, unpublished messages is added.

Publish stream: This stream always exists. It accepts tuples to be published on the MAMA feed.
Discard Message stream: If the Passthrough Cache property is enabled, the messages received on this stream are removed from the passthrough cache and not published on the MAMA feed.

Output Streams

There is one optional output stream to be configured.

The Dynamic Subscriptions output stream is present if the Enable Dynamic Subscription Output Port property is checked. If enabled, the adapter emits a subscription tuple when it receives a client subscription request for a new symbol. In a republishing scenario, this stream should feed into the Dynamic Subscription Input port of a MAMA input adapter.

Input Stream Schemas

Each input port must have certain fields present in its schema to allow the adapter to process the message.

The names of the fields are configurable by the developer, their meaning is a follows

Symbol: the symbol that this message is for. The name of the symbol field should be defined in the Special Fields tab.
Message Type: the field representing the type of the message. The name of the Message Type field should be defined in the Special Fields tab.
Passthrough ID: Required only if passthrough cache is enabled. The field in which the passthrough ID is stored in tuples emitted by the MAMA input adapter. The name of the passthrough ID field is defined in the Adapter Properties tab.

Adapter Properties

Properties are used to control much of the adapter's behavior. The properties are grouped under several tabs in the Properties view in StreamBase Studio.

General Tab

The General tab is the same for most output adapters. See Properties: General Tab for details.

Adapter Properties Tab

Middleware

Default: lbm

The middleware MAMA should use. The possible values are:

Setting	Middleware
lbm	29 West's LBM
tibrv	Tibco's Rendezous
WMW	Wombat's TCP Middleware

Transport

Default: internal

The name of the transport, defined in mama.properties, for this adapter to use. Examples: lbm_tport or tibrv_tport. This is a required setting.

Source

Default: Empty

The name of the custom Wombat MAMA source on which this adapter will publish messages. The source should be unique in the target Wombat environment, as to not clash with existing source in the Wombat Feed Handler and other publishers. The MAMA client will have to use this value for its' source parameter (-S). This is a required setting.

Mama Sender ID

The custom sender id that will be set on every outgoing MAMA message. This should be a unique value for every instance of the MAMA output adapter running in your environment.

Support Mama Price

If enabled, the adapter will publish price fields using the Mama Price datatype. Otherwise, the adapter will publish price fields at 64-bit floating point values (F64).

Refresh Period Minutes

Mama clients periodically send a refresh message for each symbol that they've subscribed to. This message lets the publisher know that there is a client still interested in a symbol. The refresh period is configurable on the transport level; the default is 50 minutes and should be verified in the Mama SDK documentation. The publisher uses this value as the timeout period for any symbols that haven't received a refresh. The publisher's refresh period should be bigger than the client's. If no refresh has been received in this period for a symbol, that symbol is marked as having no subscribers and messages for the symbol are no longer published.

Link with a Mama Input Adapter

If enabled, the adapter coordinates its initialization with the specified MAMA Input Adapter.

Link With The Mama Input Adapter Named

If Link with a Mama Input Adapter is enabled, this field specifies the name of MAMA Input Adapter to link with.

Enable Passthrough Cache

If Link with a Mama Input Adapter is enabled, this field specifies that messages should be stored in a passthrough cache (read more about passthrough cache in the overview above).

Passthrough ID Field Name

If Enable Passthrough Cache is enabled, this field specifies the name of the tuple field in the Publish Message Input schema containing the passthrough message ID.

Enable Discard Message Port

This property enables a Discard Message input port. Messages that should not be published should be sent to this port to be removed from the passthrough cache.

Log Level

Default: INFO

Choose one of the following standard Sun logging levels: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL, OFF. The log level setting for the adapter is independent of the containing application's overall log level.

Dictionary Tab

Load Dictionary From

Default: Load From Feed Handler

Specifies where the dictionary is loaded from. If set to Load From Feed Handle the adapter retrieves a Wombat field dictionary at startup from the Wombat source. If set to Load From File the adapter retrieves a Wombat field dictionary from a local file specified in Dictionary File Path

Dictionary Source

Default: WOMBAT

The name of the Wombat source to use for the dictionary for this adapter instance.

Dictionary Transport

Default: Empty

The name of the Wombat messaging middleware, defined in mama.properties, for this adapter to use to access the data dictionary (for example, LBM or tibrv). If this setting is left blank, the same transport is used as specified in the Transport setting in the Adapter Properties tab.

Dictionary File Path

Default: empty

If Load Dictionary From File is selected above, specifies that path of the file where dictionary can be loaded from.

Display Dictionary

Default: disabled

If enabled, the contents of the data dictionary, including the field ID, name, and type of each Wombat field, is logged.

Special Fields Tab

Symbol Field

Default: Empty

The name of incoming schema string field that specifies the symbol for each received message. The symbol corresponds to the symbol/subject for a subscription.

Message Type Field

Default: Empty

The name of incoming schema integer field that contains the Mama Msg type.

Note

Message Type values are defined by Wombat and may be updated independently of this adapter. See the Wombat MAMA constant-values.html Javadoc page section for the MamaMsgType class for the values supported by the version of MAMA used at your site. However, as a convenience, the following table provides a list of such values as documented by Wombat at the time this adapter document was written.

Value	Meaning
0	General update
1	Initial value
2	Trade cancel
3	Trade error
4	Trade correction
5	Closing summary
6	Refresh or recap of some or all fields
7	Deleted symbol
8	Expired security (such as option, future, and so on)
9	Full-record snapshot (no subsequent updates)
10	No subscribers (unexpected subscription)
11	Bad (unknown) symbol
12	Pre-opening summary (includes Wombat-generated morning roll)
13	Quote update
14	Trade update
15	Order update
16	Order book Initial value (complete book)
17	Order book delta
18	Clear order book
19	Order book recap
20	Order book snapshot (complete book)
21	Not permissioned (on feed)
22	Not present now, but might show up later
23	Security status update
24	Corporate action
100	Miscellaneous
101	Stale data

Line Time Field

Default: Empty

The name of the MAMA message field on which the adapter will place a timestamp before it is sent on the MAMA feed.

Cluster Aware Tab

Use the settings in this tab to allow this operator or adapter to start and stop based on conditions that occur at runtime in a cluster with more than one node. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with TIBCO Streaming 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

The Concurrency tab is the same for most output adapters. See Properties: Concurrency Tab for details.

Note

The Concurrency tab's option to Run this component in a parallel region applies to this output adapter in the same way as it does to other StreamBase adapters and operators. That is, running the adapter in its own parallel region provides an additional level of queuing to absorb traffic peaks inside StreamBase Server, provided it is suitable for your application. However, be aware that the Wombat event queue also provides a separate means of message buffering which cannot be eliminated with this adapter implementation.

Deploying an Application with the Wombat Output Adapter

To deploy an application with the Wombat MAMA Output Adapter outside of StreamBase Studio, follow the guidelines in Deploy Applications with epadmin in the Concepts Guide. In particular, edit the HOCON configuration files, and make the mamaversion.jar and any native libraries specific to the messaging middleware accessible to the adapter code at runtime as described in Using External JAR Files and in Making the MAMA Middleware Available.