Using JAXR Clients in J2EE Applications

You can create J2EE applications that use JAXR clients to access registries. This section explains how to write, compile, package, deploy, and run a J2EE application that uses JAXR to publish an organization to a registry and then query the registry for that organization. The application in this section uses two components: an application client and a stateless session bean.

The section covers the following topics:

You will find the source files for this section in the directory <INSTALL>/j2eetutorial14/examples/jaxr/clientsession. Path names in this section are relative to this directory.

The following directory contains a built version of this application: 

<INSTALL>/j2eetutorial14/examples/jaxr/provided-ears

If you run into difficulty at any time, you can open the EAR file in deploytool and compare that file to your own version. (You cannot deploy this EAR file, however. It uses an unedited version of the required properties file.)

Coding the Application Client: MyAppClient.java

The application client class, src/MyAppClient.java, obtains a handle to the PubQuery enterprise bean's remote home interface, using the JNDI API naming context java:comp/env. The program then creates an instance of the bean and calls the bean's two business methods: executePublish and executeQuery.

Coding the PubQuery Session Bean

The PubQuery bean is a stateless session bean that has one create method and two business methods. The bean uses remote interfaces rather than local interfaces because it is accessed from the application client.

The remote home interface source file is src/PubQueryHome.java.

The remote interface, src/PubQueryRemote.java, declares two business methods: executePublish and executeQuery. The bean class, src/PubQueryBean.java, implements the executePublish and executeQuery methods and their helper methods getName, getDescription, and getKey. These methods are very similar to the methods of the same name in the simple examples JAXRQuery.java and JAXRPublish.java. The executePublish method uses information in the file PubQueryBeanExample.properties to create an organization named The Coffee Enterprise Bean Break. The executeQuery method uses the organization name, specified in the application client code, to locate this organization.

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 ConnectionFactory and creating the Connection.

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

Editing the Properties File

Before you compile the application, edit the PubQueryBeanExamples.properties file in the same way you edited the JAXRExamples.properties file to run the simple examples.

  1. Uncomment the query.url and publish.url lines for the registry you wish to use. The default is the IBM registry.
  2. Provide values for the registry.username and registry.password properties to specify the user name and password you obtained when you registered with the registry.
  3. Change the values for the http.proxyHost and https.proxyHost entries so that they specify the system on your network through which you access the Internet.
  4. Feel free to change any of the organization data in the remainder of the file. Try to make the organization name unusual so that queries will return relatively few results.

Compiling the Source Files

To compile the application source files, go to the directory <INSTALL>/j2eetutorial14/examples/jaxr/clientsession. Use the following command: 

asant compile

The compile target places the properties file and the class files in the build directory.

Starting the Application Server

To run this example, you need to start the Application Server. Follow the instructions in Starting and Stopping the Application Server.

Creating JAXR Resources

To use JAXR in a J2EE application that uses the Application Server, you need to access the JAXR resource adapter (see Implementing a JAXR Client) through a connector connection pool and a connector resource. You can create these resources in the Admin Console.

If you have not done so, start the Admin Console as described in Starting the Admin Console.

To create the connector connection pool, perform the following steps:

  1. In the tree component, expand the Resources node, then expand the Connectors node.
  2. Click Connector Connection Pools.
  3. Click New.
  4. On the Create Connector Connection Pool page:
    1. Type jaxr-pool in the Name field.
    2. Choose jaxr-ra from the Resource Adapter drop-down list.
    3. Click Next.
  5. On the next page, choose javax.xml.registry.ConnectionFactory (the only choice) from the Connection Definition drop-down list, and click Next.
  6. On the next page, click Finish.

To create the connector resource, perform the following steps:

  1. Under the Connectors node, click Connector Resources.
  2. Click New. The Create Connector Resource page appears.
  3. In the JNDI Name field, type eis/JAXR.
  4. Choose jaxr-pool from the Pool Name drop-down list.
  5. Click OK.

If you are in a hurry, you can create these objects by executing the following command (from the directory <INSTALL>/j2eetutorial14/examples/jaxr/clientsession): 

asant create-resource

Creating and Packaging the Application

Creating and packaging this application involve four steps:

  1. Starting deploytool and Creating the Application
  2. Packaging the Session Bean
  3. Packaging the Application Client
  4. Checking the JNDI Names

Starting deploytool and Creating the Application

  1. Start deploytool. For instructions, see Starting the deploytool Utility.
  2. Choose FileRight ArrowNewRight ArrowApplication.
  3. Click Browse (next to the Application File Name field), and use the file chooser to locate the directory clientsession.
  4. In the File Name field, type ClientSessionApp.
  5. Click New Application.
  6. Click OK.

Packaging the Session Bean

  1. Choose FileRight ArrowNewRight ArrowEnterprise Bean to start the Enterprise Bean wizard. Then click Next.
  2. In the EJB JAR General Settings screen:
    1. Select Create New JAR Module in Application, and make sure that the application is ClientSessionApp.
    2. In the JAR Display Name field, type PubQueryJAR.
    3. Click the Edit Contents button.
    4. In the dialog box, locate the clientsession/build directory. Select PubQueryBean.class, PubQueryHome.class, PubQueryRemote.class, and PubQueryBeanExample.properties from the Available Files tree. Click Add, and then OK.
  3. In the Bean General Settings screen:
    1. From the Enterprise Bean Class menu, choose PubQueryBean.
    2. Verify that the Enterprise Bean Name is PubQueryBean and that the Enterprise Bean Type is Stateless Session.
    3. In the Remote Interfaces area, choose PubQueryHome from the Remote Home Interface drop-down list, and choose PubQueryRemote from the Remote Interface drop-down list.

After you finish the wizard, perform the following steps:

  1. Click the PubQueryBean node, and then click the Transactions tab. In the inspector pane, select the Container-Managed radio button.
  2. Click the PubQueryBean node, and then click the Resource Ref's tab. In the inspector pane:
    1. Click Add.
    2. In the Coded Name field, type eis/JAXR.
    3. From the Type menu, choose javax.xml.registry.ConnectionFactory.
    4. In the Deployment Settings area, type eis/JAXR in the JNDI name combo box, and type j2ee in both the User Name and the Password fields.

Packaging the Application Client

  1. Choose FileRight ArrowNewRight ArrowApplication Client to start the Application Client Wizard. Then click Next.
  2. In the JAR File Contents screen:
    1. Verify that Create New AppClient Module in Application is selected and that the application is ClientSessionApp.
    2. In the AppClient Display Name field, type MyAppClient.
    3. Click the Edit Contents button.
    4. In the dialog box, locate the clientsession/build directory. Select MyAppClient.class from the Available Files tree. Click Add, and then OK.
  3. In the General screen, select MyAppClient from the Main Class drop-down list.

After you finish the wizard, click the EJB Ref's tab, and then click Add in the inspector pane. In the dialog box, follow these steps:

  1. Type ejb/remote/PubQuery in the Coded Name field.
  2. Choose Session from the EJB Type drop-down list.
  3. Choose Remote from the Interfaces drop-down list.
  4. Choose PubQueryHome from the Home Interface combo box.
  5. Choose PubQueryRemote from the Local/Remote Interface combo box.
  6. In the Target EJB area, select JNDI Name and choose PubQueryBean from the combo box. The session bean uses remote interfaces, so the client accesses the bean through the JNDI name rather than the bean name.

Checking the JNDI Names

Select the application, click Sun-specific Settings on the General page, and verify that the JNDI names for the application components are correct. They should appear as shown in Tables 10-3 and 10-4.

Table 10-3 Application Pane for ClientSessionApp 
Component Type
Component
JNDI Name
EJB
PubQueryBean
PubQueryBean

Table 10-4 References Pane for ClientSessionApp 
Ref. Type
Referenced By
Reference Name
JNDI Name
EJB Ref
MyAppClient
ejb/remote/PubQuery
PubQueryBean
Resource
PubQueryBean
eis/JAXR
eis/JAXR

Deploying the Application

  1. Save the application.
  2. Choose ToolsRight ArrowDeploy.
  3. In the dialog box, type your administrative user name and password (if they are not already filled in), and click OK.
  4. In the Application Client Stub Directory area, select the Return Client Jar checkbox, and make sure that the directory is clientsession.
  5. Click OK.
  6. In the Distribute Module dialog box, click Close when the process completes. You will find a file named ClientSessionAppClient.jar in the specified directory.

Running the Application Client

To run the client, use the following command: 

appclient -client ClientSessionAppClient.jar

The program output in the terminal window looks like this: 

Looking up EJB reference
Looked up home
Narrowed home
Got the EJB
To view the bean output,
  check <install_dir>/domains/domain1/logs/server.log.

In the server log, you will find the output from the executePublish and executeQuery methods, wrapped in logging information.

After you run the example, use the run-delete target in the simple directory to delete the organization that was published.