Adding Subscriptions to Endpoints in the PubSub+ JCSMP API

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 (refer to Configuring Permissions for Non-Owner Clients) for the client to add Topic subscriptions to it or remove Topic subscriptions from it.

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

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 the JCSMPSession.addSubscription(...) method, 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)

For an example of how to add to a topic subscription to a queue, refer to the TopicToQueueMapping sample on the Solace Developer Hub.

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, refer to System-Level Subscription Exception Configuration.

Removing Subscriptions from Endpoints

To remove a topic subscription that was added to a queue or topic endpoint, call the JCSMPSession.removeSubscription(...) method and pass in the queue or topic endpoint, subscription, and any subscribe flags that are used.