Sun Microsystems Inc

11.1.9.3 FinderException

From the client’s perspective, a FinderException (or a subclass of FinderException) indicates that an application level error occurred during the find(...) operation. Typically, the client’s transaction has not been marked for rollback because of the FinderException.

The Bean Provider throws the FinderException (or subclass of FinderException) from the ejbFind<METHOD>(...) methods to indicate an application-level error in the finder method. The Bean Provider should not, typically, mark the transaction for rollback before throwing the FinderException.

The Container treats the FinderException as any other application exception. See Section 17.3.

11.1.9.4 ObjectNotFoundException

The ObjectNotFoundException is a subclass of FinderException. It is thrown by the ejbFind<METHOD>(...) methods to indicate that the requested entity object does not exist.

Only single-object finders (see Subsection 11.1.8) should throw this exception. Multi-object finders must not throw this exception. Multi-object finders should return an empty collection as an indication that no matching objects were found.

11.1.9.5 RemoveException

From the client’s perspective, a RemoveException (or a subclass of RemoveException) indicates that an application level error occurred during a remove(...) operation. If a client receives this exception, the client does not know, in general, whether the entity object was removed or not. The client also does not know if the transaction has been marked for rollback. (However, the client may determine the transaction status using the UserTransaction interface.)

The Bean Provider throws the RemoveException (or subclass of RemoveException) from the ejbRemove() method to indicate an application-level error from the entity object removal operation. Optionally, the Bean Provider may mark the transaction for rollback before throwing this exception.

The Bean Provider is encouraged to mark the transaction for rollback only if data integrity would be lost if the transaction were committed by the client. Typically, when a RemoteException is thrown, it leaves the database in a consistent state, allowing the client to recover.

The Container treats the RemoveException as any other application exception. See Section 17.3.

11.1.10 Commit options

The Entity Bean protocol is designed to give the Container the flexibility to select the disposition of the instance state at transaction commit time. This flexibility allows the Container to optimally manage the caching of entity object’s state and the association of an entity object identity with the enterprise bean instances.

The Container can select from the following commit-time options:

Sun Microsystems Inc.

Entity Bean Component Contract for Bean Managed PersistenceEnterprise JavaBeans 2.0, Public Draft Overview of Bean Managed

•Option A: The Container caches a “ready” instance between transactions. The Container ensures that the instance has exclusive access to the state of the object in the persistent storage. Therefore, the Container does not have to synchronize the instance’s state from the persistent storage at the beginning of the next transaction.

•Option B: The Container caches a “ready” instance between transactions. In contrast to Option A, in this option the Container does not ensure that the instance has exclusive access to the state of the object in the persistent storage. Therefore, the Container must synchronize the instance’s state from the persistent storage at the beginning of the next transaction.

•Option C: The Container does not cache a “ready” instance between transactions. The Container returns the instance to the pool of available instances after a transaction has completed.

The following table provides a summary of the commit-time options.

Note that the container synchronizes the instance’s state with the persistent storage at transaction commit for all three options.

The selection of the commit option is transparent to the entity bean implementation—the entity bean will work correctly regardless of the commit-time option chosen by the Container. The Bean Provider writes the entity bean in the same way.

The object interaction diagrams in subsection 11.4.4 illustrate the three alternative commit options in detail.

11.1.11 Concurrent access from multiple transactions

When writing the entity bean business methods, the Bean Provider does not have to worry about concurrent access from multiple transactions. The Bean Provider may assume that the container will ensure appropriate synchronization for entity objects that are accessed concurrently from multiple transactions.

The container typically uses one of the following implementation strategies to achieve proper synchronization. (These strategies are illustrative, not prescriptive.)

•The container activates multiple instances of the entity bean, one for each transaction in which the entity object is being accessed. The transaction synchronization is performed automatically by the underlying database during the database access calls performed by the business meth-

Sun Microsystems Inc

ods; and by the ejbLoad, ejbCreate<METHOD>, ejbStore, and ejbRemove methods. The database system provides all the necessary transaction synchronization; the container does not have to perform any synchronization logic. The commit-time options B and C in Subsection 11.4.4 apply to this type of container.

Figure 40 Multiple clients can access the same entity object using multiple instances

With this strategy, the type of lock acquired by ejbLoad leads to a trade-off. If ejbLoad acquires an exclusive lock on the instance's state in the database, then throughput of read-only transactions could be impacted. If ejbLoad acquires a shared lock and the instance is updated, then ejbStore will need to promote the lock to an exclusive lock. This may cause a deadlock if it happens concurrently under multiple transactions.

•The container acquires exclusive access to the entity object’s state in the database. The container activates a single instance and serializes the access from multiple transactions to this instance. The commit-time option A in Subsection 11.4.4 applies to this type of container.

Sun Microsystems Inc.

Entity Bean Component Contract for Bean Managed PersistenceEnterprise JavaBeans 2.0, Public Draft Overview of Bean Managed

Figure 41 Multiple clients can access the same entity object using single instance

11.1.12 Non-reentrant and re-entrant instances

An entity Bean Provider entity can specify that an entity bean is non-reentrant. If an instance of a non-reentrant entity bean executes a client request in a given transaction context, and another request with the same transaction context arrives for the same entity object, the container will throw the java.rmi.RemoteException to the second request. This rule allows the Bean Provider to program the entity bean as single-threaded, non-reentrant code.

The functionality of some entity beans may require loopbacks in the same transaction context. An example of a loopback is when the client calls entity object A, A calls entity object B, and B calls back A in the same transaction context. The entity bean’s method invoked by the loopback shares the current execution context (which includes the transaction and security contexts) with the Bean’s method invoked by the client.

If the entity bean is specified as non-reentrant in the deployment descriptor, the Container must reject an attempt to re-enter the instance via the entity bean’s remote interface while the instance is executing a business method. (This can happen, for example, if the instance has invoked another enterprise bean, and the other enterprise bean tries to make a loopback call.) The container must reject the loopback call and throw the java.rmi.RemoteException to the caller. The container must allow the call if the Bean’s deployment descriptor specifies that the entity bean is re-entrant.

Re-entrant entity beans must be programmed and used with great caution. First, the Bean Provider must code the entity bean with the anticipation of a loopback call. Second, since the container cannot, in general, tell a loopback from a concurrent call from a different client, the client programmer must be careful to avoid code that could lead to a concurrent call in the same transaction context.