Download PDF Home History |  | API Search Feedback FAQ

> ## The CartBean Example

> The `CartBean` session bean represents a shopping cart in an online bookstore. The bean's client can add a book to the cart, remove a book, or retrieve the cart's contents. To construct `CartBean`, you need the following code:

> - Session bean class (`CartBean`)
> - Home interface (`CartHome`)
> - Remote interface (`Cart`)

> All session beans require a session bean class. All enterprise beans that permit remote access must have a home and a remote interface. To meet the needs of a specific application, an enterprise bean may also need some helper classes. The `CartBean` session bean uses two helper classes (`BookException` and `IdVerifier`) which are discussed in the section Helper Classes.

> The source code for this example is in the `<``INSTALL``>/j2eetutorial14/examples/ejb/cart/` directory.

> ### Session Bean Class

> The session bean class for this example is called `CartBean`. Like any session bean, the `CartBean` class must meet these requirements:

> - It implements the `SessionBean` interface.
> - The class is defined as `public`.
> - The class cannot be defined as `abstract` or `final`.
> - It implements one or more `ejbCreate` methods.
> - It implements the business methods.
> - It contains a `public` constructor with no parameters.
> - It must not define the `finalize` method.

> The source code for the `CartBean` class follows.

>     import java.util.*;
>     import javax.ejb.*;

>     public class CartBean implements SessionBean {

>       String customerName;
>       String customerId;
>       Vector contents;

>       public void ejbCreate(String person)
>         throws CreateException {

>         if (person == null) {
>           throw new CreateException("Null person not allowed.");
>         }
>         else {
>           customerName = person;
>         }

>         customerId = "0";
>         contents = new Vector();
>       }

>       public void ejbCreate(String person, String id)
>         throws CreateException {

>         if (person == null) {
>           throw new CreateException("Null person not allowed.");
>         }
>         else {
>           customerName = person;
>         }

>         IdVerifier idChecker = new IdVerifier();
>         if (idChecker.validate(id)) {
>           customerId = id;
>         }
>         else {
>           throw new CreateException("Invalid id: "+ id);
>         }

>         contents = new Vector();
>       }

>       public void addBook(String title) {
>         contents.addElement(title);
>       }

>       public void removeBook(String title) throws BookException {

>         boolean result = contents.removeElement(title);
>         if (result == false) {
>           throw new BookException(title + "not in cart.");
>         }
>        }

>        public Vector getContents() {
>           return contents;
>        }

>        public CartBean() {}
>        public void ejbRemove() {}
>        public void ejbActivate() {}
>        public void ejbPassivate() {}
>        public void setSessionContext(SessionContext sc) {}

>     }

> #### The SessionBean Interface

> The `SessionBean` interface extends the `EnterpriseBean` interface, which in turn extends the `Serializable` interface. The `SessionBean` interface declares the `ejbRemove`, `ejbActivate`, `ejbPassivate`, and `setSessionContext` methods. The `CartBean` class doesn't use these methods, but it must implement them because they're declared in the `SessionBean` interface. Consequently, these methods are empty in the `CartBean` class. Later sections explain when you might use these methods.

> #### The ejbCreate Methods

> Because an enterprise bean runs inside an EJB container, a client cannot directly instantiate the bean. Only the EJB container can instantiate an enterprise bean. During instantiation, the example program performs the following steps.

> 1. The client invokes a `create` method on the home object:

> `Cart shoppingCart = home.create("Duke DeEarl","123");`

> 2. The EJB container instantiates the enterprise bean.
> 3. The EJB container invokes the appropriate `ejbCreate` method in `CartBean`:

> `public void ejbCreate(String person, String id)
> throws CreateException {
> if (person == null) {
> throw new CreateException("Null person not allowed.");
> }
> else {
> customerName = person;
> }
> IdVerifier idChecker = new IdVerifier();
> if (idChecker.validate(id)) {
> customerId = id;
> }
> else {
> throw new CreateException("Invalid id: "+ id);
> }
> contents = new Vector();
> }`

> Typically, an `ejbCreate` method initializes the state of the enterprise bean. The preceding `ejbCreate` method, for example, initializes the `customerName` and `customerId` variables by using the arguments passed by the `create` method.

> An enterprise bean must have one or more `ejbCreate` methods. The signatures of the methods must meet the following requirements:

> - The access control modifier must be `public`.
> - The return type must be `void`.
> - If the bean allows remote access, the arguments must be legal types for the Java Remote Method Invocation (Java RMI) API.
> - The modifier cannot be `static` or `final`.

> The `throws` clause can include the `javax.ejb.CreateException` and other exceptions that are specific to your application. The `ejbCreate` method usually throws a `CreateException` if an input parameter is invalid.

> #### Business Methods

> The primary purpose of a session bean is to run business tasks for the client. The client invokes business methods on the remote object reference that is returned by the `create` method. From the client's perspective, the business methods appear to run locally, but they actually run remotely in the session bean. The following code snippet shows how the `CartClient` program invokes the business methods:

>     Cart shoppingCart = home.create("Duke DeEarl", "123");
>     ...
>     shoppingCart.addBook("The Martian Chronicles");
>     shoppingCart.removeBook("Alice In Wonderland");
>     bookList = shoppingCart.getContents();

> The `CartBean` class implements the business methods in the following code:

>     public void addBook(String title) {
>        contents.addElement(title);
>     }

>     public void removeBook(String title) throws BookException {
>        boolean result = contents.removeElement(title);
>        if (result == false) {
>           throw new BookException(title + "not in cart.");
>        }
>     }

>     public Vector getContents() {
>        return contents;
>     }

> The signature of a business method must conform to these rules:

> - The method name must not conflict with one defined by the EJB architecture. For example, you cannot call a business method `ejbCreate` or `ejbActivate`.
> - The access control modifier must be `public`.
> - If the bean allows remote access, the arguments and return types must be legal types for the Java RMI API.
> - The modifier must not be `static` or `final`.

> The `throws` clause can include exceptions that you define for your application. The `removeBook` method, for example, throws the `BookException` if the book is not in the cart.

> To indicate a system-level problem, such as the inability to connect to a database, a business method should throw the `javax.ejb.EJBException`. When a business method throws an `EJBException`, the container wraps it in a `RemoteException`, which is caught by the client. The container will not wrap application exceptions such as `BookException`. Because `EJBException` is a subclass of `RuntimeException`, you do not need to include it in the `throws` clause of the business method.

> ### Home Interface

> A home interface extends the `javax.ejb.EJBHome` interface. For a session bean, the purpose of the home interface is to define the `create` methods that a remote client can invoke. The `CartClient` program, for example, invokes this `create` method:

>     Cart shoppingCart = home.create("Duke DeEarl", "123");

> Every `create` method in the home interface corresponds to an `ejbCreate` method in the bean class. The signatures of the `ejbCreate` methods in the `CartBean` class follow:

>     public void ejbCreate(String person) throws CreateException
>     ...
>     public void ejbCreate(String person, String id)
>        throws CreateException

> Compare the `ejbCreate` signatures with those of the `create` methods in the `CartHome` interface:

>     import java.io.Serializable;
>     import java.rmi.RemoteException;
>     import javax.ejb.CreateException;
>     import javax.ejb.EJBHome;

>     public interface CartHome extends EJBHome {
>       Cart create(String person) throws
>                 RemoteException, CreateException;
>       Cart create(String person, String id) throws
>                 RemoteException, CreateException;
>     }

> The signatures of the `ejbCreate` and `create` methods are similar, but they differ in important ways. The rules for defining the signatures of the `create` methods of a home interface follow.

> - The number and types of arguments in a `create` method must match those of its corresponding `ejbCreate` method.
> - The arguments and return type of the `create` method must be valid RMI types.
> - A `create` method returns the remote interface type of the enterprise bean. (But an `ejbCreate` method returns `void`.)
> - The `throws` clause of the `create` method must include the j`ava.rmi.RemoteException` and the `javax.ejb.CreateException`.

> ### Remote Interface

> The remote interface, which extends `javax.ejb.EJBObject`, defines the business methods that a remote client can invoke. Here is the source code for the `Cart` remote interface:

>     import java.util.*;
>     import javax.ejb.EJBObject;
>     import java.rmi.RemoteException;

>     public interface Cart extends EJBObject {

>        public void addBook(String title) throws RemoteException;
>        public void removeBook(String title) throws
>                   BookException, RemoteException;
>        public Vector getContents() throws RemoteException;
>     }

> The method definitions in a remote interface must follow these rules:

> - Each method in the remote interface must match a method implemented in the enterprise bean class.
> - The signatures of the methods in the remote interface must be identical to the signatures of the corresponding methods in the enterprise bean class.
> - The arguments and return values must be valid RMI types.
> - The `throws` clause must include the `java.rmi.RemoteException`.

> ### Helper Classes

> The `CartBean` session bean has two helper classes: `BookException` and `IdVerifier`. The `BookException` is thrown by the `removeBook` method, and the `IdVerifier` validates the `customerId` in one of the `ejbCreate` methods. Helper classes must reside in the EJB JAR file that contains the enterprise bean class.

> ### Building the CartBean Example

> Now you are ready to compile the remote interface (`Cart.java`), the home interface (`CartHome.java`), the enterprise bean class (`CartBean.java`), the client class (`CartClient.java`), and the helper classes (`BookException.java` and `IdVerifier.java`).

> 1. In a terminal window, go to this directory:

> `<``INSTALL``>/j2eetutorial14/examples/ejb/cart/`

> 2. Type the following command:

> `asant build`

> ### Creating the Application

> In this section, you'll create a J2EE application named `CartApp`, storing it in the file `CartApp.ear`.

> 1. In `deploytool`, select FileNewApplication.
> 2. Click Browse.
> 3. In the file chooser, navigate to `<INSTALL>``/j2eetutorial14/examples/ejb/cart/`.
> 4. In the File Name field, enter `CartApp`.
> 5. Click New Application.
> 6. Click OK.
> 7. Verify that the `CartApp.ear` file resides in `<``INSTALL``>/j2eetutorial14/examples/ejb/cart/`.

> ### Packaging the Enterprise Bean

> 1. In `deploytool`, select FileNewEnterprise Bean.
> 2. In the EJB JAR screen:
> 1. Select Create New JAR Module in Application.
> 2. In the Create New JAR Module in Application field, select `CartApp`.
> 3. In the JAR Name field, enter `CartJAR`.
> 4. Click Choose Module File.
> 5. Click Edit Contents.
> 6. Locate the `<``INSTALL``>/j2eetutorial14/examples/ejb/cart/build/` directory.
> 7. Select `BookException.class`, `Cart.class`, `CartBean.class`,
>    `CartHome.class`, and `IdVerifier.class`.
> 8. Click Add.
> 9. Click OK.
> 10. Click Next.
> 3. In the General screen:
> 1. In the Enterprise Bean Class field, select `CartBean`.
> 2. In the Enterprise Bean Name field, enter `CartBean`.
> 3. In the Enterprise Bean Type field, select `Stateful Session`.
> 4. In the Remote Home Interface field, select `CartHome`.
> 5. In the Remote Interface field, select `Cart`.
> 6. Click Next.
> 4. Click Finish.

> ### 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 `CartApp.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 `CartApp`.
> 3. In the AppClient Display Name field, enter `CartClient`.
> 4. Click Edit Contents.
> 5. In the tree under Available Files, locate the `<INSTALL>``/j2eetutorial14/examples/ejb/cart/build` directory.
> 6. Select `CartClient.class`.
> 7. Click Add.
> 8. Click OK.
> 9. Click Next.
> 3. General dialog box
> 1. In the Main Class combo box, select `CartClient`.
> 2. Click Next.
> 3. Click Finish.

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

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

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

> You specify this reference as follows.

> 1. In the tree, select `CartClient`.
> 2. Select the EJB Ref's tab.
> 3. Click Add.
> 4. In the Coded Name field, enter `ejb/SimpleCart`.
> 5. In the EJB Type field, select Session.
> 6. In the Interfaces field, select Remote.
> 7. In the Home Interface field, enter `CartHome`.
> 8. In the Local/Remote Interface field, enter `Cart`.
> 9. In the JNDI Name field, select `CartBean`.
> 10. Click OK.

> #### Deploying the Enterprise Application

> Now that the J2EE application contains the components, it is ready for deployment.

> 1. Select `CartApp`.
> 2. Select ToolsDeploy.
> 3. Under Connection Settings, enter the user name and password for the Sun Java System Application Server Platform Edition 8.
> 4. Under Application Client Stub Directory, check Return Client Jar.
> 5. In the field below the checkbox enter `<INSTALL>``/j2eetutorial14/examples/ejb/cart/`.
> 6. Click OK.
> 7. In the Distribute Module dialog box, click Close when the deployment completes.
> 8. Verify the deployment.
> 1. In the tree, expand the Servers node and select the host that is running the Application Server.
> 2. In the Deployed Objects table, make sure that `CartApp` is listed and that its status is `Running`.
> 3. Verify that `CartAppClient.jar` is in `<INSTALL>``/j2eetutorial14/examples/ejb/cart/.`

> #### Running the Application Client

> To run the application client, perform the following steps.

> 1. In a terminal window, go to the `<INSTALL>``/j2eetutorial14/
>    examples/ejb/cart/` directory.
> 2. Type the following command:

> `appclient -client CartAppClient.jar`

> 3. In the terminal window, the client displays these lines:

> `The Martian Chronicles
> 2001 A Space Odyssey
> The Left Hand of Darkness
> Caught a BookException: Alice in Wonderland not in cart.`

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.