Creating Durable Topic Subscribers

TopicSubscriber, a subinterface of MessageConsumer, is a publish and subscribe form of a message consumer.

A client can use a durable TopicSubscriber object to receive messages that have been published to a Topic destination. Even if that client is not connected, the durable topic subscriber ensures that the messages are maintained by the JMS broker until they are acknowledged by the consuming durable topic subscriber or until they expire.

To create a durable topic subscription and a durable topic subscriber on an event broker it must have Guaranteed Messaging and message spooling enabled, and, if using an appliance, an ADB must be installed.

To create a durable topic subscriber, call the following method from a Session:

session.createDurableSubscriber(Topic topic, java.lang.String name, java.lang.String messageSelector, boolean noLocal)

Where:

topic is the topic to subscribe to. For information on the supported Topic syntax rules, refer to Topic Support & Syntax.

name is a name to identify the durable topic subscriber. The name can be up to 200 characters (the only invalid characters are '<>*?&;). Each durable topic subscriber in a MessageVPN must be unique. Durable topic subscriber names used by the JNDI provider are the equivalent of durable topic endpoints that can also be created through SolAdmin or the Solace CLI (refer to Solace JNDI Objects).

messageSelector is a message selector expression. Only messages with matching header fields and properties are delivered. A value of null or an empty string means that there is no message selector.

noLocal is an attribute that specifies whether the subscriber can receive messages that match its subscription if they were published on the same connection. (In other words, whether a client is allowed to consume messages it has published itself when they match its Topic subscription.) To prevent the delivery of messages on the same connection that they are published on, enable the NoLocal attribute for the subscriber (the default value is false).

To create a durable topic subscriber, a topic subscription (that is, a durable topic endpoint) must be provisioned on the event broker. This durable topic subscription serves to attract messages published to the topic. Only one Session at a time can use a topic subscriber for a particular durable subscription.

If the topic subscription has already been provisioned on the event broker (through SolAdmin or the CLI), when you call the createDurableSubscriber(...) method and pass in the name of the physical subscription, an instance of that subscription (that is, an in-memory representation of the subscription in the API) is created.

If a durable topic subscription is not already provisioned on the event broker, when you call the createDurableSubscriber(...) method and pass in a subscription name, a durable topic subscription is created on the event broker if the creation of dynamic durable endpoints is permitted. (If the creation of dynamic durable endpoints is not permitted, a JMSException is thrown.)

To allow the creation of dynamic durable endpoints, you can set the InitialContext environment property SupportedProperty.SOLACE_JMS_DYNAMIC_DURABLES to true. You can also use SolAdmin or the CLI to enable the equivalent Connection Factory property in the JNDI.