Jakarta® Enterprise Beans, Optional Features

THIS DOCUMENT IS PROVIDED "AS IS," AND THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of the copyright holders or the Eclipse Foundation may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

A client obtains an entity bean’s home interface through dependency injection, or the client locates an entity bean’s home interface using JNDI. A client’s JNDI name space may be configured to include the home interfaces of enterprise beans deployed in multiple Enterprise Beans containers located on multiple machines on a network. The actual location of an Enterprise Beans container is, in general, transparent to the client.

For example, the local home interface for the Account entity bean can be located using the following code segment:

If dependency injection were used, the home interface could be obtained as follows:

The following diagram illustrates the view that a container provides to the client of the entity beans deployed in the container. Note that a client may be a local client of some entity beans and a remote client of others.

An entity bean’s remote home interface can define zero or more create<METHOD> methods, one for each way to create an entity object. The arguments of the create methods are typically used to initialize the state of the created entity object. The name of each create method starts with the prefix “create”.

The return type of a create<METHOD> method on the remote home interface is the entity bean’s remote interface.

The throws clause of every create<METHOD> method on the remote home interface includes the java.rmi.RemoteException and the jakarta.ejb.CreateException. It may include additional application-level exceptions.

The following home interface illustrates three possible create methods:

The following example illustrates how a client creates a new entity object:

An entity bean’s remote home interface defines one or more finder methods ^[2] , one for each way to find an entity object or collection of entity objects within the home. The name of each finder method starts with the prefix “find”, such as findLargeAccounts. The arguments of a finder method are used by the entity bean implementation to locate the requested entity objects. The return type of a finder method on the remote home interface must be the entity bean’s remote interface, or a type representing a collection of objects that implement the entity bean’s remote interface (see Finder Methods and Finder Method Return Type).

The throws clause of every finder method on the remote home interface includes the java.rmi.RemoteException and the jakarta.ejb.FinderException exceptions.

The remote home interface includes the findByPrimaryKey(primaryKey) method, which allows a client to locate an entity object using a primary key. The name of the method is always findByPrimaryKey; it has a single argument that is the same type as the entity bean’s primary key type, and its return type is the entity bean’s remote interface. There is a unique findByPrimaryKey(primaryKey) method for an entity bean on its remote home interface; this method must not be overloaded. The implementation of the findByPrimaryKey(primaryKey) method must ensure that the entity object exists.

The following example shows the findByPrimaryKey method:

The following example illustrates how a client uses the findByPrimaryKey method:

The jakarta.ejb.EJBHome interface defines several methods that allow the client to remove an entity object.

After an entity object has been removed, subsequent attempts to access the entity object by a remote client result in the java.rmi.NoSuchObjectException.

An entity bean’s remote home interface may define one or more home methods. Home methods are methods that the Bean Provider supplies for business logic that is not specific to an entity bean instance.

Home methods on the remote home interface can have arbitrary method names, but they must not start with “create”, “find”, or “remove”. The arguments of a home method are used by the entity bean implementation in computations that do not depend on a specific entity bean instance. The method arguments and return value types of a home method on the remote home interface must be legal types for RMI-IIOP.

The throws clause of every home method on the remote home interface includes the java.rmi.RemoteException. It may also include additional application-level exceptions.

The following example shows two home methods:

An entity bean’s local home interface can define zero or more create<METHOD> methods, one for each way to create an entity object. The arguments of the create methods are typically used to initialize the state of the created entity object. The name of each create method starts with the prefix “create”.

The return type of a create<METHOD> method on the local home interface is the entity bean’s local interface.

The throws clause of every create<METHOD> method on the local home interface includes the jakarta.ejb.CreateException. It may include additional application-level exceptions. It must not include the java.rmi.RemoteException.

The following local home interface illustrates three possible create methods:

The following example illustrates how a client creates a new entity object:

An entity bean’s local home interface defines one or more finder methods ^[3] , one for each way to find an entity object or collection of entity objects within the home. The name of each finder method starts with the prefix “find”, such as findLargeAccounts. The arguments of a finder method are used by the entity bean implementation to locate the requested entity objects. The return type of a finder method on the local home interface must be the entity bean’s local interface, or a type representing a collection of objects that implement the entity bean’s local interface (see Finder Methods and Finder Method Return Type).

The throws clause of every finder method on the local home interface includes the jakarta.ejb.FinderException. The throws clause must not include the java.rmi.RemoteException.

The local home interface includes the findByPrimaryKey(primaryKey) method, which allows a client to locate an entity object using a primary key. The name of the method is always findByPrimaryKey; it has a single argument that is the same type as the entity bean’s primary key type, and its return type is the entity bean’s local interface. There is a unique findByPrimaryKey(primaryKey) method for an entity bean on its local home interface; this method must not be overloaded. The implementation of the findByPrimaryKey method must ensure that the entity object exists.

The following example shows the findByPrimaryKey method:

The following example illustrates how a client uses the findByPrimaryKey method:

The jakarta.ejb.EJBLocalHome interface defines the remove method to allow the client to remove an entity object.

After an entity object has been removed, subsequent attempts to access the local entity object by the local client result in the jakarta.ejb.NoSuchObjectLocalException.

An entity bean’s local home interface may define one or more home methods. Home methods are methods that the Bean Provider supplies for business logic that is not specific to an entity bean instance.

Home methods can have arbitrary method names, but they must not start with “create”, “find” or “remove”. The arguments of a home method are used by the entity bean implementation in computations that do not depend on a specific entity bean instance.

The throws clause of a home method on the local home interface may include additional application-level exceptions. It must not include the java.rmi.RemoteException.

The following example shows two home methods:

A client can get a reference to an existing entity object’s remote interface in any of the following ways:

A client that has a reference to an entity object’s remote interface can do any of the following:

All references to an entity object that does not exist are invalid. All attempted invocations on an entity object that does not exist result in an java.rmi.NoSuchObjectException being thrown.

A local client can get a reference to an existing entity object’s local interface in any of the following ways:

A local client that has a reference to an entity object’s local interface can do any of the following:

All local references to an entity object that does not exist are invalid. All attempted invocations on an entity object that does not exist result in a jakarta.ejb.NoSuchObjectLocalException being thrown.

A local interface type must not be passed as an argument or result of a remote interface method.

If an entity bean is referenced from a stateful session bean, the Bean Provider is required to ensure that the PrePassivate method leaves the instance fields ready to be serialized by the container. In addition to the rules described in Enterprise Beans Core Contracts and Requirements document [2] Subsection "Instance Passivation and Conversational State", for the entity bean references, the objects that are assigned to the instance’s non-transient fields after the session bean PrePassivate method completes can also be one of the following:

The Bean Provider must observe the following programming contract when defining an entity bean class that uses container-managed persistence:

An entity bean may have relationships with other entity beans with container-managed persistence.

Relationships may be one-to-one, one-to-many, or many-to-many relationships.

Container-managed relationships can exist only among entity beans within the same local relationship scope, as defined by the relationships element in the deployment descriptor. Container-managed relationships are defined in terms of the local interfaces of the related beans.

Relationships may be either bidirectional or unidirectional. If a relationship is bidirectional, it can be navigated in both directions, whereas a unidirectional relationship can be navigated in one direction only.

A unidirectional relationship is implemented with a cmr-field on the entity bean instance from which navigation can take place, and no related cmr-field on the entity bean instance that is the target of the relationship. Unidirectional relationships are typically used when the Bean Provider wishes to restrict the visibility of a relationship.

An entity bean that does not have a local interface can have only unidirectional relationships from itself to other entity beans. The lack of a local interface prevents other entity beans from having a relationship to it.

The bean developer navigates or manipulates relationships by using the get and set accessor methods for the container-managed relationship fields and the java.util.Collection API for collection-valued container-managed relationship fields.

The Bean Provider must consider the type and cardinality of relationships when the entity bean classes are programmed. The get method for a cmr-field must return either the local interface of the entity bean or a collection (either java.util.Collection or java.util.Set) of the same. The set method for the relationship must take as an argument the entity bean’s local interface or a collection of the same.

A dependent value class is a concrete class that is the value of a cmp-field. A dependent value class may be a class that the Bean Provider wishes to use internally within an entity bean with container-managed persistence, and/or it may be a class that the Bean Provider chooses to expose through the remote (or local) interface of the entity bean.

A dependent value class can be the value of a cmp-field; it cannot be the value of a cmr-field.

The get accessor method for a cmp-field that corresponds to a dependent value class returns a copy of the dependent value class instance. The assignment of a dependent value class value to a cmp-field using the set accessor method causes the value to be copied to the target cmp-field.

A dependent value class must be serializable. The internal structure of a dependent value class is not described in the Enterprise Beans deployment descriptor.

The Bean Provider can specify the removal of an entity object in two ways:

From the viewpoint of the Bean Provider, entity objects have a runtime object identity that is maintained by the container.

The container maintains the persistent identity of an entity object on the basis of its primary key.

The primary key of an entity bean may or may not be visible as one or more cmp-fields of the instance, depending on the way in which it is specified. The Bean Provider specifies the primary key as described in Primary Keys. Once it has been set, the Bean Provider must not attempt to change the value of a primary key field by means of a set method on its cmp-fields.

When a new instance of an entity bean whose primary key fields are visible in the entity bean class is created, the Bean Provider must use the ejbCreate<METHOD> method to set all the primary key fields of the entity bean instance before the instance can participate in a relationship, e.g. be used in a set accessor method for a cmr-field. The Bean Provider must not reset a primary key value by means of a set method on any of its cmp-fields after it has been set in the ejbCreate<METHOD> method. If the Bean Provider attempts to reset a primary key value, the container must throw the java.lang.IllegalStateException.

The assignment operations for container-managed relationships have a special semantics that is determined by the referential integrity semantics for the relationship multiplicity.

In the case of a one-to-one relationship, when the Bean Provider uses a set accessor method to assign an object from a cmr-field in one instance to a cmr-field of the same relationship type (i.e., as defined by the ejb-relation and ejb-relationship-role deployment descriptor elements) in another instance, the object is effectively moved and the value of the source cmr-field is set to null in the same transaction context. If the argument to the set accessor method is not of the same type as the cmr-field, the container must throw the java.lang.IllegalArgumentException.

In the case of a one-to-many or many-to-many relationship, either the java.util.Collection API or a set accessor method may be used to manipulate the contents of a collection-valued cmr-field. These two approaches are discussed below.

This section defines the semantics of assignment and collection manipulation in one-to-one, one-to-many, and many-to-many container-managed relationships.

The figures make use of two entity beans, with local interface types A and B. Instances with local interface type A are typically designated as a1,…​,an; instances with local interface type B are typically designated as b1,…​,bm. Interface A exposes accessor methods getB and setB for navigable relationships with B: getB returns an instance of B or a collection of instances of B, depending on the multiplicity of the relationship. Similarly, B exposes accessor methods getA and setA for navigable relationships with A.

All changes in each subsection are assumed to be applied to the figure labeled “Before change” at the beginning of the subsection (i.e., changes are not cumulative). The results of changes are designated graphically as well as in conditional expressions expressed in the Java™ programming language.

The collections that are used in the representation of one-to-many and many-to-many container-managed relationships are implemented and managed by the container. The following semantics apply to these collections:

The Bean Provider may use instance variables in the entity bean instance to maintain non-persistent state, e.g. a Jakarta Messaging connection.

The Bean Provider can use instance variables to store values that depend on the persistent state of the entity bean instance, although this use is not encouraged. The Bean Provider should use the ejbLoad method to resynchronize the values of any instance variables that depend on the entity bean’s persistent state. In general, any non-persistent state that depends on the persistent state of an entity bean should be recomputed during the ejbLoad method.

The Bean Provider should exercise care in passing the contents of instance variables as the arguments or results of method invocations when local interfaces are used. In general, the Bean Provider should avoid passing state that is maintained in instance variables as the argument or result of a local method invocation.

In designing the entity bean, the Bean Provider should keep in mind the following:

This specification does not prescribe how the abstract persistence schema of an entity bean should be mapped to a relational (or other) schema of a persistent store, or define how such a mapping is described.

Relationship Example illustrates an Order entity bean with relationships to line items and customers, which are other entity beans within the same local scope. Product is indirectly related to Order by means of the relationship between LineItem and Product. Sample code for the OrderBean class follows the figure.

The persistent fields (cmp-fields) and relationships (cmr-fields) of an entity bean must be declared in the deployment descriptor.

The deployment descriptor provides the following information about the abstract persistence schemas of entity beans and their container-managed relationships:

The following example shows a deployment descriptor segment that defines the abstract persistence schema for a set of related entity beans. The deployment descriptor elements for container-managed persistence and relationships are described further in Deployment Descriptor.

This subsection describes the runtime model and the classes used in the description of the contract between an entity bean and its container. Overview of the Entity Bean Runtime Execution Model shows an overview of the runtime model. The client of an entity bean may be a local client or it may be a remote client.

An enterprise bean is an object whose class is provided by the Bean Provider. The class of an entity bean with container-managed persistence is abstract. The concrete bean class is generated by the Container Provider’s tools at deployment time. The container is also responsible for providing the implementation of the java.util.Collection classes that are used in maintaining the container-managed relationships of the entity bean.

An entity EJBObject or EJBLocalObject is an object whose class was generated at deployment time by the Container Provider’s tools. A client never references an entity bean instance directly—a client always references an entity EJBObject or EJBLocalObject whose class is generated by the Container Provider’s tools. The entity EJBObject class implements an entity bean’s remote interface. The entity EJBLocalObject class implements an entity bean’s local interface. A related entity bean never references another entity bean instance directly—a related entity bean, like any other local client of an entity bean, always references an entity EJBLocalObject whose class is generated by the Container Provider’s tools.

An entity EJBHome or EJBLocalHome object provides life cycle operations (create, find, remove) for its entity objects as well as home business methods, which are business methods that are not specific to an entity bean instance. The class for the entity EJBHome or EJBLocalHome object is generated by the Container Provider’s tools at deployment time. The entity EJBHome or EJBLocalHome object implements the entity bean’s remote or local home interface that was defined by the Bean Provider.

The following are the container responsibilities for the management of persistent state.

An entity bean instance is in one of the following three states:

The following steps describe the life cycle of an entity bean instance:

Notes:

The following describes the entity bean instance’s view of the contract as seen by the Bean Provider:

The entity Bean Provider is responsible for implementing the following methods in the abstract entity bean class:

This subsection describes the container’s view of the state management contract. The container must call the following methods:

Compliant implementations of this specification may optionally support read-only entity beans. A read-only entity bean is an entity bean whose instances are not intended to be updated and/or created by the application. Read-only beans are best suited for situations where the underlying data never changes or changes infrequently.

Containers that support read-only beans do not call the ejbStore method on them. The ejbLoad method should typically be called by the container when the state of the bean instance is initially loaded from the database, or at designated refresh intervals. ^[9]

If a read-only bean is used, the state of such a bean should not be updated by the application, and the behavior is unspecified if this occurs. ^[10]

Read-only beans are designated by vendor-specific means that are outside the scope of this specification, and their use is therefore not portable.

A container provides the entity bean instances with an EntityContext, which gives the entity bean instance access to the instance’s context maintained by the container. The EntityContext interface has the following methods:

Operations Allowed in the Methods of an Entity Bean defines the methods of an entity bean class in which the enterprise bean instances can access the methods of the jakarta.ejb.EntityContext interface, the java:comp/env environment naming context, resource managers, TimerService and Timer methods, the EntityManager and EntityManagerFactory methods, and other enterprise beans.

If an entity bean instance attempts to invoke a method of the EntityContext interface, and the access is not allowed in Operations Allowed in the Methods of an Entity Bean, the container must throw the java.lang.IllegalStateException.

If a entity bean instance attempts to invoke a method of the TimerService or Timer interface and the access is not allowed in Operations Allowed in the Methods of an Entity Bean, the container must throw the java.lang.IllegalStateException.

If an entity bean instance attempts to access a resource manager, an enterprise bean, an entity manager or entity manager factory, and the access is not allowed in Operations Allowed in the Methods of an Entity Bean, the behavior is undefined by the Enterprise Beans architecture.

Additional restrictions:

Reasons for disallowing operations:

An entity bean’s home interface defines one or more finder methods ^[11] , one for each way to find an entity object or collection of entity objects within the home. The name of each finder method starts with the prefix “find”, such as findLargeAccounts. The arguments of a finder method are used in the implementation of the query for the finder method to locate the requested entity objects.

Every finder method except findByPrimaryKey(key) must be associated with a query element in the deployment descriptor. The entity Bean Provider declaratively specifies the Enterprise Beans QL finder query and associates it with the finder method in the deployment descriptor. A finder method is normally characterized by an Enterprise Beans QL query string specified in the query element. Enterprise Beans QL is described in Enterprise Beans QL: EJB 2.1 Query Language for Container-Managed Persistence Query Methods. A compliant implementation of this specification is required to support Enterprise Beans QL as defined in Enterprise Beans QL: EJB 2.1 Query Language for Container-Managed Persistence Query Methods for use with finder methods.

In the case that both the remote home interface and local home interface define a finder method with the same name and argument types, the Enterprise Beans QL query string specified by the query element defines the semantics of both methods.

Select methods are query methods for use by the Bean Provider within an entity bean instance. Unlike finder methods, select methods are not specified in the entity bean’s home interface. A select method is an abstract method defined by the Bean Provider on an entity bean class. A select method must not be exposed in the home or component interface of an entity bean.

The semantics of a select method, like those of a finder method, are defined by an Enterprise Beans QL query string. A select method is similar to a finder method, but unlike a finder method, but it can return values that correspond to any cmp- or cmr-field type.

Every select method must be associated with a query element in the deployment descriptor. The entity Bean Provider declaratively specifies the Enterprise Beans QL query and associates it with the select method in the deployment descriptor. A select method is normally characterized by an Enterprise Beans QL query string specified in the query element. Enterprise Beans QL is described in Enterprise Beans QL: EJB 2.1 Query Language for Container-Managed Persistence Query Methods. A compliant implementation of this specification is required to support Enterprise Beans QL as defined in Enterprise Beans QL: EJB 2.1 Query Language for Container-Managed Persistence Query Methods for use with select methods.

Typically an ejbSelect<METHOD> method that returns entity objects returns these as EJBLocalObjects. If the ejbSelect<METHOD> method returns an EJBObject or collection of EJBObjects, the Bean Provider must specify the value of the result-type-mapping element in the query deployment descriptor element for the select method as Remote.

An ejbSelect<METHOD> is not based on the identity of the entity bean instance on which it is invoked. However, the Bean Provider can use the primary key of an entity bean as an argument to an ejbSelect<METHOD> to define a query that is logically scoped to a particular entity bean instance.

The following table illustrates the semantics of finder and select methods.

An entity bean can be registered with the Enterprise Beans timer service for time-based event notifications if it implements the jakarta.ejb.TimedObject interface. The container invokes the bean instance’s ejbTimeout method when a timer for the bean has expired. See Timer Service.

The Enterprise Beans specification defines the following standard application exceptions:

This section describes the use of these exceptions by entity beans with container-managed persistence.

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 association of an entity object identity with the enterprise bean instances.

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

Variants of these strategies that capture the same semantics from the Bean Provider’s viewpoint may be employed, e.g., to optimize data access.

The following illustrative lazy loading strategies are consistent with the intent of these requirements:

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.

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

With this strategy, the type of lock acquired by ejbLoad or get accessor method (if a lazy loading cache management strategy is used) leads to a trade-off. If ejbLoad or the accessor method acquires an exclusive lock on the instance’s state in the database, the throughput of read-only transactions could be impacted. If ejbLoad or the accessor method acquires a shared lock and the instance is updated, then either ejbStore or a set accessor method will need to promote the lock to an exclusive lock (which may cause a deadlock if it happens concurrently under multiple transactions), or, if the container uses an optimistic cache concurrency control strategy, the container will need to validate the state of the cache against the database at transaction commit (which may result in a rollback of the transaction).

It is expected that containers will provide deployment-time configuration options that will allow control to be exercised over the logical transaction isolation levels that their caching strategies provide.

An entity Bean Provider 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 an exception to the second request. This rule allows the Bean Provider to program the entity bean as single-threaded, non-reentrant code.

The functionality of entity beans with container-managed persistence 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 component 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.) If the attempt is made to reenter the instance through the remote interface, the container must throw the java.rmi.RemoteException to the caller. If the attempt is made to reenter the instance through the local interface, the container must throw the jakarta.ejb.EJBException 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 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.

Concurrent calls in the same transaction context targeted at the same entity object are illegal and may lead to unpredictable results. Since the container cannot, in general, distinguish between an illegal concurrent call and a legal loopback, application programmers are encouraged to avoid using loopbacks. Entity beans that do not need callbacks should be marked as non-reentrant in the deployment descriptor, allowing the container to detect and prevent illegal concurrent calls from clients.

The entity Bean Provider is responsible for providing the following class files:

The Bean Provider must provide a remote interface and a remote home interface or a local interface and a local home interface for the bean. The Bean Provider may provide a remote interface, remote home interface, local interface, and local home interface for the bean. Other combinations are not allowed.

The following are the requirements for an entity bean class:

The class must implement, directly or indirectly, the jakarta.ejb.EntityBean interface.

The class may implement, directly or indirectly, the jakarta.ejb.TimedObject interface.

The class must be defined as public and must be abstract. The class must be a top level class.

The class must define a public constructor that takes no arguments.

The class must not define the finalize() method.

The class may, but is not required to, implement the entity bean’s component interface. ^[13] If the class implements the entity bean’s component interface, the class must provide no-op implementations of the methods defined by that interface. The container will never invoke these methods on the bean instances at runtime.

The entity bean class must implement the business methods, and the ejbCreate<METHOD> and ejbPostCreate<METHOD> methods as described later in this section.

The entity bean class must implement the ejbHome<METHOD> methods that correspond to the home business methods specified in the bean’s home interface. These methods are executed on an instance in the pooled state; hence they must not access state that is particular to a specific bean instance (e.g., the accessor methods for the bean’s abstract persistence schema must not be used by these methods).

The entity bean class must implement the get and set accessor methods of the bean’s abstract persistence schema as abstract methods.

The entity bean class may have superclasses and/or superinterfaces. If the entity bean has superclasses, the business methods, the ejbCreate<METHOD> and ejbPostCreate<METHOD> methods, and the methods of the EntityBean interface and/or the TimedObject interface may be implemented in the enterprise bean class or in any of its superclasses.

The entity bean class is allowed to implement other methods (for example helper methods invoked internally by the business methods) in addition to the methods required by the Enterprise Beans specification.

The entity bean class does not implement the finder methods. The implementations of the finder methods are provided by the container.

The entity bean class must implement any ejbSelect<METHOD> methods as abstract methods.

The following are the requirements for a dependent value class:

The class must be defined as public and must not be abstract.

The class must be serializable.

The entity bean class must implement the ejbCreate<METHOD> methods that correspond to the create<METHOD> methods specified in the entity bean’s home interface or local home interface.

The entity bean class may define zero or more ejbCreate<METHOD> methods whose signatures must follow these rules:

The method name must have ejbCreate as its prefix.

The method must be declared as public.

The method must not be declared as final or static.

The return type must be the entity bean’s primary key type.

If the ejbCreate<METHOD> method corresponds to a create<METHOD> on the entity bean’s remote home interface, the method arguments and return value types must be legal types for RMI-IIOP.

The throws clause must define the jakarta.ejb.CreateException. The throws clause may define arbitrary application specific exceptions.

Compatibility Note: Enterprise Beans 1.0 allowed the ejbCreate method to throw the java.rmi.RemoteException to indicate a non-application exception. This practice was deprecated in Enterprise Beans 1.1—an Enterprise Beans 1.1 or Enterprise Beans 2.0 or later compliant enterprise bean should throw the jakarta.ejb.EJBException or another java.lang.RuntimeException to indicate non-application exceptions to the container (see System Exceptions). The ejbCreate method of an entity bean with cmp-version 2.x must not throw the java.rmi.RemoteException.

For each ejbCreate<METHOD> method, the entity bean class must define a matching ejbPostCreate<METHOD> method, using the following rules:

The method name must have ejbPostCreate as its prefix.

The method must be declared as public.

The method must not be declared as final or static.

The return type must be void.

The method arguments must be the same as the arguments of the matching ejbCreate<METHOD> method.

The throws clause may define arbitrary application specific exceptions, including the jakarta.ejb.CreateException.

Compatibility Note: Enterprise Beans 1.0 allowed the ejbPostCreate method to throw the java.rmi.RemoteException to indicate a non-application exception. This practice was deprecated in Enterprise Beans 1.1—an Enterprise Beans 1.1 or Enterprise Beans 2.0 or later compliant enterprise bean should throw the jakarta.ejb.EJBException or another java.lang.RuntimeException to indicate non-application exceptions to the container (see System Exceptions). The ejbPostCreate method of an entity bean with cmp-version 2.x must not throw the java.rmi.RemoteException.

The entity bean class may define zero or more home methods whose signatures must follow the following rules:

An ejbHome<METHOD> method must exist for every home <METHOD> method on the entity bean’s remote home or local home interface. The method name must have ejbHome as its prefix followed by the name of the <METHOD> method in which the first character has been uppercased.

The method must be declared as public.

The method must not be declared as static.

If the ejbHome<METHOD> method corresponds to a home <METHOD> on the entity bean’s remote home interface, the method argument and return value types must be legal types for RMI-IIOP.

The throws clause may define arbitrary application specific exceptions. The throws clause must not throw the java.rmi.RemoteException.

The entity bean class may define one or more select methods whose signatures must follow the following rules:

The method name must have ejbSelect as its prefix.

The method must be declared as public.

The method must be declared as abstract.

The throws clause must define the jakarta.ejb.FinderException. The throws clause may define arbitrary application specific exceptions.

The entity bean class may define zero or more business methods whose signatures must follow these rules:

The method names can be arbitrary, but they must not start with ‘ejb’ to avoid conflicts with the callback methods used by the Enterprise Beans architecture.

The business method must be declared as public.

The method must not be declared as final or static.

If the business method corresponds to a method of the entity bean’s remote interface, the method argument and return value types must be legal types for RMI-IIOP.

The throws clause may define arbitrary application specific exceptions.

Compatibility Note: Enterprise Beans 1.0 allowed the business methods to throw the java.rmi.RemoteException to indicate a non-application exception. This practice was deprecated in Enterprise Beans 1.1—an Enterprise Beans 1.1 or Enterprise Beans 2.0 or later compliant enterprise bean should throw the jakarta.ejb.EJBException or another java.lang.RuntimeException to indicate non-application exceptions to the container (see System Exceptions). The business methods of an entity bean with cmp-version 2.x must not throw the java.rmi.RemoteException.

The following are the requirements for the entity bean’s remote interface:

The interface must extend the jakarta.ejb.EJBObject interface.

The methods defined in the remote interface must follow the rules for RMI-IIOP. This means that their argument and return value types must be valid types for RMI-IIOP, and their throws clauses must include the java.rmi.RemoteException.

The remote interface is allowed to have superinterfaces. Use of interface inheritance is subject to the RMI-IIOP rules for the definition of remote interfaces.

For each method defined in the remote interface, there must be a matching method in the entity bean’s class. The matching method must have:

The remote interface methods must not expose local interface types, local home interface types, timer handles, or the managed collection classes that are used for entity beans with container-managed persistence as arguments or results.

The following are the requirements for the entity bean’s home interface:

The interface must extend the jakarta.ejb.EJBHome interface.

The methods defined in this interface must follow the rules for RMI-IIOP. This means that their argument and return types must be of valid types for RMI-IIOP, and their throws clauses must include the java.rmi.RemoteException.

The remote home interface is allowed to have superinterfaces. Use of interface inheritance is subject to the RMI-IIOP rules for the definition of remote interfaces.

Each method defined in the remote home interface must be one of the following:

Each create method must be named “create<METHOD>”, e.g. createLargeAccounts. Each create method name must match one of the ejbCreate<METHOD> methods defined in the enterprise bean class. The matching ejbCreate<METHOD> method must have the same number and types of its arguments. (Note that the return type is different.)

The return type for a create<METHOD> method must be the entity bean’s remote interface type.

All the exceptions defined in the throws clause of the matching ejbCreate<METHOD> and ejbPostCreate<METHOD> methods of the enterprise bean class must be included in the throws clause of the matching create method of the home interface (i.e., the set of exceptions defined for the create method must be a superset of the union of exceptions defined for the ejbCreate<METHOD> and ejbPostCreate<METHOD> methods).

The throws clause of a create<METHOD> method must include the jakarta.ejb.CreateException.

Each finder method must be named “find<METHOD>” (e.g. findLargeAccounts).

The return type for a find<METHOD> method must be the entity bean’s remote interface type (for a single-object finder), or a collection thereof (for a multi-object finder).

The remote home interface must always include the findByPrimaryKey method, which is always a single-object finder. The method must declare the primary key class as the method argument.

The throws clause of a finder method must include the jakarta.ejb.FinderException.

Home methods can have arbitrary names, but they must not start with “create”, “find”, or “remove”. Their argument and return types must be of valid types for RMI-IIOP, and their throws clauses must include the java.rmi.RemoteException. The matching ejbHome method specified in the entity bean class must have the same number and types of arguments and must return the same type as the home method as specified in the remote home interface of the bean.

The remote home interface methods must not expose local interface types, local home interface types, timers or timer handles, or the managed collection classes that are used for entity beans with container-managed persistence as arguments or results.

The following are the requirements for the entity bean’s local interface:

The interface must extend the jakarta.ejb.EJBLocalObject interface.

For each method defined in the local interface, there must be a matching method in the entity bean’s class. The matching method must have:

The following are the requirements for the entity bean’s local home interface:

The interface must extend the jakarta.ejb.EJBLocalHome interface.

Each method defined in the home interface must be one of the following:

Each create method must be named “create<METHOD>”, e.g. createLargeAccounts. Each create method name must match one of the ejbCreate<METHOD> methods defined in the enterprise bean class. The matching ejbCreate<METHOD> method must have the same number and types of its arguments. (Note that the return type is different.)

The return type for a create<METHOD> method on the local home interface must be the entity bean’s local interface type.

All the exceptions defined in the throws clause of the matching ejbCreate<METHOD> and ejbPostCreate<METHOD> methods of the enterprise bean class must be included in the throws clause of the matching create method of the local home interface (i.e., the set of exceptions defined for the create method must be a superset of the union of exceptions defined for the ejbCreate<METHOD> and ejbPostCreate<METHOD> methods).

The throws clause of a create<METHOD> method must include the jakarta.ejb.CreateException.

Each finder method must be named “find<METHOD>” (e.g. findLargeAccounts).

The return type for a find<METHOD> method defined on the local home interface must be the entity bean’s local interface type (for a single-object finder), or a collection thereof (for a multi-object finder).

The local home interface must always include the findByPrimaryKey method, which is always a single-object finder. The method must declare the primary key class as the method argument.

The throws clause of a finder method must include the jakarta.ejb.FinderException.

Home methods can have arbitrary names, but they must not start with “create”, “find”, or “remove”. The matching ejbHome method specified in the entity bean class must have the same number and types of arguments and must return the same type as the home method as specified in the home interface of the bean. The throws clause of a home method defined on the local home interface must not include the java.rmi.RemoteException.

The Bean Provider must specify a primary key class in the deployment descriptor.

The primary key type must be a legal Value Type in RMI-IIOP.

The class must provide suitable implementation of the hashCode() and equals(Object other) methods to simplify the management of the primary keys by the container.

The Bean Provider must specify the relationships in which the entity beans participate in the relationships element.

The Bean Provider must provide unique names to designate entity beans as follows, and as described in The Bean Provider’s View of the Deployment Descriptor.

The Bean Provider must define a query for each finder or select method except findByPrimaryKey(key). Typically this will be provided as the content of the ejb-ql element contained in the query element for the entity bean. The syntax of Enterprise Beans QL is defined in Enterprise Beans QL: EJB 2.1 Query Language for Container-Managed Persistence Query Methods.

Since Enterprise Beans QL query strings are embedded in the deployment descriptor, which is an XML document, it may be necessary to encode the following characters in the query string: “>”, “<”.

The deployment tools provided by the Container Provider are responsible for the generation of additional classes when the entity bean is deployed. The tools obtain the information that they need for generation of the additional classes by introspecting the classes and interfaces provided by the Bean Provider and by examining the entity bean’s deployment descriptor.

The deployment tools must generate the following classes:

The deployment tools may also generate a class that mixes some container-specific code with the entity bean class. The code may, for example, help the container to manage the entity bean instances at runtime. Tools can use subclassing, delegation, and code generation.

The deployment tools may also allow generation of additional code that wraps the business methods and that is used to customize the business logic for an existing operational environment. For example, a wrapper for a debit function on the Account bean may check that the debited amount does not exceed a certain limit, or perform security checking that is specific to the operational environment.

The following are the requirements for a concrete entity bean class:

The class must extend the abstract entity bean class provided by the Bean Provider.

The class must be defined as public and must not be abstract.

The class must define a public constructor that takes no arguments.

The class must implement the get and set accessor methods of the bean’s abstract persistence schema.

The class must not define the finalize method.

The entity bean class must implement the ejbFind<METHOD> methods.

The entity bean class must implement the ejbSelect<METHOD> methods.

The entity bean class is allowed to implement other methods in addition to the methods required by the Enterprise Beans specification.

For each find<METHOD> method in the remote home interface or local home interface of the entity bean, there must be a corresponding ejbFind<METHOD> method with the same argument types in the concrete entity bean class.

The method name must have ejbFind as its prefix.

The method must be declared as public.

If the ejbFind<METHOD> method corresponds to a find<METHOD> on the entity bean’s remote home interface, the method argument and return value types must be legal types for RMI-IIOP.

The return type of an ejbFind<METHOD> method must be the entity bean’s primary key type, or a collection of primary keys.

The throws clause must define the jakarta.ejb.FinderException. The throws clause may define arbitrary application specific exceptions.

Every finder method except ejbFindByPrimaryKey(key) is specified in the query deployment descriptor element for the entity. The container must use the Enterprise Beans QL query string that is the content of the ejb-ql element or the descriptive query specification contained in the description element as the definition of the query of the corresponding ejbFind<METHOD> method.

For each ejbSelect<METHOD> method in the abstract entity bean class, there must be a method with the same argument and result types in the concrete entity bean class.

Every select method is specified in a query deployment descriptor element for the entity. The container must use the Enterprise Beans QL query string that is the content of the ejb-ql element or the descriptive query specification that is contained in the description element as the definition of the query of the corresponding ejbSelect<METHOD> method.

The container must use the contents of the query element, the corresponding Enterprise Beans QL string and the type of the values selected as specified by the SELECT clause to determine the type of the values returned by a select method.

The container must ensure that there are no duplicates returned by a select method if the return type is java.util.Set.

The entity EJBHome class, which is generated by deployment tools, implements the entity bean’s remote home interface. This class implements the methods of the jakarta.ejb.EJBHome interface, and the type-specific create and finder methods specific to the entity bean.

The implementation of each create<METHOD> method invokes a matching ejbCreate<METHOD> method, followed by the matching ejbPostCreate<METHOD> method, passing the create<METHOD> parameters to these matching methods.

The implementation of the remove methods defined in the jakarta.ejb.EJBHome interface must activate an instance (if an instance is not already in the ready state) and invoke the ejbRemove method on the instance.

The implementation of each find<METHOD> method invokes a matching ejbFind<METHOD> method. The implementation of the find<METHOD> method must create an entity object reference for the primary key returned from the ejbFind<METHOD> and return the entity object reference to the client. If the ejbFind<METHOD> method returns a collection of primary keys, the implementation of the find<METHOD> method must create a collection of entity object references for the primary keys and return the collection to the client.

The implementation of each <METHOD> method invokes a matching ejbHome<METHOD> method (in which the first character of <METHOD> is uppercased in the name of the ejbHome<METHOD> method), passing the parameters of the <METHOD> method to the matching ejbHome<METHOD> method.

The entity EJBObject class, which is generated by deployment tools, implements the entity bean’s remote interface. It implements the methods of the jakarta.ejb.EJBObject interface and the remote business methods specific to the entity bean.

The implementation of the remove method (defined in the jakarta.ejb.EJBObject interface) must activate an instance (if an instance is not already in the ready state) and invoke the ejbRemove method on the instance.

The implementation of each remote business method must activate an instance (if an instance is not already in the ready state) and invoke the matching business method on the instance.

The entity EJBLocalHome class, which is generated by deployment tools, implements the entity bean’s local home interface. This class implements the methods of the jakarta.ejb.EJBLocalHome interface, and the type-specific create and finder methods specific to the entity bean.

The implementation of each create<METHOD> method invokes a matching ejbCreate<METHOD> method, followed by the matching ejbPostCreate<METHOD> method, passing the create<METHOD> parameters to these matching methods.

The implementation of the remove method defined in the jakarta.ejb.EJBLocalHome interface must activate an instance (if an instance is not already in the ready state) and invoke the ejbRemove method on the instance.

The implementation of each find<METHOD> method invokes a matching ejbFind<METHOD> method. The implementation of the find<METHOD> method must create a local entity object reference for the primary key returned from the ejbFind<METHOD> and return the local entity object reference to the local client. If the ejbFind<METHOD> method returns a collection of primary keys, the implementation of the find<METHOD> method must create a collection of local entity object references for the primary keys and return the collection to the local client.

The implementation of each <METHOD> home method invokes a matching ejbHome<METHOD> method (in which the first character of <METHOD> is uppercased in the name of the ejbHome<METHOD> method), passing the parameters of the <METHOD> method to the matching ejbHome<METHOD> method.

The entity EJBLocalObject class, which is generated by deployment tools, implements the entity bean’s local interface. It implements the methods of the jakarta.ejb.EJBLocalObject interface and the local business methods specific to the entity bean.

The implementation of the remove method (defined in the jakarta.ejb.EJBLocalObject interface) must activate an instance (if an instance is not already in the ready state) and invoke the ejbRemove method on the instance.

The implementation of each local business method must activate an instance (if an instance is not already in the ready state) and invoke the matching business method on the instance.

The deployment tools are responsible for implementing the handle class for the entity bean. The handle class must be serializable by the Java Serialization protocol.

As the handle class is not entity bean specific, the container may, but is not required to, use a single class for all deployed entity beans.

The deployment tools responsible for implementing the home handle class for the entity bean. The handle class must be serializable by the Java Serialization protocol.

Because the home handle class is not entity bean specific, the container may, but is not required to, use a single class for the home handles of all deployed entity beans.

The deployment tools are responsible for implementing the class that provides metadata information to the remote client view contract. The class must be a valid RMI-IIOP Value Type, and must implement the jakarta.ejb.EJBMetaData interface.

Because the metadata class is not entity bean specific, the container may, but is not required to, use a single class for all deployed enterprise beans.

The container runtime must enforce the rules defined in Non-reentrant and Re-entrant Instances.

The container runtime must follow the rules on transaction scoping and exception handling described in Support for Transactions and Exception Handling. The container runtime must follow the rules on security checking described in the EJB Core Contracts and Requirements document [2] Chapter “Security Management”.

The container should implement the distribution protocol between the remote client and the container such that the object references of the remote home and remote interfaces used by entity bean clients are usable for a long period of time. Ideally, a remote client should be able to use an object reference across a server crash and restart. An object reference should become invalid only when the entity object has been removed, or after a reconfiguration of the server environment (for example, when the entity bean is moved to a different Enterprise Beans server or container).

The motivation for this is to simplify the programming model for the entity bean client. While the client code needs to have a recovery handler for the system exceptions thrown from the individual method invocations on the remote home and remote interface, the client should not be forced to re-obtain the object references.

The container must implement the EntityContext.getEJBObject method such that the bean instance can use the Java language cast to convert the returned value to the entity bean’s remote interface type. Specifically, the bean instance does not have to use the PortableRemoteObject.narrow method for the type conversion.

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.

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

In special situations, the entity Bean Provider may choose not to specify the primary key class or the primary key fields 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 Container 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.

In this special case, the type of the argument of the findByPrimaryKey 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.

When defining the primary key for the enterprise bean, the Deployer using the Container Provider’s tools will typically add additional container-managed fields to the concrete subclass of the entity bean class (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 case, the container must generate the primary key value when the entity bean instance is created (and before ejbPostCreate is invoked on the instance.)

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 enterprise bean class has been written.

Enterprise Beans QL is a typed language whose design is based on the type model of Enterprise Beans 2.0 container-managed persistence. Every expression in Enterprise Beans QL has a type. The type of the expression is derived from the structure of the expression; the abstract schema types of the identification variable declarations; the types to which the cmp-fields and cmr-fields evaluate; and the types of literals. The allowable types in Enterprise Beans QL are the abstract schema types of entity beans and cmp-fields.

The abstract schema type of an entity bean is derived from its entity bean class and the information provided in the deployment descriptor. There is a one-to-one mapping between entity bean abstract schema types and entity bean homes. Abstract schema names, as specified by the abstract-schema-name elements in the deployment descriptor, are used to denote entity bean abstract schema types in Enterpise Beans QL.

Informally, the abstract schema type of an entity bean can be characterized as follows:

Abstract schema types are specific to the Enterprise Beans QL data model. The container is not required to implement or otherwise materialize an abstract schema type.

The domain of an Enterprise Beans QL query consists of the abstract schema types of all entity beans with container-managed persistence that are defined in the same deployment descriptor.

The domain of a query may be restricted by the navigability of the relationships of the entity bean on which it is based. The cmr-fields of an entity bean’s abstract schema type determine navigability. Using the cmr-fields and their values, a query can select related entity beans and use their abstract schema types in the query.

Enterprise Beans QL is used for two types of query methods:

Entity beans are designated in Enterprise Beans QL query strings by their abstract schema names. The Bean Provider assigns unique abstract schema names to entity beans as part of the development process so that they can be used within queries. These unique names are scoped within the deployment descriptor file.

The following convention refers to the names used for entity beans in subsequent examples: An entity bean as a whole is designated by <name>EJB, and its entity bean class and abstract schema type are designated by <name>, following the convention used to name the local interface of an entity bean.

The first example assumes that the Bean Provider provides several entity beans, OrderEJB, ProductEJB, LineItemEJB, ShippingAddressEJB, and BillingAddressEJB. The abstract schema types for these entity beans are Order, Product, LineItem, ShippingAddress, and BillingAddress respectively. These beans are logically in the same ejb-jar file, as shown in Several Entity Beans with Abstract Persistence Schemas Defined in the Same Ejb-jar File.. Only two of the entity beans, OrderEJB and ProductEJB, have remote interfaces and remote home interfaces.

The entity beans ShippingAddress and BillingAddress each have one-to-many relationships with Order. There is also a one-to-many relationship between Order and Lineitem. The entity bean LineItem is related to Product in a many-to-one relationship.

Enterprise Beans QL allows the Bean Provider to specify finder queries for OrderEJB by navigating over the cmr-fields and cmp-fields defined by Order and LineItem. A finder method query to find all orders with pending line items might be written as follows:

This query navigates over the cmr-field lineItems of the abstract schema type Order to find line items, and uses the cmp-field shipped of LineItem to select those orders that have at least one line item that has not yet shipped. (Note that this query does not select orders that have no line items.)

Although predefined reserved identifiers, such as DISTINCT, OBJECT, FROM, AS, IN, WHERE, and FALSE appear in upper case in this example, predefined reserved identifiers are case insensitive.

The SELECT clause of this example designates the return type of this query to be of type Order. If this query is defined for a finder method on the entity bean’s remote home interface, the finder method will return objects of the entity bean’s remote interface type corresponding to the abstract schema type instances selected by the query. If this same query is defined for a finder method on the entity bean’s local home interface, the finder method will return objects of the entity bean’s local interface type corresponding to these same abstract schema type instances. Finder methods must always return EJBObjects or EJBLocalObjects of the bean type for which the query method is defined.

Because the same deployment descriptor defines the abstract persistence schemas of the related entity beans, the Bean Provider can also specify a query for OrderEJB that utilizes the abstract schema type of ProductEJB, and hence the cmp-fields and cmr-fields of both the abstract schema types Order and Product. For example, if the abstract schema type Product has a cmp-field named product_type, a finder query for OrderEJB can be specified using this cmp-field. Such a finder query might be: “Find all orders for products with product type office supplies”. An Enterprise Beans QL query string for this might be as follows.

Because Order is related to Product by means of the relationships between Order and LineItem and between LineItem and Product, navigation using the cmr-fields lineItems and product is needed to express the query. This query is specified by using the abstract-schema-name for OrderEJB, namely Order, which designates the abstract schema type over which the query ranges. The basis for the navigation is provided by the cmr-fields lineItems and product of the abstract schema types Order and LineItem respectively.

The FROM clause of an Enterprise Beans QL query defines the domain of the query by declaring identification variables. The domain of the query may be constrained by path expressions.

Identification variables designate instances of a particular entity bean abstract schema type. The FROM clause can contain multiple identification variable declarations separated by a comma (,).

The following subsections discuss the constructs used in the FROM clause.

The WHERE clause of a query consists of a conditional expression used to select objects or values that satisfy the expression. The WHERE clause thus restricts the result of a query.

A WHERE clause is defined as follows:

The following sections describe the languageconstructs that can be used in a conditional expression of the WHERE clause.

The SELECT clause denotes the query result. The SELECT clause contains either a single range variable that ranges over an entity bean abstract schema type, a single-valued path expression, or an aggregate select expression. In the case of a finder method, the SELECT clause is restricted to contain either a single range variable or a single-valued path expression that evaluates to the abstract schema type of the entity bean for which the finder method is defined.

The SELECT clause has the following syntax:

All standalone identification variables in the SELECT clause must be qualified by the OBJECT operator. The SELECT clause must not use the OBJECT operator to qualify path expressions.

Note that the SELECT clause must be specified to return a single-valued expression. The query below is therefore not valid:

The DISTINCT keyword is used to specify that duplicate values must be eliminated from the query result. If DISTINCT is not specified, duplicate values are not eliminated unless the query is specified for a method whose result type is java.util.Set. If a query is specified for a method whose result type is java.util.Set, but does not specify DISTINCT, the container must interpret the query as if SELECT DISTINCT had been specified. In general, however, the Bean Provider should specify the DISTINCT keyword when writing queries for methods that return java.util.Set.

The SELECT clause determines the type of the values returned by a query. For example, the following query returns a collection of products:

It is the responsibility of the container to map the abstract schema types returned by the query to the Java types that are returned by the finder or select method with which the query is associated and to materialize those return types, as described in Return Value Types.

The ORDER BY clause allows the objects or values that are returned by the query to be ordered.

The syntax of the ORDER BY clause is

When the ORDER BY clause is used in an Enterprise Beans QL query, the SELECT clause of the query must be one of the following:

In the first two cases, each orderby_item must be an orderable cmp-field of the entity bean abstract schema type value returned by the SELECT clause. In the third case, the orderby_item must evaluate to the same cmp-field of the same entity bean abstract schema type as the cmp_path_expression in the SELECT clause.

For example, the first two queries below are legal, but the third and fourth are not.

If more than one orderby_item is specified, the left-to-right sequence of the orderby_item elements determines the precedence, whereby the leftmost orderby_item has highest precedence.

The keyword ASC specifies that ascending ordering be used; the keyword DESC specifies that descending ordering beused. Ascending ordering is the default.

SQL rules for the ordering of null values apply: that is, all null values must appear before all non-null values in the ordering or all null values must appear after all non-null values in the ordering, but it is not specified which.

It is the container’s responsibility to ensure that the ordering of the query result is preserved in the result of the finder or select method if the ORDER BY clause is used.

The value of a query result, specified by the SELECT clause, is an entity bean abstract schema type, a cmp-field type, or the result of an aggregate function. The finder or select method with which the query is associated in the deployment descriptor determines how this result is mapped to the Java type that is visible as the result of the query method.

How the result type of a query is mapped depends on whether the query is defined for a finder method on the remote home interface, for a finder method on the local home interface, or for a select method.

The result of a finder or select method may contain a null value if a cmp-field or cmr-field in the query result is null.

When the target of a reference does not exist in the persistent store, its value is regarded as NULL. SQL 92 NULL semantics [7] defines the evaluation of conditional expressions containing NULL values.

The following is a brief description of these semantics:

Note: Enterprise Beans QL defines the empty string, '', as a string with 0 length, which is not equal to a NULL value. However, NULL values and empty strings may not always be distinguished when queries are mapped to some persistent stores. The Bean Provider should therefore not rely on the semantics of Enterprise Beans QL comparisons involving the empty string and NULL value.

Enterprise Beans QL only permits the values of like types to be compared. A type is like another type if they correspond to the same Java language type, or if one is a primitive Java language type and the other is the wrappered Java class type equivalent (e.g., int and Integer are like types in this sense). There is one exception to this rule: it is valid to compare numeric values for which the rules of numeric promotion apply. Conditional expressions attempting to compare non-like type values are disallowed except for this numeric case.

Two entity objects of the same abstract schema type are equal if and only if they have the same primary key value.

Date and time values should use the standard Java long millisecond value. The standard way to produce millisecond values is to use java.util.Calendar.

Although SQL requires support for fixed decimal comparison in arithmetic expressions, Enterprise Beans QL does not. For this reason Enterprise Beans QL restricts exact numeric literals to those without a decimal point (and numerics with a decimal point as an alternate representation for approximate numeric values).

Support for the BigDecimal and BigInteger types is optional for containers in Enterprise Beans 2.1. Applications that depend on such types in Enterprise Beans QL queries may not be portable.

Boolean comparison is restricted to = and <>.

Enterprise Beans QL does not support the use of comments.

The data model for container-managed persistence does not currently support inheritance. Therefore, entity objects of different types cannot be compared. Enterprise Beans QL queries that contain such comparisons are invalid.

Find all orders:

Find all orders that need to be shipped to California:

Find all states for which there are orders:

Find all orders that have line items:

Note that the result of this query does not include orders with no associated line items. This query can also be written as:

Find all orders that have no line items:

Find all pending orders:

Find all orders in which the shipping address differs from the billing address. This example assumes that the Bean Provider uses two distinct entity beans to designate shipping and billing addresses, as in Several Entity Beans with Abstract Persistence Schemas Defined in the Same Ejb-jar File..

If the Bean Provider uses a single entity bean in two different relationships for both the shipping address and the billing address, the above expression can be simplified based on the equality rules defined in Equality and Comparison Semantics. The query can then be written as:

The query checks whether the same entity bean abstract schema type instance (identified by its primary key) is related to an order through two distinct relationships.

Find all orders for a book titled 'Applying Enterprise Beans: Component-Based Development for the J2EE Platform':

The following query finds the orders for a product whose name is designated by an input parameter:

For this query, the input parameter must be of the type of the cmp-field name, i.e., a string.

The following select queries illustrate the selection of values other than entity beans.

The following Enterprise Beans QL query selects the names of all products that have been ordered.

The following query finds the names of all products in the order specified by a particular order number. The order number is specified by a parameter that corresponds to the primary key of Order. Note that because this query does not specify DISTINCT in its SELECT clause, if it is specified for a query method whose return type is java.util.Collection, the collection that is returned may contain duplicates. In this example, such duplicates correspond to products that have been ordered multiple times in the given order.

It is the responsibility of the container to interpret the query such that no duplicates are produced if the result type of the query method is java.util.Set.

Consider the following query for a select method:

This query returns the names of all the cities of the shipping addresses of all orders. The result type of the select method, which is either java.util.Collection or java.util.Set, determines whether the query may return duplicate city names.

Enterprise Beans QL, like SQL, treats the FROM clause as a cartesian product. The FROM clause is similar to that of SQL in that the declared identification variables affect the results of the query even if they are not used in the WHERE clause. The Bean Provider should use caution in defining identification variables because the domain of the query can depend on whether there are any values of the declared type.

For example, the FROM clause below defines a query over all orders that have line items and existing products. If there are no Product instances in the persistent store, the domain of the query is empty and no order is selected.

The container can represent the abstract schemas of a set of entity beans in an application using a relational database. There are multiple ways to define a mapping to a set of tables in a relational database. Although this area is beyond the scope of this specification, a sample mapping and translation of Enterprise Beans QL to SQL is described to clarify the semantics of Enterprise Beans QL.

A mapping strategy from a set of entity beans to a relational database might be to map each entity bean to a separate table. One-to-many relationships may be represented by foreign keys in the related table from the many side and many-to-many relationships may be represented by using an auxiliary table that contains the primary keys of the related objects.

Because the FROM clause represents a cartesian product, the SQL result may contain duplicates. If the query is for a method whose return type is java.util.Set, the container would therefore typically utilize a SELECT DISTINCT clause in translating the query to SQL. The query method result may contain duplicates if the return type of the query method is java.util.Collection and DISTINCT is not specified in the SELECT clause of the Enterprise Beans QL query.

The following translation example illustrates the mapping of entity beans to relational database tables. The entity bean OrderEJB is represented by the table ORDER and the entity bean LineItemEJB is represented by the table LINEITEM. The column OKEY represents the primary key for OrderEJB entity bean, FKEY represents the foreign key column of LINEITEM that holds the values of the ORDER primary keys. FKEY is defined in the LINEITEM table to model the one-to-many relationship.

Using this mapping, the following Enterprise Beans QL finder query

might be represented in SQL as

Using bean-managed persistence, the entity Bean Provider writes database access calls (e.g. using JDBC™ or SQLJ) directly in the entity bean component. The data access calls are performed in the ejbCreate<METHOD>, ejbRemove, ejbFind<METHOD>, ejbLoad, and ejbStore methods, and/or in the business methods.

The data access calls can be coded directly into the entity bean class, or they can be encapsulated in a data access component that is part of the entity bean. Directly coding data access calls in the entity bean class may make it more difficult to adapt the entity bean to work with a database that has a different schema, or with a different type of database.

We expect that most enterprise beans with bean-managed persistence will be created by application development tools which will encapsulate data access in components. These data access components will probably not be the same for all tools. Further, if the data access calls are encapsulated in data access components, the data access components may require deployment interfaces to allow adapting data access to different schemas or even to a different database type. This Enterprise Beans specification does not define the architecture for data access objects, strategies for tailoring and deploying data access components or ensuring portability of these components for bean-managed persistence.

This section describes the runtime model and the classes used in the description of the contract between an entity bean with bean-managed persistence and its container.

An enterprise bean instance is an object whose class is provided by the Bean Provider.

An entity EJBObject or EJBLocalObject is an object whose class is generated at deployment time by the Container Provider’s tools. The entity EJBObject class implements the entity bean’s remote interface. The entity EJBLocalObject class implements the entity bean’s local interface. A client never references an entity bean instance directly—a client always references an entity EJBObject or entity EJBLocalObject whose class is generated by the Container Provider’s tools.

An entity EJBHome or EJBLocalHome object provides the life cycle operations (create, remove, find) for its entity objects as well as home business methods, which are not specific to an entity bean instance. The class for the entity EJBHome or EJBLocalHome object is generated by the Container Provider’s tools at deployment time. The entity EJBHome or EJBLocalHome object implements the entity bean’s home interface that was defined by the Bean Provider.

An entity bean instance is in one of the following three states:

The following steps describe the life cycle of an entity bean instance:

Notes:

This section specifies the contract between an entity bean with bean-managed persistence and its container.

Compliant implementations of this specification may optionally support read-only entity beans. A read-only entity bean is an entity bean whose instances are not intended to be updated and/or created by the application. Read-only beans are best suited for situations where the underlying data never changes or changes infrequently.

Containers that support read-only beans do not call the ejbStore method on them. The ejbLoad method should typically be called by the container when the state of the bean instance is initially loaded from the database, or at designated refresh intervals. ^[23]

If a read-only bean is used, the state of such a bean should not be updated by the application, and the behavior is unspecified if this occurs. ^[24]

Read-only beans are designated by vendor-specific means that are outside the scope of this specification, and their use is therefore not portable.

A container provides the entity bean instances with an EntityContext, which gives the entity bean instance access to the instance’s context maintained by the container. The EntityContext interface has the following methods:

Operations Allowed in the Methods of an Entity Bean defines the methods of an entity bean class in which the enterprise bean instances can access the methods of the jakarta.ejb.EntityContext interface, the java:comp/env environment naming context, resource managers, TimerService and Timer methods, the EntityManagerFactory and EntityManager methods, and other enterprise beans.

If an entity bean instance attempts to invoke a method of the EntityContext interface, and the access is not allowed in Operations Allowed in the Methods of an Entity Bean, the container must throw the java.lang.IllegalStateException.

If an entity bean instance attempts to invoke a method of the TimerService or Timer interface and the access is not allowed in Operations Allowed in the Methods of an Entity Bean, the container must throw the java.lang.IllegalStateException.

If an entity bean instance attempts to access a resource manager, an enterprise bean, or an entity manager or entity manager factory, and the access is not allowed in Operations Allowed in the Methods of an Entity Bean, the behavior is undefined by the Enterprise Beans architecture.

Additional restrictions:

Reasons for disallowing operations:

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 should handle the ejbLoad and ejbStore methods as follows:

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

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.

An entity bean can be registered with the Enterprise Beans Timer Service for time-based event notifications if it implements the jakarta.ejb.TimedObject interface. The container invokes the bean instance’s ejbTimeout method when a timer for the bean has expired. See Timer Service.

The Enterprise Beans specification defines the following standard application exceptions:

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:

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.

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

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.

An entity Bean Provider 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 an exception 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 component 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.) If the attempt is made to reenter the instance through the remote interface, the container must throw the java.rmi.RemoteException to the caller. If the attempt is made to reenter the instance through the local interface, the container must throw the jakarta.ejb.EJBException 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 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.

Concurrent calls in the same transaction context targeted at the same entity object are illegal and may lead to unpredictable results. Since the container cannot, in general, distinguish between an illegal concurrent call and a legal loopback, application programmers are encouraged to avoid using loopbacks. Entity beans that do not need callbacks should be marked as non-reentrant in the deployment descriptor, allowing the container to detect and prevent illegal concurrent calls from clients.

The Bean Provider is responsible for providing the following class files:

The Bean Provider must provide a remote interface and a remote home interface or a local interface an local home interface for the bean. The Bean Provider may provide a remote interface, remote home interface, local interface, and local home interface for the bean. Other combinations are not allowed.

The following are the requirements for an entity bean class:

The class must implement, directly or indirectly, the jakarta.ejb.EntityBean interface.

The class may implement, directly or indirectly, the jakarta.ejb.TimedObject interface.

The class must be defined as public and must not be abstract. The class must be a top level class.

The class must not be defined as final.

The class must define a public constructor that takes no arguments.

The class must not define the finalize method.

The class may, but is not required to, implement the entity bean’s component interface. ^[29] If the class implements the entity bean’s component interface, the class must provide no-op implementations of the methods defined in the jakarta.ejb.EJBObject or jakarta.ejb.EJBLocalObject interface. The container will never invoke these methods on the bean instances at runtime.

A no-op implementation of these methods is required to avoid defining the entity bean class as abstract.

The entity bean class must implement the business methods, and the ejbCreate<METHOD>, ejbPostCreate<METHOD>, ejbFind<METHOD>, and ejbHome<METHOD> methods as described later in this section.

The entity bean class may have superclasses and/or superinterfaces. If the entity bean has superclasses, the business methods, the ejbCreate and ejbPostCreate methods, the finder methods, and the methods of the EntityBean interface or the TimedObject interface may be implemented in the enterprise bean class or in any of its superclasses.

The entity bean class is allowed to implement other methods (for example helper methods invoked internally by the business methods) in addition to the methods required by the Enterprise Beans specification.

The entity bean class must implement the ejbCreate<METHOD> methods that correspond to the create<METHOD> methods specified in the entity bean’s home interface.

The entity bean class may define zero or more ejbCreate<METHOD> methods whose signatures must follow these rules:

The method name must have ejbCreate as its prefix.

The method must be declared as public.

The method must not be declared as final or static.

The return type must be the entity bean’s primary key type.

The method argument and return value types must be legal types for RMI-IIOP if the ejbCreate<METHOD> corresponds to a create<METHOD> on the entity bean’s remote home interface.

The throws clause may define arbitrary application specific exceptions, including the jakarta.ejb.CreateException.

Compatibility Note: Enterprise Beans 1.0 allowed the ejbCreate method to throw the java.rmi.RemoteException to indicate a non-application exception. This practice was deprecated in Enterprise Beans 1.1—an Enterprise Beans 1.1 or Enterprise Beans 2.0 or later compliant enterprise bean should throw the jakarta.ejb.EJBException or another java.lang.RuntimeException to indicate non-application exceptions to the container (see System Exceptions). An Enterprise Beans 2.0 or later enterprise bean should not throw the java.rmi.RemoteException from the ejbCreate method.

The entity object created by the ejbCreate<METHOD> method must have a unique primary key. This means that the primary key must be different from the primary keys of all the existing entity objects within the same home. The ejbCreate<METHOD> method should throw the DuplicateKeyException on an attempt to create an entity object with a duplicate primary key. However, it is legal to reuse the primary key of a previously removed entity object.

For each ejbCreate<METHOD> method, the entity bean class must define a matching ejbPostCreate<METHOD> method, using the following rules:

The method name must have ejbPostCreate as its prefix.

The method must be declared as public.

The method must not be declared as final or static.

The return type must be void.

The method arguments must be the same as the arguments of the matching ejbCreate<METHOD> method.

The throws clause may define arbitrary application specific exceptions, including the jakarta.ejb.CreateException.

Compatibility Note: Enterprise Beans 1.0 allowed the ejbPostCreate method to throw the java.rmi.RemoteException to indicate a non-application exception. This practice was deprecated in Enterprise Beans 1.1—an Enterprise Beans 1.1 or Enterprise Beans 2.0 or later compliant enterprise bean should throw the jakarta.ejb.EJBException or another java.lang.RuntimeException to indicate non-application exceptions to the container (see System Exceptions). An Enterprise Beans 2.0 or later enterprise bean should not throw the java.rmi.RemoteException from the ejbPostCreate method.

The entity bean class may also define additional ejbFind<METHOD> finder methods.

The signatures of the finder methods must follow the following rules:

A finder method name must start with the prefix “ejbFind” (e.g. ejbFindByPrimaryKey, ejbFindLargeAccounts, ejbFindLateShipments).

A finder method must be declared as public.

The method must not be declared as final or static.

The method argument types must be legal types for RMI-IIOP if the ejbFind<METHOD> method corresponds to a find<METHOD> method on the entity bean’s remote home interface.

The return type of a finder method must be the entity bean’s primary key type, or a collection of primary keys (see Finder Method Return Type).

The throws clause may define arbitrary application specific exceptions, including the jakarta.ejb.FinderException.

Compatibility Note: Enterprise Beans 1.0 allowed the finder methods to throw the java.rmi.RemoteException to indicate a non-application exception. This practice was deprecated in Enterprise Beans 1.1—an Enterprise Beans 1.1 or Enterprise Beans 2.0 or later compliant enterprise bean should throw the jakarta.ejb.EJBException or another java.lang.RuntimeException to indicate non-application exceptions to the container (see System Exceptions). An Enterprise Beans 2.0 or later enterprise bean should not throw the java.rmi.RemoteException from the ejbFind method.

Every entity bean must define the ejbFindByPrimaryKey method. The result type for this method must be the primary key type (i.e., the ejbFindByPrimaryKey method must be a single-object finder).

The entity bean class may define zero or more home methods whose signatures must follow the following rules:

An ejbHome<METHOD> method must exist for every home <METHOD> method on the entity bean’s remote home or local home interface. The method name must have ejbHome as its prefix followed by the name of the <METHOD> method in which the first character has been uppercased.

The method must be declared as public.

The method must not be declared as static.

The method argument and return value types must be legal types for RMI-IIOP if the ejbHome method corresponds to a method on the entity bean’s remote home interface.

The throws clause may define arbitrary application specific exceptions. The throws clause must not throw the java.rmi.RemoteException.

The entity bean class may define zero or more business methods whose signatures must follow these rules:

The method names can be arbitrary, but they must not start with “ejb” to avoid conflicts with the callback methods used by the Enterprise Beans architecture.

The business method must be declared as public.

The method must not be declared as final or static.

The method argument and return value types must be legal types for RMI-IIOP if the method corresponds to a business method on the entity bean’s remote interface.