The PlayerBean Code - The J2EE 1.4 Tutorial

The PlayerBean Code

The PlayerBean entity bean represents a player in a sports league. Like any local entity bean with container-managed persistence, PlayerBean needs the following code:

Entity bean class (PlayerBean)
Local home interface (LocalPlayerHome)
Local interface (LocalPlayer)

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

Entity Bean Class

The code of the entity bean class must meet the container-managed persistence syntax requirements. First, the class must be defined as public and abstract. Second, the class must implement the following:

The EntityBean interface
Zero or more ejbCreate and ejbPostCreate methods
The get and set access methods, defined as abstract, for the persistent and relationship fields
Any select methods, defining them as abstract
The home methods
The business methods

The entity bean class must not implement these methods:

The finder methods
The finalize method

Differences between Container-Managed and Bean-Managed Code

Because it contains no calls to access the database, an entity bean with container-managed persistence requires a lot less code than one with bean-managed persistence. For example, the PlayerBean.java source file discussed in this chapter is much smaller than the SavingsAccountBean.java code documented in Chapter 26. Table 27-1 compares the code of the two types of entity beans.

Table 27-1 Coding Differences between Persistent Types 

Difference	Container-Managed	Bean-Managed
Class definition	Abstract	Not abstract
Database access calls	Handled by container	Coded by developers
Persistent state	Represented by virtual persistent fields	Coded as instance variables
Access methods for persistent and relationship fields	Required	None
findByPrimaryKey method	Handled by container	Coded by developers
Customized finder methods	Handled by container, but the developer must define the EJB QL) queries	Coded by developers
Select methods	Handled by container	None
Return value of ejbCreate	null	Must be the primary key

Note that for both types of persistence, the rules for implementing business and home methods are the same. See the sections The Business Methods and The Home Methods in Chapter 26.

Access Methods

An entity bean with container-managed persistence has persistent and relationship fields. These fields are virtual, so you do not code them in the class as instance variables. Instead, you specify them in the bean's deployment descriptor. To permit access to the fields, you define abstract get and set methods in the entity bean class.

Access Methods for Persistent Fields

The EJB container automatically performs the database storage and retrieval of the bean's persistent fields. The deployment descriptor of PlayerBean specifies the following persistent fields:

playerId (primary key)
name
position
salary

The PlayerBean class defines the access methods for the persistent fields as follows:

public abstract String getPlayerId();
public abstract void setPlayerId(String id);

public abstract String getName();
public abstract void setName(String name);

public abstract String getPosition();
public abstract void setPosition(String position);

public abstract double getSalary();
public abstract void setSalary(double salary); 

The name of an access method begins with get or set, followed by the capitalized name of the persistent or relationship field. For example, the accessor methods for the salary field are getSalary and setSalary. This naming convention is similar to that of JavaBeans components.

Access Methods for Relationship Fields

In the RosterApp application, a player can belong to multiple teams, so a PlayerBean instance may be related to many TeamBean instances. To specify this relationship, the deployment descriptor of PlayerBean defines a relationship field named teams. In the PlayerBean class, the access methods for the teams relationship field are as follows:

public abstract Collection getTeams();
public abstract void setTeams(Collection teams); 

Finder and Select Methods

Finder and select methods use EJB QL queries to return objects and state information of entity beans using container-managed persistence.

A select method is similar to a finder method in the following ways:

A select method can return a local or remote interface (or a collection of interfaces).
A select method queries a database.
The deployment descriptor specifies an EJB QL query for a select method.
The entity bean class does not implement the select method.

However, a select method differs significantly from a finder method:

A select method can return a persistent field (or a collection thereof) of a related entity bean. A finder method can return only a local or remote interface (or a collection of interfaces).
Because it is not exposed in any of the local or remote interfaces, a select method cannot be invoked by a client. It can be invoked only by the methods implemented within the entity bean class. A select method is usually invoked by either a business or a home method.
A select method is defined in the entity bean class. For bean-managed persistence, a finder method is defined in the entity bean class, but for container-managed persistence it is not.

The PlayerBean class defines these select methods:

public abstract Collection ejbSelectLeagues(LocalPlayer player)
  throws FinderException;
public abstract Collection ejbSelectSports(LocalPlayer player)
  throws FinderException; 

The signature for a select method must follow these rules:

The prefix of the method name must be ejbSelect.
The access control modifier must be public.
The method must be declared as abstract.
The throws clause must include the javax.ejb.FinderException.

Business Methods

Because clients cannot invoke select methods, the PlayerBean class wraps them in the getLeagues and getSports business methods:

public Collection getLeagues() throws FinderException {

  LocalPlayer player = 
    (team.LocalPlayer)context.getEJBLocalObject();
  return ejbSelectLeagues(player);
}

public Collection getSports() throws FinderException {

  LocalPlayer player = 
    (team.LocalPlayer)context.getEJBLocalObject();
  return ejbSelectSports(player);
} 

Entity Bean Methods

Because the container handles persistence, the life-cycle methods in the PlayerBean class are nearly empty.

The ejbCreate method initializes the bean instance by assigning the input arguments to the persistent fields. At the end of the transaction that contains the create call, the container inserts a row into the database. Here is the source code for the ejbCreate method:

public String ejbCreate (String id, String name, 
    String position, double salary) throws CreateException {

    setPlayerId(id);
    setName(name);
    setPosition(position);
    setSalary(salary);
    return null;
} 

The ejbPostCreate method returns void, and it has the same input parameters as the ejbCreate method. If you want to set a relationship field to initialize the bean instance, you should do so in the ejbPostCreate method. You cannot set a relationship field in the ejbCreate method.

Except for a debug statement, the ejbRemove method in the PlayerBean class is empty. The container invokes ejbRemove before removing the entity object.

The container automatically synchronizes the state of the entity bean with the database. After the container loads the bean's state from the database, it invokes the ejbLoad method. In like manner, before storing the state in the database, the container invokes the ejbStore method.

Local Home Interface

The local home interface defines the create, finder, and home methods that can be invoked by local clients.

The syntax rules for a create method follow:

The name must begin with create.
It must have the same number and types of arguments as its matching ejbCreate method in the entity bean class.
It must return the local interface type of the entity bean.
The throws clause must include the exceptions specified by the throws clause of the corresponding ejbCreate method.
The throws clause must contain the javax.ejb.CreateException.

These rules apply for a finder method:

The name must begin with find.
The return type must be the entity bean's local interface type or a collection of those types.
The throws clause must contain the javax.ejb.FinderException.
The findByPrimaryKey method must be defined.

An excerpt of the LocalPlayerHome interface follows.

package team;

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

public interface LocalPlayerHome extends EJBLocalHome {
    
    public LocalPlayer create (String id, String name, 
        String position, double salary)
        throws CreateException;
    
    public LocalPlayer findByPrimaryKey (String id)
        throws FinderException;
    
    public Collection findByPosition(String position) 
        throws FinderException;
     ...
    public Collection findByLeague(LocalLeague league) 
        throws FinderException;
    ...
  } 

Local Interface

This interface defines the business and access methods that a local client can invoke. The PlayerBean class implements two business methods: getLeagues and getSports. It also defines several get and set access methods for the persistent and relationship fields. The set methods are hidden from the bean's clients because they are not defined in the LocalPlayer interface. However, the get methods are exposed to the clients by the interface:

package team;

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

public interface LocalPlayer extends EJBLocalObject {

    public String getPlayerId();
    public String getName();
    public String getPosition();
    public double getSalary();
    public Collection getTeams();

    public Collection getLeagues() throws FinderException;
    public Collection getSports() throws FinderException;
} 

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.