Download PDF Home History |  | API Search Feedback FAQ

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

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.