web server - Borland Technical Publications

Client view of an enterprise bean
Every entity bean instance must have a primary key that uniquely identifies it. An entity
bean instance can also have secondary keys that can be used to locate a particular
entity object.
Find methods and primary key class
The default find method for an entity bean is the findByPrimaryKey() method, which
locates the entity object using its primary key value. Its signature is as follows:
findByPrimaryKey( primaryKey )
Every entity bean must implement a findByPrimaryKey() method. The primaryKey
parameter is a separate primary key class that is defined in the deployment descriptor.
The key type is the type for the primary key, and it must be a legal value type in RMI-
IIOP. The primary key class can be any class--a Java class or a class you've written
yourself.
For example, you have an Account entity bean that defines the primary key class
AccountPK. AccountPK is a String type, and it holds the identifier for the Account bean.
You can obtain a reference to a specific Account entity bean instance by setting the
AccountPK to the account identifier and invoking the findByPrimaryKey() method, as
shown in the following code sample.
AccountPK accountPK = new AccountPK("1234-56-789");
Account source = accountHome.findByPrimaryKey( accountPK );
The bean provider can define additional finder methods that a client can use.
Create and remove methods
A client can also create entity beans using create methods defined in the home
interface. When a client invokes a create() method for an entity bean, the new instance
of the entity object is saved in the data store. The new entity object always has a
primary key value that is its identifier. Its state may be initialized to values passed as
parameters to the create() method.
Keep in mind that an entity bean exists for as long as data is present in the database.
The life of the entity bean is not bound by the client's session. The entity bean can be
removed by invoking one of the bean's remove() methods--these methods remove the
bean and the underlying representation of the entity data from the database. It is also
possible to directly delete an entity object, such as by deleting a database record using
the DBMS or with a legacy application.
Invoking methods
Once the client has obtained a reference to the bean's remote interface, the client can
invoke the methods defined in the remote interface for this enterprise bean. The
methods pertaining to the bean's business logic are of most interest to the client. There
are also methods for getting information about the bean and its interfaces, getting the
bean object's handle, testing if one bean is identical to another bean, and methods for
removing the bean instance.
The next code sample illustrates how a client calls methods of an enterprise bean, in
this case, a cart session bean. We pick up the client code from the point where it has
created a new session bean instance for a card holder and retrieved a Cart reference
to the remote interface. At this point, the client is ready to invoke the bean methods.
First, the client creates a new book object, setting its title and price parameters. Then, it
invokes the enterprise bean business method addItem() to add the book object to a
shopping cart. The addItem() method is defined on the CartBean session bean, and is
made public through the Cart remote interface. The client adds other items (not shown
here), then calls its own summarize() method to list the items in the shopping cart. This
is followed by the remove() method to remove the bean instance. Notice that a client
88 BES Developer’s Guide