Summary

When configuring a Java Message Services connector or service, there are two ways to identify the JMS resources (connection factories, destinations, and so on) the service or connector interacts with:

• Through resource references in the Process Commander deployment descriptor file (either ejb-jar.xml or web.xml).
• By direct JNDI name lookup through a JNDI server data object (instance of Data-Admin-Connect-JNDIServer).

If you use a JNDI server data object, you can set up JMS connector or JMS listener (although not a JMS MDB listener) without having to edit the Process Commander deployment descriptor and then re-deploy Process Commander. However, using direct JNDI lookup (through a JNDI server data object) complicates the deployment process when you want to move your application from development to testing or testing to production.

The recommended way of configuring any Web or Enterprise application to locate external resources is to use resource references that are resolved by the application server that contains the application. That way, the application server takes care of the JNDI lookups and you can modify the configuration of the JMS resources without having to change the Process Commander configuration.

Additionally, if Process Commander is deployed on multiple nodes and the listeners on each node must monitor different queues or topics, you do not have to configure different listener objects. You use the resource reference in the listener and resolve the reference so it points to the appropriate queue or topic when you deploy each node.

This article describes how to configure resource references for JMS resources and then configure JMS services and connectors to use the references rather than JNDI server objects.

 Important: This article assumes that you are an experienced Process Commander developer, are familiar with J2EE application servers and the JMS API, and have experience deploying Web or Enterprise applications.

Suggested Approach

Complete the steps in the following procedures.

Create or identify the JMS connection factory and destinations (topics or queues)

If the JMS resources you need for your implementation already exist, use the administration console of your application server to determine their JNDI names.

If the JMS resources you need do not already exist, create them now. In WebLogic, you complete the following kinds of tasks:

• Create a JMS server
• Create a JMS module
• In the JMS module, create a Connection Factory and subdeployment and a queue or topic and its subdeployment. Both of them target the JMS server.

In WebSphere, you complete the following kinds of tasks:

• Create a service integration bus
• Create the JMS resources (queue or topic and connection factory)
• Create the JMS Activation Specification

Edit the Process Commander deployment descriptor file

On the Process Commander system, use your application server deployment tools to undeploy the Process Commander application and extract the deployment descriptor:

• For a Web application, the web.xml file is located in the prweb.war file.
• For an Enterprise application, the ejb-jar.xml file is located in the prbeans.jar file.

In the deployment descriptor, insert resource references for the JMS resources – the queue connection factory and the queues or topics. Note that when Process Commander is deployed as an Enterprise Application, you need to insert the resource references in both the EngineCMT section and the EngineBMT section.

For example, the following resource references could be inserted into the <session id="Session_EngineCMT"> of the ejb-jar.xml:

<resource-ref id="ResourceRef_EngineCMT_jms_qcf_DevTestQCF">
<res-ref-name>jms/qcf/DevTestQCF</res-ref-name>
<res-type>javax.jms.QueueConnectionFactory</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
<resource-ref id="ResourceRef_EngineCMT_jms_queue_DevTestRequest">
<res-ref-name>jms/queue/DevTestRequest</res-ref-name>
<res-type>javax.jms.Queue</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
<resource-ref id="ResourceRef_EngineCMT_jms_queue_DevTestResponse">
<res-ref-name>jms/queue/DevTestResponse</res-ref-name>
<res-type>javax.jms.Queue</res-type>
<res-auth>Container</res-auth>
 <res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>

And here are the matching entries for the <session id="Session_EngineBMT"> section:

<resource-ref id="ResourceRef_EngineBMT_jms_qcf_DevTestQCF">
<res-ref-name>jms/qcf/DevTestQCF   </res-ref-name>
<res-type>javax.jms.QueueConnectionFactory</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
<resource-ref id="ResourceRef_EngineBMT_jms_queue_DevTestRequest">
<res-ref-name>jms/queue/DevTestRequest</res-ref-name>
<res-type>javax.jms.Queue</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
<resource-ref id="ResourceRef_EngineBMT_jms_queue_DevTestResponse">
<res-ref-name>jms/queue/DevTestResponse</res-ref-name>
<res-type>javax.jms.Queue</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>

Redeploy Process Commander

Using the application server deployment tools, repackage the modified deployment descriptor file into the Process Commander EAR or WAR and redeploy Process Commander. The application server deployment wizard then notices the resource references and then prompt you to bind the resource references to the actual JMS resources.

Configure the JMS Listener or Connector to use the resource reference

You create the JMS service or connector as usual and select Resource Reference as the Resource Name Resolution option. Then the fields that specify JMS resources display a list of the references present in the Process Commander deployment descriptor that are appropriate for that field. That is, connection factory fields show connection factory resource references and destination fields show topic and queue resource references.

For example, the connection factory resource reference from the example now appears in the drop-down list for the Connection Factory Name field in a JMS listener form:

Here's a JMS MDB listener that uses the queue connection factory resource reference and the queue resource reference named DevTestResponse from the example to configure its Reply To connection:

Here's a JMS connector that uses the resource references from the example: