Download PDF Home History |  | API Search Feedback FAQ

> ## Creating the Application Client

> An application client is a program written in the Java programming language. At runtime, the client program executes in a different virtual machine than the Application Server. For detailed information on the `appclient` command-line tool, see the man page at `http://java.sun.com/j2ee/1.4/docs/relnotes/cliref/index.html`.

> The application client in this example requires two JAR files. The first JAR file is for the J2EE component of the client. This JAR file contains the client's deployment descriptor and class files; it is created when you run the New Application Client wizard. Defined by the J2EE Specification, this JAR file is portable across all compliant application servers.

> The second JAR file contains stub classes that are required by the client program at runtime. These stub classes enable the client to access the enterprise beans that are running in the Sun Java System Application Server. The JAR file for the stubs is created by `deploytool` when you deploy the application. Because this JAR file is not covered by the J2EE specification, it is implementation-specific, intended only for the Application Server.

> The application client source code is in the `ConverterClient.java` file, which is in this directory:

>     <INSTALL>/j2eetutorial14/examples/ejb/converter/src/

> You compiled this code along with the enterprise bean code in the section Compiling the Source Files.

> ### Coding the Application Client

> The `ConverterClient.java` source code illustrates the basic tasks performed by the client of an enterprise bean:

> - Locating the home interface
> - Creating an enterprise bean instance
> - Invoking a business method

> #### Locating the Home Interface

> The `ConverterHome` interface defines life-cycle methods such as `create` and `remove`. Before the `ConverterClient` can invoke the `create` method, it must locate and instantiate an object whose type is `ConverterHome`. This is a four-step process.

> 1. Create an initial naming context.

> `Context initial = new InitialContext();`

> The `Context` interface is part of the Java Naming and Directory Interface (JNDI). A naming context is a set of name-to-object bindings. A name that is bound within a context is the JNDI name of the object.

> An `InitialContext` object, which implements the `Context` interface, provides the starting point for the resolution of names. All naming operations are relative to a context.

> 2. Obtain the environment naming context of the application client.

> `Context myEnv = (Context)initial.lookup("java:comp/env");`

> The `java:comp/env` name is bound to the environment naming context of the `ConverterClient` component.

> 3. Retrieve the object bound to the name `ejb/SimpleConverter`.

> `Object objref = myEnv.lookup("ejb/SimpleConverter");`

> The `ejb/SimpleConverter` name is bound to an enterprise bean reference, a logical name for the home of an enterprise bean. In this case, the `ejb/SimpleConverter` name refers to the `ConverterHome` object. The names of enterprise beans should reside in the `java:comp/env/ejb` subcontext.

> 4. Narrow the reference to a `ConverterHome` object.

> `ConverterHome home =
> (ConverterHome) PortableRemoteObject.narrow(objref,
> ConverterHome.class);`

> #### Creating an Enterprise Bean Instance

> To create the bean instance, the client invokes the `create` method on the `ConverterHome` object. The `create` method returns an object whose type is `Converter`. The remote `Converter` interface defines the business methods of the bean that the client can call. When the client invokes the `create` method, the EJB container instantiates the bean and then invokes the `ConverterBean.ejbCreate` method. The client invokes the `create` method as follows:

>     Converter currencyConverter = home.create();

> #### Invoking a Business Method

> Calling a business method is easy: you simply invoke the method on the `Converter` object. The EJB container will invoke the corresponding method on the `ConverterBean` instance that is running on the server. The client invokes the `dollarToYen` business method in the following lines of code.

>     BigDecimal param = new BigDecimal ("100.00");
>     BigDecimal amount = currencyConverter.dollarToYen(param);

> #### ConverterClient Source Code

> The full source code for the `ConverterClient` program follows.

>     import javax.naming.Context;
>     import javax.naming.InitialContext;
>     import javax.rmi.PortableRemoteObject;
>     import java.math.BigDecimal;

>     public class ConverterClient {

>       public static void main(String[] args) {

>         try {
>           Context myEnv =
>             (Context)initial.lookup("java:comp/env");
>           Object objref = myEnv.lookup("ejb/SimpleConverter");

>           ConverterHome home =
>             (ConverterHome)PortableRemoteObject.narrow(objref,
>                                 ConverterHome.class);

>           Converter currencyConverter = home.create();

>           BigDecimal param = new BigDecimal ("100.00");
>           BigDecimal amount =
>             currencyConverter.dollarToYen(param);
>           System.out.println(amount);
>           amount = currencyConverter.yenToEuro(param);
>           System.out.println(amount);

>           System.exit(0);

>         } catch (Exception ex) {
>           System.err.println("Caught an unexpected exception!");
>           ex.printStackTrace();
>         }
>       }
>     }

> ### Compiling the Application Client

> The application client files are compiled at the same time as the enterprise bean files, as described in Compiling the Source Files.

> ### Packaging the Application Client

> To package an application client component, you run the New Application Client wizard of `deploytool`. During this process the wizard performs the following tasks.

> - Creates the application client's deployment descriptor
> - Puts the deployment descriptor and client files into a JAR file
> - Adds the JAR file to the application's `ConverterApp.ear` file

> To start the New Application Client wizard, select FileNewApplication Client. The wizard displays the following dialog boxes.

> 1. Introduction dialog box
> 1. Read the explanatory text for an overview of the wizard's features.
> 2. Click Next.
> 2. JAR File Contents dialog box
> 1. Select the button labeled Create New AppClient Module in Application.
> 2. In the combo box below this button, select `ConverterApp`.
> 3. In the AppClient Display Name field, enter `ConverterClient`.
> 4. Click Edit Contents.
> 5. In the tree under Available Files, locate this directory:

> `<``INSTALL``>/j2eetutorial14/examples/ejb/converter/build/`

> 6. Select the `ConverterClient.class` file.
> 7. Click Add.
> 8. Click OK.
> 9. Click Next.
> 3. General dialog box
> 1. In the Main Class combo box, select `ConverterClient`.
> 2. Click Next.
> 3. Click Finish.

> ### Specifying the Application Client's Enterprise Bean Reference

> When it invokes the `lookup` method, the `ConverterClient` refers to the home of an enterprise bean:

>     Object objref = myEnv.lookup("ejb/SimpleConverter");

> You specify this reference in `deploytool` as follows.

> 1. In the tree, select `ConverterClient`.
> 2. Select the EJB Ref's tab.
> 3. Click Add.
> 4. In the Coded Name field, enter `ejb/SimpleConverter`.
> 5. In the EJB Type field, select Session.
> 6. In the Interfaces field, select Remote.
> 7. In the Home Interface field enter, `converter.ConverterHome`.
> 8. In the Local/Remote Interface field, enter `converter.Converter`.
> 9. In the JNDI Name field, select `ConverterBean`.
> 10. Click OK.

Download PDF Home History |  | API Search Feedback FAQ

All of the material in The J2EE(TM) 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.