Managing Subscriptions

A client must use topic subscriptions to receive Direct messages from the message VPN that it has connected to on a Solace PubSub+ 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, refer to 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.

When using the JCSMP and .NET APIs, creating a topic for a subscription follows the same procedure as creating a topic for a destination (for Direct messages, refer to Creating Topics; for Guaranteed messages, refer to Creating Topics).

Related Samples

For an example of how to add topic subscriptions, refer to the DirectPubSub sample for the JCSMP, Java RTO, C, and .NET APIs, and the TopicSubscriber sample for the JavaScript and Node.js APIs.

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

The Java RTO, C, and .NET APIs support the ability to use non-blocking network I/O in subscribe and unsubscribe operations. This ability is controlled by the subscribe blocking session property. By default, a blocking mode is used.

When a non-blocking mode is used, subscription requests, which are sent within a TCP stream, are affected by TCP flow control. A send call that cannot be immediately accepted by the messaging API returns a SOLCLIENT_WOULD_BLOCK error code to the application. When it can be accepted, the API receives a subsequent SOLCLIENT_SESSION_EVENT_CAN_SEND event, and then it can retry sending the request. In the interim, it can continue to process other actions.

When a blocking mode is used, the calling thread for each send call is blocked until the API can accept the message. As a result, the application automatically controls the flow of send calls to a rate at which the event broker can accept them. A send call remains blocked until either it is accepted by the API, or the blocking write timer expires.

Blocking Write Timers
PubSub+ Messaging API Use

Java

Not applicable (see below)

Java RTO

SessionHandle.PROPERTIES.BLOCKING_WRITE_TIMEOUT_MS

C

SOLCLIENT_SESSION_PROP_BLOCKING_WRITE_TIMEOUT_MS

.NET

SessionProperties.BlockingWriteTimeoutInMsecs

JavaScript and Node.js

Not applicable (see below)
  • For JCSMP, all subscribe and unsubscribe operations use a blocking mode.
  • For the JavaScript and Node.js APIs 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 (refer to 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 (refer to 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
PubSub+ Messaging API Use

JCSMP

JCSMPProperties.REAPPLY_SUBSCRIPTIONS

Java RTO

SessionHandle.PROPERTIES.REAPPLY_SUBSCRIPTIONS

C

SOLCLIENT_SESSION_PROP_REAPPLY_SUBSCRIPTIONS

.NET

SessionProperties.ReapplySubscriptions

JavaScript and Node.js

solace.SessionProperties.reapplySubscriptions

Related Samples

For an example of how to reapply subscriptions when a session reconnects, refer to the DirectPubSub sample for the appropriate 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.

Subscriber Priorities
PubSub+ Messaging API Use

JCSMP

JCSMPProperties.SUBSCRIBER_LOCAL_PRIORITY

Java RTO

SessionHandle.PROPERTIES.SUBSCRIBER_LOCAL_PRIORITY

C

SOLCLIENT_SESSION_PROP_SUBSCRIBER_LOCAL_PRIORITY

.NET

SessionProperties.SubscriberLocalPriority

JavaScript

DTO is not supported

Node.js

solace.SessionProperties.subscriberNetworkPriority

Related Samples

For an example of how to publish and subscribe to messages using DTO, refer to the DTOPubSub sample for the appropriate 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 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:

  • Wait for confirm (for JCSMP, Java RTO, C, and .Net)
  • Request confirm (for Java RTO, C and .Net, JavaScript, and Node.js)
  • Receive all deliver to one (for JCSMP, Java RTO, C, and .NET)

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
PubSub+ Messaging API Use

JCSMP

JCSMPSession.addSubscription(...)

Java RTO

SessionHandle.subscribe(...)

C

solClient_session_topicSubscribeExt(...)

.NET

ISession.Subscribe(...)

JavaScript and Node.js

solace.Session.subscriber(...)

Related Samples

For an example of how to add topic subscriptions, refer to the DirectPubSub sample for the Java, Java RTO, C, and .NET APIs, and the TopicSubscriber sample for the JavaScript and Node.js APIs.

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.

JCSMP, Java RTO, and .NET APIs

For the JCSMP, Java RTO, and .NET APIs, a client name endpoint instance must first be created for each client you want to manage subscriptions for. Once you create a client name endpoint instance, the subscription manager can add topic subscriptions to or remove topic subscriptions from that client name endpoint instance.

C API

For the C API, when the subscription manager client uses one of the functions listed below to add or remove a subscription on behalf of another client, an endpoint type of client name endpoint (SOLCLIENT_ENDPOINT_PROP_CLIENT_NAME) and a name for that endpoint are endpoint properties that must be passed in.

To Manage Topic Subscriptions on Behalf of Other Clients
PubSub+ Messaging API Use

JCSMP

  • JCSMPFactory.createClientName(...)

  • JCSMPSession.addSubscription(...)

  • JCSMPsession.removeSubscription(...)

Java RTO

  • Solclient.Allocator.newClientName(...)

  • SessionHandle.subscribe(...)

  • SessionHandle.unsubscribe(...)

C

  • solClient_session_endpointTopicSubscribe(...)

  • solClient_session_endpointTopicUnsubscribe(...)

.NET

  • ContextFactory.CreateClientName(...)

  • ISession.Subscribe(...)

  • ISession.UnSubscribe(...)

JavaScript and Node.js

Not currently supported
JMS

Not currently supported

Related Samples

For an example of how to use a subscriber manager client to add to a topic subscription on behalf of another client, see:

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

PubSub+ Messaging API Use

JCSMP

JCSMPsession.removeSubscription(...)

Java RTO

SessionHandle.unsubscribe(...)

C

solClient_session_topicUnsubscribeExt(...)

.NET

ISession.UnSubscribe(...)

JavaScript and Node.js

solace.Session.unsubscribe(...)

Related Samples

For an example of how to remove topic subscriptions, refer to the DirectPubSub sample for the Java, Java RTO, C, and .NET APIs, and the TopicSubscriber sample for the JavaScript and Node.js APIs.