Summary

When Process Commander is deployed as an enterprise application, you deploy JMS listeners as message-driven beans (MDBs) within the application. These MDBs route incoming messages to the appropriate JMS service rule.

Use the JMS MDB listener form to generate a definition of the MDB for inclusion in the Process Commander EJB deployment descriptor. After you define the listener in the JMS MDB listener form, click the Update Deployment Descriptor button. This generates an updated Process Commander EJB deployment descriptor file (ejb-jar.xml). If Process Commander cannot generate the EJB deployment descriptor file, it instead generates a descriptor fragment that describes the MDB, which you must manually insert into the EJB deployment descriptor file. Process Commander generates a descriptor fragment, rather than a complete descriptor file, if one of the following occurs:

• Process Commander is deployed on a server that does not support the use of EJBs, such as Apache Tomcat.
• The EJB deployment descriptor file already contains a fragment for the JMS MDB listener.

Once you update the EJB deployment descriptor file, use your application server deployment tools to bind the new MDB definition to the application server JMS resources and redeploy the application.

Suggested Approach

Complete the steps in the following procedures.

Before you Begin

Before you begin, do the following:

• Use the Admin Console of the application server to configure the JMS connection factory and destination that holds the messages the MDB will route to the JMS service.
• Complete any other configuration tasks required by the application server. For example, if the application server is WebSphere, you must create an Activation Spec and create or identify a JMS Queue Connection Factory.
• If the messages consumed by the service will have a destination specified in their JMSReplyTo header fields, configure a resource reference for the connection factory and destination in the Process Commander deployment descriptor (ejb-jar.xml). For instructions, see How to configure a JMS service or connector to find JMS resources through resource references.

Run the Service Accelerator

Run the Service Accelerator to create the JMS service. Complete the procedure in Creating Services with the Service Accelerator with the following extra instructions:

• In the Select Service Purpose form, select MDB Listener. Also, select Resource References in the Resource Name Resolution field.
• The accelerator does not display resource reference values in its fields. Therefore, on the New Service Listener form, enter placeholder strings in the following fields (you edit them in the next step):
• • Response Destination Name
  • Response Destination Factory

Edit the Listener and Generate the Deployment Descriptor Fragment

After the accelerator generates the MDB listener, open it and complete the following steps:

1. On the Listener Properties tab, verify that the Container-managed transactions option is selected or cleared, as appropriate.

   With the Container-managed transaction option selected, Process Commander generates a deployment descriptor for the listener (MDB) with transaction attributes that cause message redelivery in the case of processing failure.

2. If your system is a multiple-node cluster, determine which node(s) should run the listener. Specify each node on the Listener tab of the JMS MDB listener data object. You must deploy the MDB on each specified node.
3. On the JMS Properties tab of the JMS listener, configure the ReplyTo connection, if necessary. Replace the strings you entered for Response Destination Name and Response Destination Factory in the accelerator form with values from the drop-down lists.
4. If the Connection Factory for the response destination must connect as an authenticated user, enter values in the Factory Username and Factory Password fields.
5. Click Update Deployment Descriptor.
6. If Process Commander generated the ejb-jar.xml file successfully, copy the file from the export directory to your workstation. If Process Commander instead generated a descriptor fragment, download the generated fragment (an XML file) to your workstation.

Note: To generate the descriptor file, the system must have internet access. After Process Commander generates the descriptor file, a parser compares the descriptor against the ejb-jar.xml DTD, located at http://java.sun.com. If the system does not have internet access, or is blocked by a firewall, Process Commander instead generates a descriptor fragment.

Update the Process Commander Deployment Descriptor File

1. On the Process Commander system, use your application server deployment tools to undeploy the prpc.ear file.
2. Unzip the prpc.ear file to a location that you have access to.
3. Locate and unzip the prbeans.jar file.

If Process Commander generated the ejb-jar.xml file, replace the ejb-jar.xml file from the prbeans.jar file with your updated copy. Otherwise, continue with step 4 to update the existing ejb-jar.xml file with the generated descriptor fragment.

4. Open the ejb-jar.xml file from the jar in a text editor and scroll to the message-driven beans subsection of the enterprise-beans section.
5. Insert the first part of the generated deployment descriptor fragment — the message-driven node statement.
6. At the end of the assembly-descriptor section, insert the second part of the generated fragment — the container-transaction node statement.
7. Save the ejb-jar.xml file.

Bind the MDB Resource References to Application Server Resources

Use the process identified by the application server vendor to bind the MDB resource references -- the reference to the message-driven destination and the ejb-local-ref for EngineBMT and Engine CMT -- to the JMS resources in the application server.

• For WebSphere, you use application server deployment tools to bind the new resource references to the JNDI names of the JMS resources.
• For WebLogic, you use the documented procedures provided by BEA to update or modify the weblogic-ejb-jar.xml deployment descriptor (located in the prbeans.jar file) to specify the JNDI names of the JMS resources.

Deploy Process Commander

1. Using your application server deployment tools, repackage the prbeans.jar and Process Commander EAR files.
2. Redeploy the Process Commander application.

 Note: Be sure to deploy the MDB on each Process Commander node that you specified on the Listener Properties tab of the JMS MDB listener form.

Examples

Example of Generated Deployment Descriptor Fragments

Following is the generated deployment descriptor fragment for an MDB JMS listener named TestMDBListener. It is enabled for container-managed transactions, as indicated by the UseCMT environment entry, which is set to true.

<!-- include the following fragment into the enterprise-beans node of the ejb-jar.xml -->
<message-driven id="MessageDriven_TestMDBListener">
  <description>Message Driven Bean for JMS Listener TestMDBListener</description>
  <ejb-name>TestMDBListener</ejb-name>
  <ejb-class>com.pega.pegarules.etier.mdb.PRJMSListener</ejb-class>
  <transaction-type>Container</transaction-type>
  <message-driven-destination id="MessageDrivenDestination_TestQueue">
    <destination-type>javax.jms.Queue</destination-type>
  </message-driven-destination>
  <env-entry>
    <env-entry-name>PRListener</env-entry-name>
    <env-entry-type>java.lang.String</env-entry-type>
    <env-entry-value>TestMDBListener</env-entry-value>
  </env-entry>
  <env-entry>
    <env-entry-name>UseCMT</env-entry-name>
    <env-entry-type>java.lang.String</env-entry-type>
    <env-entry-value>true</env-entry-value>
  </env-entry>
  <ejb-local-ref id="EJBLocalRef_TestMDBListener_EngineBMTLocal">
    <description></description>
    <ejb-ref-name>ejb/EngineBMTLocal</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <local-home>com.pega.pegarules.etier.interfaces.EngineLocalHome</local-home>
    <local>com.pega.pegarules.etier.interfaces.EngineLocal</local>
    <ejb-link>EngineBMT</ejb-link>
  </ejb-local-ref>
  <ejb-local-ref id="EJBLocalRef_TestMDBListener_EngineCMTLocal">
    <description></description>
    <ejb-ref-name>ejb/EngineCMTLocal</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <local-home>com.pega.pegarules.etier.interfaces.EngineLocalHome</local-home>
    <local>com.pega.pegarules.etier.interfaces.EngineLocal</local>
    <ejb-link>EngineCMT</ejb-link>
  </ejb-local-ref>
</message-driven>
<!-- include the following fragment into the assembly-descriptor node of the ejb-jar.xml -->
<container-transaction>
  <method>
    <ejb-name>TestMDBListener</ejb-name>
    <method-name>onMessage</method-name>
    <method-params>
      <method-param>javax.jms.Message</method-param>
    </method-params>
  </method>
  <trans-attribute>Required</trans-attribute>
</container-transaction>

Example Component Description: WebLogic

Following is an example of what the component description from the weblogic-ejb-jar.xml file that identifies the JMS MDB described in the example fragments might look like after you finished binding the references to the JMS resources.

In this example, the name of the Process Commander MDB is TestMDBListener and the JNDI name of the queue is JMSTest_ServiceClient.

<weblogic-enterprise-bean>
  <ejb-name>TestMDBListener</ejb-name>
  <message-driven-descriptor>
    <destination-jndi-name>JMSTest_ServiceClient</destination-jndi-name>
  </message-driven-descriptor>
  <reference-descriptor>
    <ejb-local-reference-description>
      <ejb-ref-name>ejb/EngineBMTLocal</ejb-ref-name>
      <jndi-name>ejb/EngineBMTLocal</jndi-name>
    </ejb-local-reference-description>
    <ejb-local-reference-description>
      <ejb-ref-name>ejb/EngineCMTLocal</ejb-ref-name>
      <jndi-name>ejb/EngineCMTLocal</jndi-name>
    </ejb-local-reference-description>
  </reference-descriptor>
  <enable-call-by-reference>True</enable-call-by-reference>
  <jndi-name>TestMDBListener</jndi-name>
</weblogic-enterprise-bean>

Example Component Description: WebSphere

Following is an example of what the component description from the ibm-ejb-jar-bnd.xml file that identifies the JMS MDB described in the example fragments might look like after you finished binding the references to the JMS resources.

In this example, the name of the Process Commander MDB is TestMDBListener and the name of the WebSphere activation spec that identifies the queue is MDBActivation.

<ejbBindings xmi:type="ejbbnd:MessageDrivenBeanBinding"
xmi:id="MessageDrivenBeanBinding_TestMDBListener" activationSpecJndiName="MDBActivation">
  <enterpriseBean xmi:type="ejb:MessageDriven" href="https://docs-previous.pega.com/META-INF/ejb-jar.xml#MessageDriven_TestMDBListener"/>
  <ejbRefBindings xmi:id="EjbRefBinding_TestMDBListener_1" jndiName="ejb/PREngineBMT">
    <bindingEjbRef xmi:type="common:EJBLocalRef" href="https://docs-previous.pega.com/META-INF/ejb-jar.xml#EJBLocalRef_TestMDBListener_EngineBMTLocal"/>
  </ejbRefBindings>
  <ejbRefBindings xmi:id="EjbRefBinding_TestMDBListener_2" jndiName="ejb/PREngineCMT">
    <bindingEjbRef xmi:type="common:EJBLocalRef" href="https://docs-previous.pega.com/META-INF/ejb-jar.xml#EJBLocalRef_TestMDBListener_EngineCMTLocal"/>
  </ejbRefBindings>
</ejbBindings>

Example Component Description: Oracle Application Server

Following is an example of what the component description from the orion-ejb-jar.xml file that identifies the JMS MDB described in the example fragments might look like after you finished binding the references to the JMS resources. In this example, the name of the Process Commander MDB is TestMDBListener and the JNDI name of the queue is JMSTest_TestQueue and the name of the connection factory is JMSTest_TestQCF.  

<message-driven-deployment name="TestMDBListener" destination-location="JMSTest_TestQueue" connection-factory-location="JMSTest_TestQCF">
  <ejb-ref-mapping name="ejb/EngineBMTLocal" location="ejb/PREngineBMTLocal" />
  <ejb-ref-mapping name="ejb/EngineCMTLocal" location="ejb/PREngineCMTLocal" />
</message-driven-deployment>

Example Component Description: JBOSS Application Server

Following is an example (for JBoss 4.3 EAP) of the component description from the jboss.xml file (present inside prpc_j2ee14_jbossJBM\prbeans\META-INF). This file identifies the JMS MDB described in the example fragments and binds the references to the JMS resources. In this example, the name of the Process Commander MDB is TestMDBListener and the JNDI name of the queue is queue/testmdbqueue. 

<message-driven>
            <ejb-name>TestMDBListener</ejb-name>
            <destination-jndi-name>queue/testmdbqueue</destination-jndi-name>
   <ejb-local-ref>
         <ejb-ref-name>ejb/EngineBMTLocal</ejb-ref-name>
         <local-jndi-name>ejb/PREngineBMTLocal</local-jndi-name>
   </ejb-local-ref>
   <ejb-local-ref>
         <ejb-ref-name>ejb/EngineCMTLocal</ejb-ref-name>
         <local-jndi-name>ejb/PREngineCMTLocal</local-jndi-name>
   </ejb-local-ref>
</message-driven>