Section 7.9. JMS-Based JNDI References in Web-Based Deployment Descriptors

7.9. JMS-Based JNDI References in Web-Based Deployment Descriptors

In previous chapters, we've used the web.xml file to describe and deploy Servlets and JNDI resources. Example 7-6 shows the new JMS-based JNDI references in web.xml , so that we can use the JMS ConnectionFactory and the CreditCheckQueue .

Example 7-6. web.xml

<?xml version="1.0" encoding="UTF-8"?>

<web-app  xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4">
  ...
   <resource-ref >
      <res-ref-name>jms/CreditCheckQueue</res-ref-name>
      <res-type>javax.jms.Queue</res-type>
      <res-auth>Container</res-auth>
   </resource-ref>

   <resource-ref >
      <res-ref-name>jms/MyXAQueueConnectionFactory</res-ref-name>
      <res-type>javax.jms.QueueConnectionFactory</res-type>
      <res-auth>Container</res-auth>
   </resource-ref>
  ...
</web-app>

<res-ref-name> is the JNDI name for each resource java:comp/env/jms/CreditCheckQueue and java:comp/env/jms/MyXAQueueConnectionFactory . Notice that you don't have to specify java:comp/env/ because it is the assumed prefix. The <res-type> for the CreditCheckQueue is a JMS Queue, and javax.jms.Queue is its fully qualified class name. The <res-type> for the Connection Factory is a JMS Queue Connection Factory javax.jms.QueueConnectionFactory. We want JBoss to manage our JMS resources, so you set <res-auth> to Container .

A JNDI resource links into an application only if we ask for it. JBoss binds resources under its in-JVM context, java:/ . The jboss-web.xml file provides a mapping between the J2EE-style ENC names and the local JBoss-specific JNDI names that JBoss uses to deploy JNDI-based resources. Example 7-7 shows the JMS- related JNDI references in jboss-web.xml .

Example 7-7. jboss-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 2.4//EN"
"http://www.jboss.org/j2ee/dtd/jboss-web_4_0.dtd">

<jboss-web>
  ...
   <resource-ref>
      <res-ref-name>jms/CreditCheckQueue</res-ref-name>
      <jndi-name>queue/CreditCheckQueue</jndi-name>
   </resource-ref>

   <resource-ref>
      <res-ref-name>jms/MyXAQueueConnectionFactory</res-ref-name>
      <jndi-name>java:/JmsXA</jndi-name>
   </resource-ref>
  ...
</jboss-web>

<res-ref-name> is the JNDI name for each resource wherein java:comp/env/ is the assumed prefix. The textual value of each <res-ref-name> element in jboss-web.xml MUST match the value of the <res-ref-name> in web.xml . The Queue's <jndi-name> is the local JBoss-specific JNDI name that JBoss uses to deploy a JMS Queue . You'll usually prefix queue JNDI names with queue/ and topic JNDI names with topic/ . The Queue Connection Factory's <jndi-name> is the local JBoss-specific JNDI name that JBoss uses to deploy a JMS QueueConnectionFactory , and the value java:/JmsXA indicates that this QueueConnectionFactory participates in distributed transactions. Let's take a more detailed look at JMS and its relationship to J2EE transactions.

7.9.1. JMS and Its Relationship to J2EE Transactions

When you use JMS, you can participate in either distributed or local transactions:

Local transaction

A local JMS transaction uses programmatic transaction management and only includes JMS messages in its transaction context. If any of the message send operations fail, then the transaction manager rolls back all JMS messages so they're not delivered to the JMS destination. Other resources (such as JDBC, EJB, and JCA) are not considered part of the transaction context. In this case, you'll use the JMS Session to manage the transaction, so you set the transaction flag to true , and then call the Session 's commit( ) or rollback( ) method to manage the transaction yourself. You can use a local transaction from both external and in-container clients . However, container-managed transactions are one of a J2EE container's core services, and you normally wouldn't use a local transaction within a J2EE component.

Distributed transaction

A distributed transaction (or two-phase commit) uses the JTA for container-managed transactions that include JMS and other resources, including JDBC, EJBs, and JCA in its transaction context. Any failure causes JMS messages and database updates to be rolled back. The transaction manager commits only if access to all resources was successful. Set the transaction flag to false, and use a ConnectionFactory that participates in a distributed transaction. You can use a distributed transaction only from within a J2EE container. When you get a ConnectionFactory that participates in a distributed transaction, you're actually getting an XAConnectionFactory that uses the XA two-phase commit transaction protocol.

7.9.2. Automating JMS-Related JNDI Settings in Web-Based Deployment Descriptors

As in previous chapters, we don't want to hardcode your deployment descriptors. Since the JAW Motors application uses JMS from the web tier , we need to add XDoclet tags to the Controller Servlet so that the Ant build process generates the J2EE standard ( web.xml ) and JBoss-specific ( jboss-web.xml ) web deployment descriptors, as in Example 7-8.

Example 7-8. ControllerServlet.java

/**
 * ...
 *
 * @web.resource-ref
 *  name="jms/CreditCheckQueue"
 *  type="javax.jms.Queue"
 *  auth="Container"
 *
 * @jboss.resource-ref
 *  res-ref-name="jms/CreditCheckQueue"
 *  jndi-name="queue/CreditCheckQueue"
 *
 * @web.resource-ref
 *  name="jms/MyXAQueueConnectionFactory"
 *  type="javax.jms.QueueConnectionFactory"
 *  auth="Container"
 *
 * @jboss.resource-ref
 *  res-ref-name="jms/MyXAQueueConnectionFactory"
 *  jndi-name="java:/JmsXA"
 *
 */
public class ControllerServlet extends HttpServlet
{
    ...
}

The @web.resource-ref XDoclet tags generate the <resource-ref> elements for the CreditCheckQueue and MyXAQueueConnectionFactory in web.xml , and the @jboss.resource XDoclet tags generate the corresponding <resource-ref> elements in jboss-web.xml .

At this point, we've written code to send a JMS message and added JMS-based JNDI references to your web deployment descriptors. To complete the deployment, we'll deploy our Queue on JBoss.