Sun Microsystems Inc.

•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.

•Accessing resource managers and enterprise beans, including accessing the persistent state of an entity bean instance, is disallowed in the entity bean methods for which the Container does not have a meaningful transaction context or client security context.

9.6.6 Finder method return type

9.6.6.1 Single-object finder

Some finder methods (such as findByPrimaryKey) are designed to return at most one entity object. For these single-object finders, the result type of the find<METHOD>(...)method defined in the entity bean’s home interface is the entity bean’s remote interface. The result type of the corresponding ejbFind<METHOD>(...) method defined in the entity’s implementation class is the entity bean’s primary key type.

Sun Microsystems Inc

Instance life cycle contract between the bean, the container, and the persistence managerEnterprise JavaBeans 2.0, Public Draft Entity

The following code illustrates the definition of a single-object finder.

// Entity’s home interface

public AccountHome extends javax.ejb.EJBHome {

...

Account findByPrimaryKey(AccountPrimaryKey primkey) throws FinderException, RemoteException;

...

}

In general, when defining a single-object finder method, the entity Bean Provider should be sure that the finder method will always return only a single entity object. This may occur, for example, if the EJB QL query string that is used to specify the finder query to the Persistence Manager includes an equality test on the entity bean’s primary key fields.

If the entity Bean Provider wishes to provide more flexibility to the Persistence Manager by using an unknown primary key class (see Section 9.10.1.3), the Bean Provider will typically define the finder method as a multi-object finder.

9.6.6.2 Multi-object finders

Some finder methods are designed to return multiple entity objects. For these multi-object finders, the result type of the find<METHOD>(...)method defined in the entity bean’s home interface is a collection of objects implementing the entity bean’s remote interface. The result type of the corresponding ejbFind<METHOD>(...) implementation method defined in the entity bean’s implementation class is a collection of objects of the entity bean’s primary key type.

The Bean Provider uses the Java™ 2 java.util.Collection interface to define a collection type for the result type of a finder method for an entity bean with container managed persistence.

The Persistence Manager must ensure that the objects in the java.util.Collection returned from the ejbFind<METHOD>(...) method are instances of the entity bean’s primary key class.

A client program must use the PortableRemoteObject.narrow(...) method to convert the objects contained in the collections returned by the finder method to the entity bean’s remote interface type.

The following is an example of a multi-object finder method definition:

// Entity’s home interface

public AccountHome extends javax.ejb.EJBHome {

...

java.util.Collection findLargeAccounts(double limit) throws FinderException, RemoteException;

...

}