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.
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,
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.
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.
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.
mamajni.jar(found in your Wombat MAMA's
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:
WOMBAT_PATHenvironment variable to the path of the
mama.propertiesfile on your system.
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.
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.
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.
There is one optional output stream to be configured.
The Dynamic Subscriptions output stream is present if the
Enable Dynamic Subscription Output Portproperty 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.
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
Message Type: the field representing the type of the message. The name of the Message Type field should be defined in the
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
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.
The General tab is the same for most output adapters. See Properties: General Tab for details.
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
The name of the transport, defined in
mama.properties, for this adapter to use. Examples:
tibrv_tport. This is a required setting.
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
Link with a Mama Input Adapteris enabled, this field specifies the name of MAMA Input Adapter to link with.
- Enable Passthrough Cache
Link with a Mama Input Adapteris 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
Enable Passthrough Cacheis 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
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.
- 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
The name of the Wombat source to use for the dictionary for this adapter instance.
- Dictionary Transport
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
If Load Dictionary From File is selected above, specifies that path of the file where dictionary can be loaded from.
- Display Dictionary
If enabled, the contents of the data dictionary, including the field ID, name, and type of each Wombat field, is logged.
- Symbol Field
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
The name of incoming schema integer field that contains the Mama Msg type.
Message Type values are defined by Wombat and may be updated independently of this adapter. See the Wombat MAMA
constant-values.htmlJavadoc page section for the
MamaMsgTypeclass 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
The name of the MAMA message field on which the adapter will place a timestamp before it is sent on the MAMA feed.
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.
The Concurrency tab is the same for most output adapters. See Properties: Concurrency Tab for details.
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.
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
mama 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.