10    An Application Example that Uses Two J2EE^TM Servers

This chapter explains how to write, compile, package, deploy, and run a pair of J2EE^TM applications that use the JMS API and run on two J2EE servers. A common practice is to deploy different components of an enterprise application on different systems within a company, and this example illustrates on a small scale how to do this for an application that uses the JMS API.

The applications use the following components:

• An application client that uses two connection factories--one ordinary one and one that is configured to communicate with the remote server--to create two publishers and two subscribers and to publish and to consume messages
• A message-driven bean that is deployed twice--once on the local server and once on the remote one--to process the messages and to send replies

In this chapter, the term local server means the server on which the application client is deployed. The term remote server means the server on which only the message-driven bean is deployed.

Another possible situation is that an application deployed on a J2EE server must be accessed from another system on which no J2EE server is running. The last section of this chapter discusses how to handle this situation.

The chapter covers the following topics:

• An overview of the applications
• Writing and compiling the application components
• Creating and packaging the applications
• Deploying and running the applications
• Accessing a J2EE application from a remote system that is not running a J2EE server

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/multi_server (on UNIX® systems) or jms_tutorial\examples\multi_server (on Microsoft Windows systems). The directory ear_files in the examples directory contains two built applications, called SampleMultiApp.ear and SampleReplyBeanApp.ear. If you run into difficulty at any time, you can open one of these files in the deploytool and compare that file to your own version.

10.1   Overview of the Applications

This pair of applications is somewhat similar to the application in Chapter 7 in that the only components are a client and a message-driven bean. However, the applications here use these components in more complex ways. One application consists of the application client. The other application contains only the message-driven bean and is deployed twice, once on each server.

The basic steps of the applications are as follows.

1. The administrator starts two J2EE servers.
2. On the local server, the administrator creates a connection factory to communicate with the remote server.
3. The application client uses two connection factories--a preconfigured one and the one just created--to create two connections, sessions, publishers, and subscribers. Each publisher publishes five messages.
4. The local and the remote message-driven beans each receive five messages and send replies.
5. The client's message listener consumes the replies.

Figure 10.1 illustrates the structure of this application.

Figure 10.1   A J2EE Two-Server Application

10.2   Writing and Compiling the Application Components

Writing and compiling the components of the applications involve

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

10.2.1   Coding the Application Client: MultiAppServerRequester.java

The application client class, MultiAppServerRequester.java, does the following.

1. It uses the Java^TM Naming and Directory Interface^TM (JNDI) API naming context java:comp/env to look up two connection factories and a topic.
2. For each connection factory, it creates a connection, a publisher session, a publisher, a subscriber session, a subscriber, and a temporary topic for replies.
3. Each subscriber sets its message listener, ReplyListener, and starts the connection.
4. Each publisher publishes five messages and creates a list of the messages the listener should expect.
5. When each reply arrives, the message listener displays its contents and removes it from the list of expected messages.
6. When all the messages have arrived, the client exits.

10.2.2   Coding the Message-Driven Bean: ReplyMsgBean.java

The onMessage method of the message-driven bean class, ReplyMsgBean.java, does the following:

1. Casts the incoming message to a TextMessage and displays the text
2. Creates a connection, session, and publisher for the reply message
3. Publishes the message to the reply topic
4. Closes the connection

10.2.3   Compiling the Source Files

To compile the files in the application, go to the directory multi_server 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 MultiAppServerRequester.java
   javac ReplyMsgBean.java
   

10.3   Creating and Packaging the Application

Creating and packaging this application involve several steps:

1. Starting the J2EE servers and the deploytool
2. Creating a connection factory
3. Creating the first J2EE application
4. Packaging the application client
5. Creating the second J2EE application
6. Packaging the message-driven bean
7. Checking the JNDI API names ("JNDI names")

10.3.1   Starting the J2EE Servers and the Deploytool

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

1. At a command line prompt on the local system, 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 on the local system, start the deploytool:

   deploytool
   

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

3. At a command line prompt on the remote system, start the J2EE server:

   j2ee -verbose
   

10.3.2   Creating a Connection Factory

For this example, you create on the local system a connection factory that allows the client to communicate with the remote server. If you downloaded the tutorial examples as described in the preface, you will find in the multi_server directory in the multi_server directory a Microsoft Windows script called setup.bat and a UNIX script called setup.sh. You can use one of these scripts to create the connection factory on the local system. The command in setup.bat looks like this:

call j2eeadmin -addJmsFactory jms/RemoteTCF topic -props url=corbaname:iiop:%1:1050#%1

The UNIX command in setup.sh looks like this:

#!/bin/sh -x
j2eeadmin -addJmsFactory jms/RemoteTCF topic -props url=corbaname:iiop:$1:1050#$1

1. To run the script, specify the name of the remote server as an argument. Use the host name that is visible to you on your network; do not use an IP address. For example, if the remote system is named mars, enter the following:

   setup.bat mars
   

   or

   setup.sh mars
   

2. Verify that the connection factory was created:

   j2eeadmin -listJmsFactory
   

   One line of the output looks like this:

   < JMS Cnx Factory : jms/RemoteTCF , Topic , [ url=corbaname:iiop:mars:1050#mars ] >
   

10.3.3   Creating the First J2EE Application

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

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

10.3.4   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 MultiApp.
2. From the File menu, choose New -> Application Client. The wizard displays a series of dialog boxes.

10.3.4.1   Introduction Dialog Box

Click Next.

10.3.4.2   JAR File Contents Dialog Box

1. In the combo box labeled Create Archive Within Application, select MultiApp.
2. Click the Edit button next to the Contents text area.
3. In the dialog box Edit Contents of <Application Client>, choose the multi_server 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 MultiAppServerRequester.class and MultiAppServerRequester$ReplyListener.class from the Available Files tree area and click Add.
5. Click OK.
6. Click Next.

10.3.4.3   General Dialog Box

1. In the Application Client combo box, select MultiAppServerRequester in the Main Class field, and enter MultiAppServerRequester in the Display Name field.
2. In the Callback Handler Class combo box, verify that container-managed authentication is selected.
3. Click Next.

10.3.4.4   Environment Entries Dialog Box

Click Next.

10.3.4.5   Enterprise Bean References Dialog Box

Click Next.

10.3.4.6   Resource References Dialog Box

In this dialog box, you associate the JNDI API context names for the connection factories in the MultiAppServerRequester.java source file with the names of the local and remote connection factories. You also specify container authentication for the connection factory resources, 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/TopicConnectionFactory1--the first logical name referenced by MultiAppServerRequester.
3. In the Type field, select javax.jms.TopicConnectionFactory.
4. In the Authentication field, select Container.
5. In the Sharable field, make sure that the checkbox is selected. This allows the container to optimize connections.
6. In the JNDI Name field, enter jms/TopicConnectionFactory.
7. In the User Name field, enter j2ee.
8. In the Password field, enter j2ee.
9. Click Add.
10. In the Coded Name field, enter jms/TopicConnectionFactory2--the other logical name referenced by MultiAppServerRequester.
11. In the Type field, select javax.jms.TopicConnectionFactory.
12. In the Authentication field, select Container.
13. In the Sharable field, make sure that the checkbox is selected.
14. In the JNDI Name field, enter jms/RemoteTCF.
15. In the User Name field, enter j2ee. (If the user name and the password appear to be filled in already, make sure that you follow the instructions at the end of Section 10.3.4.8, "Review Settings Dialog Box," after you exit the Wizard.)
16. In the Password field, enter j2ee.
17. Click Next.

10.3.4.7   JMS Destination References Dialog Box

In this dialog box, you associate the JNDI API context name for the topic in the MultiAppServerRequester.java source file with the name of the default topic. The client code also uses a reply topic, but it is a temporary topic created programmatically rather than administratively and does not have to be specified in the deployment descriptor. Follow these steps.

1. Click Add.
2. In the Coded Name field, enter jms/PTopic--the logical name for the publisher topic referenced by MultiAppServerRequester.
3. In the Type field, select javax.jms.Topic.
4. In the JNDI Name field, enter jms/Topic--the preconfigured topic.
5. Click Next.

10.3.4.8   Review Settings Dialog Box

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

After you exit the Wizard, do the following.

1. Select the MultiAppServerRequester node in the tree.
2. Select the Resource Refs tabbed pane.
3. Select the second entry in the table, jms/TopicConnectionFactory2.
4. If the User Name and the Password fields are blank, enter j2ee in each field.
5. Choose Save from the File menu to save the application.

10.3.5   Creating the Second J2EE Application

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

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

10.3.6   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 ReplyBeanApp.
2. From the File menu, choose New -> Enterprise Bean.

10.3.6.1   Introduction Dialog Box

Click Next.

10.3.6.2   EJB JAR Dialog Box

1. In the combo box labeled JAR File Location, verify that Create New JAR File in Application and ReplyBeanApp are selected.
2. In the JAR Display Name field, verify that the name is Ejb1, the default display name.
3. Click the Edit button next to the Contents text area.
4. In the dialog box Edit Contents of Ejb1, choose the multi_server 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 ReplyMsgBean.class file from the Available Files tree area and click Add.
6. Click OK.
7. Click Next.

10.3.6.3   General Dialog Box

1. In the Bean Type combo box, select the Message-Driven radio button.
2. Under Enterprise Bean Class, select ReplyMsgBean. The combo boxes for the local and remote interfaces are grayed out.
3. In the Enterprise Bean Name field, enter ReplyMDB. This name will represent the message-driven bean in the tree view.
4. Click Next.

10.3.6.4   Transaction Management Dialog Box

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.

10.3.6.5   Message-Driven Bean Settings Dialog Box

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

10.3.6.6   Environment Entries Dialog Box

Click Next.

10.3.6.7   Enterprise Bean References Dialog Box

Click Next.

10.3.6.8   Resource References Dialog Box

1. Click Add.
2. In the Coded Name field, enter jms/TopicConnectionFactory.
3. In the Type field, select javax.jms.TopicConnectionFactory.
4. In the Authentication field, select Container.
5. In the JNDI Name field, enter jms/TopicConnectionFactory.
6. In the User Name field, enter j2ee.
7. In the Password field, enter j2ee.
8. Click Finish. You do not need to enter anything in the other dialog boxes.

10.3.7   Checking the JNDI Names

Verify that the JNDI names for the application components are correct. To do so, do the following.

1. In the tree view, select the MultiApp application.
2. Select the JNDI Names tabbed pane.
3. Verify that the JNDI names appear as shown in Table 10.1.

   Table 10.1:    References Pane

   Ref. Type	Referenced By	Reference Name	JNDI Name
   Resource	MultiAppServerRequester	jms/TopicConnectionFactory1	jms/TopicConnectionFactory
   Resource	MultiAppServerRequester	jms/TopicConnectionFactory2	jms/RemoteTCF
   Env Resource	MultiAppServerRequester	jms/PTopic	jms/Topic

4. In the tree view, select the ReplyBeanApp application.
5. Select the JNDI Names tabbed pane.
6. Verify that the JNDI names appear as shown in Table 10.2 and Table 10.3.

Table 10.2:    Application Pane

Component Type	Component	JNDI Name
EJB	ReplyMDB	jms/Topic

Table 10.3:    References Pane

Ref. Type	Referenced By	Reference Name	JNDI Name
Resource	ReplyMDB	jms/TopicConnectionFactory	jms/TopicConnectionFactory

10.4   Deploying and Running the Applications

Deploying and running this application involve several steps:

1. Adding the server
2. Deploying the applications
3. Running the client
4. Undeploying the applications
5. Removing the applications and stopping the server

10.4.1   Adding the Server

Before you can deploy the application, you must make available to the deploytool both the J2EE servers you started in Section 10.3.1, "Starting the J2EE Servers and the Deploytool." To add the remote server, follow these steps.

1. From the File menu, choose Add Server.
2. In the Add Server dialog box, enter the name of the remote system in the Server Name field. Use the same name you specified when you ran the setup script in Section 10.3.2, "Creating a Connection Factory."
3. Click OK.

A node with the name of the remote system appears under Servers in the tree view.

Because you started the local 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.

The localhost node appears under Servers in the tree view.

10.4.2   Deploying the Applications

To deploy the MultiApp application, perform the following steps.

1. In the tree view, select the MultiApp application.
2. From the Tools menu, choose Deploy.
3. In the Introduction dialog box, verify that the Object to Deploy selection is MultiApp, and select localhost as the Target Server.
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 MultiApp is complete" message appears.
9. In the tree view, expand Servers and select the host name. Verify that MultiApp is deployed.

To deploy the ReplyBeanApp application on the local server, perform the following steps.

1. In the tree view, select the ReplyBeanApp application.
2. From the Tools menu, choose Deploy.
3. In the Introduction dialog box, verify that the Object to Deploy selection is ReplyBeanApp, and select the local server as the Target Server.
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 ReplyBeanApp is complete" message appears.
9. In the tree view, expand Servers and select the host name. Verify that ReplyBeanApp is deployed.
10. Repeat steps 1–9 for the remote server, selecting the remote server as the Target Server in step 3.

10.4.3   Running the Client

To run the client, perform the following steps.

1. At a command line prompt on the local system, enter the following:

   runclient -client MultiApp.ear -name MultiAppServerRequester -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. Output from the message-driven beans appears on both the local and the remote systems, in the windows in which you started each J2EE server.

10.4.4   Undeploying the Applications

To undeploy the J2EE applications, follow these steps.

1. In the tree view, select localhost under Servers.
2. Select MultiApp in the Deployed Objects area.
3. Click Undeploy.
4. Answer Yes in the confirmation dialog.
5. Repeat steps 1–4 for ReplyBeanApp on both the local and the remote servers.

10.4.5   Removing the Applications and Stopping the Servers

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

1. Select MultiApp in the tree view.
2. Select Close from the File menu.
3. Repeat these steps for ReplyBeanApp.

To delete the connection factory you created, enter the following at a command line prompt on the local system:

j2eeadmin -removeJmsFactory jms/RemoteTCF

To stop the J2EE servers, use the following command on each system:

j2ee -stop

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

10.5   Accessing a J2EE Application from a Remote System that Is Not Running a J2EE Server

To run an application installed on a J2EE server from a system that is not running a J2EE server, you perform tasks similar to those described in Section 4.4.2, "Communicating Between a J2EE Server and a System Not Running a J2EE Server." Again, the J2EE SDK must be installed on both systems. You may also want to use the runclient command to run an application client installed on a remote system.

This section describes both of these situations:

• Accessing a J2EE application from a standalone client
• Using runclient to access a remote application client

10.5.1   Accessing a J2EE Application from a Standalone Client

You can run a standalone client that uses messages to communicate with a J2EE application. For example, you can use the deploytool to deploy the ReplyBeanApp application on a system running the J2EE server, then use a standalone client to publish messages to the topic that the ReplyMsgBean is listening on and receive replies on a temporary topic.

For example, suppose that the ReplyBeanApp application is deployed on the server running on the system earth, and suppose that the standalone client is named PubSub and will run on the system mars. Section 10.5.1.1 shows the client program.

To specify the remote system on the command line, you use a command line just like the one in Section 4.4.2 (you do so after setting your environment variables as shown in Table 4.1).

• On a Microsoft Windows system, type the following command:

  java -Djms.properties=%J2EE_HOME%\config\jms_client.properties -Dorg.omg.CORBA.ORBInitialHost=earth PubSub jms/Topic
  

• On a UNIX system, type the following command:

  java -Djms.properties=$J2EE_HOME/config/jms_client.properties -Dorg.omg.CORBA.ORBInitialHost=earth PubSub jms/Topic
  

If all the remote applications you need to access are deployed on the same server, you can edit the file %J2EE_HOME%\config\orb.properties (on Microsoft Windows systems) or $J2EE_HOME/config/orb.properties (on UNIX systems) on the local system. The second line of this file looks like this:

host=localhost

Change localhost to the name of the system on which the remote applications are deployed (for example, earth):

host=earth

You can now run the client program as before, but you do not need to specify the option -Dorg.omg.CORBA.ORBInitialHost.

10.5.1.1   The Sample Client Program: PubSub.java

The sample client program PubSub.java can publish messages to a topic that the ReplyMsgBean is listening on and receive the message bean's replies.

10.5.2   Using runclient to Access a Remote Application Client

If you need to run a J2EE application that contains an application client and that is deployed on a remote system, you can use the runclient command to do so. For example, if you deploy both ReplyBeanApp and MultiApp on the server running on earth, the steps are as follows.

1. Make sure that the multi_server directory on earth is accessible to you via the file system so that the runclient command can find it.
2. Follow the instructions in Section 10.3.2, "Creating a Connection Factory," and create on mars a connection factory that will refer to the corresponding connection factory on earth.
3. Set the host property in the orb.properties file in the J2EE SDK on mars, as described in Section 10.5.1, because the runclient command does not allow you to specify the ORBInitialHost value:

   host=earth
   

4. Go to the multi_server directory on earth--or specify the complete path to the MultiApp.ear file--and issue the runclient command:

   runclient -client MultiApp.ear -name MultiAppServerRequester -textauth