How to Look Up a Destination

Use a JNDI Name

The recommended way to lookup any type of 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 Using a JNDI Name and Examples of Syntax Used to Look Up Destinations.

Use a Create Destination Identifier

Create Destination Identifier (CDI) is a less common method to lookup a destination or member of a distributed destination that does not use JNDI. CDI uses one of the following QueueSession or TopicSession methods to reference a queue or topic, respectively:

public Queue createQueue(
 String queueName
) throws JMSException

public Topic createTopic(
 String topicName
) throws JMSException

The syntax of the queueName and topicName strings is not defined by the JMS specification. For WebLogic JMS, the syntax is described here:

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 Using JMS Module Helper to Manage Applications.

Default WebLogic CDI Syntax

Default WebLogic CDI Syntax is a string which contains a JMS server name, module, and the destination configuration name. See Examples of Syntax Used to Look Up Destinations.

Custom WebLogic CDI Syntax

In addition to the default CDI syntax, WebLogic JMS provides the JMSCreateDestinationIdentifier as an additional configuration parameter of a Destination or Uniform Distributed Destination. This enables you to configure a unique reference name when there is more than one queue or topic defined (in one or more modules) with the same value for the default CDI syntax. In other words, it is useful for differentiating two different destinations in two different modules that have the same default CDI name. See Examples of Syntax Used to Look Up Destinations

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:

Because, 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.

Server Affinity When Looking Up Destinations

The createTopic() and createQueue() methods also allow a "./Destination_Name" syntax to indicate server affinity when looking up destinations. This will locate destinations that are locally deployed in the same JVM as the JMS connection's connection factory host. If the name is not on the local JVM an exception is thrown, even though the same name might be deployed on a different JVM.

An application might use this convention to avoid hard-coding the server name when using the createTopic() and createQueue() methods so that the code can be reused on different JMS servers without requiring any changes.

Examples of Syntax Used to Look Up Destinations

The following sections provide examples of the syntax used to reference a destination or a member of a distributed destination:

Non distributed Destinations

The following section provides examples of syntax used to reference regular destinations (destinations that are not distributed):

JNDI Syntax for Non distributed Destinations

Most applications use JNDI instead of CDI to lookup destinations. The following section provides examples of the syntax used to reference non distributed 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 non distributed destinations. The JNDI context host is not necessarily the same as the JMS connection host.

CDI Syntax for Non distributed destinations

This section provides examples of the syntax used to reference a non-distributed destination using thecreateQueue or createTopicmethod using CDI:

When using the default CDI, a string defined by:

JMS_Server_Name/JMS_Module_Name!Destination_Name
When using the default CDI in an interop module, a string defined by:

JMS_Server_Name/interop-jms!Destination_Name

When a custom 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.

To reference destination in releases earlier than WebLogic 9.0 Server , use a string defined by JMS_Server_Name!Destination_Name (for example, myjmsserver!mydestination).

Uniform Distributed Destinations

The following section provides examples of the syntax used to reference Uniform Distributed Destinations (UDDs):

JNDI Syntax for UDDs

Most applications use JNDI instead of CDI to lookup destinations. The following section provides examples how to reference an individual member or logical UDD using JNDI

For a logical UDD, a string defined by:

udd-jndi-name

For an individual member of a UDD hosted on a set of individually configured JMS servers, a string defined by:

jms-server-name@udd-jndi-name
For an individual member of a UDD hosted on a cluster targeted JMS server, a string defined by:

jms-server-name@wl-server-name@udd-jndi-name

Where the wl-server-name in this case is the configured name of a WebLogic Server in a configured cluster, or is the dynamic-server server-name-prefix appended with a server number in a dynamic cluster.

CDI Syntax for UDDs

Note:

You can use the helper methods weblogic.jms.extensions.JMSModuleHelper class uddMemberName and uddMemberJNDIName APIs to help create UDD CDI names in the correct syntax.

This section provides an example of how to reference a UDD member using createQueue or createTopic 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
A logical UDD is referenced using a string defined by: module-name!udd-name.

Note:

When jms-server-name is replaced with ".", the API returns the first locally available/started member of the UDQ. A member is considered to be locally available if the JMS client connection is hosted by the same WebLogic Server that currently hosts the member.

Weighted Distributed Destinations

Note:

Weighted distributed destinations are deprecated in Weblogic Server 10.3.4.0. Oracle recommends using Uniform Distributed Destinations.

A weighted distributed destination is a set of individually configured regular destinations that has its own JNDI and CDI name. The logical name of the WDD represents the entire set, and is configured as a JNDI name. There is no option for accessing the logical for a WDD using CDI.

JNDI Syntax for WDDs

The following section provides examples how to reference an individual member or logical WDD using JNDI:

For a logical WDD, a string defined by:

wdd-jndi-name

For an individual member logical WDD, see JNDI Syntax for Non distributed Destinations.

CDI Syntax for WDDs

This section provides an example of how to reference a WDD member using thecreateQueue or createTopicmethod with and without using CDI:

There is no option for accessing a WDD logical name using the createQueue() or createTopic() methods. A logical WDD must always be referenced using a string defined by the JNDI name of the member. Sometimes it is useful to look up the local individual member using the "." server affinity syntax for non distributed destinations.

For an individual member when CDI is configured on the member, see CDI Syntax for Non distributed destinations.