Configuring Solace OpenMAMA Bridges

The Solace Middleware and Payload Bridges are required to establish the transports used to connect OpenMAMA clients and Solace PubSub+, and to allow messaging data to pass between them.

For an OpenMAMA client application to publish messages to or receive messages from Solace PubSub+, it must establish one or more transports through a Solace Middleware Bridge to an event broker.

To select the Solace Middleware Bridge, an OpenMAMA application must use the bridge identifier of solace (for example, when calling mama_loadBridge()).

The OpenMAMA API uses the properties provided in a mama.properties configuration file to establish a middleware bridge and to establish the transports on that bridge.

Configuration File Conventions

The mama.properties file uses a hierarchical naming convention (from left to right) with “.” as the separator between each element. The terminating element is “=” followed by the property value. The Solace Middleware Bridge and Solace Payload Bridge transport properties begin with mama.solace.transport, and payload-related properties begin with mama.solace.payload.

The following entries show Solace-specific transport properties for two separate transports, mamapublisher7 and mamasubscriber3:

mama.solace.transport.mamapublisher7.session_vpn_name=default
mama.solace.transport.mamapublisher7.session_reconnect_retries=3
mama.solace.transport.mamasubscriber3.session_vpn_name=default
mama.solace.transport.mamasubscriber3.session_reconnect_retries=3

A sample_mama.properties file for the Solace Middleware Bridge is provided in the solopenmama_bridge directory where you extracted the SolOpenMAMA Bridge archive file. This sample file shows some of the Solace‑specific OpenMAMA properties.

By default, the OpenMAMA API calls mama_open() to load the mama.properties file used for the middleware bridge from the location specified by the WOMBAT_PATH environment variable. Alternatively, the OpenMAMA API can use open functions to use another mama.properties file located in a specific directory instead of the mama.properties file provided by the WOMBAT_PATH environment variable.

Solace Bridge Configuration Properties

In addition to standard middleware bridge configuration properties, for a Solace Middleware Bridge the following Solace‑specific transport properties must be configured:

These Solace-specific transport properties map to the Solace C API initialize function, and context and session properties, which are required to establish client connections to an event broker.

When the PubSub+ Cache last-value caching facility is to be used, Solace C API cache session properties must also be configured.

The Global and Context settings apply to all transports, but the other properties must be set for each transport to be established for the bridge. To create multiple transports for the Middleware Bridge, you must provide a unique transport name in the mama.properties file for each transport.

If transport properties are not explicitly set in the mama.properties file, they are set to the default values for the corresponding C API session property. Although the defaults can be used in many cases, some session properties require explicit input for the client application to establish a transport connection to the event broker. Refer to Per-Transport Properties.

Global Properties

The mama.solace.transport.global_* properties are used to initialize the underlying Solace C API. The C API equivalent for these properties is solClient_initialize(...).

Although the logging levels to be used for the transports to the event broker can be set through these mama.solace.transport.global_* properties, it is recommended that you set the transport logging levels through standard OpenMAMA methods. The Solace Middleware Bridge will then automatically make the appropriate adjustments. For more information, refer to Logging.

Context Properties

The mama.solace.transport.context_* properties are used to configure the context properties for all transports to an event broker. A context acts as a container in which one or more client Sessions are configured and Session‑related events are handled. It encapsulates threads that drive network I/O and message delivery notification for the Sessions associated with that Context.

The C API equivalents for these properties are:

  • CONTEXT_TIME_RES_MS
  • CONTEXT_CREATE_THREAD

    The Solace Middleware Bridge presets the mama.solace.transport.context_create_thread to a value 1 so that an internal context thread is automatically created. This value cannot be overridden.

Properties that Affect All Transports

The following transport properties are Solace-specific properties that set subscribe and publish preferences for the Solace Middleware Bridge. These properties affect all transports rather than a particular given transport.

  • mama.solace.transport.queue_max_size—This property specifies the maximum number of messages permitted for a middleware queue used for a transport.

    Default: 50000

    Valid range: 1 to 2147483647

    When the defined value is exceeded, the Solace Middleware Bridge will either suspend receiving messages (if asynchronous behavior is used for subscribe/unsubscribe operations) or discard any further received messages (if synchronous behavior is used for subscribe/unsubscribe operations).

  • mama.solace.transport.subscribe_async—This property specifies whether the Solace Middleware uses synchronous or asynchronous behavior for subscribe/unsubscribe operations.

    Default: 1

    To use asynchronous behavior so that a subscribe/unsubscribe call does not wait for a confirmation to be received from the event broker, set the value to 1.

    To use synchronous behavior so that a topic subscribe/unsubscribe call blocks until either a confirmation is received from the event broker or a timeout is reached, set the value to 0.

  • mama.solace.transport.send_publisher_info—This property sets whether the Solace Middleware Bridge will automatically include additional publisher information with every published message.

    Default: 1

    To include publisher information, set the value to 1. To not include the information, set the value to 0.

  • mama.solace.transport.defaultqueue.timeout—This property specifies the queue destroy timeout for closing the default event queue while closing the Solace Middleware Bridge.

    Default: 2000

    Valid Range: 1 to 2147483647

    If the mama.solace.transport.defaultqueue.timeout is omitted, then the value of the mama.defaultqueue.timeout property is used; if both are omitted, then the default value is used. Should either property value be out of range, the default value is used and a warning log is produced.

Per-Transport Properties

The mama.solace.transport.<transport_name>.session_* properties are used to define single transports to the event broker (that is, a single client connection). The Solace Message Format (SMF) is used to facilitate the communication between a client established by a Session and an event broker, and this SMF communication is encapsulated through a single TCP connection.

When the Solace Middleware Bridge specifies more than one transport, a separate set of Session properties are required for each transport.

Session properties that are not explicitly supplied for a transport are set to default values. Although the defaults can be used in many cases, some client and event broker parameters require specific input to establish a connection to the event broker.

The Solace Middleware Bridge hard codes the following Session properties to an enabled state. Theses properties cannot be overridden even if you attempt to explicitly overwrite these properties in the mama.properties file:

  • session_reapply_subscriptions—Topic subscriptions are remembered and reapplied after a Session reconnect occurs.
  • session_topic_dispatch—Messages that are published to specific topics can be handled by separate receive callbacks.
  • session_connect_blocking— After a client connection is established, a blocking operation mode is used for send, subscribe, and unsubscribe operations.

The following parameters should be explicitly set for each transport:

For information on the full range of session properties, see the session properties listed in the “Defines” section of the PubSub+ Messaging API C reference documentation.

By default, Sessions are unsecured—in a connected Session, the SMF data sent between a client and an event broker is transmitted as plain text. However, it is also possible to establish a secure Session that uses Transport Layer Security (TLS)/ Secure Sockets Layer (SSL) protocols so that the SMF data is encrypted. For information on how to configure specific TLS/SSL Session properties and establish a secure Session, refer to Creating Secure Sessions.

Allow Recover Gaps

The Allow Recover Gaps property (mama.solace.transport.<transport_name>.allow_recover_gaps) specifies whether the Solace Middleware Bridge should override the subscription setting for Recover Gaps.

To maintain the subscription setting, set a value of 1. To override the subscription setting and not recover subscription gaps, set a value of 0. The default value is 0.

Authentication Scheme

When a host event broker initially accepts a connection from a client, that connection is in an unauthenticated state, and the event broker cannot process any requests from the client until the connection is authenticated.

The credentials that a client will use to authenticate its connection to the event broker are determined by the authentication scheme that is configured for the Session. The authentication scheme can be one of the following:

  • Basic Authentication

    • The AUTHENTICATION_SCHEME_BASIC session property sets a Basic authentication scheme. Basic authentication allows a client to authenticate with an event broker using a valid client username and password. This is the default authentication scheme.

  • Client Certificate

    • The AUTHENTICATION_SCHEME_CLIENT_CERTIFICATE session property sets a client certificate authentication scheme. Client certificate authentication allows a client to prove its identity to the event broker through an X509v3 client certificate. This authentication scheme also requires the client to use a secure connection (refer to Creating Secure Sessions).

  • Kerberos

    • The AUTHENTICATION_SCHEME_GSS_KRB session property sets a Kerberos authentication scheme. Kerberos authentication authenticates a connecting client using a ticket that the client obtains through an approved Ticket Granting Service (TGS).

Each of these client authentication schemes require explicit input for related session properties to successfully authenticate a client. For more information, refer to Client Authentication Properties.

Host

The SESSION_HOST property is required to indicate the host event broker to connect or reconnect the Session to. A host entry is composed of the following:

[Protocol:]Host[:Port]

Where:

Protocol is the protocol used for the transport channel. The valid values are:

  • tcp: or tcp://—Use a TCP channel for communications between the application and its peers. If no protocol is set, TCP is used by default.
  • tcps: or tcps://—Use a TLS/SSL channel over TCP for secure communications between the application and its peers.
  • ws: or ws://—Use a WebSockets transport for communication between the application and its peers.
  • wss: or wss://—Use a TLS/SSL channel over WebSockets for secure communication between the application and its peers.
  • http: or http://—Use Hypertext Transfer Protocol (HTTP) for communication between the application and its peers.
  • https: or https://—Use a TLS/SSL channel over HTTP for secure communication between the application and its peers.

Host is one or more IP addresses or hostnames of event brokers to connect to. Up to four potential hosts to connect or reconnect to can be entered in a comma‑separated list. Listing more than one host allows a client to attempt to connect or reconnect to alternate hosts should the first event broker be unavailable. Connect or reconnect attempts are made to the hosts in the order in which they are presented in the list. The listed host event brokers may be in separate geographic locations.

  • When event brokers are operating in high-availability (HA) redundant pairs, do not list both event brokers in the pair as hosts. The redundant pair use the same IP address for the connection, so they appear as one event broker to the messaging API.
  • The connect and reconnect behavior of a client is controlled by the Session properties used for its connection with the event broker. For more information, refer to Connect Retries Per Host.

Port is the port number to use to establish the connection. An explicit value is only required when the client needs to use a port other than the automatically‑assigned default port number. The default port number for TCP is 55555 when channel compression is not in use, or 55003 when compression is in use. The default port for TLS/SSL is 55443 (note that compression is not available when TLS/SSL is used).

The following examples show how to specify transport channel types. Unless it is otherwise specified, the default port 55555 is used.

  • 192.168.160.28—connect to IP address 192.168.160.28 over TCP.
  • dev212—connect to hostname dev212 over TCP.
  • dev212.solacesystems.com—connect to hostname dev212.
    solacesystems.com     over TCP.
  • tcp:192.168.160.28—connect to IP address 192.168.160.28 over TCP.
  • tcps:192.168.160.28—connect to IP address 192.168.160.28 and port 55443 with TLS/SSL over TCP.
  • tcp:192.168.160.28:65535—connect to IP address 192.168.160.28 and port 65535 over TCP.
  • In a Windows environment, a fully qualified domain name (FQDN) should be used for the host parameter, and it must match the FQDN that the event broker uses for the Kerberos Service Principal Name (SPN).
  • When a SPN is generated for the client, the following format is used: service_name/<customer-provided_host>@REALM. The service name portion is configured through the KRB service name session property (by default, it is solace), and the realm portion is determined by the configuration files used by the KRB library. An example of a resulting service principle name is solace/dev212@SIMPLESPNEXAMPLE.COM.
  • When using multiple hosts, the host used for the current connection generates the SPN.

Local Host

The SESSION_BIND_IP property indicates the hostname or IP address of the physical host on which the application is running. This Session property may be required when the application is running on a multi‑homed host.

On a multi-homed host, a local hostname or IP address helps ensure that the API uses the correct network interface for communication with the event broker.

Message VPN

The SESSION_VPN_NAME property indicates the name of the Message VPN to assign the client to when the Session connects to an event broker.

Message VPNs are created on the event broker to provide isolation between groups of clients connecting to Solace PubSub+. A client’s username is scoped by the Message VPN in which it was provisioned.

If a specific Message VPN is not provided, the Message VPN named default is used. The default Message VPN is always present on an event broker. Although a network administrator can change the configuration settings for default, it cannot be deleted.

Send Subscription Requests

If PubSub+ Cache is enabled for one or more transports (that is, mama.solace.transport.<transport_name>.use_SolCache=1), the Send Subscription Requests property (mama.solace.transport.<transport_name>.send_subreq) specifies whether the Solace Middleware Bridge should also send a subscription request message to an interactive publisher when a cache request is made.

When a client makes a cache request, a PubSub+ Cache Instance returns an initial value in response, so another subscription request to a publisher for an initial value is typically unnecessary. However, the request to a publisher may be of benefit if some special behavior is associated with receiving the subscription request. For example, receiving a subscription request may be used to prompt an interactive publisher to start publishing real-time market data for a symbol when an initial subscriber shows interest in the symbol.

To send a subscription request message to a publisher after each cache request is made, set the property value to 1. To not send a subscription request message to a publisher after a cache request, set the property value to 0. The default value is 0.

Client Authentication Properties

Each of the three possible authentication schemes (Basic, Client Certificate, or Kerberos) that can be chosen for client authentication must be provided with additional configuration parameters specified in session properties:

Basic Authentication Properties

Basic authentication is the default client authentication scheme. When this scheme is used, the client must provide the following properties for the event broker to authenticate the client (these properties are not encrypted):

Username

A username is required for a Session to authenticate any clients connecting with the event broker over that Session. A username must be provided in the SESSION_USERNAME property for each transport, and it must match with a client username account provisioned on the event broker.

When a Session connects to an event broker, clients are created and deleted dynamically as they connect and disconnect from the event broker on that Session. Therefore, it is possible that multiple clients can use a single username.

The username property is the same as the client-username property that can be shown through the Solace CLI or SolAdmin.

Password

When basic authentication is enabled on the event broker, a valid username/password pair must be provided in the SESSION_PASSWORD property to connect a Session to an event broker. The default is no password.

Client Certificate Authentication Properties

A client certificate authentication scheme allows a client to prove its identity to the event broker using a valid X509v3 client certificate obtained from a Certification Authority (CA). When the client certificate authentication scheme is used for the Session, the client must specify a client certificate and a private key and password through the following session properties:

  • SESSION_SSL_CLIENT_CERTIFICATE_FILE—the client certificate file name
  • SESSION_SSL_CLIENT_PRIVATE_KEY_FILE—the private key file name
  • SESSION_SSL_CLIENT_PRIVATE_KEY_FILE_PASSWORD—the password that decrypts the private key

If a specified key store cannot be loaded (for example, a private key file or client certificate file is not readable) the connection is not attempted and an error is reported to the application.

Client certificate authentication depends on the TLS/SSL facility on the event broker, so it can only be used for secure Sessions (refer to Creating Secure Sessions).

Required Event Broker Configurations

For a client to use a client certificate authentication scheme, the host event broker must be properly configured for TLS/SSL connections, and Client Certificate Authentication must be enabled for the particular Message VPN that the client is connecting to. The Message VPN that the client connects to can be configured to use the common name in the client certificate’s subject as the client username or to use a client username (refer to Username that the client provides. (By default, the event broker assigns the client username based on the common name in the client certificate.)

Kerberos Authentication Properties

Kerberos authentication can be used to authenticate clients for either secured or unsecured Sessions to the event broker. Unlike client certificate authentication, Kerberos authentication does not depend on the TLS/SSL facility on the event broker.

To use the Kerberos authentication scheme, the following configurations must be made:

  • Required versions and libraries for the:
    • C API on Linux and SunOS systems—libraries that implement GSSAPI Version 2 must be used
    • C APIs on Windows systems—the Security Support Provided Interface (SSPI) that is distributed with Windows is used
  • Set Kerberos as the authentication scheme to use for the session (refer to Authentication Scheme).

Required Event Broker Configurations

For a client to use a Kerberos authentication scheme, a Kerberos key tab file must be configured and Kerberos authentication must be configured on the host event broker and enabled for any Message VPNs that a client will connect to. For more information, refer to Management & Shell Users.

Creating Secure Sessions

Clients can optionally create secure Sessions that require trusted server certificates to establish a TLS/SSL-encrypted client connection to an event broker. When a secure Session is created, SMF information is transported using TLS/SSL over TCP instead of plain text over TCP.

To create a secure Session, a number of TLS/SSL-specific Session properties must be specified as discussed below. In addition, the event broker that the secure Session will connect to must be properly configured, and the appropriate server certificate must be in place. For information on configuring an event broker to allow for secure connections, refer to TLS / SSL Service Configuration.

TLS/SSL-Specific Properties for Secure Sessions

To create a secure Session, the following Session properties must be properly configured:

  • Host—Each host entry for a TLS/SSL connection requires an appropriate TLS/SSL protocol, and a specific TLS/SSL port number can optionally be specified. If no port number is specified, the default port of 55443 is used. For more information on configuring hosts, refer to Host.
  • SSL Excluded Protocols—A comma‑separated list of encryption protocols that may not be used for secure connections. Possible values are:
    • SSL v3.0 (SSLv3)
    • TLS v1.0 (TLSv1)
    • TLS v1.1 (TLSv1.1)
    • TLS v1.2 (TLSv1.2)

    The default list is empty, meaning that any encryption protocol can be used (no protocols are excluded).

  • SSL Validate Certificate (SESSION_SSL_VALIDATE_CERTIFICATE)—Indicates whether the API should validate server certificates with the trusted certificates in the trust store. The trust store is a directory on a server that contains the trusted certificates. The default value for this property is true.
  • SSL Validate Certificate Date (SESSION_SSL_VALIDATE_CERTIFICATE_DATE)—Indicates whether the Session connection should fail when an expired certificate or a certificate not yet in use is received. The default is true.
  • SSL Cipher Suites (SESSION_SSL_CIPHER_SUITES)—A comma-separated list of cipher suites, listed in order of importance, to use to negotiate with the event broker.

    A cipher suite is a combination of cryptographic parameters that define the security algorithms and key sizes used for authentication, key agreement, encryption, and integrity protection. For a listing of the supported cipher suites in order of preference, see the PubSub+ Messaging API C reference documentation. By default, no cipher suites are listed, which indicates that all supported ciphers should be considered.

  • SSL Trusted Common Name List (SESSION_SSL_TRUSTED_COMMON_NAME_LIST)—A list of up to 16 comma-separated common names trusted by the client. The list should include the common names of all of the event brokers the client can connect to.

    By default, no common names are provided; this means that there is no common name verification and all common names are acceptable. Also, no common name validation is performed if SSL Validate Certificate is set to false.

  • SSL Trusted Store Directory (SESSION_SSL_TRUST_STORE_DIR)—The network directory where the trusted certificates are stored.

Connect/Reconnect Properties

The following Session properties are used to configure Session connect and reconnect behavior:

For an example of how these Session properties work in relation to one another when a list of potential hosts are provided for client connection attempts, refer to Connect Retry Example. (For more information on listing multiple hosts, refer to Host.)

  • To find the default value for the properties listed in this section, see the PubSub+ Messaging API C reference documentation.
  • When using HA redundant event broker pairs, a failover from one event broker to its mate will typically occur in under 30 seconds, however, applications should attempt to reconnect for at least five minutes. To allow for a reconnect duration of five minutes for HA redundant event brokers, set the following session property values:
    • connect retries—1
    • reconnect retries—5
    • reconnect retry wait—3000 ms
    • connect retries per host—20
Connection Time-Out

The connection time-out property (SESSION_CONNECT_TIMEOUT_MS) sets the maximum amount of time (in milliseconds) that is allowed for a Session to establish an initial connection to an event broker.

When a host list is used, the amount of time set for the Connection Time-Out property is applied to each connection attempt to a host. So, for example, if there are four host entries, a worst-case scenario would be that an application would have to wait for the connection time-out to occur for each host entry, times the number of connect attempts, before receiving a notice of an established connection or a connection failure. This wait time is also extended by the Reconnect Retry Wait time that occurs after each unsuccessful attempt to connect to a host.

A connection attempt can terminate quicker if a failure is detected by the socket layer.

Connect Retries

The connect retries property (SESSION_CONNECT_RETRIES) sets the number of times to retry to establish an initial connection for a Session to a host event broker.

The valid range for the Connect Retries property is –1 or greater. A value of –1 means retry forever; a value of 0 means no automatic connection retries (that is, try once and give up).

When a list of hosts is used, the API attempts to establish a connection to the first listed event broker. If that attempt fails, the API waits for the amount of time set for the Reconnect Retry Wait property before attempting another connection to either the same host. (The value of Connect Retries Per Host property sets the number times to attempt to connect to one host before moving to the next listed host.) The API attempts to connect to the host entries sequentially in the order they are listed.

If the Connect Retries property is greater than 0, the API can retry a connection attempt at the beginning of the host list if no connection could be established to any of the entries in the list. Each time the API works through the host list without establishing a connection is considered a connect retry. For example, if a Connect Retries value of 2 is used, the API could possibly work through all of the listed hosts without connecting to them three times: one time through for the initial connect attempt, and then two times through for each connect retry. Each connect retry begins with the first host listed.

Reconnect Retries

The Reconnect Retries property (SESSION_RECONNECT_RETRIES) sets the number of times to try to reconnect to a host after a connected Session goes down. If a host list is used, this property sets the number of times the API will traverse the host list in an attempt to reconnect to one of the hosts in the list.

The valid range is greater than or equal to –1. A value of –1 means retry forever; a value of 0 means no automatic connection retries (that is, try once and give up).

When a host list is used, if the API cannot connect to the first event broker on the list (that is, the preferred event broker), it attempts to connect to the next listed event broker, and so on. The API attempts to connect to each host for the number of times set for the Connect Retries Per Host property before attempting to connect to the next host.

After each unsuccessful connection attempt, the API waits for the amount of time set for the Reconnect Retry Wait property to expire before attempting to connect to the same host, the next listed host, or, after all of the listed hosts have been attempted, to the first host on the list again.

Multiple reconnects should be specified when the Session is working with a host for which event broker redundancy has been enabled (that is, the IP address listed as a host is used by a pair of redundant event brokers). Disabling reconnect retries could affect activity switches that might occur when active/active redundancy is used and could cause service disruptions. For example, in a failover scenario, if no reconnect retries are enabled, a connection attempt cannot be made to the redundant event broker.

Reconnect Retry Wait

The Reconnect Retry Wait property (SESSION_RECONNECT_RETRY_WAIT_MS) sets the amount of time (in milliseconds) to wait after an unsuccessful attempt to reconnect to the same host that the client was connected to. After this time expires, another reconnect attempt can be made. Valid values are 1 or greater.

If the API works through all of the entries in the host list without establishing a connection, and a Connect Retry is permitted because the Connect Retry property is greater than 0, the API waits for the amount of time set for the Reconnect Retry Wait property before retrying to connect to the first host in the host list.

Connect Retries Per Host

When using a host list, the Reconnect Retries Per Host (SESSION_CONNECT_RETRIES_PER_HOST) property sets how many times to try to connect or reconnect the Session to one host before moving to the next host in the list.

A value of 0 means make a single connection or reconnection attempt (that is, 0 retries). A value of –1 means attempt an infinite number of connect or reconnect retries (in this case, the API only tries to connect or reconnect to first host listed).

If a connect or reconnect attempt to host is not successful, the API must wait for the amount of time set for the Reconnect Retry Wait property before making another connect or reconnect attempt.

Connect Retry Example

The following figure shows how the Connect Try and Retry properties can affect Session connection attempt behavior when a host list is used. For demonstration purposes, this example shows the worst case scenario where all potential connection attempts are unsuccessful.

Connection Attempt Behavior When Using a Host List

For this example, the Connect Retry Per Host property of 1 means that a connection attempt is tried twice for each of the four listed host entries. If the first connection attempt is not successful, the Reconnect Retry Wait value of 20 milliseconds must pass, then an attempt to “reconnect” to the same host can occur. If this attempt is not successful, an attempt to connect to the next host entry can occur, and so on.

Each time the API works through all of the entries in the host list without establishing a connection is considered a Connect Try or Retry. So if a connection to one of the listed hosts is not established during the initial Connect Try, a Connect Retry value of 2 means that API can work through the host list two more times (again, each listed host can be attempted up to two times for each Connect Retry). Each Connect Retry begins with the first host and works through the entries in the order in which they are listed.

Therefore, in the worst case scenario, the API could possibly work through the host list three times without making a connection to a host (one time through for the initial Connect Try, and then two times through for the Connect Retries), and because the Connect Retry Per Host value of 2 causes each host to be attempted twice, a maximum of 24 connection attempts can be made.

PubSub+ Cache Properties

Solace properties are required when the PubSub+ Cache last‑value caching facility is to be used. Cache properties are set on a per-transport basis. Therefore, to enable OpenMAMA clients to use the optional PubSub+ Cache facility, set a value of 1 for the mama.solace.transport.<transport_name>.use_solcache property.

When PubSub+ Cache is enabled for the given transport, the mama.solace.transport.<transport_name>.cachesession_* properties are used to configure cache sessions established on that transport. A cache session contains static cache properties and cache state information. It also allows multiple outstanding cache requests and synchronizes those requests.

The available cache session properties are listed below. For more detailed information on these properties, refer to the “Defines” section of the PubSub+ Messaging API C reference.

Cache Session Properties
Parameter Description

cachesession_cache_name

The identifying name of the Distributed Cache, Cache Cluster, or PubSub+ Cache Instance to send the cache requests to.

Specifying a Distributed Cache is the preferred method because specifying a PubSub+ Cache Instance bypasses redundancy and load balancing of cache requests.

cachesession_max_age

The maximum age (in seconds) of the messages to retrieve. Messages that have been cached for more than this amount of time are not retrieved.

A value of 0 returns all possible messages for the topic, as defined by cachesession_max_msgs.

cachesession_max_msgs

The maximum number of cached messages to retrieve for any one topic. If more messages are cached for a topic than the maximum value, the newest messages are returned.

A value of 0 retrieves all messages newer than cachesession_max_age.

cachesession_reply_to

The reply-to topic for the cache request.

For most situations, it is recommended that this property be left unspecified so that the API uses the session P2P Reply To Topic. For more information, refer to session_p2p_in_use in the PubSub+ Messaging API C reference.

cachesession_rr_timeout_ms

The amount of time (in milliseconds) to wait for a response to the cache request. This is a per‑request timeout where each request sent by the application could result in multiple underlying requests.

Solace Payload Configuration Properties

The mama.solace.payload.version property is used to indicate at run-time which Solace-specific payload format to use for encoding and decoding messages. It can have a value of 1 (payload version 1 format) or 2 (use payload version 2 format). A value of 2 is the default, and if no value is explicitly set, a payload version 2 is used.

The mama.solace.payload.version property was introduced in Solace bridges for SolOpenMAMA 6.2.1.

Solace bridges for OpenMAMA 6.2.1+ that communicate with one another must use the same value for the mama.solace.payload.version property because payload format conversion between bridges is not supported. Interaction between different payload versions is not supported and will result in unwanted behavior.

As of the SolOpenMAMA 7.5.0 release, the PubSub+ Cache instance handles messages as follows:

  • Non-book messages—The PubSub+ Cache instance can handle both payload version 1 and 2 messages. Update messages are only cached if their payload version matches that of the initial message received for the topic. You can replace an initial message with a new initial of a different payload version, but an update message with a different payload version than the initial will not be cached.
  • Book messages—The PubSub+ Cache instance requires book messages to be published using payload version 2. Book messages using payload version 1 will be dropped by the PubSub+ Cache instance.

Clients using SolOpenMAMA versions prior to 7.5.0 can continue operating, but payload version 1 book messages will be discarded by PubSub+ Cache.

Payload Version 1

The payload version 1 format is backwards compatible with Solace bridges for OpenMAMA 2.4.1 and 6.1.0 for dates in the range January 1, 1970 to February 7, 2106.

Additionally, this format supports dates from March 881 to October 3058, but only between Solace bridges for OpenMAMA 6.2.1 configured to run payload format version 1.

When a date outside of the range March 881 to October 3058 is published from a Solace bridge for OpenMAMA 6.2.1 that uses payload format version 1, the publishing client will get a run-time error because those dates are not supported.

Payload Version 1 is not fully compliant with OpenMAMA 6.2.1+ because wireline is not fully compatible, and, therefore, is not recommended for use with OpenMAMA 6.2.1+. If it is used, and a date between March 881 to January 1970 or February 2106 to October 3058 is sent from a Solace bridge for OpenMAMA 6.2.1+ to a Solace bridge for OpenMAMA 2.4.1 or 6.1.0, the date will not cause any run-time issues, but will be received as invalid; that is, data integrity will be broken.

Payload Version 2

The payload version 2 format supports the Extended Date Time Format introduced in OpenMAMA 6.2.1.

Payload version 2 is not backward compatible with Solace bridges prior to 6.2.1.

Interoperability between Solace bridges for OpenMAMA 6.2.1+ running different payload format versions is not supported.

The table below summarizes how payload format version affects different versions of Solace bridges and their interoperability.

Payload Version Formats Specifications and Interoperability

OpenMAMA Date Property Payload Version 1 for OpenMAMA 2.4.1 & 6.1.0 Payload Version 1 for OpenMAMA 6.2.1 Payload Version 2
Seconds 0 to (232-1) seconds
(corresponds to January 1,1970 to February 7, 2106)		 -(236/2) to (236/2 -1) seconds
(corresponds to March 7, 881 to October 26, 3058; refer to Datetime for details on implementation limitations)		 -(264/2) to (264/2-1) seconds
(as per OpenMAMA API; refer to Datetime for details on implementation limitations)
Fraction of the second 0 to 1,048,576 microseconds(with microsecond precision) 0 to 999,999 microseconds(with microsecond precision, nanoseconds are rounded) 0 to (232-1) nanoseconds(as per OpenMAMA API;with nanoseconds precision)
Precision 0 to 15 0 to 15 0 to 255
Hints 0 to 15 0 to 15 0 to 255
Wire Format Backwards compatible Partially backwards compatible Non-backwards compatible