Receiving Direct Messages

Direct messages can be delivered to a client 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.

JCSMP

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

Acquiring an XMLMessageConsumer

PubSub+ Messaging API

Use

JCSMP

JCSMPSession.getMessageConsumer(XMLMessageListener) 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.

Java RTO API

Direct messages are received through a message receive callback that is set when the session is created. This message receive callback is invoked for each received Direct message.

C API

Direct messages are received through a message receive callback that is set when the session is created. This message receive callback is invoked for each received Direct message.

The message receive callback that is chosen dictates which messaging interface is used: the solClientMsg interface or the deprecated solClient_bufInfo_t interface. A value of NULL is required for the interface that is not used.

For new deployments, the solClientMsg interface is recommended because it provides access to additional event broker features, such as SDTs and PubSub+ cache.

.NET API

Direct messages are received through a message receive delegate that is set when the session is created. This message receive delegate is invoked for each received Direct message.

JavaScript and Node.js APIs

Direct messages are received through a message listener defined for the session for the solace.SessionEventCode.MESSAGE event.

Message Receive Callback/Delegate

PubSub+ Messaging API	Set Through
JCSMP	Not applicable
Java RTO	MessageCallback
C	solClient_session_rxMsgCallbackFunc_t
.NET	EventHandler<MessageEventArgs>
JavaScript and Node.js	solace.Session.subscribe(...)

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

PubSub+ Messaging API	Call
JCSMP	XMLMessage.getDiscardIndication()
Java RTO	MessageHandle.getDiscardIndication()
C	solClient_msg_isDiscardIndication(...)
.NET	IMessage.DiscardIndication
JavaScript and Node.js	solace.Message.isDiscardIndication()

Receiving Topic-Specific Messages with Custom Callbacks

When using the Java RTO, C, or .NET APIs, by default, Direct messages are dispatched to the receive callback or delegate that is configured for the session. However, you can also use special receive callbacks or delegates to handle Direct messages that are published to specific topics. This functionality is also known as topic dispatching because messages with a specific topic are dispatched to a specific callback or delegate.

Dispatching messages according to their topics to a custom message receive callback or delegate can be useful when the matching subscriptions contain wildcards because it enables you to separate out received messages with more precision. For example if a session’s topic is part1/>, a client could receive messages with the topics part1/item1 and part1/item2. Using topic dispatch subscriptions, you can configure one receive callback or delegate for messages published to part1/item1 and another for messages published to part1/item2.

Even if topic dispatching is enabled for the session, the message receive callback or delegate that is set when the session is created is still used, and it acts as a default callback/delegate for all subscriptions that were added without the dispatch option (refer to Adding Topic Subscriptions). Therefore, a received message is handled by the session message receive callback/delegate if, and only if, that message’s topic does not match one or more subscriptions that were added using the topic subscribe with dispatch function/method. Otherwise, the message is dispatched to the callbacks/delegates configured for those subscriptions, instead of being handled by the default session callback/delegate.

Full wildcard subscription syntax is supported for topic dispatching. Therefore if a message matches multiple subscriptions with configured dispatch callbacks/delegates (for example, message with a topic of part1/item1 matches subscription topics for part1/item1 and part1/>), then each matching subscription invokes a callback/delegate. As a result, a client can receive and process a message multiple times. (For information on topic syntax rules supported for subscriptions, refer to Topic Support & Syntax.)

When a message does not match a subscription topic with a specific callback/delegate, it is dispatched to the default session message receive callback/delegate only once, regardless of the number of subscriptions it matches.

To add a subscription that will use topic dispatch, the topic dispatch session property must be enabled for the session.

To Enable Topic Dispatch for a Session

PubSub+ Messaging API	Session Property
JCSMP	Not applicable
Java RTO	SessionHandle.PROPERTIES.TOPIC_DISPATCH
C	SOLCLIENT_SESSION_PROP_TOPIC_DISPATCH
.NET	ISession.TopicDispatch
JavaScript and Node.js	Not applicable

To use dispatch for a specific topic, use a function or method listed below, and do the following:

• For the Java RTO API, create a MessageDispatchTargetHandle and pass it in as the topic subscription.
• For the C API, pass in a topic subscription and the message receive callback to use for that topic.
• For the .NET API, pass in a IDispatchTarget object. The IDispatchTarget encapsulates a subscription and a message receive delegate for messages with topics matching that subscription.
• For each API, you can also set optional subscription flags.

To Use Topic Dispatch for a Subscription

PubSub+ Messaging API	Call
JCSMP	Not applicable
Java RTO	Solclient.Allocator. newMessageDispatchTargetHandle(...) SessionHandle.subscribe (MessageDispatchTargetHandle ...)
C	solClient_session_topicSubscribeWithDispatch(...)
.NET	IMessageDispatcher.Subscribe(...) An ISession implements the IMessageDispatcher interface.
JavaScript and Node.js	Not applicable

Available Topic Dispatch Subscription Flags

Flag	Description
Request Confirm	The call should return immediately and a confirmation event is generated after the event broker has completed the subscription add or remove request.
All Deliver‑To‑One	When present in a subscription add request, this flag overrides the deliver‑to‑one property in a message. If there is a topic match for subscriptions with the all deliver‑to‑one flag, the message is delivered to the clients with those subscriptions and to one additional client with a matching topic subscription that does not have the all deliver‑to‑one override. For the .NET API, this option is set as a topic property.
Wait for Confirm	The call should not return until a confirmation is received from the event broker.
Local Dispatch Only	Add the topic subscription to the messaging API’s dispatch table only. Do not add the subscription to the event broker.

For more information and examples for dispatching received Direct messages based on subscription topics, refer to the reference material  PubSub+ Messaging APIs for Java RTO, C, or .NET.

Related Samples

For an example of how to use topic dispatch for a subscription, refer to the TopicDispatch sample for the appropriate messaging API.

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.

To Send Reply Messages

PubSub+ Messaging API	Call
JCSMP	XMLMessageProducer.sendReply(...)
Java RTO	SessionHandle.sendReply(...)
C	solClient_session_sendReply(...)
.NET	ISession.SendReply(...)
JavaScript and Node.js	solace.SessionsendReply(...)

Related Samples

For an example of how to send and receive request/reply messages, refer to the RRDirectRequester and RRDirectReplier samples for the Java, Java RTO, C, and .NET APIs. For the JavaScript and Node.js APIs refer to the BasicRequestor and BasicReplier samples.