Managing Subscriptions

A client must use topic subscriptions to receive Direct messages from the message VPN that it has connected to on a Solace event broker. A subscription represents a message attractor a client can use in a publish/ subscribe (pub/sub) messaging domain to express its interest in the messages it wants to receive.

A topic represents a logical destination. A client can publish messages to a topic destination. A client can also subscribe to a topic, and when the event broker has a topic subscription for the client that matches the message's destination, the client can receive the message.

Topics can be grouped in hierarchies. Therefore topic subscriptions, which support wildcards, can attract parts of the hierarchy for a client without subscribing to each possible combination of the hierarchy levels. For detailed information on the characters and syntax supported by event brokers, see Topic Support & Syntax.

A topic has the following properties:

  • Name—A string that represents the topic to publish and/or subscribe to.
  • Durability—That is, whether it is temporary (where the scope and lifetime of a temporary topic is that of the session it is created in) or non‑temporary (created at the factory level).
  • Whether it has the receive all deliver‑to‑one (DTO) flag enabled—When the topic has this flag is enabled in a subscription ADD request, it overrides an enabled DTO flag in a published message. Therefore, if the topic in the message matches, it is delivered to clients with topics that have the receive all deliver‑to‑one flag set, in addition to any one client that is subscribed to the topic without this override.

Related Samples

For an example of how to add topic subscriptions, see the TopicSubscriber sample for the Solace JavaScript API and Solace Node.js API.

Session-Level Controls for Subscription Operations

A number of session level controls can affect the subscription operations, they are:

Network I/O Blocking and Non-Blocking Modes

For the Solace JavaScript API and Solace Node.js API all subscribe and unsubscribe operations are non-blocking and are only considered successful when solace.SessionEventCode.SUBSCRIPTION_OK has been received.

Reapplying Subscriptions on Reconnect

By default, the event broker that a client connects to does not maintain that client's subscriptions (that is, by default, subscriptions are non‑durable). However, the reapply subscriptions property can be enabled for a session so that all subscriptions a client adds or deletes are remembered by the API, and, if the session fails, the client's last subscription set is automatically reapplied to the event broker upon a successful reconnect. Therefore, enabling the reapply subscriptions property effectively makes a client's subscriptions durable.

This property doesn't apply to subscriptions on endpoints. Endpoint subscriptions are maintained by the event broker (that is, topic subscriptions applied to queues are durable). If a client is using a temporary queue and disconnects for over a minute, the temporary queue will be removed from the event broker, and automatically recreated once the client reconnects. However, the subscription will not be re-applied even if REAPPLY_SUBSCRIPTIONS is enabled.

If an error occurs when reapplying subscriptions, the channel connection is declared down, and the client attempts to reconnect according to the configured reconnection properties for the session (see Reconnect Retries). The subscriptions must be successfully reapplied for the connection to be reestablished.

Topic subscriptions made on behalf of another client are not maintained by the event broker that that client connects to—that is, they are not durable (see Managing Topic Subscriptions on Behalf of Other Clients). In addition, topic subscriptions are not maintained in API memory; so they cannot be reapplied when the client reconnects.

To enable the reapplication of subscriptions, set solace.SessionProperties.reapplySubscriptions.

Related Samples

For an example of how to reapply subscriptions when a session reconnects, see the DirectPubSub sample for the appropriate Solace Messaging API.

Setting Subscriber Priority Levels

To control which clients receive DTO messages, the clients are assigned a local subscriber priority. A local priority is the priority that a client's subscriptions have for receiving DTO messages published on the event broker that the client is directly connected to. Subscriber priority levels range from 1 (the highest) to 4 (the lowest).

When a message is published with the DTO feature enabled, a local client with the highest subscriber priority level receives the message, and if that subscriber local priority level is shared by multiple clients, a single client is chosen in a round‑robin fashion.

If there is no local client with a matching subscription, the message may be delivered to one client with matching subscription that is connected to a neighbor event broker.

DTO is not supported for the Solace JavaScript API. For the Solace Node.js API, set solace.SessionProperties.subscriberNetworkPriority.

Related Samples

For an example of how to publish and subscribe to messages using DTO, see the DTOPubSub sample for the appropriate Solace Messaging API.

Adding Topic Subscriptions

In a publish/subscribe messaging domain, a client can use topic subscriptions to attract messages of interest.

To add topic subscriptions to event broker, call a method or function appropriate for the Solace Messaging API used and pass in the topic subscription. You can also set optional subscribe flags to control the behavior of the API call.

The subscription flags that can be set include:

  • Request confirm (for the Solace JavaScript API and Solace Node.js API)

A topic subscription of the ">" character alone will attract all published messages regardless of their topic, and it acts as a deliver always subscription (that is, it overrides enabled deliver‑to‑one flags in published messages).

To add subscriptions, call solace.Session.subscriber(...).

Related Samples

For an example of how to add topic subscriptions, see the TopicSubscriber sample for the Solace JavaScript API and Solace Node.js API.

Managing Topic Subscriptions on Behalf of Other Clients

A client can act as a subscription manager to add and remove topic subscriptions for other clients in the same message VPN. For a client to be a subscription manager, it must connect to the router using a client username which has been configured to be a subscription manager. These clients are referred to as OBO (on-behalf-of) agents, or OBO subscription managers. Using an OBO subscription manager allows you to centralize the management of which clients get which subscriptions. For information on how to enable the subscription manager capability for a client username, see Configuring Subscription Managers.

  • Only direct messages can be received through topic subscriptions made on behalf of other clients.
  • A subscription manager can add topic subscriptions on behalf of a client only for direct messaging. It does not necessarily have the permissions to modify the subscriptions of the guaranteed messaging endpoints (queues or topic-endpoints) owned by those clients.
  • The subscription manager must create a client name endpoint for a client to add or remove topic subscriptions for that client. When subscriptions are added on behalf of another client, they behave like any other subscriptions. For example, subscriptions added by a subscription manager are removed if the client disconnects. Disconnecting the subscription manager has no effect on the subscriptions already added.

Managing topic subscriptions on behalf of other clients is not currently supported for the Solace JavaScript API and Solace Node.js API.

Removing Subscriptions

You can also set optional subscribe flags to control the behavior of the API call. (These flags are the same as their add subscription counterparts.)

To remove subscriptions, call solace.Session.unsubscribe(...).

Related Samples

For an example of how to remove topic subscriptions, see the TopicSubscriber sample for the Solace JavaScript API and Solace Node.js API.