Learn how to use JNDI and a Create Destination Identifier to look up a message destination.
For information about how to configure JMS resources, see Understanding JMS Resource Configurationin Administering JMS Resources for Oracle WebLogic Server
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(
Topic topic = (Topic) context.lookup(
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
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
topicName strings is not defined by the JMS specification. For WebLogic JMS, the syntax is described here:
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.
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
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
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:
When a local JNDI name is configured:
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 the
createTopicmethod using CDI:
When using the default CDI, a string defined by:
When using the default CDI in an interop module, a string defined by:
When a custom CDI is configured, a string defined by:
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
Destination_Name (for example,
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:
For an individual member of a UDD hosted on a set of individually configured JMS servers, a string defined by:
For an individual member of a UDD hosted on a cluster targeted JMS server, a string defined by:
wl-server-namein 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
This section provides an example of how to reference a UDD member using
createTopic using CDI:
For an individual member when CDI is not configured, a string defined by:
For an individual member when CDI is configured, a string defined by:
A logical UDD is referenced using a string defined by:
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
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:
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 the
createTopicmethod with and without using CDI:
There is no option for accessing a WDD logical name using the
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.