Bean-Managed Persistence - Java Database Programming Bible - page 526

bean's remote interface. In addition to the findByPrimaryKey()method , other findByxxx
methods can be defined in the home interface to implement application-specific business logic. As seen
in Listing 21-2 , the MemberEJB 's home interface defines two finder methods. The
findByPrimaryKey(String id) method returns the remote interface. But the
findByMembershipYear(int minYear) returns a Collection because there may be zero or
more members that have established their membership for a certain number of years.

Like the create methods, each finder method must have a matching method in the implementation
classes. The method name in the implementation class is the same as that in the home interface,
except a prefix ejb is added, for example, ejbFindByPrimaryKey . The method must have the same
signature. However, the return type may be different. If only one entity-bean reference is returned, the
ejbFindByxxx method returns the primary key, instead of the remote interface.

The implementation of the MemberEJB 's finder methods is shown in Listing 21-6 . With BMP, the SQL
code is written in these implementations to locate the entity objects in the database. Th e implementation
of ejbFindByPrimaryKey method may look strange to you because it uses a primary key ( String in
this case) for both the method argument and return value. However, remember that a client does not
call ejbFindByPrimaryKey directly. The EJB container calls the ejbFindByPrimaryKey method.
The client invokes the findByPrimaryKey method, which is defined in the home interface and returns
the remote interface.

The following list summarizes the rules for the finder methods you implement in an entity bean class
with BMP:

All finder methods defined in the home interface must be implemented.

At a minimum, the ejbFindByPrimaryKey method must be implemented.

A finder method name must match the name of the corresponding method in the home interface
and must start with the prefix ejb .

The method must be public and cannot be final or static

The return type must be the primary key or a collection of primary keys.

The throws clause may include the javax.ejb.FinderException and exceptions that are specific
to your application. If a finder method returns a single primary key but the requested entity does not
exist, the method should throw the javax.ejb.ObjectNotFoundException (a subclass of
FinderException ). If a finder method returns a collection of primary keys, but it does not find any
objects, it should return an empty collection.

Synchronization of Bean Instance Variable and State of Persistent
Object

Recall from earlier in this chapter that the state of an entity object is kept in the database. The attribute
values of the EJB instance are merely the image of the entity object's state. Since multiple clients can
access the same entity objects via multiple EJB instances, the EJB container must keep the attribute
values of the EJB instances and the state of the corresponding entity object synchronized. The
synchronization mechanisms are different between the BMP and CMP entity beans. With BMP, the EJB
container maintains the synchronization by calling the ejbLoad and ejbStore methods you have
coded in the EJB implementation class.

The ejbLoad and ejbStore methods are defined in the EntityBean interface, which is shown in
Listing 21-4 . The EntityBean interface defines a group of life-cycle methods for the EJB container to
use. All entity-bean implementation classes extend the EntityBean interface. You may have noticed
that the implementation class shown in Listing 21-6 (in Section: An Example BMP Entity EJB) extends
the EntityBean interface. Therefore, all the methods defined in the EntityBean interface must be
implemented in the EJB class. With BMP, you need to write a certain amount of code to implement the
ejbLoad and ejbStore methods. The other methods are typically empty or have only a few lines of
code.

Listing 21-4: EntityBean home interface