Sun Microsystems Inc.

EJB QL is used for queries of two types of finder methods:

•Finder methods that are defined in the home interface of an entity bean and which return entity objects.

•Select methods, which are not exposed to the client, but which are used by the Bean Provider to select persistent values that are maintained by the Persistence Manager or to select entity objects that are related to the entity bean on which the query is defined.

The syntax of an EJB QL query differs slightly depending on the type of finder method it is used for. In particular,

•A finder method, which is defined in the home interface of an entity bean, must return either a remote object representing an entity object or a collection of remote objects representing a collection of entity objects. The result type of such a finder method is determined by the entity bean for which it is defined. The EJB QL query string for such a finder must not have a SELECT clause since it is implicit.

•A select method is defined only on the entity bean’s implementation class. A query for a select method must have a SELECT clause which specifies the type of values to be selected.

For a detailed discussion of the different types of finder methods and restrictions on their result types, see Section 9.6.7.

An EJB QL query is statically defined in the deployment descriptor.

An EJB QL query has parameters that correspond to the parameters of the finder or select method for which it is defined.

An EJB QL query can use finder methods of other entity beans, but cannot use select methods of other beans.

The Bean Provider normally uses the ejb-ql deployment descriptor for the entity to specify an EJB QL query string that corresponds to a finder or select method. If the Bean Provider needs to utilize features which are not yet available in EJB QL in order to specify a query, he or she should use the query-spec element to precisely describe the semantics of the query. The query-spec element should be used only to specify queries whose semantics cannot be captured in EJB QL.

An EJB QL query must have no more than one SELECT, FROM or WHERE clause.

10.2.1 Abstract Schemas and Query Domains

EJB QL is a typed expression language whose design is based on the type model of EJB 2.0 container managed persistence, with one difference: EJB QL queries use the abstract schema types of entity beans that are “local,” that is, within the same ejb-jar file, and the remote types of the entity beans that are “remote,” that is, not specified within the same ejb-jar file. Navigation within local beans (using cmr-fields) results in values of the related entity beans abstract schema types instead of their remote types.

Sun Microsystems Inc

The domain of an EJB QL query is

•The abstract schemas of all entity beans and their dependent objects in the ejb-jar file. These entity beans are considered to be local.

•All remote entity beans whose abstract schemas are not defined within the ejb-jar file but which participate in relationships within the ejb-jar file.

The Bean Provider creates an ejb-jar file by including in the file several related entity beans and their dependent objects, along with a deployment descriptor which describes their relationships. EJB QL assumes that a single ejb-jar file constitutes a nondecomposable unit for the persistence manager responsible for implementing the abstract schemas of the entity beans, their dependent objects, and the relationships defined in the ejb-jar file. Therefore, queries can be written by utilizing navigation over the cmr-fields of related beans (and dependent object classes) supplied in the same ejb-jar by the Bean Provider because they are implemented and managed by the same persistence manager.

A query cannot use arbitrary entity beans or dependent objects as its domain. The domain of a query is 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 determine navigability. Using the cmr-fields and their values, a query can select related dependent objects and entity objects and use their abstract schemas in the query. However, the query can be specified only over navigable relationships described in the deployment descriptor. All entity beans or dependent objects that participate in relationships navigable from an entity bean can be used in a finder query. A query cannot use entity beans or dependent objects that are not related via navigation to the entity bean on which it is based.

10.2.1.1 Examples

To illustrate, we extend the example introduced in Section 10.1. We use the following convention to refer to entity beans: An entity bean is designated by its name <name>EJB and its abstract schema is designated by the bean’s implementation class name, <name>Bean.

Assume that a Bean Provider provides two entity beans, OrderEJB and ProductEJB. The abstract schema OrderBean and the dependent objects LineItem, ShippingAddress, BillingAddress, and the abstract schema ProductBean are in the same ejb-jar file, as shown in Figure 35. We call this example case (1).

Figure 35 Two beans, OrderEJB and ProductEJB, defined in the same ejb-jar file.

In this example, ProductEJB is located in the same ejb-jar file as OrderEJB. This means that the abstract schemas of both beans are available to the Bean Provider and that the Bean Provider can use the cmp-fields and cmr-fields of the related beans in queries. The abstract schema OrderBean describes relationships using cmr-fields. The dependent object classes, ShippingAddress and BillingAddress, are used in two different one-to-one relationships in the schema. There is a one-to-many relationship between OrderBean and Lineitem. LineItem is also related to ProductEJB by a one-to-one relationship.

Sun Microsystems Inc.

ejb-jar file

Since both beans are in the same ejb-jar file, the Bean Provider can specify a query for the OrderEJB entity bean which utilizes the abstract schema of ProductEJB, by using cmp-fields and cmr-fields in ProductBean. This can be done because the abstract schemas of OrderBean and ProductBean are related to each other by means of their relationship with LineItem. For example, if the abstract schema ProductBean has a cmp-field named product_type, a finder query for the Order entity bean can be specified based on this cmp-field. Such a finder query might be: “Find all Orders for products which have the product type office supplies ”.

The deployment descriptor describes the relationships between entity beans and dependent objects using the name of the entity bean, namely the ejb-name element defined for an entity bean. In this example, OrderEJB and ProductEJB are the ejb-names of the entity beans.

Container managed persistence allows one way navigable relationships from dependent objects and entity beans to other entity beans which are not in the same ejb-jar file. EJB QL similarly allows navigation to entity beans which are not part of the same ejb-jar file. The Bean Provider designates a unique name for such a remote bean using the remote-ejb-name deployment descriptor element.

The Bean Provider can write queries that utilize relationships to such remote entity beans. The Bean Provider, however, cannot access the abstract schemas of the remote beans because they are not available. Instead, the Bean Provider can define finder queries on remote entity beans using special navigation expressions within EJB QL.

Figure 36 illustrates this case. The example uses the same entity beans as in the previous example. However, in this example, the abstract schema of ProductEJB is in a different ejb-jar file and it may be deployed using a different persistence manager. The Bean Provider can utilize the abstract schemas of

OrderEJB and its dependent object classes, LineItem, ShippingAddress, and BillingAddress in queries, but cannot use the abstract schema ProductBean. However, the bean programmer can find related remote objects of ProductEJB and can also utilize finder methods defined on ProductEJB to locate remote entity objects.