Integration with JNDI

Universal Messaging supports integration with JNDI through its own provider for JNDI. Universal Messaging's provider for JNDI enables clients using Universal Messaging Provider for JMS to locate references to JMS administered objects.

As with all Java APIs that interface with host systems, JNDI is independent of the system's underlying implementation. In the case of the Universal Messaging product, the JNDI provider stores object references in the Universal Messaging channel /naming/defaultContext, which is the channel representing the Universal Messaging Initial Context for JNDI, and locates the references to the objects using a channel iterator. Note that if a realm is part of a cluster, the channel will be created on all cluster realm servers. This ensures that any object references bound into the context are available on each realm server in the cluster. See the section “Creating The Initial Context” for information about how and when the channel for the Initial Context is created.

Setting Up the Context and Connection Factories for JNDI

The provider for JNDI can be managed using the Enterprise Manager tool, by selecting any realm node from the namespace tree, and then clicking on the JNDI tab in the right hand panel. The JNDI panel enables the creation of the provider and Initial Context for JNDI, and of TopicConnectionFactory and QueueConnectionFactory references for JMS, as well as references to Topics and Queues.

Creating The Initial Context

When you select a realm node from the namespace tree, one of the tabs on the right hand side of the Enterprise Manager will be labelled JNDI.

Selecting this tab will display the default JNDI panel for a realm.

If the Universal Messaging channel /naming/defaultContext has not been created yet, you will be prompted to create it.

The Initial Context uses the (potentially clustered) Universal Messaging context channel to store all JNDI references. This channel is called /naming/defaultContext. When the channel is initially created, full permissions are assigned to the first client who creates it and to all other users and clients who wish to use the channel.

Removing/destroying the Initial Context is as simple as deleting the /naming/defaultContext channel. This will of course result in the loss of all existing JNDI references (so make sure you don't accidentally delete this channel).

If the Initial Context no longer exists, then clicking the Create JNDI context button at the bottom of the screen will recreate it (though it will not contain any of its previous JNDI entries/references).

Viewing the JNDI Namespace

Whenever you open the JNDI Panel, Enterprise Manager will enable display of the JNDI Namespace. The JNDI Namespace is displayed as a tree structure within the Namespace section of the panel. The root of this tree will be the JNDI Provider URL.

In the case of a cluster, the comma-separated list of RNAME values for each server in the cluster.

If you are using a horizontal scalability connection factory, the URL syntax allows you to specify multiple connection URLs, where each connection URL can specify either a standalone realm or a cluster.

The JNDI namespace tree will render 6 "folders":

Connection Factories

Queue Connection Factories

Queues

Topic Connection Factories

Topics

XA Connection Factories

The image below shows this view after the JNDI panel has been loaded with the JNDI namespace tree expanded:

You can also use the Refresh button to update the contents of the JNDI namespace tree with any changes done outside the current instance of the Enterprise Manager.

Creating Connection Factories

By using a connection factory you can connect to both topics and queues. With a topic connection factory (see description below) you connect only to topics, and with a queue connection factory (also described below) you connect to queues. Normally connection factories can be used as a more generic replacement for both topic connection factories and queue connection factories.

How to create a connection factory

To create a connection factory, proceed as follows:

1. Select the node Connection Factories and open the context menu of this node.

2. In the dialog, supply a name to be displayed for the new connection factory, for example "connectionFactory2". Also provide a connection URL, for example "nsp://localhost:9000".

You can specify a cluster of realms by specifying a comma-separated list of connection URLs, for example "nsp://localhost:9000,nsp://localhost:9010".

I f you want to use a horizontal scalability connection factory, you can specify several connection URLs, where each connection URL can point to a standalone realm or a cluster. In this case, each connection URL is bounded by a set of round brackets - "(" and ")".

Examples:

(UM1)(UM2)(UM3)(UM4) - Indicates 4 standalone realms, namely UM1, UM2, UM3 and UM4, so 4 connections will be constructed here.

(UM1,UM2)(UM3,UM4) - Indicates 2 clusters, one consisting of UM1 and UM2 and the other consisting of UM3 and UM4, so only 2 connections will be constructed here.

(UM1)(UM2,UM3)(UM4) - Indicates one cluster consisting of UM2 and UM3, and two standalone realms, namely UM1 and UM4. A total of 3 connections will be constructed here

For the round-robin URL syntax, the following rules apply:

Each set of brackets must contain at least one valid connection URL.

There is no limit on the number of sets of brackets in the URL.

Each set of bracket indicates a unique connection, and the realm names within each sets of brackets will be supplied unchanged to the underlying implementation.

3. Use the dropdown list to select the appropriate durable type for durable consumers for topics that can be created using this connection factory.

The following durable types are supported:

Named: There can be only one active consumer at a time.

Shared: Multiple durable consumers can connect to the same durable subscription and can consume messages in a round-robin manner.

Shared-Queued: Multiple durable consumers can connect to the same durable subscription and can consume messages in a round-robin manner using a queue-based durable.

Serial: Multiple durable consumers can connect to the same durable subscription and can consume messages in a serial manner.

Priority: Multiple consumers can connect to the same durable subscription but there can be only one active consumer at any one time.

Durable subscribers can be defined only for topics; they are not available for queues.

4. Click OK to save your changes and close the dialog.

Editing Connection Factories

To edit an existing connection factory, proceed as follows:

1. Expand the node Connection Factories to display the available connection factories. Then double-click the required connection factory to open the edit dialog.

2. Make your changes in the dialog.

3. Click OK to save your changes and close the dialog.

Creating Topic and Queue Connection Factories

In order to allow JMS clients to use the Universal Messaging Context Factory to reference objects via JNDI, we first of all need to create Topic and Queue connection factories.

To create a topic connection factory, proceed as follows:

1. Select the tree node labelled Topic Connection Factories and select the menu option New Topic Connection Factory.

2. In the dialog, supply a name for the connection factory. Enter any name (in this example, we will use the name TopicConnectionFactory). Also provide a connection URL, for example "nsp://localhost:9000".

3. Select the desired durable type from the dropdown list.

4. Click OK to save your changes and close the dialog.

You will see that a new node has been created under the Topic Connection Factories folder with the name that you entered. The image below shows the JNDI namespace with a newly created topic connection factory:

The Topic Connection Factory object you just created is actually stored as an event, published onto the /naming/defaultContext channel. This event is what will be referenced by JMS clients when they attempt to find the details for the connection factory.

To create a queue connection factory, proceed as follows:

1. Select the tree node labelled Queue Connection Factories and select the menu option New Queue Connection Factory.

2. In the dialog, supply a name for the connection factory. Also provide a connection URL, for example "nsp://localhost:9000".

3. Click OK to save your changes and close the dialog.

You will see that a new node has been created under the Queue Connection Factories folder with the name that you entered.

Note: Durable types are only applicable to topics or normal connection factories.

Creating References to Topics and Queues

When JMS clients use the Universal Messaging Initial Context for JNDI, they also reference the topics and queues from the same Initial Context. In order for these clients to access these objects we need to create references to each topic and queue. Creating such references will also create the underlying channel or queue if it does not already exist; note that channels or queues created in this way will have the same default permissions as channels or queues created manually.

In this example, we will add a new topic into the JNDI namespace that corresponds to a Universal Messaging channel that already exists as a cluster channel. To do this, first, right-click on the folder called Topics within the JNDI namespace, and select the menu option New Topic. If we enter the name GlobalOrderStatus, then a new object will be created under the Topics folder called GlobalOrderStatus. This is because, under the covers, a corresponding event was published to the/naming/defaultContext channel. JMS clients can thus look up the reference to this topic (channel) and begin using it within their application. The following image shows the newly created Topic within the JNDI namespace for the existing topic GlobalOrderStatus:

Once we have created both the topic connection factory and the topic, we can snoop (see Channel Snoop) the /naming/defaultContext channel to view the individual events that represent these references. If you click the /naming/defaultContext channel within the Enterprise Manager namespace, then the Snoop panel, and click Start, you will see the events representing the JNDI entries that have been created. By selecting any of the events you will see the content of each event on the channel and the corresponding JNDI context information given to the JMS applications that will require it.

The image below shows an example of the Topic Connection Factory created earlier using the JNDI panel: