Movatterモバイル変換

A Java EE Application That Uses the JMS API with an Entity

This section explains how to write, compile, package, deploy, and run a JavaEE application that uses the JMS API with an entity. The application usesthe following components:

An application client that both sends and receives messages
Two message-driven beans
An entity class

This section covers the following topics:

You will find the source files for this section in the directorytut-install/javaeetutorial5/examples/jms/clientmdbentity/. Path names in this section are relative to this directory.

Overview of the`clientmdbentity` Example Application

This application simulates, in a simplified way, the work flow of a company’shuman resources (HR) department when it processes a new hire. This application alsodemonstrates how to use the Java EE platform to accomplish a task thatmany JMS client applications perform.

A JMS client must often wait for several messages from various sources. Itthen uses the information in all these messages to assemble a messagethat it then sends to another destination. The common term for this processisjoining messages. Such a task must be transactional, with all the receives andthe send as a single transaction. If not all the messages are receivedsuccessfully, the transaction can be rolled back. For a client example that illustratesthis task, seeA Local Transaction Example.

A message-driven bean can process only one message at a time ina transaction. To provide the ability to join messages, a Java EE applicationcan have the message-driven bean store the interim information in an entity. Theentity can then determine whether all the information has been received; when it has,the entity can report this back to one of the message-driven beans,which then creates and sends the message to the other destination. After ithas completed its task, the entity can be removed.

The basic steps of the application are as follows.

The HR department’s application client generates an employee ID for each new hire and then publishes a message (M1) containing the new hire’s name, employee ID, and position. The client then creates a temporary queue,ReplyQueue, with a message listener that waits for a reply to the message. (SeeCreating Temporary Destinations, for more information.)
Two message-driven beans process each message: One bean,OfficeMDB, assigns the new hire’s office number, and the other bean,EquipmentMDB, assigns the new hire’s equipment. The first bean to process the message creates and persists an entity namedSetupOffice, then calls a business method of the entity to store the information it has generated. The second bean locates the existing entity and calls another business method to add its information.
When both the office and the equipment have been assigned, the entity business method returns a value oftrue to the message-driven bean that called the method. The message-driven bean then sends to the reply queue a message (M2) describing the assignments. Then it removes the entity. The application client’s message listener retrieves the information.

Figure 32-2 illustrates the structure of this application. Of course, an actual HR applicationwould have more components; other beans could set up payroll and benefits records, scheduleorientation, and so on.

Figure 32-2 assumes thatOfficeMDB is the first message-driven bean to consume themessage from the client.OfficeMDB then creates and persists theSetupOffice entity andstores the office information.EquipmentMDB then finds the entity, stores the equipmentinformation, and learns that the entity has completed its work.EquipmentMDB then sends themessage to the reply queue and removes the entity.

Figure 32-2 A Java EE Application: Client to Message-Driven Beans to Entity

Diagram of application showing an application client, two message-driven beans, and an entity

Writing the Application Components for the`clientmdbentity` Example

Writing the components of the application involves the following:

Coding the Application Client:`HumanResourceClient.java`

The application client program,clientmdbentity-app-client/src/java/HumanResourceClient.java, performs the following steps:

InjectsConnectionFactory andTopic resources
Creates aTemporaryQueue to receive notification of processing that occurs, based on new-hire events it has published
Creates aMessageConsumer for theTemporaryQueue, sets theMessageConsumer’s message listener, and starts the connection
Creates aMessageProducer and aMapMessage
Creates five new employees with randomly generated names, positions, and ID numbers (in sequence) and publishes five messages containing this information

The message listener,HRListener, waits for messages that contain the assigned office andequipment for each employee. When a message arrives, the message listener displays theinformation received and determines whether all five messages have arrived. When they have,the message listener notifies the main program, which then exits.

Coding the Message-Driven Beans for the`clientmdbentity` Example

This example uses two message-driven beans:

clientmdbentity-ejb/src/java/EquipmentMDB.java
clientmdbentity-ejb/src/java/OfficeMDB.java

The beans take the following steps:

They injectMessageDrivenContext andConnectionFactory resources.
TheonMessage method retrieves the information in the message. TheEquipmentMDB’sonMessage method chooses equipment, based on the new hire’s position; theOfficeMDB’sonMessage method randomly generates an office number.
After a slight delay to simulate real world processing hitches, theonMessage method calls a helper method,compose.
Thecompose method takes the following steps:
1. It either creates and persists theSetupOffice entity or finds it by primary key.
2. It uses the entity to store the equipment or the office information in the database, calling either thedoEquipmentList or thedoOfficeNumber business method.
3. If the business method returnstrue, meaning that all of the information has been stored, it creates a connection and a session, retrieves the reply destination information from the message, creates aMessageProducer, and sends a reply message that contains the information stored in the entity.
4. It removes the entity.

Coding the Entity Class for the`clientmdbentity` Example

TheSetupOffice class,SetupOffice.java, is an entity class. The entity and the message-drivenbeans are packaged together in an EJB JAR file. The entity class isdeclared as follows:

@Entitypublic class SetupOffice implements Serializable {

The class contains a no-argument constructor and a constructor that takes two arguments,the employee ID and name. It also contains getter and setter methods forthe employee ID, name, office number, and equipment list. The getter method forthe employee ID has the@Id annotation to indicate that this field isthe primary key:

@Id public String getEmployeeId() {    return id;}

The class also implements the two business methods,doEquipmentList anddoOfficeNumber, andtheir helper method,checkIfSetupComplete.

The message-driven beans call the business methods and the getter methods.

Thepersistence.xml file for the entity specifies the most basic settings:

<persistence>    <persistence-unit name="clientmdbentity">        <jta-data-source>jdbc/__default</jta-data-source>        <class>eb.SetupOffice</class>        <properties>            <property name="toplink.ddl-generation"                 value="drop-and-create-tables"/>        </properties>    </persistence-unit></persistence>

Creating Resources for the`clientmdbentity` Example

This example uses the connection factoryjms/ConnectionFactory and the topicjms/Topic, both ofwhich you used inA Java EE Application That Uses the JMS API with a Session Bean. It also uses the JDBC resource namedjdbc/__default, which is enabled by default when you start the Application Server.

If you deleted the connection factory or topic, you can create them againusing targets in thebuild.xml file for this example. Use the following commandsto create the resources:

ant create-cf ant create-topic

Building, Deploying, and Running the`clientmdbentity` Example Using NetBeans IDE

To build, deploy, and run the application using NetBeans IDE, do the following:

Start the Application Server, if it is not already running.
Start the database server as described inStarting and Stopping the Java DB Database Server, if it is not already running.
In NetBeans IDE, choose Open Project from the File menu.
In the Open Project dialog, navigate totut-install/javaeetutorial5/examples/jms/.
Select theclientmdbentity folder.
Select the Open as Main Project check box and the Open Required Projects check box.
Click Open Project.
Right-click theclientmdbentity project and choose Build.
This task creates the following:
- An application client JAR file that contains the client class and listener class files, along with a manifest file that specifies the main class
- An EJB JAR file that contains the message-driven beans and the entity class, along with thepersistence.xml file
- An application EAR file that contains the two JAR files along with anapplication.xml file
Right-click the project and choose Undeploy and Deploy.
Right-click the project and choose Run.
This command returns a JAR file namedclientmdbentityClient.jar and then executes it.

The output of the application client in the Output pane looks something likethis:

PUBLISHER: Setting hire ID to 25, name Gertrude Bourbon, position Senior ProgrammerPUBLISHER: Setting hire ID to 26, name Jack Verdon, position ManagerPUBLISHER: Setting hire ID to 27, name Fred Tudor, position ManagerPUBLISHER: Setting hire ID to 28, name Fred Martin, position ProgrammerPUBLISHER: Setting hire ID to 29, name Mary Stuart, position ManagerWaiting for 5 message(s)New hire event processed:  Employee ID: 25  Name: Gertrude Bourbon  Equipment: Laptop  Office number: 183Waiting for 4 message(s)New hire event processed:  Employee ID: 26  Name: Jack Verdon  Equipment: Pager  Office number: 20Waiting for 3 message(s)New hire event processed:  Employee ID: 27  Name: Fred Tudor  Equipment: Pager  Office number: 51Waiting for 2 message(s)New hire event processed:  Employee ID: 28  Name: Fred Martin  Equipment: Desktop System  Office number: 141Waiting for 1 message(s)New hire event processed:  Employee ID: 29  Name: Mary Stuart  Equipment: Pager  Office number: 238

The output from the message-driven beans and the entity class appears in theserver log, wrapped in logging information.

For each employee, the application first creates the entity and then finds it.You may see runtime errors in the server log, and transaction rollbacks mayoccur. The errors occur if both of the message-driven beans discover at thesame time that the entity does not yet exist, so they bothtry to create it. The first attempt succeeds, but the second fails becausethe bean already exists. After the rollback, the second message-driven bean tries againand succeeds in finding the entity. Container-managed transactions allow the application to run correctly,in spite of these errors, with no special programming.

You can run the application client repeatedly.

Undeploy the application after you finish running the client. To undeploy the application,follow these steps:

Click the Services tab.
Expand the Servers node.
Expand the Application Server node.
Expand the Applications node.
Expand the Enterprise Applications node.
Right-clickclientmdbentity and choose Undeploy.

To remove the generated files, right-click theclientmdbentity project and choose Clean.

Building, Deploying, and Running the`clientmdbentity` Example Using Ant

To create and package the application using Ant, perform these steps:

Start the Application Server, if it is not already running.
Start the database server as described inStarting and Stopping the Java DB Database Server.

Go to the following directory:

tut-install/javaeetutorial5/examples/jms/clientmdbentity/

To compile the source files and package the application, use the following command:
```
ant
```

Theant command creates the following:

An application client JAR file that contains the client class and listener class files, along with a manifest file that specifies the main class
An EJB JAR file that contains the message-driven beans and the entity class, along with thepersistence.xml file
An application EAR file that contains the two JAR files along with anapplication.xml file

To deploy the application and run the client, use the following command:

ant run

Ignore the message that states that the application is deployed at a URL.

The program output in the terminal window looks something like this:

running application client container.PUBLISHER: Setting hire ID to 25, name Gertrude Bourbon, position Senior ProgrammerPUBLISHER: Setting hire ID to 26, name Jack Verdon, position ManagerPUBLISHER: Setting hire ID to 27, name Fred Tudor, position ManagerPUBLISHER: Setting hire ID to 28, name Fred Martin, position ProgrammerPUBLISHER: Setting hire ID to 29, name Mary Stuart, position ManagerWaiting for 5 message(s)New hire event processed:  Employee ID: 25  Name: Gertrude Bourbon  Equipment: Laptop  Office number: 183Waiting for 4 message(s)New hire event processed:  Employee ID: 26  Name: Jack Verdon  Equipment: Pager  Office number: 20Waiting for 3 message(s)New hire event processed:  Employee ID: 27  Name: Fred Tudor  Equipment: Pager  Office number: 51Waiting for 2 message(s)New hire event processed:  Employee ID: 28  Name: Fred Martin  Equipment: Desktop System  Office number: 141Waiting for 1 message(s)New hire event processed:  Employee ID: 29  Name: Mary Stuart  Equipment: Pager  Office number: 238

The output from the message-driven beans and the entity class appears in theserver log, wrapped in logging information.

Undeploy the application after you finish running the client:

ant undeploy

To remove the generated files, use the following command in theclientmdbentity,clientmdbentity-app-client, andclientmdbentity-ejb directories:

ant clean

Movatterモバイル変換

The Java EE 5 Tutorial

A Java EE Application That Uses the JMS API with an Entity

Overview of theclientmdbentity Example Application

Writing the Application Components for theclientmdbentity Example

Coding the Application Client:HumanResourceClient.java

Coding the Message-Driven Beans for theclientmdbentity Example

Coding the Entity Class for theclientmdbentity Example

Creating Resources for theclientmdbentity Example

Building, Deploying, and Running theclientmdbentity Example Using NetBeans IDE

Building, Deploying, and Running theclientmdbentity Example Using Ant