C How to Lookup a Destination

The following sections provide information on how to lookup a destination:

Use a JNDI Name

The recommended way to lookup a destination or member of a distributed destination is to use JNDI. You can look up a destination by establishing a JNDI context (context) and executing one of the following commands, for PTP or Pub/Sub messaging, respectively:

Queue queue = (Queue) context.lookup(Dest_name);

Topic topic = (Topic) context.lookup(Dest_name);

The Dest_name argument specifies the destination's JNDI name defined during configuration. See Step 1: Look Up a Connection Factory in JNDI.

Use a Reference

A less common method to lookup a destination or member of a distributed destination that does not use JNDI is to use one of the following QueueSession or TopicSession methods to reference a queue or topic, respectively:

Note:

The createQueue() and createTopic() methods do not create destinations dynamically; they create only references to destinations that already exist. For information about creating destinations dynamically, see Chapter 6, "Using JMS Module Helper to Manage Applications."

The value of queueName and/or topicName string is defined by:

Once the destination has been defined, you can use the following Queue or Topic method to access the queue or topic name, respectively:

public String getQueueName(
) throws JMSException

public String getTopicName(
) throws JMSException

To ensure that the queue and topic names are returned in printable format, use the toString() method.

Using the Create Destination Identifier

The Create Destination Identifier (CDI) is a reference name for a destination or a member of a distributed destination that provides a way to lookup a destination without JNDI using the standard JMS javax.jms.Session createQueue or createTopic API.

This name must be unique within the scope of the JMS server to which this destination is targeted. However, it does not need to be unique within the scope of the entire JMS module. For example, two queues can have the same CDI name as long as those queues are targeted to different JMS servers.

Note:

Since this name must be unique within the scope of a JMS server, verify whether other JMS modules may contain destination names that conflict with this name. It is the responsibility of the deployer to resolve the destination names targeted to JMS servers.

Examples of How to Lookup Destinations

The following sections provide examples on how to reference a destination or a member of a distributed destination:

Destinations

The following section provides examples how to reference destinations:

createQueue and createTopic Syntax for Destinations

This section provides an example of how to reference a destination using createQueue or createTopic with and without using CDI:

  • When CDI is not configured, a string defined by:

    JMS_Server_Name/JMS_Module_Name!Destination_Name

  • When CDI is configured, a string defined by:

    JMS_Server_Name/CDI_Name

Note:

When using server affinity, (replacing JMS_Server_Name with "."), the search is restricted to the JMS connection host rather than the entire cluster.

JNDI Syntax for Destinations

The following section provides examples how to reference destinations using JNDI:

  • When a JNDI name is configured, a string defined by:

    Dest_JNDI_Name

  • When a local JNDI name is configured:

    Dest_Local_JNDI_Name

Note:

The local JNDI name only works when the JNDI context host is on the same server as the destination. The JNDI context host is not necessarily the same as the connection host.

Uniform Distributed Destinations

The following section provides examples how to reference Uniform Distributed Destinations (UDDs):

createQueue and createTopic Syntax for UDDs

This section provides an example of how to reference a UDD member or logical UDD using createQueue or createTopic with and without using CDI:

  • For an individual member when CDI is not configured, a string defined by:

    jms-server-name)/module-name!jms-server-name@udd-name

  • For an individual member when CDI is configured, a string defined by:

    jms-server-name)/cdi-name

Note:

In the CDI case when jms-server-name is replaced with ".", the API returns the first locally available/started member of the UDQ.

JNDI Syntax for UDDs

The following section provides examples how to reference an individual member using JNDI

  • When a JNDI name is configured, a string defined by:

    dest-jndi-name

  • When a local JNDI name is configured, a string defined by:

    dest-local-jndi-name

Note:

The local JNDI name only works when the JNDI context host is on the same server as the destination. The JNDI context host is not necessarily the same as the connection host.

Referencing a Logical UDD

When referencing a logical UDD, regardless of whether CDI is configured, a string defined by: module-name!udd-name

Weighted Distributed Destinations

WDDs (Weighted Distributed Destinations) do not have a CDI parameter as this type of destination does not extend destination-type in the schema. To use the CDI, you must specify a CDI on each member destination.