- Index

< Previous |  | Next >

# Wombat MAMA Output Adapter

## 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 StreamBase Server configuration file (usually, `sbd.sbconf`), add a `<java-vm/library>` 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:

1. Create a new StreamBase project, choosing the option to create an EventFlow application.

2. Drag the Wombat MAMA Output icon from the Operators and Adapter drawer in the Palette view to the EventFlow canvas.

3. Click the Wombat adapter's icon to open its Properties view.

4. Define properties for the Wombat adapter and add any output and output streams required, as described in the next sections.

For additional details, including instructions on adding an adapter to a StreamSQL application, see Using Embedded Adapters.

## 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 and their StreamSQL equivalents.

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

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

1. Symbol: the symbol that this message is for. The name of the symbol field should be defined in the `Special Fields` tab.

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

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

These sections list the name of each property setting in two forms. One is the name of the property in the Studio Properties view, while the other is the name of the property used in StreamSQL programs. If no StreamSQL name is listed for a property, then its StreamSQL name is the same as its Studio Properties view name.

### General Tab

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

### Adapter Properties Tab

Middleware

  StreamSQL name: Bridge

  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 enable, 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

  StreamSQL name: LogLevelAsString

  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

  StreamSQL name: LoadDictionaryFrom

  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

  StreamSQL name: DictSource

  Default: WOMBAT

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

Dictionary Transport

  StreamSQL name: DictionaryTransport

  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

  StreamSQL name: SymbolField

  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

  StreamSQL name: MdMsgTypeField

  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

  StreamSQL name: LineTimeField

  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.

### 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 with epadmin in the Concepts Guide. In particular, edit the HOCON configuration files, and make the `mama`version`.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.