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:

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 entity bean class must not implement these methods:

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:

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:

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

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:

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:

These rules apply for a finder method:

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;
}