Client's View
You've now learned how to specify, implement, and deploy BMP Entity beans, but how are they used? As you can probably imagine, the steps to obtain a reference to an Entity bean are similar to that for Session beans:
1. |
Look up the home interface for the Entity bean from JNDI. |
2. |
To create a new entity instance, use the relevant home.create() method. |
3. | |
4. |
For the returned local proxy to the Entity bean, invoke the business methods defined in the local interface of the bean. |
The javax.ejb.EJBLocalObject interface also defines a number of other methods that can be called by the client, and it is worth discussing the semantics of these briefly:
The getPrimaryKey() method of EJBLocalObject returns the primary key that identifies the bean.
Caution
Note that because EJBLocalObject is also the super-interface for Session bean interfaces, this method can also be called when the client has a reference to the local proxy of a Session bean. However, because primary keys do not make sense for Session beans, an EJBException will always be thrown.
If an Entity bean has both a local and a remote interface, and then EJBObject.getPrimaryKey() (from the remote proxy) and EJBLocalObject.getPrimaryKey() (from the local proxy) will both return objects that are equal (according to the definition the primary key's definition of equals()).
The isIdentical() method can be used instead of comparing primary key classes to determine if two bean references refer to the same Entity bean. In other words, bean1.isIdentical(bean2) returns true if and only if bean1.getPrimaryKey().equals(bean2.getPrimaryKey()).
One scenario that can occur is that a client can have a reference to an Entity bean, and then the bean could be deleted by some other client. This could occur either by an EJB application client that invokes remove() on the same Entity bean, or it could be a non-EJB client that deletes the data directly from the underlying persistent data store. Either way, the original client will not be notified of this, and won't detect this situation until it next invokes a method on the Entity bean. In this case, the client will receive a javax.ejb.NoSuchObjectLocalException (a subclass of javax.ejb.EJBException, in turn a subclass of java.lang.RuntimeException) if accessing the Entity bean through its local interface.
The javax.ejb.NoSuchObjectLocalException caught by local clients is analogous to the java.rmi.NoSuchObjectException that would be caught if accessing the Entity bean through its remote interface. Table 6.3 shows the table from yesterday detailing various other exceptions, supplemented with the exception classes received by local clients.
| What | Event | Local Client Receives | Remote Client Receives |
|---|---|---|---|
| Any bean | Throws javax.ejb.EJBException (or any subclass) | javax.ejb.EJBException (or subclass) | java.rmi.RemoteException |
| BMP Entity bean | Throws NoSuchEntityException | javax.ejb.NoSuchObjectException | java.rmi.NoSuchEntity Exception |
| Container | When client invokes method ona reference to a bean that no longer exists | javax.ejb.NoSuchObjectLocalException | java.rmi.NoSuchObject Exception |
| When client calls a method without a transaction context | javax.ejb.TransactionRequired LocalException | javax.transaction.TransactionRequired Exception | |
| When client has insufficient security access | javax.ejb.AccessLocal | java.rmi.AccessException Exception | |
| When transaction needs to be rolled back | javax.ejb.TransactionRolledBack LocalException | javax.transaction.TransactionRolledBack Exception |
As you can see, the EJB Specification makes some attempt at a naming standard so that the models are as similar as possible for local and remote clients.