Receiving Direct Messages in the PubSub+ JCSMP API

Direct messages can be delivered to a client using the PubSub+ JCSMP API in a session when the event broker has matching topic subscriptions for that client. For the client to receive the messages, it must use a message receive interface or callback/delegate appropriate for the programming language used.

Direct messages are received through an acquired XMLMessageConsumer interface. An XMLMessageConsumer can operate in either an asynchronous mode (when a listener is specified) or a synchronous mode (if no message listener is specified).

To acquire an XMLMessageConsumer, use the JCSMPSession.getMessageConsumer(XMLMessageListener) method.

  • To use a asynchronous message delivery mode, pass in an XMLMessageListener callback interface.
  • To use a synchronous message delivery mode, set the message listener to null.

    After start() is invoked for the consumer, use the following methods to receive messages:

    • receive()—receives the next available message, and waits until one is available.
    • receive(int timeoutInMillis)—receives the next available message. If no message is available, the method blocks until a set amount of time expires.
    • receiveNoWait()—receives the next available message.

To enable an acquired XMLMessageConsumer to read messages from the underlying connection and deliver messages to the application, call XMLMessageConsumer.start(). To stop delivering messages to the application, call XMLMessageConsumer.stop().

XMLMessageConsumer is in an “opened” state until the XMLMessageConsumer.close() method is called.

Message Discard Indications

A receiving client can use a message discard indication method or function to query whether the event broker has for any reason discarded any Direct messages previous to the current received message. If the call returns true, the event broker has discarded one or more messages prior to the current message; if the call returns false, no messages prior to the current message were lost.

When a client application detects a message discard has occurred, it should handle this event appropriately. For example, it can follow its regular session re‑initialization procedure.

To query whether messages have been discarded, use the XMLMessage.getDiscardIndication() method.

  • Message discards can occur if an event broker’s egress per-client priority queues fill up with received messages. When this occurs, the oldest messages on the queues can be discarded to allow new incoming messages to be enqueued. Egress per-client priority queues could fill up in a situation where there are slow subscriber (that is, clients that are not consuming messages quickly enough). For more information on egress per-client priority queues and how to configure them, refer to Message Delivery Resources.
  • It is recommended that consuming clients do not use discard indications when using message eliding. In a situation where an event broker’s egress priority queue for a client fills up with received messages, the oldest messages on the egress queue are discarded to make room for newly arriving messages, and the message at the head of the queue is flagged with the discard indication. However, if eliding is enabled, that message could be elided, and the client would not receive the discard indication.

Replying to Request Messages

To reply to an incoming request message, an application can call one of the methods listed below and provide the request message that is being replied to and the message contents to reply with. Typically, the ReplyTo address and a correlation ID for the Reply message are provided by the received Request message. The Reply method or function automatically sets a single bit response attribute, and it uses a correlation ID that matches that of the incoming request message.

For information on sending request messages, refer to Publishing Messages that Request Replies in the PubSub+ JCSMP API.

To send reply messages, use the XMLMessageProducer.sendReply(...) method.

Related Samples

For an example of how to send and receive request/reply messages, see the RRDirectRequester and RRDirectReplier samples in the Solace Developer Hub.