J2EE^TM Developer's Guide
Clients

J2EE Application Clients

Although a J2EE application client is a Java application, it differs from a stand-alone Java application client because it is a J2EE component. Like other J2EE components, a J2EE application client is created with the Application Deployment Tool and added to a J2EE application. Because it is part of a J2EE application, a J2EE application client has two advantages over a stand-alone Java application client. First, a J2EE application client is portable-- it will run on any J2EE-compliant server. Second, it may access J2EE services.

Accessing J2EE Services

A J2EE application client may use the following J2EE services:

Security authentication
JNDI lookups

Security Authentication

Of the J2EE services available to a J2EE application client, authentication is probably the most useful. Because the the authentication service provides a log-in mechanism, you don't have to code the log-in routines. When you run the J2EE application client, a log-in window automatically pops open and requests a J2EE user name and password. The authentication service verifies the user name and password before allowing the client to access the enterprise beans. For more information on enterprise bean security, see the Security chapter.

JNDI Lookups

A J2EE application client may use the JNDI API to look up enterprise beans, resources (databases), and environment entries. For example, the J2EEClient program locates an enterprise bean with the following call:

Object objref = initial.lookup("java:comp/env/ejb/SimpleConverter");

The ejb/SimpleConverter string is the name by which the J2EEClient code refers to the enterprise bean. This name does not have to be identical to the JNDI name of the enterprise bean in the deployed application. For example, the enterprise bean's JNDI name might be MyConverter. In this case, you would map ejb/SimpleConverter, the name coded in the client, to MyConverter, the JNDI name of the enterprise bean. (A later section "Specifying the JNDI Name", shows you how to map the names with the Application Deployment Tool.)

Although this mapping adds a level of indirection, it provides a major benefit to distributed applications: Clients may use different names to refer to the same enterprise bean. The J2EEClient code, for example, uses the SimpleConverter name, but another client might refer to the same bean as CurrencyConverter. Even if you changed the bean's JNDI name (MyConverter) on the server, you wouldn't have to change the client's source code. But you would have to map the names again and re-deploy the application.

A stand-alone Java application client (such as ConverterClient), also locates an enterprise bean by calling the JNDI lookup method. However, the name coded in the stand-alone client must be identical to the bean's JNDI name on the server. You cannot map the two names in the Application Deployment Tool.

Setting Up the Application for the J2EE Application Client

The sections that follow show how to create and run an application with a J2EE application client called J2EEClient. The application contains the session bean documented in the Getting Started chapter. The source code required by the application resides in the doc/guides/ejb/examples/converter subdirectory. Before stepping through the instructions in the next section, you should prepare the application:

Create a J2EE application called ConverterApp.
Create a session bean for the ConverterEJB class.
Add this session bean to the J2EE application.
Set the JNDI name for the session bean to MyConverter.
Compile the J2EEClient program.

Creating the J2EE Application Client

You create a J2EE application client with the New Application Client Wizard of the Application Deployment tool. To start the wizard, from the File menu choose New Application client. The wizard displays the following dialog boxes. (You may skip any dialog box not listed here.)

Introduction Dialog Box:

a. Read this explanatory text for an overview of the wizard's features.

b. Click Next.

General Dialog Box:

a. Click the Add button next to the Contents text area.

b. In the dialog box titled "Add files to JAR," choose the directory containing the J2EEClient.class file (examples/converter). You may either type the directory name in the Root Directory field or locate it by clicking Browse.

c. Select the J2EEClient.class file from the text area and click Add.

d. Click OK.

e. In the Display Name field, enter MyConverterClient.

f. Click Next.

Enterprise Bean References Dialog Box:

a. Click Add.

b. In the Coded Name column enter ejb/SimpleConverter.

c. In the Type column select Session.

d. In the Home column enter ConverterHome.

e. In the Remote column enter Converter.

f. Click Finish.

Specifying the JNDI Name

In the ConverterApp application, the JNDI name of the ConverterBean is MyConverter. But the J2EEClient program refers to the same enterprise bean as SimpleConverter. Therefore, you must map the SimpleConverter name to MyConverter:

1. In the tree view, select the ConverterApp application.

2. In the JNDI Names tabbed pane perform these steps:

a. Verify that the ConverterBean component has the MyConverter JNDI name.

b. For the ejb/SimpleConverter reference, enter MyConverter for the JNDI name.

Deploying the J2EE Application

1. From the Tools menu, choose Deploy Application.

2. In the first dialog box, select the checkbox labelled "Return Client Jar."

3. In the text field that appears, enter the full path name for the file ConverterAppClient.jar.

Running the J2EE Application Client

To run the J2EEClient program , enter this command:

runclient -client ConverterApp.ear -name MyConverterClient

The ConverterApp.ear file contains the J2EE application. The MyConverterClient option is the display name of the J2EE application client component.

The client container pops open a login window. In the User Name field enter guest and in the Password field enter guest123. (These entries are the default values specified in the config/auth.properties file.)

If the J2EE application client does not reside on the same host as the J2EE server, you should follow these steps:

1. Copy the ConverterAppClient.jar file to the client host machine. Created during deployment, the ConverterAppClient.jar file contains stub classes that enable remote connectivity.

2. Copy the ConverterApp.ear file to the client host machine.

3. Set the APPCPATH environment variable to the fully qualified name of the .jar file. In the following example, the fully qualified name is /user/duke/ConverterAppClient.jar:

UNIX, C-shell:

setenv APPCPATH /user/duke/ConverterAppClient.jar

UNIX, Bourne and Korn shells:

APPCPATH=/user/duke/ConverterAppClient.jar
export APPCPATH

Windows:

set APPCPATH=\user\duke\ConverterAppClient.jar

4. Set the VMARGS environment variable to the -Dorg.omg.CORBA.ORBInitialHost option. In the following example, the option points to the remote host named buzz, where the J2EE server is running:

UNIX, C-shell:

setenv VMARGS -Dorg.omg.CORBA.ORBInitialHost=buzz

UNIX, Bourne and Korn shells:

VMARGS="-Dorg.omg.CORBA.ORBInitialHost=buzz"
export VMARGS

Windows:

set VMARGS=-Dorg.omg.CORBA.ORBInitialHost=buzz

5. Run the runclient script:

runclient -client ConverterApp.ear -name MyConverterClient

Prev | Next

TOC | Index