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. This opens the JNDI panel for the selected realm. 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 display will show a 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 renders 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:
Viewing / Editing JNDI Settings
You can view and edit JNDI settings using the JNDI tab. With this tab you can also add new properties to existing JNDI entries.
Viewing JNDI Settings of a connection factory
To view the JNDI settings of an existing connection factory:
Select a realm node from the namespace tree, and select the
JNDI tab.
Expand the node
Topic Connection Factories to display the available connection factories.
Double-click the required connection factory to open the dialog.
The dialog displays all of the mandatory and optional JNDI parameters in tabular format. The mandatory parameters are shown at the start of the dialog, and must always be present and contain a value. The optional parameters are parameters that are not required by JNDI, but which you can define for your own purposes. The optional parameters are listed under the heading Optional Parameter. The image below shows an example of JNDI settings for a connection factory.
Editing JNDI Settings of a connection factory
The dialog described above in the section Viewing JNDI Settings of a connection factory allows you to edit the values displayed. To edit a value, move the cursor to the appropriate field and enter a new value. The following general rules apply:
For mandatory parameters, you can edit the value but not the name.
For optional parameters, you can change the parameter's key, value and data type.
When you have finished making your edits, confirm the changes and close the dialog.
The edits you have just made cause an event containing the new JNDI settings to be published on the /naming/defaultContext channel. Also, the old event on the /naming/defaultContext channel containing the previous JNDI settings will be purged automatically.
Adding a New JNDI Parameter for a connection factory
In the view/edit dialog described above, there is a panel Property Input. This panel allows you to enter new optional JNDI settings for the connection factory, consisting of a key, value and data type.
To add a new optional setting, enter values for each of the key, value and data type fields, then click Add. A new row containing the definition will be added in the Optional Parameter table.
When you have finished adding new optional settings, confirm the changes and close the dialog.
The edits you have just made cause an event containing the new JNDI settings to be published on the /naming/defaultContext channel. Also, the old event on the /naming/defaultContext channel containing the previous JNDI settings will be purged automatically.
Viewing JNDI settings using Channel Snoop
As described above, JNDI settings are stored as events on the
/naming/defaultContext channel. You can use the
Channel Snoop feature (see the section
Channel Snoop) to view the individual events on the
/naming/defaultContext channel.
To view the individual events, first select the /naming/defaultContext channel within the Enterprise Manager namespace, then select the Snoop tab. In the Snoop display, click Start. Now you will see the events representing the JNDI entries that have been created. By selecting any event 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.
Note:
In most cases, Channel Snoop allows you not only to
view events on any channel but also
edit them (using the "edit and republish" feature). However, in the particular case of the
/naming/defaultContext channel, the "edit and republish" feature for editing JNDI settings has been disabled. If you wish to edit JNDI settings in the
/naming/defaultContext channel, you can ONLY do this via the
JNDI tab, as described above in the section
Viewing / Editing JNDI Settings.
The image below shows an example of the Topic Connection Factory created earlier using the JNDI panel:
Note:
If an old event on the /naming/defaultContext channel has been purged (as a result of the JNDI editing mechanism as described above) while you are viewing the Snoop display, you need to select Stop and then Start again to see the changes in the Snoop display.
