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.

Special Character Translation By Solace Middleware Bridge

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_DICT is translated to #MDDD/TEST/DATA_DICT
  • a published OpenMAMA data dictionary topic of _MDDD.TEST.DATA_DICT is 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.

Mapping SOLCLIENT Subcodes to OpenMAMA Transport Topic Events

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.

Mapping OpenMAMA Log Levels to C API Log Levels

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.

Mapping C API Log Levels to OpenMAMA Log Levels

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.