C How to Lookup a Destination

This chapter describes how to use JNDI and a Create Destination Identifier to look up a message destination.

Note:

For information on how to configure JMS resources, see "Understanding JMS Resource Configuration" in 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(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 Lookup 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 Chapter 8, "Using JMS Module Helper to Manage Applications."

Default WebLogic CDI Syntax

A string which contains a JMS server name, module, and the destination configuration name. See Examples of Syntax Used to Lookup Destinations.

Custom WebLogic CDI Syntax

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.

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 Lookup 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 aren't 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 createQueue or createTopic 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

Notes:

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 prior to WebLogic 9.0, 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 logical UDD, a string defined by:

    jms-server-name@udd-jndi-name

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

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

CDI Syntax for WDDs

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

  • There is no option for accessing a WDD logical name using createQueue() or 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.