JavaTM Message Service Tutorial
Tutorial Homepage | TOC | Prev | Next | Index

8    A J2EETM Application that Uses the JMS API with a Session Bean

This chapter explains how to write, compile, package, deploy, and run a J2EETM application that uses the JMS API in conjunction with a session bean. The application contains the following components:

The chapter covers the following topics:

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_ses_mdb (on UNIX® systems) or jms_tutorial\examples\client_ses_mdb (on Microsoft Windows systems). The directory ear_files in the examples directory contains a built application called SamplePubSubApp.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.

8.1   Writing and Compiling the Application Components

This application demonstrates how to send messages from an enterprise bean--in this case, a session bean--rather than from an application client, as in the example in Chapter 7. Figure 8.1 illustrates the structure of this application.

Figure 8.1   A J2EE Application: Client to Session Bean to Message-Driven Bean

The Publisher enterprise bean in this example is the enterprise-application equivalent of a wire-service news feed that categorizes news events into six news categories. The message-driven bean could represent a newsroom, where the Sports desk, for example, would set up a subscription for all news events pertaining to sports news.

The application client in the example obtains a handle to the Publisher enterprise bean's home interface and calls the enterprise bean's business method. The enterprise bean creates 18 text messages. For each message, it sets a String property randomly to one of six values representing the news categories and then publishes the message to a topic. The message-driven bean uses a message selector for the property to limit which of the published messages it receives.

Writing and compiling the components of the application involve

8.1.1   Coding the Application Client: MyAppClient.java

The application client program, MyAppClient.java, performs no JMS API operations and so is simpler than the client program in Chapter 7. The program obtains a handle to the Publisher enterprise bean's home interface, using the JavaTM Naming and Directory InterfaceTM (JNDI) API naming context java:comp/env. The program then creates an instance of the bean and calls the bean's business method twice.

8.1.2   Coding the Publisher Session Bean

The Publisher bean is a stateless session bean with one create method and one business method. The Publisher bean uses remote interfaces rather than local interfaces because it is accessed from outside the EJB container.

8.1.2.1   The Remote Home Interface: PublisherHome.java

The remote home interface source file is PublisherHome.java.

8.1.2.2   The Remote Interface: Publisher.java

The remote interface, Publisher.java, declares a single business method, publishNews.

8.1.2.3   The Bean Class: PublisherBean.java

The bean class, PublisherBean.java, implements the publishNews method and its helper method chooseType. The bean class also implements the required methods ejbCreate, setSessionContext, ejbRemove, ejbActivate, and ejbPassivate.

The ejbCreate method of the bean class allocates resources--in this case, by looking up the TopicConnectionFactory and the topic and creating the TopicConnection. The business method publishNews creates a TopicSession and a TopicPublisher and publishes the messages.

The ejbRemove method must deallocate the resources that were allocated by the ejbCreate method. In this case, the ejbRemove method closes the TopicConnection.

8.1.3   Coding the Message-Driven Bean: MessageBean.java

The message-driven bean class, MessageBean.java, is identical to the one in Section 7.1.2.

8.1.4   Compiling the Source Files

To compile all the files in the application, go to the directory client_ses_mdb 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

8.2   Creating and Packaging the Application

Creating and packaging this application involve several steps:

  1. Starting the J2EE server and the deploytool*
  2. Creating a topic
  3. Creating a connection factory
  4. Creating the J2EE application
  5. Packaging the application client
  6. Packaging the session bean
  7. Packaging the message-driven bean
  8. Specifying the JNDI API names ("JNDI names")

Step 1, marked with an asterisk (*), is not needed if the server and deploytool are still running.

8.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.)

8.2.2   Creating a Topic

In Section 4.3.4, "Creating the JMS Administered Objects," you used the j2eeadmin command to create a topic. This time, you will create the topic by using the deploytool. Follow these steps.

  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 Topic Destinations area, click Add.
  5. In the text field, enter jms/MyTopic. (We will observe the J2EE convention of placing the topic in the jms namespace.)
  6. Click OK.
  7. If you wish, you can verify that the topic was created: 
    j2eeadmin -listJmsDestination

8.2.3   Creating a Connection Factory

For this application, you create a new connection factory. This application will use a durable subscriber, so you need a connection factory that has a client ID. (For more information, see Section 5.2.1, "Creating Durable Subscriptions.") Follow these steps.

  1. At the command line prompt, enter the following command: 
    j2eeadmin -addJmsFactory jms/DurableTopicCF topic -props clientID=MyID
  2. Verify that the connection factory was created:
    3.  
    j2eeadmin -listJmsFactory

You can also create connection factories by using the deploytool's Server Configuration dialog.

8.2.4   Creating the J2EE Application

Create a new J2EE application called PubSubApp and store it in the file named PubSubApp.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_ses_mdb.
  4. In the File Name field, enter PubSubApp.
  5. Click New Application.
  6. Click OK.

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

8.2.5   Packaging the Application Client

In this section, you will run the New Application Client Wizard of the deploytool to package the application client. To start the New Application Client Wizard, follow these steps.

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

Click Next.

8.2.5.2   JAR File Contents Dialog Box
  1. In the combo box labeled Create Archive Within Application, select PubSubApp.
  2. Click the Edit button next to the Contents text area.
  3. In the dialog box Edit Contents of <Application Client>, choose the client_ses_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 the MyAppClient.class file from the Available Files tree area and click Add.
  5. Click OK.
  6. Click Next.
8.2.5.3   General Dialog Box
  1. In the Application Client combo box, select MyAppClient in the Main Class field, and enter MyAppClient in the Display Name field.
  2. In the Callback Handler Class combo box, verify that container-managed authentication is selected.
  3. Click Next.
8.2.5.4   Environment Entries Dialog Box

Click Next.

8.2.5.5   Enterprise Bean References Dialog Box

In this dialog box, you associate the JNDI API context name for the EJB reference in the MyAppClient.java source file with the home and remote interfaces of the Publisher enterprise bean. Follow these steps.

  1. Click Add.
  2. In the Coded Name column, enter ejb/MyEjbReference.
  3. In the Type column, select Session.
  4. In the Interfaces column, select Remote.
  5. In the Home Interface column, enter PublisherHome.
  6. In the Local/Remote Interface column, enter Publisher.
  7. In the Deployment Settings combo box, select JNDI Name. In the JNDI Name field, enter MyPublisher.
  8. Click Finish. You do not need to enter anything in the other dialog boxes.

8.2.6   Packaging the Session Bean

In this section, you will run the New Enterprise Bean Wizard of the deploytool to package the session bean. Follow these steps.

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

Click Next.

8.2.6.2   EJB JAR Dialog Box
  1. In the combo box labeled JAR File Location, verify that Create New JAR File in Application and PubSubApp 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_ses_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 files Publisher.class, PublisherBean.class, and PublisherHome.class from the Available Files tree area and click Add.
  6. Click OK.
  7. Click Next.
8.2.6.3   General Dialog Box
  1. In the Bean Type combo box, select the Session radio button.
  2. Select the Stateless radio button.
  3. In the Enterprise Bean Class combo box, select PublisherBean.
  4. In the Enterprise Bean Name field, enter PublisherEJB.
  5. In the Remote Interfaces combo box, select PublisherHome for Remote Home Interface and Publisher for Remote Interface. Ignore the Local Interfaces combo box.
  6. Click Next.
8.2.6.4   Transaction Management Dialog Box
  1. Select the Container-Managed radio button.
  2. In the Transaction Attribute field opposite the publishNews method, verify that Required is selected.
  3. Click Next.
8.2.6.5   Environment Entries Dialog Box

Click Next.

8.2.6.6   Enterprise Bean References Dialog Box

Click Next.

8.2.6.7   Resource References Dialog Box
  1. Click Add.
  2. In the Coded Name field, enter jms/MyTopicConnectionFactory.
  3. In the Type field, select javax.jms.TopicConnectionFactory.
  4. In the Authentication field, select Container.
  5. In the JNDI Name field, enter jms/DurableTopicCF.
  6. In the User Name field, enter j2ee.
  7. In the Password field, enter j2ee.
  8. Click Next.
8.2.6.8   Resource Environment References Dialog Box
  1. Click Add.
  2. In the Coded Name field, enter jms/TopicName--the logical name referenced by the PublisherBean.
  3. In the Type field, select javax.jms.Topic.
  4. In the JNDI Name field, enter jms/MyTopic.
  5. Click Next.
8.2.6.9   Security Dialog Box

Use the default Security Identity setting for a session or an entity bean, Use Caller ID. Click Next.

8.2.6.10   Review Settings Dialog Box
  1. Check the settings for the deployment descriptor.
  2. Click Finish.

8.2.7   Packaging the Message-Driven Bean

In this section, you will run the New Enterprise Bean Wizard of the deploytool to package the message-driven bean. To start the New Enterprise Bean Wizard, follow these steps.

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

Click Next.

8.2.7.2   EJB JAR Dialog Box
  1. In the combo box labeled JAR File Location, verify that Create New JAR File in Application and PubSubApp are selected.
  2. In the JAR Display Name field, verify that the name is Ejb2, the default display name.
  3. Click the Edit button next to the Contents text area.
  4. In the dialog box Edit Contents of Ejb2, choose the client_ses_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.
8.2.7.3   General Dialog Box
  1. In the Bean Type combo box, select the Message-Driven radio button.
  2. In the Enterprise Bean Class combo box, select MessageBean.
  3. In the Enterprise Bean Name field, enter MessageBean.
  4. Click Next.
8.2.7.4   Transaction Management Dialog Box
  1. Select the Container-Managed radio button.
  2. In the Transaction Type field opposite the onMessage method, verify that Required is selected.
  3. Click Next.
8.2.7.5   Message-Driven Bean Settings Dialog Box
  1. In the Destination Type combo box, select Topic.
  2. Check the Durable Subscriber checkbox.
  3. In the Subscription Name field, enter MySub.
  4. In the Destination field, select jms/MyTopic.
  5. In the Connection Factory field, select jms/DurableTopicCF.
  6. In the JMS Message Selector field, enter the following exactly as shown: 
    NewsType = 'Opinion' OR NewsType = 'Sports'

    This will cause the message-driven bean to receive only messages whose NewsType property is set to one of these values.

  7. Click Finish. You do not need to enter anything in the other dialog boxes.

8.2.8   Specifying the JNDI Names

Verify that the JNDI names are correct, and add one for the PublisherEJB component. Follow these steps.

  1. In the tree view, select the PubSubApp application.
  2. Select the JNDI Names tabbed pane.
  3. Make sure that the JNDI names appear as shown in Table 8.1 and Table 8.2. You will need to enter MyPublisher as the JNDI name for the PublisherEJB component.
Table 8.1:    Application Pane
Component Type
Component
JNDI Name
EJB
MessageBean
jms/MyTopic
EJB
PublisherEJB
MyPublisher

Table 8.2:    References Pane
Ref. Type
Referenced By
Reference Name
JNDI Name
Resource
PublisherEJB
jms/MyTopicConnectionFactory
jms/DurableTopicCF
Env Resource
PublisherEJB
jms/TopicName
jms/MyTopic
EJB Ref
MyAppClient
ejb/MyEjbReference
MyPublisher

8.3   Deploying and Running the Application

Deploying and running this application involve several steps:

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

8.3.1   Adding the Server

Before you can deploy the application, you must make available to the deploytool the J2EE server you started in Section 8.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.

8.3.2   Deploying the Application

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 PubSubApp 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 PubSubApp is complete" message appears.
  9. In the tree view, expand Servers and select localhost. Verify that PubSubApp is deployed.

8.3.3   Running the Client

To run the client, perform the following steps.

  1. At the command line prompt, enter the following: 
    runclient -client PubSubApp.ear -name MyAppClient -textauth
  2. At the login prompts, enter j2ee as the user name and j2ee as the password.
  3. Click OK.

The client program runs in the command window and has output that looks like this: 

Binding name:'java:comp/env/ejb/MyEjbReference'
Looking up EJB reference
Looked up home
Narrowed home
Got the EJB
Unbinding name:'java:comp/env/ejb/MyEjbReference'

Output from the application appears in the window in which you started the J2EE server. Suppose that the last few messages from the Publisher session bean look like this: 

PUBLISHER: Setting message text to: Item 13: Opinion
PUBLISHER: Setting message text to: Item 14: Sports
PUBLISHER: Setting message text to: Item 15: Nation/World
PUBLISHER: Setting message text to: Item 16: Living/Arts
PUBLISHER: Setting message text to: Item 17: Opinion

Because of the message selector, the last few messages received by the message-driven bean will look like this: 

MESSAGE BEAN: Message received: Item 13: Opinion
MESSAGE BEAN: Message received: Item 14: Sports
MESSAGE BEAN: Message received: Item 17: Opinion

8.3.4   Undeploying the Application

To undeploy the J2EE application, follow these steps.

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

8.3.5   Removing the Application and Stopping the Server

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

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

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

j2eeadmin -removeJmsDestination jms/MyTopic

To delete the connection factory you created, enter the following: 

j2eeadmin -removeJmsFactory jms/DurableTopicCF

To stop the J2EE server, use the following command: 

j2ee -stop


TOC | Prev | Next | Index

This Tutorial contains information on the 1.3.1 version of the Java 2 Platform, Enterprise Edition.

Copyright © 2002 Sun Microsystems, Inc. All rights reserved.