Download PDF Home History |  | API Search Feedback FAQ

> ## Full Syntax

> This section discusses the EJB QL syntax, as defined in the Enterprise JavaBeans specification. Much of the following material paraphrases or directly quotes the specification.

> ### BNF Symbols

> Table 29-1 describes the BNF symbols used in this chapter.

> Table 29-1 BNF Symbol Summary
> Symbol | Description
> --- | ---
> ::= | The element to the left of the symbol is defined by the constructs on the right.
> * | The preceding construct may occur zero or more times.
> {...} | The constructs within the curly braces are grouped together.
> [...] | The constructs within the square brackets are optional.
> | | An exclusive OR.
> BOLDFACE | A keyword (although capitalized in the BNF diagram, keywords are not case-sensitive).
> Whitespace | A whitespace character can be a space, a horizontal tab, or a linefeed.

> ### BNF Grammar of EJB QL

> Here is the entire BNF diagram for EJB QL:

>     EJB QL ::= select_clause from_clause [where_clause]
>     [orderby_clause]

>     from_clause ::=FROM identification_variable_declaration
>         [, identification_variable_declaration]*

>     identification_variable_declaration ::=
>     collection_member_declaration |
>         range_variable_declaration

>     collection_member_declaration ::= IN (
>     collection_valued_path_expression) [AS ] identifier

>     range_variable_declaration ::=
>         abstract_schema_name [AS ] identifier

>     cmp_path_expression ::=
>         {identification_variable |
>          single_valued_cmr_path_expression}.cmp_field

>     single_valued_cmr_path_expression ::=
>         identification_variable.[single_valued_cmr_field.]*
>          single_valued_cmr_field

>     single_valued_path_expression ::=
>         cmp_path_expression | single_valued_cmr_path_expression

>     collection_valued_path_expression ::=
>         identification_variable.[single_valued_cmr_field.]
>         *collection_valued_cmr_field

>     select_clause ::= SELECT [DISTINCT ] {select_expression
>         |OBJECT( identification_variable) }

>     select_expression ::= single_valued_path_expression |
>     aggregate_select_expression

>     aggregate_select_expression ::=
>         {AVG |MAX |MIN |SUM |COUNT }( [DISTINCT ]
>          cmp_path_expression) |
>         COUNT ( [DISTINCT ] identification_variable |
>          single_valued_cmr_path_expression)

>     where_clause ::= WHERE conditional_expression

>     conditional_expression ::= conditional_term |
>         conditional_expression OR conditional_term

>     conditional_term ::= conditional_factor |
>         conditional_term AND conditional_factor

>     conditional_factor ::= [NOT ] conditional_primary

>     conditional_primary ::= simple_cond_expression |
>          (conditional_expression)

>     simple_cond_expression ::=
>         comparison_expression | between_expression |
>         like_expression | in_expression |
>         null_comparison_expression |
>         empty_collection_comparison_expression |
>         collection_member_expression

>     between_expression ::=
>         arithmetic_expression [NOT ]BETWEEN
>         arithmetic_expression AND arithmetic_expression

>     in_expression ::=
>         cmp_path_expression [NOT ] IN
>         ( {literal | input_parameter}
>         [, { literal | input_parameter} ]*)

>     like_expression ::=
>         cmp_path_expression [NOT ] LIKE
>         pattern_value [ESCAPE escape_character]

>     null_comparison_expression ::=
>         {single_valued_path_expression |
>         input_parameter}IS [NOT ] NULL

>     empty_collection_comparison_expression ::=
>         collection_valued_path_expression IS [NOT] EMPTY

>     collection_member_expression ::=
>         {single_valued_cmr_path_expression |
>          identification_variable | input_parameter}
>         [NOT ] MEMBER [OF ] collection_valued_path_expression

>     comparison_expression ::=
>         string_value comparison_operator string_expression |
>         boolean_value {= |<> } boolean_expression} |
>         datetime_value comparison_operator datetime_expression |
>         entity_bean_value {= |<> } entity_bean_expression |
>         arithmetic_value comparison_operator arithmetic_expression

>     arithmetic_value ::= cmp_path_expression |
>          functions_returning_numerics

>     comparison_operator ::=
>         = |> |>= |< |<= |<>

>     arithmetic_expression ::= arithmetic_term |
>         arithmetic_expression {+ |- } arithmetic_term

>     arithmetic_term ::= arithmetic_factor |
>          arithmetic_term {* |/ } arithmetic_factor

>     arithmetic_factor ::= [{+ |- }] arithmetic_primary

>     arithmetic_primary ::= cmp_path_expression | literal |
>         (arithmetic_expression) | input_parameter |
>         functions_returning_numerics

>     string_value ::= cmp_path_expression |
>          functions_returning_strings

>     string_expression ::= string_primary | input_parameter

>     string_primary ::= cmp_path_expression | literal |
>         (string_expression) | functions_returning_strings

>     datetime_value ::= cmp_path_expression

>     datetime_expression ::= datetime_value | input_parameter

>     boolean_value ::= cmp_path_expression

>     boolean_expression ::= cmp_path_expression | literal |
>         input_parameter

>     entity_bean_value ::= single_valued_cmr_path_expression |
>         identification_variable

>     entity_bean_expression ::= entity_bean_value | input_parameter

>     functions_returning_strings ::=
>         CONCAT( string_expression, string_expression) |
>         SUBSTRING( string_expression, arithmetic_expression,
>         arithmetic_expression)

>     functions_returning_numerics ::=
>         LENGTH( string_expression) |
>         LOCATE( string_expression, string_expression
>         [, arithmetic_expression]) |
>         ABS( arithmetic_expression) |
>         SQRT( arithmetic_expression) |
>         MOD( arithmetic_expression, arithmetic_expression)

>     orderby_clause ::= ORDER BY orderby_item [, orderby_item]*

>     orderby_item ::= cmp_path_expression [ASC |DESC ]

> ### FROM Clause

> The `FROM` clause defines the domain of the query by declaring identification variables. Here is the syntax of the `FROM` clause:

>     from_clause ::= FROM identification_variable_declaration
>         [, identification_variable_declaration]*

>     identification_variable_declaration ::=
>         collection_member_declaration |
>         range_variable_declaration

>     collection_member_declaration ::=
>         IN (collection_valued_path_expression) [AS] identifier

>     range_variable_declaration ::=
>         abstract_schema_name [AS] identifier

> #### Identifiers

> An identifier is a sequence of one or more characters. The first character must be a valid first character (letter, `$`, `_`) in an identifier of the Java programming language (hereafter in this chapter called simply "Java"). Each subsequent character in the sequence must be a valid nonfirst character (letter, digit, `$`, `_`) in a Java identifier. (For details, see the J2SE API documentation of the `isJavaIdentifierStart` and `isJavaIdentifierPart` methods of the `Character` class.) The question mark (`?`) is a reserved character in EJB QL and cannot be used in an identifier. Unlike a Java variable, an EJB QL identifier is not case-sensitive.

> An identifier cannot be the same as an EJB QL keyword:

> `AND` `AS` `ASC` `AVG` `BETWEEN` `BY` `COUNT` `DESC` `DISTINCT` `EMPTY` | `FALSE` `FROM` `IN` `IS` `LIKE` `MAX` `MEMBER` `MIN` `MOD` `NOT` | `NULL` `OBJECT` `OF` `OR` `ORDER` `SELECT` `SUM` `TRUE` `UNKNOWN` `WHERE`

> EJB QL keywords are also reserved words in SQL. In the future, the list of EJB QL keywords may expand to include other reserved SQL words. The Enterprise JavaBeans specification recommends that you not use other reserved SQL words for EJB QL identifiers.

> #### Identification Variables

> An identification variable is an identifier declared in the `FROM` clause. Although the `SELECT` and `WHERE` clauses can reference identification variables, they cannot declare them. All identification variables must be declared in the `FROM` clause.

> Because an identification variable is an identifier, it has the same naming conventions and restrictions as an identifier. For example, an identification variable is not case-sensitive, and it cannot be the same as an EJB QL keyword. (See the preceding section for more naming rules.) Also, within a given EJB JAR file, an identifier name must not match the name of any entity bean or abstract schema.

> The `FROM` clause can contain multiple declarations, separated by commas. A declaration can reference another identification variable that has been previously declared (to the left). In the following `FROM` clause, the variable `t` references the previously declared variable `p`:

>     FROM Player p, IN (p.teams) AS t

> Even if an identification variable is not used in the `WHERE` clause, its declaration can affect the results of the query. For an example, compare the next two queries. The following query returns all players, whether or not they belong to a team:

>     SELECT OBJECT(p)
>     FROM Player p

> In contrast, because the next query declares the `t` identification variable, it fetches all players that belong to a team:

>     SELECT OBJECT(p)
>     FROM Player p, IN (p.teams) AS t

> The following query returns the same results as the preceding query, but the `WHERE` clause makes it easier to read:

>     SELECT OBJECT(p)
>     FROM Player p
>     WHERE p.teams IS NOT EMPTY

> An identification variable always designates a reference to a single value whose type is that of the expression used in the declaration. There are two kinds of declarations: range variable and collection member.

> ##### Range Variable Declarations

> To declare an identification variable as an abstract schema type, you specify a range variable declaration. In other words, an identification variable can range over the abstract schema type of an entity bean. In the following example, an identification variable named `p` represents the abstract schema named `Player`:

>     FROM Player p

> A range variable declaration can include the optional `AS` operator:

>     FROM Player AS p

> In most cases, to obtain objects a query uses path expressions to navigate through the relationships. But for those objects that cannot be obtained by navigation, you can use a range variable declaration to designate a starting point (or root).

> If the query compares multiple values of the same abstract schema type, then the `FROM` clause must declare multiple identification variables for the abstract schema:

>     FROM Player p1, Player p2

> For a sample of such a query, see Example 9 .

> ##### Collection Member Declarations

> In a one-to-many relationship, the multiple side consists of a collection of entity beans. An identification variable can represent a member of this collection. To access a collection member, the path expression in the variable's declaration navigates through the relationships in the abstract schema. (For more information on path expressions, see the following section.) Because a path expression can be based on another path expression, the navigation can traverse several relationships. See Example 6 .

> A collection member declaration must include the `IN` operator, but it can omit the optional `AS` operator.

> In the following example, the entity bean represented by the abstract schema named `Player` has a relationship field called `teams`. The identification variable called `t` represents a single member of the `teams` collection.

>     FROM Player p, IN (p.teams) AS t

> ### Path Expressions

> Path expressions are important constructs in the syntax of EJB QL, for several reasons. First, they define navigation paths through the relationships in the abstract schema. These path definitions affect both the scope and the results of a query. Second, they can appear in any of the three main clauses of an EJB QL query (`SELECT`, `WHERE`, `FROM`). Finally, although much of EJB QL is a subset of SQL, path expressions are extensions not found in SQL.

> #### Syntax

> Here is the syntax for path expressions:

> cmp_path_expression ::=
> {identification_variable |
> single_valued_cmr_path_expression}.cmp_field
> single_valued_cmr_path_expression ::=
> identification_variable.[single_valued_cmr_field.]*
> single_valued_cmr_field
> single_valued_path_expression ::=
> cmp_path_expression | single_valued_cmr_path_expression
> collection_valued_path_expression ::=
> identification_variable.[single_valued_cmr_field.]
> *collection_valued_cmr_field

> In the preceding diagram, the `cmp_field` element represents a persistent field, and the `cmr_field` element designates a relationship field. The term `single_valued` qualifies the relationship field as the single side of a one-to-one or one-to-many relationship; the term `collection_valued` designates it as the multiple (collection) side of a relationship. The `single_valued_cmr_path_expression` is the abstract schema type of the related entity bean.

> The period (.) in a path expression serves two functions. If a period precedes a persistent field, it is a delimiter between the field and the identification variable. If a period precedes a relationship field, it is a navigation operator.

> #### Examples

> In the following query, the `WHERE` clause contains a `cmp_path_expression`. The `p` is an identification variable, and `salary` is a persistent field of `Player`.

>     SELECT DISTINCT OBJECT(p)
>     FROM Player p
>     WHERE p.salary BETWEEN ?1 AND ?2

> The `WHERE` clause of the next example also contains a `cmp_path_expression`. The `t` is an identification variable, `league` is a single-valued relationship field, and `sport` is a persistent field of `league`.

>     SELECT DISTINCT OBJECT(p)
>     FROM Player p, IN (p.teams) AS t
>     WHERE t.league.sport = ?1

> In the next query, the `WHERE` clause contains a `collection_valued_path_expression`. The `p` is an identification variable, and `teams` designates a collection-valued relationship field.

>     SELECT DISTINCT OBJECT(p)
>     FROM Player p
>     WHERE p.teams IS EMPTY

> #### Expression Types

> The type of an expression is the type of the object represented by the ending element, which can be one of the following:

> - Persistent field
> - Single-valued relationship field
> - Collection-valued relationship field

> For example, the type of the expression `p.salary` is `double` because the terminating persistent field (`salary`) is a `double`.

> In the expression `p.teams`, the terminating element is a collection-valued relationship field (`teams`). This expression's type is a collection of the abstract schema type named `Team`. Because `Team` is the abstract schema name for the `TeamBean` entity bean, this type maps to the bean's local interface, `LocalTeam`. For more information on the type mapping of abstract schemas, see the section Return Types.

> #### Navigation

> A path expression enables the query to navigate to related entity beans. The terminating elements of an expression determine whether navigation is allowed. If an expression contains a single-valued relationship field, the navigation can continue to an object that is related to the field. However, an expression cannot navigate beyond a persistent field or a collection-valued relationship field. For example, the expression `p.teams.league.sport` is illegal, because `teams` is a collection-valued relationship field. To reach the `sport` field, the `FROM` clause could define an identification variable named `t` for the `teams` field:

>     FROM Player AS p, IN (p.teams) t
>     WHERE t.league.sport = 'soccer'

> ### WHERE Clause

> The `WHERE` clause specifies a conditional expression that limits the values returned by the query. The query returns all corresponding values in the data store for which the conditional expression is `TRUE`. Although usually specified, the `WHERE` clause is optional. If the `WHERE` clause is omitted, then the query returns all values. The high-level syntax for the `WHERE` clause follows:

>     where_clause ::= WHERE conditional_expression

> #### Literals

> There are three kinds of literals: string, numeric, and Boolean.

> ##### String Literals

> A string literal is enclosed in single quotes:

>     'Duke'

> If a string literal contains a single quote, you indicate the quote by using two single quotes:

>     'Duke''s'

> Like a Java `String`, a string literal in EJB QL uses the Unicode character encoding.

> ##### Numeric Literals

> There are two types of numeric literals: exact and approximate.

> An exact numeric literal is a numeric value without a decimal point, such as 65, -233, and +12. Using the Java integer syntax, exact numeric literals support numbers in the range of a Java `long`.

> An approximate numeric literal is a numeric value in scientific notation, such as 57., -85.7, and +2.1. Using the syntax of the Java floating-point literal, approximate numeric literals support numbers in the range of a Java `double`.

> ##### Boolean Literals

> A Boolean literal is either `TRUE` or `FALSE`. These keywords are not case-sensitive.

> #### Input Parameters

> An input parameter is designated by a question mark (`?`) followed by an integer. For example, the first input parameter is `?1`, the second is `?2`, and so forth.

> The following rules apply to input parameters:

> - They can be used only in a `WHERE` clause.
> - Their use is restricted to a single-valued path expression within a conditional expression.
> - They must be numbered, starting with the integer 1.
> - The number of input parameters in the `WHERE` clause must not exceed the number of input parameters in the corresponding finder or select method.
> - The type of an input parameter in the `WHERE` clause must match the type of the corresponding argument in the finder or select method.

> #### Conditional Expressions

> A `WHERE` clause consists of a conditional expression, which is evaluated from left to right within a precedence level. You can change the order of evaluation by using parentheses.

> Here is the syntax of a conditional expression:

>     conditional_expression ::= conditional_term |
>         conditional_expression OR conditional_term

>     conditional_term ::= conditional_factor |
>         conditional_term AND conditional_factor

>     conditional_factor ::= [NOT ] conditional_primary

>     conditional_primary ::= simple_cond_expression |
>          (conditional_expression)

>     simple_cond_expression ::=
>         comparison_expression | between_expression |
>         like_expression | in_expression |
>         null_comparison_expression |
>         empty_collection_comparison_expression |
>         collection_member_expression

> #### Operators and Their Precedence

> Table 29-2 lists the EJB QL operators in order of decreasing precedence.

> Table 29-2 EJB QL Operator Precedence
> Type | Precedence Order
> --- | ---
> Navigation | `.` (a period)
> Arithmetic | `+ -` (unary) `* /` (multiplication and division) + - (addition and subtraction)
> Comparison | `=` `>` `>=` `<` `<=` `<>` (not equal)
> Logical | `NOT` `AND` `OR`

> #### BETWEEN Expressions

> A `BETWEEN` expression determines whether an arithmetic expression falls within a range of values. The syntax of the `BETWEEN` expression follows:

>     between_expression ::=
>       arithmetic_expression [NOT] BETWEEN
>       arithmetic_expression AND arithmetic_expression

> These two expressions are equivalent:

>     p.age BETWEEN 15 AND 19
>     p.age >= 15 AND p.age <= 19

> The following two expressions are also equivalent:

>     p.age NOT BETWEEN 15 AND 19
>     p.age < 15 OR p.age > 19

> If an arithmetic expression has a `NULL` value, then the value of the `BETWEEN` expression is unknown.

> #### IN Expressions

> An `IN` expression determines whether or not a string belongs to a set of string literals. Here is the syntax of the `IN` expression:

>     in_expression ::=
>         cmp_path_expression [NOT ] IN
>         ( {literal | input_parameter}
>         [, { literal | input_parameter} ]*)

> The path expression must have a string or numeric value. If the path expression has a `NULL` value, then the value of the `IN` expression is unknown.

> In the following example, if the country is `UK` the expression is `TRUE`. If the country is `Peru` it is `FALSE`.

>     o.country IN ('UK', 'US', 'France')

> #### LIKE Expressions

> A `LIKE` expression determines whether a wildcard pattern matches a string. Here is the syntax:

>     like_expression ::=
>         cmp_path_expression [NOT ] LIKE
>         pattern_value [ESCAPE escape_character]

> The path expression must have a string or numeric value. If this value is `NULL`, then the value of the `LIKE` expression is unknown. The pattern value is a string literal that can contain wildcard characters. The underscore (_) wildcard character represents any single character. The percent (`%`) wildcard character represents zero or more characters. The `ESCAPE` clause specifies an escape character for the wildcard characters in the pattern value. Table 29-3 shows some sample `LIKE` expressions.

> Table 29-3 LIKE Expression Examples
> Expression | TRUE | FALSE
> --- | --- | ---
> `address.phone LIKE '12%3'` | `'123'` `'12993'` | `'1234'`
> `asentence.word LIKE 'l_se'` | `'lose'` | `'loose'`
> `aword.underscored LIKE '\_%' ESCAPE '\'` | `'_foo'` | `'bar'`
> `address.phone NOT LIKE '12%3'` | `'1234'` | `'123'` `'12993'`

> #### NULL Comparison Expressions

> A `NULL` comparison expression tests whether a single-valued path expression or an input parameter has a `NULL` value. Usually, the `NULL` comparison expression is used to test whether or not a single-valued relationship has been set. Here is the syntax of a `NULL` comparison expression:

>     null_comparison_expression ::=
>         {single_valued_path_expression |

>      input_parameter}IS [NOT ] NULL

> #### Empty Collection Comparison Expressions

> An empty collection comparison expression tests whether a collection-valued path expression has no elements. In other words, it tests whether or not a collection-valued relationship has been set. Here is the syntax:

>     empty_collection_comparison_expression ::=
>        collection_valued_path_expression IS [NOT] EMPTY

> If the collection-valued path expression is `NULL`, then the empty collection comparison expression has a `NULL` value.

> #### Collection Member Expressions

> The collection member expression determines whether a value is a member of a collection. The value and the collection members must have the same type. The expression syntax follows:

>     collection_member_expression ::=
>         {single_valued_cmr_path_expression |
>         identification_variable | input_parameter}
>         [NOT ] MEMBER [OF ] collection_valued_path_expression

> If either the collection-valued or single-valued path expression is unknown, then the collection member expression is unknown. If the collection-valued path expression designates an empty collection, then the collection member expression is `FALSE`.

> #### Functional Expressions

> EJB QL includes several string and arithmetic functions, which are listed in the following tables. In Table 29-4, the `start` and `length` arguments are of type `int`. They designate positions in the `String` argument. The first position in a string is designated by 1. In Table 29-5, the `number` argument can be either an `int`, a `float`, or a `double`.

> Table 29-4 String Expressions
> Function Syntax | Return Type
> --- | ---
> `CONCAT(String, String)` | `String`
> `LENGTH(String)` | `int`
> `LOCATE(String, String [, start])` | `int`
> `SUBSTRING(String, start, length)` | `String`

> Table 29-5 Arithmetic Expressions
> Function Syntax | Return Type
> --- | ---
> `ABS(number)` | `int`, `float`, or `double`
> `MOD(int, int)` | `int`
> `SQRT(double)` | `double`

> #### NULL Values

> If the target of a reference is not in the persistent store, then the target is `NULL`. For conditional expressions containing `NULL`, EJB QL uses the semantics defined by SQL92. Briefly, these semantics are as follows:

> - If a comparison or arithmetic operation has an unknown value, it yields a `NULL` value.
> - Two `NULL` values are not equal. Comparing two `NULL` values yields an unknown value.
> - The`IS NULL` test converts a `NULL` persistent field or a single-valued relationship field to `TRUE`. The `IS NOT NULL` test converts them to `FALSE`.
> - Boolean operators and conditional tests use the three-valued logic defined by Table 29-6 and Table 29-7. (In these tables, T stands for `TRUE`, F for `FALSE`, and U for unknown.)

>   Table 29-6 AND Operator Logic
>   AND | T | F | U
>   --- | --- | --- | ---
>   T | T | F | U
>   F | F | F | F
>   U | U | F | U

>   Table 29-7 OR Operator Logic
>   OR | T | F | U
>   --- | --- | --- | ---
>   T | T | T | T
>   F | T | F | U
>   U | T | U | U

> #### Equality Semantics

> In EJB QL, only values of the same type can be compared. However, this rule has one exception: Exact and approximate numeric values can be compared. In such a comparison, the required type conversion adheres to the rules of Java numeric promotion.

> EJB QL treats compared values as if they were Java types and not as if they represented types in the underlying data store. For example, if a persistent field could be either an integer or a `NULL`, then it must be designated as an `Integer` object and not as an `int` primitive. This designation is required because a Java object can be `NULL` but a primitive cannot.

> Two strings are equal only if they contain the same sequence of characters. Trailing blanks are significant; for example, the strings `'abc'` and `'abc '` are not equal.

> Two entity beans of the same abstract schema type are equal only if their primary keys have the same value. Table 29-8 shows the operator logic of a negation, and Table 29-9 shows the truth values of conditional tests.

> Table 29-8 NOT Operator Logic
> NOT Value | Value
> --- | ---
> T | F
> F | T
> U | U

> Table 29-9 Conditional Test
> Conditional Test | T | F | U
> --- | --- | --- | ---
> Expression `IS TRUE` | T | F | F
> Expression `IS FALSE` | F | T | F
> Expression is unknown | F | F | T

> ### SELECT Clause

> The `SELECT` clause defines the types of the objects or values returned by the query. The `SELECT` clause has the following syntax:

>     select_clause ::= SELECT [DISTINCT ] {select_expression
>         |OBJECT( identification_variable) }

>     select_expression ::= single_valued_path_expression |
>         aggregate_select_expression

>     aggregate_select_expression ::=
>         {AVG |MAX |MIN |SUM |COUNT }( [DISTINCT ]
>         cmp_path_expression) |
>         COUNT ( [DISTINCT ] identification_variable |
>         single_valued_cmr_path_expression)

> #### Return Types

> The return type defined by the `SELECT` clause must match that of the finder or select method for which the query is defined.

> For finder method queries, the return type of the `SELECT` clause is the abstract schema type of the entity bean that defines the finder method. This abstract schema type maps to either a remote or a local interface. If the bean's remote home interface defines the finder method, then the return type is the remote interface (or a collection of remote interfaces). Similarly, if the local home interface defines the finder method, the return type is the local interface (or a collection). For example, the `LocalPlayerHome` interface of the `PlayerBean` entity bean defines the `findall` method:

>     public Collection findAll() throws FinderException;

> The EJB QL query of the `findall` method returns a collection of `LocalPlayer` interface types:

>     SELECT OBJECT(p)
>     FROM Player p

> For select method queries (except for aggregate function queries), the return type of the `SELECT` clause can be one of the following:

> - The abstract schema of the entity bean that contains the select method.
> - The abstract schema of a related entity bean. (By default, each of these abstract schema types maps to the local interface of the entity bean. Although it is uncommon, in the deployment descriptor you can override the default mapping by specifying a remote interface.)
> - A persistent field.

> The `PlayerBean` entity bean, for example, implements the `ejbSelectSports` method, which returns a collection of `String` objects for `sport`. The `sport` is a persistent field of the `LeagueBean` entity bean. See Example 11 .

> A `SELECT` clause cannot specify a collection-valued expression. For example, the `SELECT` clause `p.teams` is invalid because `teams` is a collection. However, the clause in the following query is valid because the `t` is a single element of the `teams` collection:

>     SELECT t
>     FROM Player p, IN (p.teams) AS t

> For select method queries with an aggregate function (`AVG`, `COUNT`, `MAX`, `MIN`, or `SUM`) in the `SELECT` clause, the following rules apply:

> - The select method must return a single object, primitive, or wrapper type that is compatible with the standard JDBC conversion mappings for the persistent field type.
> - For the `AVG`, `MAX`, `MIN`, and `SUM` functions, if the select method return type is an object and the function returns no values, then the select method returns `null`. In this case, if the select method return type is a primitive, then the container throws the `ObjectNotFoundException`.
> - For the `COUNT` function, the result of the select method must be an exact numeric type. If the function returns no values, the select method returns 0.

> #### DISTINCT and OBJECT Keywords

> The `DISTINCT` keyword eliminates duplicate return values. If the method of the query returns a `java.util.Collection`--which allows duplicates--then you must specify the `DISTINCT` keyword to eliminate duplicates. However, if the method returns a `java.util.Set`, the `DISTINCT` keyword is redundant because a `java.util.Set` cannot contain duplicates.

> The `OBJECT` keyword must precede a stand-alone identification variable, but it must not precede a single-valued path expression. If an identification variable is part of a single-valued path expression, it is not stand-alone.

> #### Aggregate Functions

> The `SELECT` clause can contain an aggregate function with the following syntax:

>     aggregate_select_expression ::=
>         {AVG |MAX |MIN |SUM |COUNT }( [DISTINCT ]
>         cmp_path_expression) |
>         COUNT ( [DISTINCT ] identification_variable |
>         single_valued_cmr_path_expression)

> Except for the `COUNT` function, the path expression argument for an aggregate function must terminate in a persistent field. For the `COUNT` function, the path expression argument can terminate in a persistent field, a relationship field, or an identification variable.

> The arguments of the `SUM` and `AVG` functions must be numeric. The arguments of the `MAX` and `MIN` functions must be orderable: numeric, string, character, or date.

> If the argument is empty, the `COUNT` function returns 0 and the other aggregate functions return `NULL`.

> If the `DISTINCT` keyword is specified, duplicate values are eliminated before the aggregate function is applied. `NULL` values are always eliminated before the function is applied, whether or not the `DISTINCT` keyword is used.

> ### ORDER BY Clause

> As its name suggests, the `ORDER BY` clause orders the values or objects returned by the query. The syntax of the clause follows:

>     orderby_clause ::= ORDER BY orderby_item [, orderby_item]*

>     orderby_item ::= cmp_path_expression [ASC |DESC ]

> If the `ORDER BY` clause contains multiple `orderby_item` elements, the left-to-right sequence of the elements determines the high-to-low precedence.

> The `ASC` keyword specifies ascending order (the default), and the `DESC` keyword indicates descending order.

> If the `ORDER BY` clause is used, then the `SELECT` clause must be one of the following:

> - An identification variable `x`, denoted as `OBJECT(x)`
> - A `single_valued_cmr_path_expression`
> - A `cmp_path_expression`

> If the `SELECT` clause is an identification variable or a `single_valued_cmr_path_expression`, then the `orderby_item` must be an orderable persistent field of the entity bean returned by the `SELECT` clause. If the `SELECT` clause is a `cmp_path_expression`, then the `cmp_path_expression` and the `orderby_item` must evaluate to the same persistent field of the same entity bean.

Download PDF Home History |  | API Search Feedback FAQ

All of the material in The J2EE(TM) 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.