Sending Direct Messages in the PubSub+ JCSMP API
When sending a Direct message, client applications using the PubSub+ JCSMP API must consider the following factors:
- Whether you want to send messages using a streaming or non-streaming mode. Refer to Streaming and Non-Streaming Sends in the PubSub+ JCSMP API.
- The number of messages to publish per send invocation. Refer to Sending One Message at a Time or Sending Multiple Messages at a Time.
- Whether you want to send messages that require a reply from the receiver. Refer to Publishing Messages that Request Replies in the PubSub+ JCSMP API.
For an example of how to publish and receive Direct messages, see the DirectPubSub 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, 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, see 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.
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 the application:
- Does not send a
Messageinstance created either in a previousJCSMPSessionor by anotherXMLMessageProducer. Attempting to do this throws anIllegalArgumentException. - Does not send the same message multiple times. Attempting to do this throws an
InvalidOperationException. - 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 a Time
A group of Direct 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, a Direct Delivery mode should be set for all of the messages, see Delivery Mode.
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(...)).
The PubSub+ JCSMP API attempts to write all of the messages to the network at once and blocks until completion.
To publish a group of messages, use the XMLMessageProducer.sendMultiple(...) method.
For more information, see the PubSub+ Messaging API for JCSMP reference.