7    A Simple J2EE^TM Application that Uses the JMS API

This chapter explains how to write, compile, package, deploy, and run a simple J2EE^TM application that uses the JMS API. The application in this chapter uses the following components:

• An application client that sends several messages to a queue
• A message-driven bean that asynchronously receives and processes the messages

The chapter covers the following topics:

• Writing and compiling the application components
• Creating and packaging the application
• Deploying and running the application

If you downloaded the tutorial examples as described in the preface, you will find the source code files for this chapter in jms_tutorial/examples/client_mdb (on UNIX® systems) or jms_tutorial\examples\client_mdb (on Microsoft Windows systems). The directory ear_files in the examples directory contains a built application called SampleMDBApp.ear. If you run into difficulty at any time, you can open this file in the deploytool and compare that file to your own version.

7.1   Writing and Compiling the Application Components

The first and simplest application contains the following components:

• An application client that sends several messages to a queue
• A message-driven bean that asynchronously receives and processes the messages

Figure 7.1 illustrates the structure of this application.

Figure 7.1   A Simple J2EE Application: Client to Message-Driven Bean

The application client sends messages to the queue, which is created administratively, using the j2eeadmin command. The JMS provider--in this case, the J2EE server--delivers the messages to the message-driven bean instances, which then process the messages.

Writing and compiling the components of this application involve

• Coding the application client
• Coding the message-driven bean
• Compiling the source files

7.1.1   Coding the Application Client: SimpleClient.java

The application client class, SimpleClient.java, is almost identical to SimpleQueueSender.java. The only significant differences are as follows.

• You do not specify the queue name on the command line. Instead, the client obtains the queue name through a Java^TM Naming and Directory Interface^TM (JNDI) API lookup.
• You do not specify the number of messages on the command line; the number of messages is set at 3 for simplicity, and no end-of-messages message is sent.
• The JNDI API lookup uses the java:/comp/env/jms naming context.

7.1.2   Coding the Message-Driven Bean: MessageBean.java

The message-driven bean class, MessageBean.java, implements the methods setMessageDrivenContext, ejbCreate, onMessage, and ejbRemove. The onMessage method, almost identical to that of TextListener.java, casts the incoming message to a TextMessage and displays the text. The only significant difference is that it calls the MessageDrivenContext.setRollbackOnly method in case of an exception. This method rolls back the transaction so that the message will be redelivered.

7.1.3   Compiling the Source Files

To compile the files in the application, go to the client_mdb directory and do the following.

1. Make sure that you have set the environment variables shown in Table 4.1: JAVA_HOME, J2EE_HOME, CLASSPATH, and PATH.
2. At a command line prompt, compile the source files:

   javac *.java
   

7.2   Creating and Packaging the Application

Creating and packaging this application involve several steps:

1. Starting the J2EE server and the Application Deployment Tool
2. Creating a queue
3. Creating the J2EE application
4. Packaging the application client
5. Packaging the message-driven bean
6. Checking the JNDI API names ("JNDI names")

7.2.1   Starting the J2EE Server and the Deploytool

Before you can create and package the application, you must start the J2EE server and the deploytool. Follow these steps.

1. At the command line prompt, start the J2EE server:

   j2ee -verbose
   

   Wait until the server displays the message "J2EE server startup complete."

   (To stop the server, type j2ee -stop.)

2. At another command line prompt, start the deploytool:

   deploytool
   

   (To access the tool's context-sensitive help, press F1.)

7.2.2   Creating a Queue

In Section 4.2.4, "Creating the JMS Administered Objects," you used the j2eeadmin command to create a queue. This time, you will create it by using the deploytool, as follows.

1. In the deploytool, select the Tools menu.
2. From the Tools menu, choose Server Configuration.
3. Under the JMS folder, select Destinations.
4. In the JMS Queue Destinations area, click Add.
5. In the text field, enter jms/MyQueue. (We will observe the J2EE convention of placing the queue in the jms namespace.)
6. Click OK.
7. Verify that the queue was created:

   j2eeadmin -listJmsDestination
   

7.2.3   Creating the J2EE Application

Create a new J2EE application called MDBApp and store it in the file named MDBApp.ear. Follow these steps.

1. In the deploytool, select the File menu.
2. From the File menu, choose New -> Application.
3. Click Browse next to the Application File Name field and use the file chooser to locate the directory client_mdb.
4. In the File Name field, enter MDBApp.
5. Click New Application.
6. Click OK.

A diamond icon labeled MDBApp appears in the tree view on the left side of the deploytool window. The full path name of MDBApp.ear appears in the General tabbed pane on the right side.

7.2.4   Packaging the Application Client

In this section, you will run the New Application Client Wizard of the deploytool to package the application client. The New Application Client Wizard does the following:

• Identifies the application toward which the client is targeted
• Identifies the main class for the application client
• Identifies the queue and the connection factory referenced by the application client

To start the New Application Client Wizard, follow these steps.

1. In the tree view, select MDBApp.
2. From the File menu, choose New -> Application Client. The wizard displays a series of dialog boxes.

7.2.4.1   Introduction Dialog Box

1. Read this explanatory text for an overview of the wizard's features.
2. Click Next.

7.2.4.2   JAR File Contents Dialog Box

1. In the combo box labeled Create Archive Within Application, select MDBApp.
2. Click the Edit button next to the Contents text area.
3. In the dialog box Edit Contents of <Application Client>, choose the client_mdb directory. If the directory is not already in the Starting Directory field, type it in the field, or locate it by browsing through the Available Files tree.
4. Select SimpleClient.class from the Available Files tree area and click Add.
5. Click OK.
6. Click Next.

7.2.4.3   General Dialog Box

1. Verify that the Main Class and the Display Name are both SimpleClient.
2. In the Callback Handler Class combo box, verify that container-managed authentication is selected.
3. Click Next.

7.2.4.4   Environment Entries Dialog Box

Click Next.

7.2.4.5   Enterprise Bean References Dialog Box

Click Next.

7.2.4.6   Resource References Dialog Box

In this dialog box, you associate the JNDI API context name for the connection factory in the SimpleClient.java source file with the name of the QueueConnectionFactory. You also specify container authentication for the connection factory resource, defining the user name and the password that the user must enter in order to be able to create a connection. Follow these steps.

1. Click Add.
2. In the Coded Name field, enter jms/MyQueueConnectionFactory--the logical name referenced by SimpleClient.
3. In the Type field, select javax.jms.QueueConnectionFactory.
4. In the Authentication field, select Container.
5. In the Sharable field, make sure that the checkbox is checked. This allows the container to optimize connections.
6. In the JNDI Name field, enter jms/QueueConnectionFactory.
7. In the User Name field, enter j2ee.
8. In the Password field, enter j2ee.
9. Click Next.

7.2.4.7   JMS Destination References Dialog Box

In this dialog box, you associate the JNDI API context name for the queue in the SimpleClient.java source file with the name of the queue you created using j2eeadmin. Follow these steps.

1. Click Add.
2. In the Coded Name field, enter jms/QueueName--the logical name referenced by SimpleClient.
3. In the Type field, select javax.jms.Queue.
4. In the JNDI Name field, enter jms/MyQueue.
5. Click Next.

7.2.4.8   Review Settings Dialog Box

1. Check the settings for the deployment descriptor.
2. Click Finish.

7.2.5   Packaging the Message-Driven Bean

In this section, you will run the New Enterprise Bean Wizard of the deploytool to perform these tasks:

• Create the bean's deployment descriptor
• Package the deployment descriptor and the bean class in an enterprise bean JAR file
• Insert the enterprise bean JAR file into the application's MDBApp.ear file

To start the New Enterprise Bean Wizard, follow these steps.

1. In the tree view, select MDBApp.
2. From the File menu, choose New -> Enterprise Bean. The wizard displays a series of dialog boxes.

7.2.5.1   Introduction Dialog Box

Click Next.

7.2.5.2   EJB JAR Dialog Box

1. In the combo box labeled JAR File Location, verify that Create New JAR File in Application and MDBApp are selected.
2. In the JAR Display Name field, verify that the name is Ejb1, the default display name. Representing the enterprise bean JAR file that contains the bean, this name will be displayed in the tree view.
3. Click the Edit button next to the Contents text area.
4. In the dialog box Edit Contents of Ejb1, choose the client_mdb directory. If the directory is not already in the Starting Directory field, type it in the field, or locate it by browsing through the Available Files tree.
5. Select the MessageBean.class file from the Available Files tree area and click Add.
6. Click OK.
7. Click Next.

7.2.5.3   General Dialog Box

1. In the Bean Type combo box, select the Message-Driven radio button.
2. Under Enterprise Bean Class, select MessageBean. The combo boxes for the local and remote interfaces are grayed out.
3. In the Enterprise Bean Name field, enter MessageBean. This name will represent the message-driven bean in the tree view. The display name does not have to be different from the bean class name.
4. Click Next.

7.2.5.4   Transaction Management Dialog Box

In this dialog box, you specify how transactions for the onMessage method should be handled. Although an ordinary enterprise bean has six possible transaction attributes, a message-driven bean has only two. (The others are meaningful only if there might be a preexisting transaction context, which doesn't exist for a message-driven bean.) Follow these steps.

1. Select the Container-Managed radio button.
2. In the Transaction Attribute field opposite the onMessage method, verify that Required is selected.
3. Click Next.

7.2.5.5   Message-Driven Bean Settings Dialog Box

In this dialog box, you specify the deployment properties for the bean. Because you are using container-managed transactions, the Acknowledgment field is grayed out. Follow these steps.

1. In the Destination Type combo box, select Queue.
2. In the Destination field, select jms/MyQueue.
3. In the Connection Factory field, select jms/QueueConnectionFactory.
4. Click Next.

7.2.5.6   Environment Entries Dialog Box

Click Next.

7.2.5.7   Enterprise Bean References Dialog Box

Click Next.

7.2.5.8   Resource References Dialog Box

Click Next. (You do not need to specify the connection factory for the message-driven bean, because it is not referred to in the message-driven bean code. You specified the connection factory in the Message-Driven Bean Settings dialog box.)

7.2.5.9   Resource Environment References Dialog Box

Click Next. (You do not need to specify the queue name here, because it is not referred to in the message-driven bean code. You specified it in the Message-Driven Bean Settings dialog box.)

7.2.5.10   Security Dialog Box

Use the default Security Identity setting for a message-driven bean, Run As Specified Role. Click Next.

7.2.5.11   Review Settings Dialog Box

1. Check the settings for the deployment descriptor.
2. Click Finish.

7.2.6   Checking the JNDI Names

Verify that the JNDI names for the application components are correct.

• You give the JNDI name of the destination--in this case, the queue--to the message-driven bean component.
• You check to make sure that the context names for the connection factory and the destination are correctly matched to their JNDI names.
• In the tree view, select the MDBApp application.
• Select the JNDI Names tabbed pane.
• Verify that the JNDI names appear as shown in Table 7.1 and Table 7.2.

Table 7.1:    Application Pane

Component Type	Component	JNDI Name
EJB	MessageBean	jms/MyQueue

Table 7.2:    References Pane

Ref. Type	Referenced By	Reference Name	JNDI Name
Resource	SimpleClient	jms/MyQueueConnectionFactory	jms/QueueConnectionFactory
Env Resource	SimpleClient	jms/QueueName	jms/MyQueue

7.3   Deploying and Running the Application

Deploying and running this application involve several steps:

1. Looking at the deployment descriptor
2. Adding the server, if necessary
3. Deploying the application
4. Running the client
5. Undeploying the application
6. Removing the application and stopping the server

7.3.1   Looking at the Deployment Descriptor

As you package an application, the deploytool creates a deployment descriptor in accordance with the packaging choices you make. To see some of the JMS API-related elements of the enterprise bean deployment descriptor, follow these steps.

1. Select Ejb1 in the tree view.
2. Choose Descriptor Viewer from the Tools menu.
3. Select SimpleClient in the tree view and repeat step 2.

In the Deployment Descriptor Viewer window, click Save As if you want to save the contents as an XML file for future reference. Table 7.3 describes the elements that are related to the JMS API.

Table 7.3:    JMS API-Related Deployment Descriptor Elements

Element Name	Description
<message-driven>	Declares a message-driven bean.
<message-selector>	Specifies the JMS API message selector to be used in determining which messages a message-driven bean is to receive.
<message-driven-destination>	Tells the Deployer whether a message-driven bean is intended for a queue or a topic, and if it is intended for a topic, whether the subscription is durable. Contains the element <destination-type> and optionally, for topics, <subscription-durability>.
<destination-type>	Specifies the type of the JMS API destination (either javax.jms.Queue or javax.jms.Topic). In this case, the value is javax.jms.Queue.
<subscription-durability>	Optionally specifies whether a topic subscription is intended to be durable or nondurable.
<resource-env-ref>	Declares an enterprise bean's reference to an administered object associated with a resource in the enterprise bean's environment--in this case, a JMS API destination. Contains the elements <resource-env-ref-name> and <resource-env-ref-type>.
<resource-env-ref-name>	Specifies the name of a resource environment reference; its value is the environment entry name used in the enterprise bean code--in this case, jms/QueueName.
<resource-env-ref-type>	Specifies the type of a resource environment reference--in this case, javax.jms.Queue.
<resource-ref>	Contains a declaration of the enterprise bean's reference to an external resource--in this case, a JMS API connection factory. Contains the elements <res-ref-name>, <res-type>, and <res-auth>.
<res-ref-name>	Specifies the name of a resource manager connection factory reference--in this case, jms/MyQueueConnectionFactory.
<res-type>	Specifies the type of the data source--in this case, javax.jms.QueueConnectionFactory.
<res-auth>	Specifies whether the enterprise bean code signs on programmatically to the resource manager (Application) or whether the Container will sign on to the resource manager on behalf of the bean. In the latter case, the Container uses information that is supplied by the Deployer.
<res-sharing-scope>	Specifies whether connections obtained through the given resource manager connection factory reference can be shared. In this case, the value is Shareable.

7.3.2   Adding the Server

Before you can deploy the application, you must make available to the deploytool the J2EE server you started in Section 7.2.1, "Starting the J2EE Server and the Deploytool." Because you started the J2EE server before you started the deploytool, the server, named localhost, probably appears in the tree under Servers. If it does not, do the following.

1. From the File menu, choose Add Server.
2. In the Add Server dialog box, enter localhost in the Server Name field.
3. Click OK. A localhost node appears under Servers in the tree view.

7.3.3   Deploying the Application

You have now created an application that consists of an application client and a message-driven bean. To deploy the application, perform the following steps.

1. From the File menu, choose Save to save the application.
2. From the Tools menu, choose Deploy.
3. In the Introduction dialog box, verify that the Object to Deploy selection is MDBApp and that the Target Server selection is localhost.
4. Click Next.
5. In the JNDI Names dialog box, verify that the JNDI names are correct.
6. Click Next.
7. Click Finish.
8. In the Deployment Progress dialog box, click OK when the "Deployment of MDBApp is complete" message appears.
9. In the tree view, expand Servers and select localhost. Verify that MDBApp is deployed.

7.3.4   Running the Client

To run the client, you use the MDBApp.ear file that you created in Section 7.2.3, "Creating the J2EE Application." Make sure that you are in the directory client_mdb. Then perform the following steps.

1. At the command line prompt, enter the following:

   runclient -client MDBApp.ear -name SimpleClient
   

2. When the Login for user: dialog box appears, enter j2ee for the user name and j2ee for the password.
3. Click OK.

The client program runs in the command window, generating output that looks like this:

Binding name:'java:comp/env/jms/QueueName'
Binding name:'java:comp/env/jms/MyQueueConnectionFactory'
Java(TM) Message Service 1.0.2 Reference Implementation (build b14)
Sending message: This is message 1
Sending message: This is message 2
Sending message: This is message 3
Unbinding name:'java:comp/env/jms/QueueName'
Unbinding name:'java:comp/env/jms/MyQueueConnectionFactory'

Output from the application appears in the window in which you started the J2EE server. By default, the server creates three instances of the MessageBean to receive messages.

In MessageBean.MessageBean()
In MessageBean.setMessageDrivenContext()
In MessageBean.ejbCreate()
MESSAGE BEAN: Message received: This is message 1
In MessageBean.MessageBean()
In MessageBean.setMessageDrivenContext()
In MessageBean.ejbCreate()
In MessageBean.MessageBean()
In MessageBean.setMessageDrivenContext()
In MessageBean.ejbCreate()
MESSAGE BEAN: Message received: This is message 2
MESSAGE BEAN: Message received: This is message 3

7.3.5   Undeploying the Application

To undeploy the J2EE application, follow these steps.

1. In the tree view, select localhost.
2. Select MDBApp in the Deployed Objects area.
3. Click Undeploy.
4. Answer Yes in the confirmation dialog.

7.3.6   Removing the Application and Stopping the Server

To remove the application from the deploytool, follow these steps.

1. Select MDBApp in the tree view.
2. Select Close from the File menu.

To delete the queue you created, enter the following at the command line prompt:

j2eeadmin -removeJmsDestination jms/MyQueue

To stop the J2EE server, use the following command:

j2ee -stop

To exit the deploytool, choose Exit from the File menu.