Working with Destinations

A destination object is a JMS‑administered object that provides a destination that clients can publish messages to and consume messages from. Destinations can be temporary (TemporaryTopic or TemporaryQueue) or durable (Topic or Queue). Durable destination objects are provisioned on the event broker and can be found through a JNDI lookup.

The JMS API supports the use of wildcards in destination names. For a detailed overview on wildcarding and destination syntax support when using an event broker, refer to Topic Support & Syntax.

Performing Destination JNDI Lookups

If a destination object is configured on the JNDI store on the event broker, a JMS application can perform a destination lookup after obtaining an InitialContext (as described in Working with JNDI) by executing the following command:

Destination dest = (Destination)context.lookup(Dest_name)

The Dest_name argument specifies the destination’s configured JNDI name defined.

If a destination object is configured on an LDAP-based JNDI store on a remote host, a JMS application can perform a destination lookup after obtaining an InitialContext by executing the same command for configured SolConnectionFactory, SolTopic, and SolQueue objects, as shown by the following code snippet:

SolTopic topic = (SolTopic)ctx.lookup(ldapDestDN);

The process for configuring Connection Factory, Queue, and Topic JNDI objects on an LDAP store is dependent on the particular LDAP provider that is used. For an example of how to bind JMS administered objects in an Open LDAP JNDI store, refer to the SolJMSLDAPBind.java sample.

Creating Temporary Destinations

A client can call createTemporaryTopic() or createTemporaryQueue() on a Session to create a unique temporary destination (either a TemporaryTopic or a TemporaryQueue respectively) that has the same scope and lifetime of its connection. Only the client that establishes a temporary destination’s connection is allowed to create MessageConsumers for that temporary destination.

Temporary topics and temporary queues are unique JMS topic and queue objects that are created at the Session level. Temporary topics can also be created at the TopicSession level, and temporary queues can be created at the QueueSession level. One use for a temporary destination is as a JMSReplyTo destination.

Temporary topics and queues are briefly maintained on the event broker when a client disconnects, instead of being immediately destroyed. This allows temporary topics and queues to survive event broker activity switch-overs where the client is momentarily disconnected from one event broker and is then connected to its mate. When Guaranteed Transport is used, messages for the temporary topics and queues received during the outage are stored, and they can be consumed when the client reconnects. When Direct Transport is used, messages for the temporary topics and queues received during the outage are not stored, so they cannot be consumed when the client reconnects.

To create a temporary topic, call the following method from a Session:
```
TemporaryTopic = session.createTemporaryTopic()
```
To create a temporary queue, call the following method from a session:
```
TemporaryQueue = session.createTemporaryQueue()
```

Creating Topics

You can call the createTopic(java.lang.String topicName) method from a Session to create a durable topic as a destination that a producer can publish messages to. The topicName is the physical name of the destination.

To create a durable Topic on an event broker, the event broker must have an ADB installed, and it must have Guaranteed Messaging and message spooling enabled.

To consume messages published to a topic, a topic subscriber is required. Refer to Creating Durable Topic Subscribers.

Creating Queues

You can call the createQueue(java.lang.String queueName) method from a Session to create a queue instance. When using Queue destinations, durable queues must be provisioned on the event broker with the same names as the Queue instance.

To create a durable Queue on an event broker, the event broker must have an ADB installed, and it must have Guaranteed Messaging and message spooling enabled.

If a physical queue has already been provisioned on the event broker (through SolAdmin or the CLI), when you call the createQueue(java.lang.String queueName) method and pass in the name of the physical queue, an instance of that queue (that is, an in-memory representation of the queue in the API) is created.
You can use SolAdmin or the Solace CLI to configure and provision a durable queue on an event broker. The default configuration parameters can be modified, as required.
If a physical queue has not already provisioned on the event broker, and the creation of dynamic durable endpoints are permitted (refer to Dynamic Durables), you can call the createQueue(java.lang.String queueName) method and pass in a queue name to dynamically create a durable physical queue on the event broker.
When a queue is dynamically created, the default queue configuration parameters are used, which results in an exclusive queue that does not provide access to users other than the queue owner. For information on all of the queue configuration parameters, refer to Configuring Queues.
To allow the creation of dynamic durable endpoints, set the InitialContext environment property SupportedProperty.SOLACE_JMS_DYNAMIC_DURABLES to true. You can also use SolAdmin or the Solace CLI to enable the equivalent JNDI Connection Factory property.

Provide feedback