|Oracle® Fusion Middleware Programming JMS for Oracle WebLogic Server
11g Release 1 (10.3.4)
Part Number E13727-04
This section describes methods for looking up a destination. It does not describe how to create them. For information on how to configure JMS resources, see "Understanding JMS Resource Configuration" in Configuring and Managing JMS for Oracle WebLogic Server.
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(
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 Chapter 7, "Using JMS Module Helper to Manage Applications."
A string which contains a JMS server name, module, and the destination configuration name. See Examples of Syntax Used to Lookup Destinations.
In addition to the default CDI syntax, WebLogic JMS provides JMSCreateDestinationIdentifier as an additional configuration parameter of a Destination or Uniform Distributed Destination. This allows you to configure a unique reference name when there are 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 disambiguating two different destinations in two different modules that have the same default CDI name. See Examples of Syntax Used to Lookup 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: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.
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.
The following sections provide examples of the syntax used to reference a destination or a member of a distributed destination:
The following section provides examples of syntax used to reference regular destinations (destinations that aren't distributed):
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:
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.
This section provides examples of the syntax used to reference a non-distributed destination using
createTopic 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:
Notes:When using server affinity, (replacing
."), the search is restricted to the JMS connection host rather than the entire cluster.
To reference destination in releases prior to WebLogic 9.0, use a string defined by
Destination_Name (for example,
The following section provides examples of the syntax used to reference Uniform Distributed Destinations (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 logical UDD, a string defined by:
Note:You can use the helper methods
uddMemberJNDINameAPIs to help create UDD CDI names in the correct syntax.
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-nameis 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.
Note:Weighted distributed destinations are deprecated in Weblogic Server 10.3.4.0. Oracle recommends using Uniform Distributed Destinations.
A weighted distributed destination is simply a set of individually configured regular destinations that each have their 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.
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.
This section provides an example of how to reference a WDD member using
createTopic with and without using CDI:
There is no option for accessing a WDD logical name using
createTopic(). A logical WDD must always be referenced using a string defined by the JNDI name of the member. Sometimes it is useful instead to lookup 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.