Sun Microsystems Inc.

FROM l in LineItems, p FOR l.Product

10.2.4 WHERE Clause and Conditional Expressions

The WHERE clause of a finder query consists of a conditional expression used to select the objects or values that satisfy the expression. The order of evaluation is from left to right within precedence level. Parentheses can be used to change the order of evaluation.

A WHERE clause is defined as follows:

Where_clause ::= WHERE conditional_expression

Although predefined reserved literals and operator names appear in upper case, they are case insensitive.

The following sections describe the language constructs used in the conditional expressions of a EJB QL query.

10.2.4.1 Literals

A string literal is enclosed in single quotes—for example: ‘literal’. A string literal that includes a single quote is represented by two single quotes—for example: ‘literal’’s’. EJB QL string literals use unicode character encoding, the same as Java String literals.

An exact numeric literal is a numeric value without a decimal point, such as 57, -957, +62. Exact numeric literals support numbers in the range of Java long. Exact numeric literals use the Java integer literal syntax.

An approximate numeric literal is a numeric value in scientific notation, such as 7E3, -57.9E2, or a numeric value with a decimal, such as 7., -95.7, +6.2. Approximate numeric literals support numbers in the range of Java double. Approximate literals use the Java floating point literal syntax.

The boolean literals are TRUE and FALSE.

10.2.4.2 Identifiers

An identifier is a character sequence of unlimited length. The character sequence must begin with a Java identifier start character and all other characters must be Java identifier part characters. An identifier start character is any character for which the method Character.isJavaIdentifierStart returns true. This includes the underscore (_) character and the dollar sign ($) character. An identifier part character is any character for which the method Character.isJavaIdentifierPart returns true. The question mark (?) character is reserved for EJB QL.

Sun Microsystems Inc

Identifiers are

•cmp-field names

•cmr-field names

•correlation variables

•ejb-names or remote-ejb-names that uniquely designate entity beans

•abstract schema names

The following are the reserved identifiers in EJB QL: NULL, TRUE, FALSE, NOT, AND, OR, BETWEEN, LIKE, IN, FOR, FROM, WHERE, UNKNOWN and IS. When naming clashes occur, quoted names should be used to resolve ambiguity. See Section 10.2.4.4.

Identifiers are case sensitive.

Identifiers evaluate to a value of the type to which they refer.

10.2.4.3 Correlation Variables

A correlation variable is a valid identifier declared using the special operators IN or FOR in the FROM clause of an EJB QL query. All correlation variables must be declared in the FROM clause.

A correlation variable evaluates to a value of the type of the path expression used in declaring the variable. For example, given the declaration l in lineitems in the FROM clause of a finder query for OrderEJB, the correlation variable l evaluates to any LineItem value directly reachable from OrderBean. The cmr-field lineitems is a reference to the collection of LineItem dependent objects and the correlation variable l refers to a value in the collection.

Correlation variables are existentially quantified in the WHERE clause.

A correlation variable must not be a reserved identifier. A correlation variable must not have the same name as a cmp-field, cmr-field, ejb-name, remote-ejb-name, or abstract schema.

10.2.4.4 Quoted Names

Since there are reserved literals in EJB QL, the Bean Provider is expected to designate cmp-field and cmr-field names that use reserved words specially.

The Bean Provider must use double quotes to distinguish cmp-field and cmr-fields that use reserved literals in an expression. This is necessary to resolve ambiquity since there are no restrictions on the names of cmp-fields or cmr-fields. A quoted name is used in the same context where a cmp-field or a cmr-field name is used.

Sun Microsystems Inc.

For example, the abstract schema OrderBean might have a String-valued cmp-field named TRUE. In a finder query WHERE clause, a reference to the cmp-field must be designated as a cmp-field instead of the reserved literal TRUE, which has a boolean value. Therefore, a quoted name is used to resolve ambiguity as follows:

WHERE “TRUE” = ‘quoted name example’

10.2.4.5 Path Expressions

A cmp-field or cmr-field is a path expression. A path expression can be composed from other path expressions based on navigability using the period (.) operator. Path expressions can be composed from other path expressions if the original path expression evaluates to a single valued type (not a collection) described by a cmr-field. The type of the path expression is the type that is computed as the result of navigation, that is, the type of a cmp-field or a cmr-field.

The BNF for path expressions is defined as follows:

Path_expression :: = Single_valued_path_expression | Collection_valued_Path_expression

Single_valued_path_expression ::= [Single_valued_navigation.]cmp_field |

Single_valued_navigation

Single_valued_navigation ::=

[Correlation_variable.][single_valued_cmr_field.]* single_valued_cmr_field

Collection_Valued_Path_Expression ::=

[Correlation_variable.][single_valued_cmr_field.]*collection_valued_cmr_field)

A single_valued_cmr_field is designated by a cmr-field name in a one-to-one relation. This type of expression evaluates to a single value of the abstract schema type of the related entity bean or dependent object.

A Collection_valued_cmr_field is designated by a cmr-field in a one-to-many or a many-to-many relationship. The role in a one-to-many relationship that requires a reference is designated by a single_valued_cmr_field. The type of the expression is the abstract schema of the related entity bean or dependent object. A collection_valued_cmr_field has a collection of values of the designated type. They are terminal symbols in the BNF of EJB QL.

Navigation to other related entity beans in the abstract schema always returns a value of the related entity bean’s abstract schema type. Navigation using the period (.) operator in path expressions is only valid within the navigable abstract schemas defined within the same ejb-jar file. Navigation using the period (.) operator to cmr-fields that refer to remote entity bean interface types is not allowed. Navigation to the remote interface type of a related entity bean is handled using a different operator (=>); this is covered in the next section.

Sun Microsystems Inc

For example, if l is a correlation variable representing a value of type LineItem, a path expression l.product will have the type identified by the name ProductBean if ProductBean and OrderBean are in the same ejb-jar file. The expression l.product.name will have the type String as a result of navigation composition. If the two beans are not in the same ejb-jar file, the path expression l.product is invalid because the navigation operator (.) cannot be used to navigate to the remote interface type of an entity bean. Therefore, this expression is invalid for case(2) of Section 10.2.1.1.

It is syntactically illegal to compose a path expression from another path expression that evaluates to a multi-valued collection. For example, if O designates OrderBean, the path expression O.lineitems.product is illegal since navigation to lineitems results in a multivalued collection. This case results in an error when verifying an EJB QL query string. Instead, a correlation variable must be declared to range over values of the lineitems collection in the FROM clause, and another path expression must be designated to navigate over the members of a collection in the WHERE clause of the finder query. For example, the following two expressions are legal and equivalent.

FROM l in lineitems, P FOR l.product WHERE P.name=’foobar’

FROM l in lineitems WHERE l.product.name = ‘foobar’

10.2.4.6 Remote Interface Reference Expressions

The EJB QL navigation operator => is used to navigate to instances of an entity bean’s remote type. The Bean Provider uses this operator in an expression to obtain the remote interface value of a related entity bean (i.e., the entity object). The operator is used to navigate over cmr-fields that refer to other entity beans remotely. References to remote interfaces can only be handled using the => operator.

In our example, where the correlation variable l designates a LineItem value, the expression l=>product evaluates to the type of the remote interface for ProductEJB, namely Product. Its value is an instance of Product, which designates an entity object.

Bean Providers can use remote interface reference expressions to access entity objects remotely, regardless of whether the abstract schema of the entity bean is known to the Bean Provider. Therefore, the expression l=>product is valid for both scenerios case(1) and case(2) discussed in the Examples Section 10.2.1.1.

EJB QL does not allow further navigation from values that designate the instance of a remote type. These values can only be used in comparisons and IN expressions. Therefore,

Remote_interface_reference expessions are terminal.

Remote Interface Reference Expressions have the following syntax:

Remote_Interface_reference_expression ::= Single_valued_refence_expression|

Collection_valued_reference_expression

Single_valued_reference_expression ::=

(Single_valued_navigation | Correlation_variable) => single_valued_cmr_field