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

When a client invokes a create method, the EJB container invokes the corresponding ejbCreate
method. Typically, an ejbCreate method in an entity bean performs the following tasks:

Inserts the entity state into the database

Initializes the instance variables

Returns the primary key

Thus, when an entity bean is created , the data that the EJB represents is placed in the database, and a
copy of that data is stored in the EJB container's memory as part of the EJB instance. If a record with
the same primary key already exists in the database, a CreationException will be thrown, and the
EJB object will not be instantiated.

For each ejbCreate method, you must write an ejbPostCreate method in the entity-bean
implementation class. (The ejbPostCreate method is defined in the EntityBean interface that
discussed later.) The EJB container invokes ejbPostCreate immediately after it calls ejbCreate .
Unlike the ejbCreate method, the ejbPostCreate method can invoke the getPrimaryKey method.
In most of situations, however, your ejbPostCreate methods are empty.

A client deletes an entity bean by invoking the remove method. This invocation causes the EJB
container to call the ejbRemove method, which deletes the business-entity object from the database. It
should be noted that the business-entity object is deleted from the database. The entity-bean instance is
not necessarily garbage collected. It is just disassociated with a specific entity object and may be
returned to the EJB pool maintained by the EJB container and ready to represent another business-
entity object (for example, another row in the same table). If the ejbRemove method encounters a
system problem, it should throw the EJBException . If it encounters an application error, it should
throw a RemoveException .

Note

Calling ejbCreate creates a business entity (for example, a row in a database table) in
the persistent storage. Calling ejbRemove deletes a business-entity object from the
persistent storage.

You can find the implementation of the ejbCreate and ejbRemove methods for MemberEJB later in
this chapter, under " An Example BMP Entity Bean — MemberEJB. " You can see that the SQL
commands are coded to insert into and delete from the database.

An entity object can also be created or deleted directly by native database operations. For example, if a
SQL script deletes a row from a table, the entity object represented by the row is deleted, and the
corresponding entity-bean instances become disassociated with the entity object. If a client attempts to
invoke a business method on an entity bean instance after its underlying business object has been
deleted from the database, the client receives NoSuchObjectException .

Find Entity Object

Calling the ejbCreate method creates a business entity in the database. In many situations, the
business entity already exists in the database, and you just need to instantiate an EJB instance to
represent it. The finder methods are designed just for this purpose.

All entity beans have finder methods. Similar to the select command in SQL statements, finder
methods are used by clients to locate business objects stored in the database and to associate them
with entity-bean instances. Each finder method can have different logic for locating the entity object.
The logic may find one entity object or a group of entity objects. If a finder method returns a single
reference to the remote reference, it will return the first valid occurrence of the bean that is located. If a
finder method returns the Collection interface, it will return zero or more references to entity beans.
The client can then iterate over the collection to access each of the available beans.

All home interfaces must have a findByPrimaryKey(PrimaryKeyClass key) method. Since
lookup operations are common for all entity beans, a standard mechanism for looking up one entity
bean by its unique identifier (that is, the primary key) is defined as the findByPrimaryKey() method.
All entity beans have this method available and return exactly one reference to a bean in the form of the