Sending Guaranteed Messages in the PubSub+ JCSMP API

When sending a Guaranteed message, client applications using the PubSub+ JCSMP API must consider the following factors:

For examples of how to publish and receive Guaranteed messages, see the simpleFlowToQueue sample in the Solace Developer Hub.

Streaming and Non-Streaming Sends in the PubSub+ JCSMP API

The PubSub+ JCSMP API only supports a blocking network I/O model. However, when publishing messages, the JCSMP API can use a publish event handler that operates in either a streaming or a non-streaming mode. The mode used by the publish event handler is set when an XMLmessageProducer is acquired.

To publish messages using the PubSub+ JCSMP API, a client must acquire an XMLMessageProducer from the JCSMPSession. Once it is acquired, the JCSMPSession maintains a connection to the event broker and the application can then send messages.

XMLMessageProducer can also be used to create Session‑dependent messages through the Producer interface (refer to Message Ownership).

The XMLMessageProducer is in an “open” state until the close() method is called on XMLMessageProducer.

A client should cache an acquired instance and close it only when it is no longer required. It is not efficient to acquire a new XMLMessageProducer instance for every message sent.

To acquire an XMLMessageProducer instance, call getMessageProducer(JCSMPStreamingPublishEventHandler callback) and set the callback handler. When a non-null instance of the JCSMPStreamingPublishEventHandler parameter is passed in, the send operation uses a JCSMPStreamingPublishEventHandler to asynchronously get confirmation of message delivery failures using a callback mechanism.

Adjusting the Guaranteed Message Publish Window Size

The Guaranteed message publish window size can be adjusted, if necessary, to better suit your messaging environment. The valid range is 1 through 255.

Although the default value has been proven to provide good performance for most LAN situations, increasing the value might help in a situation where messages are being published over a WAN or a network with higher delay (possibly incurring event broker/switch induced latencies), and the window is experiencing flow control situations.

Windowed acknowledgment properties have no effect for Direct messages.

To set the Guaranteed message publish window size, use the JCSMPProperties.PUB_ACK_WINDOW_SIZE property:

JCSMPProperties properties = new JCSMPProperties();   
properties.setProperty(JCSMPProperties.PUB_ACK_WINDOW_SIZE, 255);

Adjusting the Guaranteed Message Publish Ack Timer

The Guaranteed message publish acknowledgment timer sets the amount of time (in milliseconds) that the publishing API waits for an acknowledgment from the event broker before resending. Guaranteed messages not acknowledged within the publish acknowledgment time are retransmitted automatically by the API.

Although the default Guaranteed message publish acknowledgment timer value has been proven to provide good performance, it can be adjusted, if necessary.

Windowed acknowledgment properties have no effect for Direct messages.

To adjust the Guaranteed message publish acknowledgment timer, use JCSMPProperties.PUB_ACK_TIME:

JCSMPProperties properties = new JCSMPProperties();   
properties.setProperty(JCSMPProperties.PUB_ACK_TIME, 2500);

Sending One Message at a Time

To publish a single message per API call, call the XMLMessageProducer.send(...) method:

producer.send(message, JCSMPFactory.onlyInstance().createTopic(topicString));

When using JCSMP, and sending messages created from a Producer (that is Session‑dependent messages), ensure that a client:

  • Does not send the same message multiple times. Attempting to do this throws an InvalidOperationException.
  • Does not send a Message instance created either in a previous JCSMPSession or by another XMLMessageProducer. Attempting to do this throws an IllegalArgumentException.
  • Calls close() to close the producer when finished publishing. Any further access, such as sending messages, causes an exception to be raised.

Sending Multiple Messages at Once

A group of Direct or Guaranteed messages can be sent through a single API call. This allows messages to be sent in a batch or a vector. The messages to be sent are specified as an array; up to fifty messages can be sent through the call.

When batch-sending messages through a send-multiple API call, the same Delivery mode (for example, Direct or Persistent) should be set for all of the messages (refer to Delivery Mode).

In the PubSub+ JCSMP API, an array of {Message, Destination} pairs, each represented by a JCSMPSendMultipleEntry instance, must be passed in. This pairing allows messages to be sent to individual destinations. Each message must be an application‑owned message instance (that is, acquired from JCSMPFactory.createMessage(...)).

The PubSub+ JCSMP API attempts to write all of the messages to the network at once and blocks until completion.

When Guaranteed messages are sent, messages are transmitted serially.

To publish a group of messages, use the XMLMessageProducer.sendMultiple(...) method.

For more information, see the PubSub+ Messaging API for JCSMP reference.

Message Correlation

When using Guaranteed Messaging, a correlation key or tag is used to correlate a message with its ack or nack. For the PubSub+ JCSMP API, the correlation key is an object that is passed back to the client during the event broker ack or nack.

To set a correlation key on a message:

  • msg.setCorrelationKey(...)

The correlation key is passed back to the client through:

  • JCSMPStreamingPublishCorrelatingEventhandler.
    responseReceivedEx()     (for an ack)
  • JCSMPStreamingPublishCorrelatingEventhandler.
    handleErrorEx()     (for a nack)

For an example of how to use correlation keys, see the adPubAck sample in the Solace Developer Hub.