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 round-robin 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 round-robin 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.
For more information on round-robin connection factories, see the section
Provider for JMS in the Developer Guide.
3. Use the checkbox Shared Durable if you want the connection factory to be shared and durable (see description below).
If you select "shared durable", the topic allows "shared durable" subscriptions.
If you do not select "shared durable", the topic only allows "non-shared durable" subscriptions.
4. Click OK to save your changes and close the dialog.
A connection factory allows you to create two types of topic subscription:
Non-durable: A non-durable subscription lasts for the lifetime of its subscriber object. This means that a client will only see the messages published on a topic while its subscriber is active. If the subscriber is not active, it will miss messages published on its topic.
Durable: A durable subscription is used by an application that needs to receive all the messages published on a topic, including the ones published when there is no consumer associated with it. The JMS provider retains a record of this durable subscription and ensures that all messages from the topic's publishers are retained until they are delivered to, and acknowledged by, a consumer on the durable subscription or until they have expired.
Durable subscriptions can be of two types:
non-shared durable: A non-shared durable subscription may have only one active (i.e. not closed) consumer at any given time.
shared durable: A shared durable subscription is used by a client that needs to be able to share the work of receiving messages from a durable subscription amongst multiple consumers. A shared durable subscription may therefore have more than one consumer. Each message from the subscription will be delivered to only one of the consumers on that subscription.
Durable subscribers can be defined only for topics; they are not available for queues.
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". If you wish the connection factory to be shared and durable, mark the checkbox "Shared Durable".
3. 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: The option Shared Durable, which was described above for topic connection factories, is not available for queues.
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:
