user manual

Chapter 11: Writing enterprise bean clients 105
Client view of an enterprise bean
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 calls the enterprise