Solace Implementation Considerations
This section provides some Solace-specific implementation details to assist developers when implementing OpenMAMA messaging applications.
Topic Structure
When a client application subscribes to a topic or publishes a message to a topic, the root, source, and symbol string values presented to the Solace Middleware Bridge are used for the topic. (Note that subscriptions do not provide the root variable but may have the root value incorporated in the source.)
OpenMAMA uses the dot (“.”) character to separate topic levels. However, Solace PubSub+ uses the forward slash (“/”) character to separate these three topic levels.
Therefore, to generate topics from the three variables provided by OpenMAMA clients that complies with the topic syntax used by Solace, the Solace Middleware Bridge replaces any “/’”characters in the root, source, and symbol variables in a received subscription with “^” characters. The root, source, and symbol are then joined in a string and a “/” character is used to separate the variables that are not NULL. Topic subscriptions are saved to the event broker with the converted topic syntax.
| Language | Call | |||
|---|---|---|---|---|
Original Character | / | ^ | \ | . |
Solace Middleware Bridge Use | ^ | \ | \\ | / |
Topic Wildcards
When an OpenMAMA wildcard basic subscription create function is used, the Solace Middleware Bridge will treat the “*” and “>” characters as wildcards when they are used for the root, source, symbol variables. The “*” and “>”wildcard characters are only supported as wildcards when used for special wildcard basic subscription create functions.
Handling of Dictionary Prefixes and Suffixes
Subscription requests for OpenMAMA dictionaries add an identifying prefix “_MDDD.” to the topic (for example, “_MDDD.TEST.DATA_DICT”, where TEST is the source).
Publishing OpenMAMA dictionaries add an identifying “.DATA_DICT” suffix to the topic (for example, “TEST.DATA_DICT”, where TEST is the source).
The Solace Middleware Bridge handles these dictionary prefixes and suffixes in the following manner, and changes the OpenMAMA Topic separator of “.” to the Solace topic separator “/”:
Messages published to topics ending with “.DATA_DICT” and not starting with “_MDDD.” are prefixed with “#MDDD/”.
Examples:
- a published OpenMAMA data dictionary topic of
TEST.DATA_DICTis translated to#MDDD/TEST/DATA_DICT - a published OpenMAMA data dictionary topic of
_MDDD.TEST.DATA_DICTis translated to_MDDD/TEST/DATA_DICT
When PubSub+ Cache is enabled, Dictionary snapshot subscriptions (MAMA_SUBSC_DDICT_SNAPSHOT) are redirected to PubSub+ Cache Instances, and have their topic changed from _MDDD/TEST/DATA_DICT to #MDDD/TEST/DATA_DICT
Example:
an OpenMAMA dictionary snapshot topic subscription of _MDDD.TEST.DATA_DICT is translated a Solace topic of #MDDD/TEST/DATA_DICT
Solace Special Prefixes
Solace PubSub+ uses some special topics to facilitate specific message exchange patterns. These special topics always begin with the “#” character. For example, a Solace API can create a unique topic subscription for a client that begins with “#P2P”, which enables messages to be sent directly to the client in request/reply scenarios. The Solace Middleware Bridge does not forcibly restrict OpenMAMA topic subscriptions that begin with “#”, however, it is recommended that you avoid using them.
Payload Field Types
The Solace Payload Bridge supports all payload types supported by OpenMAMA version 2.3.1. In addition, the Solace Payload Bridge also provides support for Boolean vector and character vector payload types.
Currently these payload types are only supported by the Solace Payload Bridge when using OpenMAMA version 2.3.1. However, they have been accepted by the OpenMAMA project, and it is anticipated they will be supported in OpenMAMA version 2.3.3.
- To set a Boolean vector payload, call
mamaMsg_addVectorBool(...). - To set a character vector payload, call
mamaMsg_addVectorChar(...)
Async Publish Failure Notifications
For a Solace Middleware Bridge, transport topic events are used to notify an application of an async publisher failure.
An OpenMAMA publisher transport topic event is raised when a Solace session receives the SOLCLIENT_SESSION_EVENT_REJECTED_MSG_ERROR session event in the session event callback. The last error subcode is checked and mapped to an OpenMAMA transport topic event in accordance with the following table.
| SOLCLIENT Subcode | OpenMAMA Transport Topic Event | |||
|---|---|---|---|---|
|
SOLCLIENT_SUBCODE_PUBLISH_ACL_DENIED |
MAMA_TRANSPORT_TOPIC_PUBLISH_ERROR_NOT_ENTITLED |
|||
|
SOLCLIENT_SUBCODE_TOPIC_MISSING |
MAMA_TRANSPORT_TOPIC_PUBLISH_ERROR_BAD_SYMBOL |
|||
|
SOLCLIENT_SUBCODE_TOPIC_TOO_LARGE |
MAMA_TRANSPORT_TOPIC_PUBLISH_ERROR_BAD_SYMBOL |
|||
|
SOLCLIENT_SUBCODE_INVALID_TOPIC_SYNTAX |
MAMA_TRANSPORT_TOPIC_PUBLISH_ERROR_BAD_SYMBOL |
|||
|
SOLCLIENT_SUBCODE_TIMEOUT |
MAMA_TRANSPORT_TOPIC_PUBLISH_ERROR |
|||
|
All other subcodes |
MAMA_TRANSPORT_TOPIC_PUBLISH_ERROR |
|||
Logging
The following table shows how generated OpenMAMA logs map to C API logs.
| OpenMAMA-Generated Log Level | Corresponds with C API Log Level... | |||
|---|---|---|---|---|
|
MAMA_LOG_LEVEL_SEVERE |
SOLCLIENT_LOG_EMERGENCY SOLCLIENT_LOG_CRITICAL |
|||
|
MAMA_LOG_LEVEL_ERROR |
SOLCLIENT_LOG_ERROR |
|||
|
MAMA_LOG_LEVEL_WARN |
SOLCLIENT_LOG_WARNING SOLCLIENT_LOG_NOTICE |
|||
|
MAMA_LOG_LEVEL_NORMAL |
SOLCLIENT_LOG_NOTICE |
|||
|
MAMA_LOG_LEVEL_FINE |
SOLCLIENT_LOG_INFO |
|||
|
MAMA_LOG_LEVEL_FINER |
SOLCLIENT_LOG_INFO |
|||
|
MAMA_LOG_LEVEL_FINEST |
SOLCLIENT_LOG_DEBUG |
|||
|
MAMA_LOG_LEVEL_OFF |
SOLCLIENT_LOG_EMERGENCY This C API log level, as the most stringent log level, is the best match because very few, if any, logs are generated. |
|||
The following table shows how generated C API logs map to OpenMAMA logs.
| C API-Generated Log Level | Corresponds with Mama Log Level... | |||
|---|---|---|---|---|
SOLCLIENT_LOG_EMERGENCY | MAMA_LOG_LEVEL_SEVERE | |||
SOLCLIENT_LOG_CRITICAL | MAMA_LOG_LEVEL_SEVERE | |||
SOLCLIENT_LOG_ERROR | MAMA_LOG_LEVEL_ERROR | |||
SOLCLIENT_LOG_WARNING | MAMA_LOG_LEVEL_WARN | |||
SOLCLIENT_LOG_NOTICE | MAMA_LOG_LEVEL_WARN | |||
SOLCLIENT_LOG_INFO | MAMA_LOG_LEVEL_FINE | |||
SOLCLIENT_LOG_DEBUG | MAMA_LOG_LEVEL_FINEST | |||
When last value caching is used, the logging level for each SolOpenMAMA Plug-In (set through their mama.properties files) must match the logging level set for its PubSub+ Cache Instance (set through the PubSub+ Cache Instance configuration file). By default, the logging levels set for the provided SolOpenMAMA Plug-In matches that set for the sample PubSub+ Cache Instance configuration file. However, if you want to change the logging level used for last-value caching, you must manually change the OpenMAMA log level for the mama.properties file and change the log level in the PubSub+ Cache Instance configuration file to an equivalent C API log level.
Datetime
The format of the datetime string returned by SolOpenMAMA depends on the platform and date range.
Win32, Win64 and Linux_x86_64 Platforms
For dates before January 1, 1601, SolOpenMAMA returns a datetime string with its value in seconds.
For dates after January 1, 1601, SolOpenMAMA returns a datetime string with its value in standard OpenMAMA datetime string format.
Linux_i386 Platforms
For dates between December 13, 1901 and January 18, 2038, SolOpenMAMA returns a datetime string with its value in standard OpenMAMA datetime string format.
For dates before December 13, 1901 and after January 18, 2038, SolOpenMAMA returns a datetime string with its value in seconds.