Sending Guaranteed Messages

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

• When using the Solace Java RTO API, whether you want to send messages using a blocking or non-blocking mode. See Blocking and Non-Blocking Network I/O in the Solace Java RTO API.
• The number of messages to publish per send invocation. See Sending One Message at a Time or Sending Multiple Messages at Once.
• Whether you want to send messages that require a reply from the receiver. See Publishing Messages that Request Replies.

• If you are publishing in a network environment that experiences higher than usual delays, you might need to adjust the Guaranteed message publish window size (see Adjusting the Guaranteed Message Publish Window Size ) or acknowledgment timer (see Adjusting the Guaranteed Message Publish ACK Timer).

Related Samples

For examples of how to publish and receive Guaranteed messages, see the simpleFlowToQueue sample for the Solace Java RTO API.

Blocking and Non-Blocking Network I/O in the Solace Java RTO API

The Solace Java RTO API 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.

Sending Messages Larger Than the Event Broker's Maximum Message Size

You cannot publish a Guaranteed message larger than the event broker's maximum Guaranteed message size—30MB in most cases. If you try to publish a message that exceeds the maximum size, the Solace Java RTO API returns an error, throws an exception, or raises an error with the subcode MESSAGE_TOO_LARGE. To prevent disruptions, design your application to control message sizes and ensure they stay within the supported limit.

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.

In the Solace Java RTO API, use SessionHandle.PROPERTIES.PUB_WINDOW_SIZE

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.

In the Solace Java RTO API, use SessionHandle.PROPERTIES.PUB_ACK_TIMER

Sending One Message at a Time

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

In the Solace Java RTO API, use SessionHandle.send(...)

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 (see Delivery Mode).

When using the Solace Java RTO API, an array of messages must be passed in. 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 Solace Java RTO 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.

In the Solace Java RTO API, use SessionHandle.send(...)

Related Samples

For examples of how to publish a group of messages, see the PerfTest sample for the Solace Java RTO 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 Solace Java RTO API, the correlation key is an object that is passed back to the client during the event broker ACK or NACK.

In the Solace Java RTO API, to set a correlation key on a message, use MessageHandle.setCorrelationKey(...). The correlation key is passed back to the client through the following session events: ACKNOWLEDGEMENT and REJECTED_MSG_ERROR.

Related Samples

For an example of how to use correlation keys, see the adPubAck sample for the Solace Java RTO API.