Home TOC Index

Search Feedback

The PlayerEJB Code

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

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

The source code for this example is in the j2eetutorial/examples/src/ejb/cmproster directory. To compile the code, go to the j2eetutorial/examples directory and type ant cmproster. A sample RosterApp.ear file is in the j2eetutorial/examples/ears directory.

Entity Bean Class

For container-managed persistence, the code of the entity bean class must meet the syntax requirements. First, the class must be defined as public and abstract. Also, 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 5. Table 6-1 compares the code of the two types of entity beans.

Table 6-1 Coding Differences between Persistent Types 

Difference	Container-Managed	Bean-Managed
Class definition	Abstract	Not abstract
Database access calls	Generated by tools	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	Should be 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 5 .

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 PlayerEJB 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, since a player can belong to multiple teams, a PlayerEJB instance may be related to many TeamEJB instances. To specify this relationship, the deployment descriptor of PlayerEJB 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);
 

Select Methods

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

• A select method queries a database and returns objects.
• 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 persistent fields or the home interfaces of related entity beans. A finder method can return only the home interface (or a collection thereof) that defines it.
• Since 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 a business 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

Since 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. After the ejbCreate method completes, 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;	
}
 

Except for a debug statement, the ejbRemove method in the PlayerBean class is empty. The container invokes ejbRemove right before it deletes the database row.

The ejbPostCreate method must have the same input parameters and return type 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 may not set a relationship field in the ejbCreate method.

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 may be invoked by local clients.

The syntax rules for a create method follow:

• The name begins with create.
• It has the same number and types of arguments as its matching ejbCreate method in the entity bean class.
• It returns the local interface type of the entity bean.
• The throws clause includes the exceptions specified by the throws clause of the corresponding ejbCreate method.
• The throws clause contains the javax.ejb.CreateException.

These rules apply for a finder method:

• The name begins with find.
• The return type is the entity bean's local interface type, or a collection of those types.
• The throws clause contains 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 may 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;	
}
 

Home TOC Index

Search Feedback