Document Information

Preface

Part I Introduction

1.  Overview

2.  Using the Tutorial Examples

Part II The Web Tier

3.  Getting Started with Web Applications

4.  Java Servlet Technology

5.  JavaServer Pages Technology

6.  JavaServer Pages Documents

7.  JavaServer Pages Standard Tag Library

8.  Custom Tags in JSP Pages

9.  Scripting in JSP Pages

10.  JavaServer Faces Technology

11.  Using JavaServer Faces Technology in JSP Pages

12.  Developing with JavaServer Faces Technology

13.  Creating Custom UI Components

14.  Configuring JavaServer Faces Applications

15.  Internationalizing and Localizing Web Applications

Part III Web Services

16.  Building Web Services with JAX-WS

17.  Binding between XML Schema and Java Classes

18.  Streaming API for XML

19.  SOAP with Attachments API for Java

Part IV Enterprise Beans

20.  Enterprise Beans

21.  Getting Started with Enterprise Beans

22.  Session Bean Examples

A Web Service Example: helloservice

The Web Service Endpoint Implementation Class

Stateless Session Bean Implementation Class

Building, Packaging, Deploying, and Testing the helloservice Example

Building, Packaging, and Deploying the helloservice Example Using NetBeans IDE

Building, Packaging, and Deploying the helloservice Example Using Ant

Testing the Service without a Client

Using the Timer Service

The Timeout Method

Creating Timers

Canceling and Saving Timers

Getting Timer Information

Transactions and Timers

The timersession Example

Building, Packaging, Deploying, and Running the timersession Example

Building, Packaging, Deploying, and Running the timersession Example Using NetBeans IDE

Building, Packaging, and Deploying the timersession Example Using Ant

Running the timersession Application Client Using Ant

Handling Exceptions

23.  A Message-Driven Bean Example

Part V Persistence

24.  Introduction to the Java Persistence API

25.  Persistence in the Web Tier

26.  Persistence in the EJB Tier

27.  The Java Persistence Query Language

Part VI Services

28.  Introduction to Security in the Java EE Platform

29.  Securing Java EE Applications

30.  Securing Web Applications

31.  The Java Message Service API

32.  Java EE Examples Using the JMS API

33.  Transactions

34.  Resource Connections

35.  Connector Architecture

Part VII Case Studies

36.  The Coffee Break Application

37.  The Duke's Bank Application

Part VIII Appendixes

A.  Java Encoding Schemes

B.  About the Authors

Index

 

The cart Example

The cart 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 assemble cart, you need the following code:

  • Session bean class (CartBean)

  • Remote business interface (Cart)

All session beans require a session bean class. All enterprise beans that permit remote access must have a remote business 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 tut-install/javaeetutorial5/examples/ejb/cart/ directory.

The Business Interface

The Cart business interface is a plain Java interface that defines all the business methods implemented in the bean class. If the bean class implements a single interface, that interface is assumed to the business interface. The business interface is a local interface unless it is annotated with the javax.ejb.Remote annotation; the javax.ejb.Local annotation is optional in this case.

The bean class may implement more than one interface. If the bean class implements more than one interface, either the business interfaces must be explicitly annotated either @Local or @Remote, or the business interfaces must be specified by decorating the bean class with @Local or @Remote. However, the following interfaces are excluded when determining if the bean class implements more than one interface:

  • java.io.Serializable

  • java.io.Externalizable

  • Any of the interfaces defined by the javax.ejb package

The source code for the Cart business interface follows:

package com.sun.tutorial.javaee.ejb;

import java.util.List;
import javax.ejb.Remote;

@Remote
public interface Cart {
    public void initialize(String person) throws BookException;
    public void initialize(String person, String id)
         throws BookException;
    public void addBook(String title);
    public void removeBook(String title) throws BookException;
    public List<String> getContents();
    public void remove();
}

Session Bean Class

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

  • The class is annotated @Stateful.

  • The class implements the business methods defined in the business interface.

Stateful session beans also may:

  • Implement the business interface, a plain Java interface. It is good practice to implement the bean’s business interface.

  • Implement any optional life cycle callback methods, annotated @PostConstruct, @PreDestroy, @PostActivate, and @PrePassivate.

  • Implement any optional business methods annotated @Remove.

The source code for the CartBean class follows.

package com.sun.tutorial.javaee.ejb;

import java.util.ArrayList;
import java.util.List;
import javax.ejb.Remove;
import javax.ejb.Stateful;

@Stateful
public class CartBean implements Cart {
    String customerName;
    String customerId;
    List<String> contents;

    public void initialize(String person) throws BookException {
        if (person == null) {
            throw new BookException("Null person not allowed.");
        } else {
            customerName = person;
        }

        customerId = "0";
        contents = new ArrayList<String>();
    }

    public void initialize(String person, String id)
                 throws BookException {
        if (person == null) {
            throw new BookException("Null person not allowed.");
        } else {

            customerName = person;
        }

        IdVerifier idChecker = new IdVerifier();

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

        contents = new ArrayList<String>();
    }

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

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

    public List<String> getContents() {
        return contents;
    }

    @Remove
    public void remove() {
        contents = null;
    }
}
Life-Cycle Callback Methods

Methods in the bean class may be declared as a life-cycle callback method by annotating the method with the following annotations:

  • javax.annotation.PostConstruct

  • javax.annotation.PreDestroy

  • javax.ejb.PostActivate

  • javax.ejb.PrePassivate

Life-cycle callback methods must return void and have no parameters.

@PostConstruct methods are invoked by the container on newly constructed bean instances after all dependency injection has completed and before the first business method is invoked on the enterprise bean.

@PreDestroy methods are invoked after any method annotated @Remove has completed, and before the container removes the enterprise bean instance.

@PostActivate methods are invoked by the container after the container moves the bean from secondary storage to active status.

@PrePassivate methods are invoked by the container before the container passivates the enterprise bean, meaning the container temporarily removes the bean from the environment and saves it to secondary storage.

Business Methods

The primary purpose of a session bean is to run business tasks for the client. The client invokes business methods on the object reference it gets from dependency injection or JNDI lookup. 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.create("Duke DeEarl", "123");
...
cart.addBook("Bel Canto");
 ...
List<String> bookList = cart.getContents();
...
cart.removeBook("Gravity’s Rainbow");

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.remove(title);
   if (result == false) {
      throw new BookException(title + "not in cart.");
   }
}

public List<String> getContents() {
   return contents;
}

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

  • The method name must not begin with ejb to avoid conflicts with callback methods 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 through a remote business interface, the arguments and return types must be legal types for the Java RMI API.

  • If the bean is a web service endpoint, the arguments and return types for the methods annotated @WebMethod must be legal types for JAX-WS.

  • 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 a javax.ejb.EJBException. 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.

The Remove Method

Business methods annotated with javax.ejb.Remove in the stateful session bean class can be invoked by enterprise bean clients to remove the bean instance. The container will remove the enterprise bean after a @Remove method completes, either normally or abnormally.

In CartBean, the remove method is a @Remove method:

@Remove
public void remove() {
    contents = null;
}

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 create methods. Helper classes may reside in the EJB JAR file that contains the enterprise bean class, or in an EAR that contains the EJB JAR.

Building, Packaging, Deploying, and Running the cart Example

You can build, package, deploy, and run the cart application using either NetBeans IDE or the Ant tool.

Building, Packaging, and Deploying the cart Example Using NetBeans IDE

Follow these instructions to build, package, and deploy the cart example to your Application Server instance using NetBeans IDE.

  1. In NetBeans IDE, select File→Open Project.

  2. In the Open Project dialog, navigate to tut-install/javaeetutorial5/examples/ejb/.

  3. Select the cart folder.

  4. Select the Open as Main Project and Open Required Projects check boxes.

  5. Click Open Project.

  6. In the Projects tab, right-click the cart project and select Undeploy and Deploy.

This builds and packages the application into cart.ear, located in tut-install/javaeetutorial5/examples/ejb/cart/dist/, and deploys this EAR file to your Application Server instance.

Running the cart Application Client Using NetBeans IDE

To run cart’s application client, select Run→Run Main Project. You will see the output of the application client in the Output pane:

...
Retrieving book title from cart: Infinite Jest
Retrieving book title from cart: Bel Canto
Retrieving book title from cart: Kafka on the Shore
Removing "Gravity’s Rainbow" from cart.
Caught a BookException: "Gravity’s Rainbow" not in cart.
Java Result: 1
run-cart-app-client:
run-nb:
BUILD SUCCESSFUL (total time: 14 seconds)
Building, Packaging, and Deploying the cart Example Using Ant

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:

    tut-install/javaeetutorial5/examples/ejb/cart/
  2. Type the following command:

    ant

    This command calls the default target, which builds and packages the application into an EAR file, cart.ear, located in the dist directory.

  3. Type the following command:

    ant deploy

    cart.ear will be deployed to the Application Server.

Running the cart Application Client Using Ant

When you run the client, the application client container injects any component references declared in the application client class, in this case the reference to the Cart enterprise bean. To run the application client, perform the following steps.

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

    tut-install/javaeetutorial5/examples/ejb/cart/
  2. Type the following command:

    ant run

    This task will retrieve the application client JAR, cartClient.jar and run the application client. cartClient.jar contains the application client class, the helper class BookException, and the Cart business interface.

    This is the equivalent of running:

    appclient -client cartClient.jar
  3. In the terminal window, the client displays these lines:

    [echo] running application client container.
    [exec] Retrieving book title from cart: Infinite Jest
    [exec] Retrieving book title from cart: Bel Canto
    [exec] Retrieving book title from cart: Kafka on the Shore
    [exec] Removing "Gravity’s Rainbow" from cart.
    [exec] Caught a BookException: "Gravity’s Rainbow" not in cart.
    [exec] Result: 1
The all Task

As a convenience, the all task will build, package, deploy, and run the application. To do this, enter the following command:

ant all

Undeploying the cart Example

To undeploy cart.ear using NetBeans IDE:

  1. Click the Services tab.

  2. Expand the Servers node and locate the Application Server instance to which you deployed cart.

  3. Expand your Application Server instance node, then Applications→Enterprise Applications.

  4. Right-click cart and select Undeploy.

To undeploy cart.ear using Ant, enter the following command:

ant undeploy