Sun Microsystems Inc.

Additional restrictions:

•The getRollbackOnly and setRollbackOnly methods of the EntityContext interface should be used only in the enterprise bean methods that execute in the context of a transaction. The Container must throw the java.lang.IllegalStateException if the methods are invoked while the instance is not associated with a transaction.

Reasons for disallowing operations:

•Invoking the getEJBObject and getPrimaryKey methods is disallowed in the entity bean methods in which there is no entity object identity associated with the instance.

•Invoking the getCallerPrincipal and isCallerInRole methods is disallowed in the entity bean methods for which the Container does not have a client security context.

•Invoking the getRollbackOnly and setRollbackOnly methods is disallowed in the entity bean methods for which the Container does not have a meaningful transaction context. These are the methods that have the NotSupported, Never, or Supports transaction attribute.

•Accessing resource managers and enterprise beans is disallowed in the entity bean methods for which the Container does not have a meaningful transaction context or client security context.

9.1.7 Caching of entity state and the ejbLoad and ejbStore methods

An instance of an entity bean with bean-managed persistence can cache the entity object’s state between business method invocations. An instance may choose to cache the entire entity object’s state, part of the state, or no state at all.

The container-invoked ejbLoad and ejbStore methods assist the instance with the management of the cached entity object’s state. The instance must handle the ejbLoad and ejbStore methods as follows:

•When the container invokes the ejbStore method on the instance, the instance must push all cached updates of the entity object’s state to the underlying database. The container invokes the ejbStore method at the end of a transaction, and may also invoke it at other times when the instance is in the ready state. (For example the container may invoke ejbStore when passivating an instance in the middle of a transaction, or when transferring the instance’s state to another instance to support distributed transactions in a multi-process server.)

•When the container invokes the ejbLoad method on the instance, the instance must discard any cached entity object’s state. The instance may, but is not required to, refresh the cached state by reloading it from the underlying database.

The following examples, which are illustrative but not prescriptive, show how an instance may cache the entity object’s state:

•An instance loads the entire entity object’s state in the ejbLoad method and caches it until the container invokes the ejbStore method. The business methods read and write the cached

Sun Microsystem Inc

entity state. The ejbStore method writes the updated parts of the entity object’s state to the database.

•An instance loads the most frequently used part of the entity object’s state in the ejbLoad method and caches it until the container invokes the ejbStore method. Additional parts of the entity object’s state are loaded as needed by the business methods. The ejbStore method writes the updated parts of the entity object’s state to the database.

•An instance does not cache any entity object’s state between business methods. The business methods access and modify the entity object’s state directly in the database. The ejbLoad and ejbStore methods have an empty implementation.

We expect that most entity developers will not manually code the cache management and data access calls in the entity bean class. We expect that they will rely on application development tools to provide various data access components that encapsulate data access and provide state caching.

9.1.7.1 ejbLoad and ejbStore with the NotSupported transaction attribute

The use of the ejbLoad and ejbStore methods for caching an entity object’s state in the instance works well only if the Container can use transaction boundaries to drive the ejbLoad and ejbStore methods. When the NotSupported[7] transaction attribute is assigned to a remote interface method, the corresponding enterprise bean class method executes with an unspecified transaction context (See Subsection 11.6.3). This means that the Container does not have any well-defined transaction boundaries to drive the ejbLoad and ejbStore methods on the instance.

Therefore, the ejbLoad and ejbStore methods are “unreliable” for the instances that the Container uses to dispatch the methods with an unspecified transaction context. The following are the only guarantees that the Container provides for the instances that execute the methods with an unspecified transaction context:

•The Container invokes at least one ejbLoad between ejbActivate and the first business method in the instance.

•The Container invokes at least one ejbStore between the last business method on the instance and the ejbPassivate method.

Because the entity object’s state accessed between the ejbLoad and ejbStore method pair is not protected by a transaction boundary for the methods that execute with an unspecified transaction context, the Bean Provider should not attempt to use the ejbLoad and ejbStore methods to control caching of the entity object’s state in the instance. Typically, the implementation of the ejbLoad and ejbStore methods should be a no-op (i.e. an empty method), and each business method should access the entity object’s state directly in the database.

[7]This applies also to the Never and Supports attribute.