B How to Look Up a Destination

Learn how to use JNDI and a Create Destination Identifier to look up a message destination.

Note:

For information about how to configure JMS resources, see Understanding JMS Resource Configuration in Administering JMS Resources for Oracle WebLogic Server.

Use a JNDI Name

For configured destinations, JNDI lookup is the recommended approach. Given an established javax.naming.Context named context and a String named destinationJndiName containing the configured JNDI name, use the appropriate lookup statement:

jakarta.jms.Queue queue = (jakarta.jms.Queue) context.lookup(destinationJndiName);

jakarta.jms.Topic topic = (jakarta.jms.Topic) context.lookup(destinationJndiName);

The destinationJndiName value is the destination's configured JNDI name. The binding must be visible through the selected naming context. See Using a JNDI Name and Examples of Syntax Used to Look Up Destinations.

Use a Create Destination Identifier

A Create Destination Identifier (CDI) is a WebLogic-specific destination name supplied to Session.createQueue() or Session.createTopic(), instead of looking up the destination by its application-visible JNDI name. The corresponding domain-specific QueueSession and TopicSession methods are also available. The classic Session methods have these signatures: 

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:

In WebLogic JMS, these methods return references to existing destinations; they do not provision new physical queues or topics. For information about creating destinations dynamically, see Using JMS Module Helper to Manage Applications.

Default WebLogic CDI Syntax

CDI syntax depends on whether the name identifies a physical destination or a logical distributed destination. For a standalone destination in a JMS system module, the default is JMS_Server_Name/JMS_Module_Name!Destination_Name. For a logical distributed destination, use its module-qualified configuration name. See Examples of Syntax Used to Look Up Destinations.

Custom WebLogic CDI Syntax

JMSCreateDestinationIdentifier supplies a custom CDI lookup name for a destination or distributed-destination member. It replaces the default lookup identifier for that physical destination; it is not the destination's JNDI name. See Examples of Syntax Used to Look Up Destinations.

The effective CDI lookup name must be unique among destinations on the same JMS server instance, including destinations from different modules. Destinations on different JMS server instances can use the same custom identifier.

Note:

Check custom identifiers against both custom and default lookup names already used on the target JMS server. A conflicting name prevents successful destination deployment.

Server Affinity When Looking Up Destinations

Use ./ followed by the physical destination's CDI lookup identifier to restrict lookup to the WebLogic Server hosting the JMS connection. For example, use ./JMS_Module_Name!Destination_Name for a standalone system-module destination with its default identifier, or ./CDI_Name for a custom identifier. This locality is distinct from the host serving the application's JNDI context and from the connection factory's Server Affinity Enabled setting.

The lookup returns a matching started and available destination of the requested queue or topic type on that host. If more than one local JMS server has a match, no particular matching destination should be assumed. If none matches, lookup fails; it does not search other WebLogic Servers. The identifier after ./ must still identify the intended destination.

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 look up 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 shows CDI forms for a non-distributed destination using createQueue() or createTopic():

  • When using the default CDI, a string defined by:

    JMS_Server_Name/JMS_Module_Name!Destination_Name

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

    JMS_Server_Name/CDI_Name

Note:

Replacing JMS_Server_Name with . restricts CDI lookup to the JMS connection host; the remaining lookup identifier is unchanged.

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 look up destinations. The following section provides examples of 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

    Here, wl-server-name is the WebLogic Server name used to identify the JMS server instance. For a dynamic server, use its configured prefix and server number, respecting the configured starting index. The instance identity is distinct from its current hosting server after migration.

CDI Syntax for UDDs

Note:

JMSModuleHelper.uddMemberName(jmsServerName, uddName) constructs the member configuration name. JMSModuleHelper.uddMemberJNDIName(jmsServerName, uddJndiName) constructs the member JNDI name. Neither returns a complete CDI argument. For CDI, use the appropriate JMS server instance and module-qualified member name shown below.

The following forms apply to UDDs in JMS system modules. Let jms-server-instance-name be the name of the JMS server instance for the member: the JMS server name for an individually targeted server, or jms-server-name@wl-server-name for an instance of a cluster-targeted distributed JMS server. Use the actual instance identity; do not substitute a different current host name merely because the service migrates.

  • Physical member with its default CDI identifier: jms-server-instance-name/module-name!jms-server-instance-name@udd-name.

  • Physical member with a custom CDI identifier: jms-server-instance-name/cdi-name, where cdi-name is the effective custom identifier for that member.

  • Logical UDD: module-name!udd-name.

For example, for JMS server instance OrdersJMS@Managed1, system module OrdersModule, and UDD OrdersQueue, the default physical-member CDI argument is OrdersJMS@Managed1/OrdersModule!OrdersJMS@Managed1@OrdersQueue. The logical argument is OrdersModule!OrdersQueue. These are configuration names, not JNDI names.

Note:

For a physical UDD member, ./ restricts lookup to the JMS connection host. The remaining identifier must match that member's effective CDI name; with a default identifier, this includes the member-name prefix. This applies to both queues and topics. It does not request an arbitrary local member of the logical UDD. Lookup fails if there is no eligible local match.

Weighted Distributed Destinations

Note:

Weighted distributed destinations have been deprecated since WebLogic Server 10.3.4.0. Oracle recommends uniform distributed destinations.

A weighted distributed destination (WDD) groups individually configured physical destinations. Look up the logical WDD by its configured JNDI name. The logical WDD and each physical member are different destination objects; looking up a member does not return the logical WDD.

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

For a logical WDD in a JMS system module, supply module-name!wdd-name to createQueue() or createTopic(), using the WDD's configuration name and matching destination type. The logical destination must be deployed and known to the server handling the lookup. A physical member's JNDI name is not the logical WDD's CDI argument.

For an individual member, use that physical destination's default or custom CDI form. The ./ prefix can restrict physical-member lookup to the JMS connection host. See CDI Syntax for Non-Distributed Destinations.