Sun Microsystems Inc.

9.10 Primary Keys

9.10.1 primary key type

The container must be able to manipulate the primary key type. Therefore, the primary key type for an entity bean with container-managed persistence must follow the rules in this subsection, in addition to those specified in Subsection 9.7.12.

There are two ways to specify a primary key class for an entity bean with container-managed persistence:

•Primary key that maps to a single field in the entity bean class.

•Primary key that maps to multiple fields in the entity bean class.

The second method is necessary for implementing compound keys, and the first method is convenient for single-field keys. Without the first method, simple types such as String would have to be wrapped in a user-defined class.

9.10.1.1 Primary key that maps to a single field in the entity bean class

The Bean Provider uses the primkey-field element of the deployment descriptor to specify the container-managed field of the entity bean class that contains the primary key. The field’s type must be the primary key type.

9.10.1.2 Primary key that maps to multiple fields in the entity bean class

The primary key class must be public, and must have a public constructor with no parameters.

All fields in the primary key class must be declared as public.

The names of the fields in the primary key class must be a subset of the names of the container-managed fields. (This allows the container to extract the primary key fields from an instance’s container-managed fields, and vice versa.)

9.10.1.3 Special case: Unknown primary key class

In special situations, the entity Bean Provider may choose not to specify the primary key class for an entity bean with container-managed persistence. This case usually happens when the entity bean does not have a natural primary key, and/or the Bean Provider wants to allow the Deployer using the Persistence Manager Provider’s tools to select the primary key fields at deployment time. The entity bean’s primary key type will usually be derived from the primary key type used by the underlying database system that stores the entity objects. The primary key used by the database system may not be known to the Bean Provider.

Sun Microsystems Inc

Connection and Transaction Management Contracts between the Persistence Manager and the ContainerEnterprise JavaBeans 2.0,

When defining the primary key for the enterprise bean, the Deployer using the Persistence Manager Provider’s tools may sometimes need to subclass the entity bean class to add additional container-man- aged fields (this typically happens for entity beans that do not have a natural primary key, and the primary keys are system-generated by the underlying database system that stores the entity objects).

In this special case, the type of the argument of the findByPrimaryKey method must be declared as java.lang.Object, and the return value of ejbCreate<METHOD>() must be declared as java.lang.Object. The Bean Provider must specify the primary key class in the deployment descriptor as of the type java.lang.Object.

The primary key class is specified at deployment time in the situations when the Bean Provider develops an entity bean that is intended to be used with multiple back-ends that provide persistence, and when these multiple back-ends require different primary key structures.

Use of entity beans with a deferred primary key type specification limits the client application programming model, because the clients written prior to deployment of the entity bean may not use, in general, the methods that rely on the knowledge of the primary key type.

The implementation of the enterprise bean class methods must be done carefully. For example, the methods should not depend on the type of the object returned from EntityContext.getPrimaryKey(), because the return type is determined by the Deployer after the EJB class has been written.

9.11Connection and Transaction Management Contracts between the Persistence Manager and the Container

This section specifies connection and transaction management contracts between the Persistence Manager and the Container.

9.11.1 Transaction context

In order to manage the access to the persistent state that it has cached on behalf of a bean instance, the persistence manager needs to keep track of when the transaction context for the bean instance has changed. There are various strategies that the Persistence Manager can use to detect when the transaction context for a bean instance has changed. The following are illustrative:

•The Persistence Manager can check which transaction context is in effect on each get or set accessor method access to the state of the bean instance.

•Because the transaction context of a bean instance can be changed by the container only on remote method call boundaries, the persistence manager can wrapper the remote methods of the entity bean to identify when a new remote method has been called, and hence detect when the transaction context may have changed.

•The Persistence Manager can use the ejbLoad, ejbStore, ejbCreate, and ejbFind method invocations to keep track of changes in transaction context. If Commit Option B or C is used, the Persistence Manager needs to check the transaction context in the ejbLoad, ejb-

Sun Microsystems Inc.

Entity Bean Component Contract for Container Managed PersistenceEnterprise JavaBeans 2.0, Public Draft Connection and Transac-

Create, and ejbFind methods only. If Commit Option A is used, however, the transaction context may have changed even though ejbLoad was not invoked. In this case, it is possible to use the ejbStore method to note that the immediately following accessor method invocation on the bean instance might occur in a different transaction context. The transaction context of the next accessor method invocation must be checked accordingly.

The Persistence Manager can use the javax.transaction.TransactionManager.getTransaction() method to identify the transaction context in effect for a given method invocation. The getTransaction() method returns the transaction object that represents the transaction context of the calling thread.

The Container provides an implementation of the TransactionManager interface to the Persistence Manager through JNDI. The Persistence Manager can locate the TransactionManager through the standard JNDI API as java:pm/TransactionManager.

9.11.2 Connection management

When there is a change in transaction context, the Persistence Manager may need to obtain a new connection from the container for use in accessing the persistent state of the bean.

The Persistence Manager may want to ask the Container for a connection that is enlisted in the current transaction or for a connection that is not enlisted.

The Container should typically provide to the Persistence Manager the ability to specify separate resource manager connection factories for these two types of connections, and make those resource manager connection factories available to the persistence manager through JNDI. As part of the persistence manager configuration process, the Persistence Manager Provider’s tools will typically provide mechanisms that allow these resource manager connection factory dependencies to be declaratively expressed.

Note: This specification does not prescribe how the Persistence Manager obtains the resource manager connection factories, but recommends that the java:pm/env subcontext be used for this purpose. We expect to standardize this use in a later release of this specification.

Only Persistence Managers that use an optimistic concurrency control strategy will typically need to obtain connections that have not been enlisted in the current transaction context.

•The Persistence Manager calls the getConnection method (e.g., in the case of JDBC, javax.sql.DataSource.getConnection()) on the resource manager connection factory that provides container management of the transactional enlistment of connections to obtain a connection that has been enlisted by the container in the transaction context of the calling thread. It is the container (not the persistence manager) that is responsible for the transaction management of the connection that is associated with the distributed transaction. If the container is using the local transaction optimization, the connection that is returned by the container as a result of the getConnection method invocation may be a local connection. The persistence manager operates on this connection exactly the same as it would on a connection associated with a distributed transaction, and is not aware of the use of the local transaction optimization.