Sending Guaranteed Messages

When sending a Guaranteed message, client applications must consider the following factors:

Related Samples

For examples of how to publish and receive Guaranteed messages, refer to the simpleFlowToQueue sample for the Java, Java RTO, C, and .NET APIs, and the QueueProducer sample for the JavaScript and Node.js APIs.

Streaming and Non-Streaming Sends in JCSMP

JCSMP only supports a blocking network I/O model. However, when publishing messages, JCSMP 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 JCSMP, 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.

Blocking and Non-Blocking Network I/O in the Java RTO, C, and .NET APIs

The Java RTO, C, and .NET APIs can use a blocking or non‑blocking network I/O model for send operations. This is controlled by the send blocking session property. By default, this property is set to true or ENABLE, so that a blocking mode is used.

When the send blocking session property is set to false or DISABLE, a non-blocking mode is used. If the OS/network cannot send the whole message without blocking the calling thread until more buffer space is available, the client application gets a WOULD_BLOCK return code. When a WOULD_BLOCK return code is received, the message is not sent and the client application must wait for a CAN_SEND session event, which indicates that the network is then ready for the send.

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
PubSub+ Messaging API Use

JCSMP

JCSMPProperties#PUB_ACK_WINDOW_SIZE

Java RTO

SessionHandle.PROPERTIES.PUB_WINDOW_SIZE

C

SOLCLIENT_SESSION_PROP_PUB_WINDOW_SIZE

.NET

SessionProperties.ADPublishWindowSize

JavaScript and Node.js

solace.MessagePublisherProperties.windowSize

where the solace.MessagePublisherProperties object is assigned to solace.SessionProperties.publisherProperties

Adjusting the Guaranteed Message Publish ACK Timer

The Guaranteed message publish acknowledgment timer sets the amount of time (in milliseconds) that the publishing API will wait 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
PubSub+ Messaging API Use

JCSMP

JCSMPProperties#PUB_ACK_TIME

Java RTO

SessionHandle.PROPERTIES.PUB_ACK_TIMER

C

SOLCLIENT_SESSION_PROP_PUB_ACK_TIMER

.NET

SessionProperties.ADPublishAckTimerInMsecs

JavaScript and Node.js

solace.MessagePublisherProperties.acknowledgeTimeoutInMsecs

where the solace.MessagePublisherProperties object is assigned to solace.SessionProperties.publisherProperties

Sending One Message at a Time

To publish a single message per API call, call one of the send methods or functions listed below.

To Send Messages
PubSub+ Messaging API Use

JCSMP

XMLMessageProducer.send(...)

Java RTO

SessionHandle.send(...)

C

solClient_session_sendMsg(...)

.NET

ISession.Send(...)

JavaScript and Node.js

solace.Session.send(...)

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).

JCSMP

When using JCSMP, 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(...)).

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

Java RTO, C, JavaScript, Node.js, and .NET APIs

When using the Java RTO, C, JavaScript, Node.js, or .NET APIs, an array of messages must be passed in. Unlike JCSMP, message destinations are not set through a send method, rather they are set as a property for each message.

When a blocking mode is configured for the session through the session properties, the call blocks until all messages can be accepted by the messaging API. If a non‑blocking mode is configured, and the API cannot accept all messages to publish, SOLCLIENT_WOULD_BLOCK is returned, and the number of messages that were accepted is returned in the in_out_howManySent, numberOfMessagesWritten, or messagesSent parameter. The application can reattempt to send the messages that were not accepted or take another action.

When Guaranteed messages are sent, messages are transmitted serially.

Publishing a Group of Messages
PubSub+ Messaging API Use

JCSMP

XMLMessageProducer.sendMultiple(...)

Java RTO

SessionHandle.send(...)

C

solClient_session_sendMultipleMsg(...)

.NET

ISession.Send(...)

JavaScript and Node.js

Not applicable

Related Samples

For examples of how to publish a group of messages, refer to the PerfTest sample for the appropriate messaging API.

Message Correlation

When using Guaranteed messaging, a correlation key or tag is used to correlate a message with its ACK or NACK. For the JCSMP, Java RTO, and .NET APIs, the correlation key is an object that is passed back to the client during the event broker ACK or NACK. For the C API, the correlation tag is a pointer that is passed back to the client during the event broker ACK or NACK.

Using Correlation Keys
PubSub+ Messaging API Use

JCSMP

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)

Java RTO

To set a correlation key on a message:

  • MessageHandle.setCorrelationKey(...)

 

The correlation key is passed back to the client through the following session events:

  • ACKNOWLEDGEMENT
  • REJECTED_MSG_ERROR

C

To set a correlation tag on a message:

  • solClient_msg_setCorrelationTagPtr(...)

The correlation tag is passed back to the client in the session event callback for the following session events:

  • SOLCLIENT_SESSION_EVENT_ACKNOWLEDGEMENT
  • SOLCLIENT_SESSION_EVENT_REJECTED_MSG_ERROR

.NET

To set the correlation key property of a message:

  • message.CorrelationKey = myCorrelationKey;

The correlation key is passed back to the client in the HandleSessionEvent callback for the following events:

  • Session.Acknowledgement
  • Session.RejectedMessageError

JavaScript and Node.js

To set the correlation key property of a message:

  • message.setCorrelationKey(...)

The correlation key is passed back to the client in the listeners for the following events:

  • solace.SessionEventCode.ACKNOWLEDGED_MESSAGE

  • solace.SessionEventCode.REJECTED_MESSAGE_ERROR

Related Samples

For an example of how to use correlation keys, refer to the adPubAck sample for the appropriate messaging API.

For the JavaScript and Node.js APIs, refer to the ConfirmedPublish sample.