Adding Subscriptions to Endpoints

Typically, messages are published to a queue when it is set as the destination of the message. However, you can also add a topic subscription to a queue so that it receives any messages that are published to a matching topic destination.

As shown in the figure below, when a topic subscription is added to a queue, it is possible for a message published to a topic to be sent to a queue, a topic endpoint, and directly to the message bus where it can be matched with clients’ topic subscriptions.

Possible Routing of Messages Published to Topics

Adding Subscriptions to Queues

A client can add or remove topic subscriptions whether it is bound to the queue or not, but the queue must have at least modify-topic privileges for the client to add topic subscriptions to it or remove topic subscriptions from it. For more information, see Configuring Permissions for Non-Owner Clients.

A client cannot remove topic subscriptions that an administrator has added to a queue through the Solace CLI or SolAdmin.

When a queue is deleted, all topic-to-queue mappings for that queue are also deleted.

If persistent or non-persistent messages are published to a topic that matches a queue's subscriptions but the event broker cannot persist the message on the queue (for example, if the message size exceeds the queue's configured size limit or if the queue is over quota), the message is discarded. Whether the publisher receives a rejection (NACK) depends on the queue's reject-msg-to-sender-on-discard setting, which is enabled by default on the event broker. For more information, see Configuring Message Discard Handling.

To add a topic subscription to a queue, call a method or function listed below appropriate for the messaging API used, and pass in the queue name and the topic that you want to add to that queue.

The subscription flags that can be set include:

  • Wait For Confirm
  • Request Confirm (for Java RTO, C and .NET)

To add a topic subscription to a queue
PubSub+ Messaging API Call

JCSMP

JCSMPSession.addSubscription(...)

Java RTO

SessionHandle.subscribe(...)

C

solClient_session_
endpointTopicSubscribeExt(...)

.NET

ISession.Subscribe(...)

JavaScript and Node.js

messageConsumer.addSubscription(...)

Related Samples

For an example of how to add to a topic subscription to a queue, refer to the TopicToQueueMapping sample for the appropriate messaging API.

Adding Subscriptions with Custom Callbacks to Queues

When using the Java RTO, C, or .NET APIs, you can add topic subscriptions to the flow bound to a queue and use specific message receive callbacks or delegates to handle the Guaranteed messages that are received with matching topics. This functionality is also known as topic dispatching because messages with a specific topic are dispatched to a specific callback or delegate.

By default, each topic subscription with a custom callback or delegate is added to the event broker, and it is removed when there is no longer a custom callback or delegate associated with the subscription. However, you can use the Local Dispatch Only subscribe flag to add a topic subscription that uses a specific callback or delegate without adding the subscription to the event broker.

Error indications are not returned to the publishing client if the message cannot be delivered to a queue for some reason (that is, the feedback to the publishing client is the same as what occurs when a message terminates on a topic endpoint).

To add a subscription with a custom callback to a queue
PubSub+ Messaging API Call

JCSMP

Not applicable

Java RTO

FlowHandle.subscribe(...) and pass in the following:

  • a MessageDispatchTargetHandle

  • optional subscribe flags

  • a message correlation key

A MessageDispatchTargetHandle encapsulates a topic subscription and a message callback. Call Solclient.Allocator.newMessageDispatchTargetHandle(...) to create one.

C

solClient_flow_topicSubscribeWithDispatch(...) and pass in the following:

  • the flow bound to the queue

  • the topic subscription that you want to add

  • message receive callback information

  • optional subscribe flags

.NET

IMessageDispatcher.Subscribe(...) and pass in an IDispatchTarget object and any optional subscribe flags.

An IDispatchTarget encapsulates a subscription (an ISubscription) and a message callback delegate (a MessageHandler). Call IFlow.CreateDispatchTarget() to create an IDispatchTarget instance.

JavaScript and Node.js

Not applicable

Adding Subscription Exceptions to Queues

To add a topic subscription exception to the given durable message queue so that Guaranteed messages published to the topic are not delivered to the queue, repeat the steps to add a subscription and append a leading "!" character to the topic name. In other words, use the same call to create a subscription and pass in the topic parameter with a leading "!" character (in the form !a/b/c).

Subscription exceptions are enabled by default. If subscription exceptions are disabled, the leading "!" is treated as a literal character. For more information about enabling and disabling subscription exceptions, see System-Level Subscription Exception Configuration.

Adding Subscriptions to Topic Endpoints

Typically, a flow for a topic endpoint receives messages according to the single topic defined for it when the flow is created. (For the C API, a flow property sets the topic; for the .NET API, the ISubscription that is passed in sets the topic.)

When using the Java RTO, C, or .NET APIs, you can add additional topic subscriptions to a flow bound to a topic endpoint and use specific message receive callbacks or delegates to handle Guaranteed messages for those topics.

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

It is not possible to dynamically add subscriptions to a provisioned topic endpoint on the event broker. Therefore a subscription with a custom callback or message delegate for a topic endpoint is only saved to the messaging API’s local dispatch table. This is the same behavior that occurs when the Local Dispatch subscribe flag is enabled when adding a topic subscription with a custom callback or delegate to a queue. For more information, see Adding Subscriptions with Custom Callbacks to Queues.

To add a topic subscription with custom callback or delegate
PubSub+ Messaging API Call

JCSMP

Not applicable

Java RTO

FlowHandle.subscribe(...) and pass in the following:

  • a MessageDispatchTargetHandle

  • the LOCAL_ONLY subscribe flag (required)

  • optional subscribe flags

  • a message correlation key

A MessageDispatchTargetHandle encapsulates a topic subscription and a message callback. Call Solclient.Allocator.newMessageDispatchTargetHandle(...) to create one.

C

solClient_flow_topicSubscribeWithDispatch(...) and pass in the following:

  • the flow bound to the topic endpoint

  • the topic subscription that you want to add

  • message receive callback information

  • optional subscribe flags

.NET

IMessageDispatcher.Subscribe(...) and pass in an IDispatchTarget object and any optional subscribe flags.

An IDispatchTarget encapsulates a subscription (an ISubscription) and a message callback delegate (a MessageHandler). Call IFlow.CreateDispatchTarget(...) to create an IDispatchTarget instance.

JavaScript and Node.js

messageConsumer.addSubscription(...) and pass in the following:

  • the topic destination

  • optional correlation key

  • optional timeout period in milliseconds

Related Samples

For an example of how to add to a topic subscription with a custom callback or delegate, refer to the TopicDispatch sample for the Java RTO, C, or .NET APIs.

Removing Subscriptions from Endpoints

To remove a topic subscription that was added to a queue or topic endpoint, call the method or function listed below appropriate for the messaging API used and pass in the queue or topic endpoint, subscription, and any subscribe flags that are used.

To remove a topic subscription from an endpoint
PubSub+ Messaging API Call

JCSMP

JCSMPSession.removeSubscription(...)

Java RTO

  • FlowHandle.unsubscribe(...)

  • SessionHandle.unsubscribe(...) if passing an endpoint as an argument.

C

  • solClient_session_endpointTopicUnsubscribe(...)

  • solClient_flow_topicUnsubscribeWithDispatch(...)

.NET

ISession.Unsubscribe(...)

JavaScript and Node.js

messageConsumer.removeSubscription(...)