Solace Binding

The Solace binding provides native integration with Solace PubSub+ message brokers for high-performance, low-latency messaging in Talon microservices.

Overview

The Solace binding uses Solace's native APIs (not JMS) to achieve optimal performance with Solace PubSub+ message brokers. It supports both Solace PubSub+ hardware appliances and software brokers.

For configuration details, see Solace Binding Configuration.

JNI vs Java Implementation

The Solace binding includes both a Java-based and JNI-based implementation:

Java Binding (JCSMP)

• Uses Solace's JCSMP (Java Client Software Messaging Protocol) API

• Works on all platforms supported by Talon

• Not zero-garbage but provides good performance

• Fully managed Java implementation

JNI Binding (CCSMP)

• Uses Solace's CCSMP (C Client Software Messaging Protocol) API via JNI

• Linux only

• Supports zero-garbage messaging in steady state

• Maximum performance for latency-sensitive applications

Key Differences

Aspect	Java (JCSMP)	JNI (CCSMP)
Platforms	All	Linux only
Garbage	Non-zero	Zero in steady state
UnhandledMessageEvent topic	Sent topic name	Subscription name
UnhandledMessageEvent sequence	Appliance-wide sequence number	Session-specific sequence number
Pass-through properties	Properties starting with jcsmp	Properties starting with FLOW_ or SESSION_

The binding rationalizes some common properties between the two implementations, but if using properties specific to JCSMP or CCSMP that aren't rationalized, consider whether JNI is enabled.

Solace Topic Format

Solace topics are hierarchical with each level separated by / character. Topics cannot exceed 250 characters in length.

Example topics:

• orders/events/MSFT

• market-data/trades/US/APPL

• alerts/critical/region1

For more details on Solace topics, refer to Solace documentation.

Wildcard Topics

Solace supports wildcard characters for matching multiple topics in channel filters. Wildcards are not applied to sent topics (treated as literals).

The Solace binding preserves these wildcards when nv.sma.cleanchannelfilter=true:

Wildcard	Description	Example
*	Matches 0 or more characters at end of topic level	orders/gin* matches: - orders/gin - orders/ginseng Does not match: - orders - orders/in - orders/gin/foo
>	Matches multiple topic levels. Must be only character in last level.	orders/> matches: - orders/events/MSFT - orders/updates/APPL - orders/cancels/US/IBM Does not match: - orders - order-updates

Topic Routing Example

The following example demonstrates dynamic topic resolution with wildcards:

<buses>
  <bus name="trading" descriptor="solace://solacehost:55555&topic_starts_with_channel=false">
    <channels>
      <channel name="orders">
        <qos>Guaranteed</qos>
        <key>${InitiatingClient::NONE}/${Region::NONE}/${Symbol::NONE}</key>
      </channel>
    </channels>
  </bus>
</buses>

<apps>
  <app name="order-manager">
    <messaging>
      <buses>
        <bus name="trading">
          <channels>
            <channel name="orders">
              <filter>Region="US";Symbol=A*|MSFT</filter>
            </channel>
          </channels>
        </bus>
      </buses>
    </messaging>
  </app>

  <app name="client">
    <messaging>
      <buses>
        <bus name="trading" join="true">
          <channels>
            <channel name="orders" join="false" />
          </channels>
        </bus>
      </buses>
    </messaging>
  </app>
</apps>

The order-manager application uses filter Region="US";Symbol=A*|MSFT, creating these subscriptions:

• */US/A* - Any client, US region, symbols starting with A

• */US/MSFT - Any client, US region, MSFT symbol

Matching messages:

{InitiatingClient: "CLIENTA", Region: "US", Symbol: "MSFT"} → CLIENTA/US/MSFT → matches */US/MSFT
{InitiatingClient: "CLIENTA", Region: "US", Symbol: "APPL"} → CLIENTA/US/APPL → matches */US/A*
{Region: "US", Symbol: "MSFT"} → NONE/US/MSFT → matches */US/MSFT

Non-matching messages:

{InitiatingClient: "CLIENTA", Region: "US", Symbol: "IBM"} → CLIENTA/US/IBM → no match
{Symbol: "IBM"} → NONE/NONE/IBM → no match

Message Metadata Version

When messages are sent through the Solace binding, SMA (Simple Messaging API) metadata is included to help receivers deserialize and dispatch messages.

By default, the Solace binding sends messages using V1 metadata to ensure compatibility with older receivers (pre-Talon 1.8.396). The difference:

• V1: Receivers must introspect serialized message content to determine type

• V2: Message type is encoded in metadata (more efficient)

If all downstream receivers use Talon 1.8.396 or later, set sma_metadata_version=2 as a Solace binding property for more efficient metadata.

Sending and Receiving from External Applications

This section describes integration with non-Talon applications over Solace. This is an uncommon use case - see Sending Messages for Talon-to-Talon messaging.

These examples use ADM-generated messages for convenience, but this is not required. Messages can be encoded in any format (e.g., Protobuf, Xbuf) and encoded/decoded manually.

Sending Messages to Talon

The Solace binding transports encoded messages in a BytesMessage with:

• Message data: Serialized message payload

• x-sma-metadata property: Serialized MessageMetadata

Example using Solace JCSMP client:

// populate a message
OrderEventMessage orderEvent = OrderEventMessage.create();
orderEvent.setOrderId(1);

// serialize the payload to a byte buffer
byte[] serializedPayload = orderEvent.serializeToByteArray();

// prepare message metadata
MessageMetadata metadata = MessageMetadataFactory.getInstance().createMessageMetadata();
metadata.serializeV2(orderEvent.getMessageEncodingType(),
                     orderEvent.getVfid(),
                     orderEvent.getType(),
                     0,  // message sender id
                     0,  // message flow
                     0,  // message sequence number (unsequenced)
                     -1, // channel id (unspecified)
                     XString.create("order-events"));
byte[] serializedMetadata = metadata.serializeToByteArray();

// prepare solace message
com.solacesystems.jcsmp.BytesMessage message = producer.createBytesMessage();
message.setData(serializedPayload);
message.setDeliveryMode(DeliveryMode.DIRECT);
SDTMap props = producer.createMap();
if (serializedMetadata != null) {
  props.putBytes("x-sma-metadata", serializedMetadata);
}
message.setProperties(props);

// send
com.solacesystems.jcsmp.Topic topic = producer.createTopic("order-events");
producer.send(message, topic);

// dispose
orderEvent.dispose();
metadata.dispose();

Receiving Messages from Talon

Example using Solace JCSMP client:

public void onMessage(BytesXMLMessage message) {
  if (!(message instanceof BytesMessage)) {
    handleNonTalonMessage(message);
    return;
  }

  BytesMessage bytesMessage = (BytesMessage) message;

  // extract sma metadata
  final SDTMap props = bytesMessage.getProperties();
  ByteBuffer serializedMetadata = null;
  if (props != null) {
    byte[] metadataBytes = props.getBytes("x-sma-metadata");
    if (metadataBytes != null) {
      serializedMetadata = ByteBuffer.wrap(metadataBytes);
    }
  }

  if (serializedMetadata == null) {
    handleNonTalonMessage(message);
    return;
  }

  // extract metadata fields
  final byte encodingType = MessageMetadata.getMessageEncodingType(serializedMetadata);
  final short vfid = MessageMetadata.getMessageViewFactory(serializedMetadata);
  final short vtype = MessageMetadata.getMessageViewType(serializedMetadata);

  // extract payload
  byte[] payloadBytes = bytesMessage.getData();
  Object payload = payloadBytes;
  if (encodingType == MessageView.ENCODING_TYPE_JSON) {
    payload = new String(payloadBytes);
  }

  // lookup factory (assumes view factories already registered)
  MessageViewFactory factory = viewFactoryRegistry.getMessageViewFactory(vfid);
  if (factory != null) {
    MessageView view = factory.wrap(vtype, encodingType, payload);
    if (view instanceof OrderEventMessage) {
      handleOrderEvent((OrderEventMessage) view);
    }
  }
  else {
    handleNonTalonMessage(message);
  }
}

See Also

• Solace Binding Configuration - Configuration reference

• Messaging Model - Overview of Talon messaging

• Configuring Bus Connections - General bus configuration

• Solace PubSub+ - Solace message broker information