Publishing Messages that Request Replies

The enterprise messaging APIs enable clients to use convenience functions and methods to publish Direct messages that request replies from receiving clients. This differs from a traditional publish and subscribe scenario where a message is published to a particular topic and clients interested in that topic can receive the message without providing replies to the publisher.

A request message is published with a unique identifying ReplyTo destination topic in its ReplyTo message header field. This ReplyTo topic serves as the return address that the reply should be sent to.

When a client connects to an event broker, a point‑to‑point (P2P) Inbox subscription is automatically registered for that client, and, by default, this P2P address is used for the ReplyTo destination for requests. Automatically setting the P2P address as the ReplyTo destination allows clients to perform request/reply operations without worrying about registering appropriate topic subscriptions to receive replies.

Clients can query the P2P address in use by performing a get for the P2P session property; for more information, refer to the appropriate PubSub+ Messaging APIs documentation.

To send a request message, call one of the methods or functions listed in table below, and pass in the following information:

  • The message content to be sent.
  • A reply time‑out value.

    A reply time‑out value of 0 creates a non-blocking request (that is, the call returns immediately upon the successful buffering of the message for transmission). For a non-blocking request, if a response is received from the destination client, it is delivered in the received message callback along with all other received messages. It is the responsibility of the application to manage non‑blocking responses.

    For a non-blocking call (that is, a time-out value of 0), correlation ID matching is optional, and its implementation is the responsibility of the application. To map replies to requests, the replying application should specify an identifier in the correlationId message header field of the reply.

    A reply time‑out with a value greater than 0 sets the number of milliseconds that the API will wait for a reply from the receiving client. This is a blocking request. In this case, if a response is received before the time‑out expires, the reply message is returned; if a response is not received in time, an error is signaled. By default, when the request is blocking, a correlation ID is automatically generated.

  • When using JCSMP, pass in a topic destination to publish to.

    For the Java RTO, C, and .NET APIs, the topic destination is set as a message property (refer to Destination).

For information on replying to request messages, refer to Replying to Request Messages.

JCSMP

To send a request message, you must create an XMLMessageProducer and an XMLMessageConsumer in a session, and start the XMLMessageConsumer. You can then call Session.createRequestor() to acquire a Requestor instance.

To Send a Request Message
PubSub+ Messaging API Use

JCSMP

Requestor.request(...)

Java RTO

SessionHandle.sendRequest(...)

C

solClient_session_sendRequest(...)

.NET

ISession.SendRequest(...)

JavaScript and Node.js

solace.Session.sendRequest(...)

Related Samples

For examples of how to send a Direct request message, refer to the RRDirectRequester and RRDirectReplier samples for the Java, Java RTO, C, and .NET APIs, and the BasicReplier and BasicRequestor samples for JavaScript and Node.js APIs.

Setting Custom ReplyTo Suffixes and Destinations

Although by default a ReplyTo destination value is automatically generated, applications may optionally add a specific ReplyTo suffix to the session’s default ReplyTo base topic. (If the given string does not start with a / delimiter, one is inserted.)

To Add a ReplyTo suffix
PubSub+ Messaging API Use

JCSMP

XMLMessage.setReplyToSuffix(...)

Java RTO

MessageHandle.setReplyToSuffix(...)

C

solClient_msg_setReplyTo(...)

.NET

IMessage.SetReplyToSuffix(...)

JavaScript and Node.js

Not applicable

You can also set a specific ReplyTo destination value (that is, a queue or a topic).

To Set a Specific ReplyTo Destination
PubSub+ Messaging API Use

JCSMP

XMLMessage.setReplyTo(...)

Java RTO

MessageHandle.setReplyTo(...)

C

solClient_msg_setReplyTo(...)

.NET

IMessage.ReplyTo

JavaScript and Node.js

solace.Message.setReplyTo(...)