Configuring Queries for 1.1 Finders

The following topics are addressed here:

• About JDOQL Queries

• Query Filter Expression

• Query Parameters

• Query Variables

• JDOQL Examples

About JDOQL Queries

The Enterprise JavaBeans Specification, v1.1 does not specify the format of the finder method description. The GlassFish Server uses an extension of Java Data Objects Query Language (JDOQL) queries to implement finder and selector methods. You can specify the following elements of the underlying JDOQL query:

• Filter expression - A Java-like expression that specifies a condition that each object returned by the query must satisfy. Corresponds to the WHERE clause in EJB QL.

• Query parameter declaration - Specifies the name and the type of one or more query input parameters. Follows the syntax for formal parameters in the Java language.

• Query variable declaration - Specifies the name and type of one or more query variables. Follows the syntax for local variables in the Java language. A query filter might use query variables to implement joins.

• Query ordering declaration - Specifies the ordering expression of the query. Corresponds to the ORDER BY clause of EJB QL.

The GlassFish Server specific deployment descriptor (glassfish-ejb-jar.xml) provides the following elements to store the EJB 1.1 finder method settings:

query-filter
query-params
query-variables
query-ordering

The bean developer uses these elements to construct a query. When the finder method that uses these elements executes, the values of these elements are used to execute a query in the database. The objects from the JDOQL query result set are converted into primary key instances to be returned by the EJB 1.1 ejbFind method.

The JDO specification, JSR 12, provides a comprehensive description of JDOQL. The following information summarizes the elements used to define EJB 1.1 finders.

Query Filter Expression

The filter expression is a String containing a Boolean expression evaluated for each instance of the candidate class. If the filter is not specified, it defaults to true. Rules for constructing valid expressions follow the Java language, with the following differences:

• Equality and ordering comparisons between primitives and instances of wrapper classes are valid.

• Equality and ordering comparisons of Date fields and Date parameters are valid.

• Equality and ordering comparisons of String fields and String parameters are valid.

• White space (non-printing characters space, tab, carriage return, and line feed) is a separator and is otherwise ignored.

• The following assignment operators are not supported.

  • Comparison operators such as =, +=, and so on

  • Pre- and post-increment

  • Pre- and post-decrement

• Methods, including object construction, are not supported, except for these methods.

  Collection.contains(Object o)
  Collection.isEmpty()
  String.startsWith(String s)
  String.endsWith(String e)

  In addition, the GlassFish Server supports the following nonstandard JDOQL methods.

  String.like(String pattern)
  String.like(String pattern, char escape)
  String.substring(int start, int length)
  String.indexOf(String str)
  String.indexOf(String str, int start)
  String.length()
  Math.abs(numeric n)
  Math.sqrt(double d)

• Navigation through a null-valued field, which throws a NullPointerException, is treated as if the sub-expression returned false.

The following expressions are supported.

• Relational operators (==, !=, >, <, >=, <=)

• Boolean operators (&, &&, |, ||, ~, !)

• Arithmetic operators (+, -, *, /)

• String concatenation, only for String + String

• Parentheses to explicitly mark operator precedence

• Cast operator

• Promotion of numeric operands for comparisons and arithmetic operations

The rules for promotion follow the Java rules extended by BigDecimal, BigInteger, and numeric wrapper classes. See the numeric promotions of the Java language specification.

Query Parameters

The parameter declaration is a String containing one or more parameter type declarations separated by commas. This follows the Java syntax for method signatures.

Query Variables

The type declarations follow the Java syntax for local variable declarations.

JDOQL Examples

This section provides a few query examples.

Example 1

The following query returns all players called Michael. It defines a filter that compares the name field with a string literal:

name == "Michael"

The finder element of the glassfish-ejb-jar.xml file looks like this:

<finder>
   <method-name>findPlayerByName</method-name>
   <query-filter>name == "Michael"</query-filter>
</finder>

Example 2

This query returns all products in a specified price range. It defines two query parameters which are the lower and upper bound for the price: double low, double high. The filter compares the query parameters with the price field:

low < price && price < high

Query ordering is set to price ascending.

The finder element of the glassfish-ejb-jar.xml file looks like this:

<finder>
   <method-name>findInRange</method-name>
   <query-params>double low, double high</query-params>
   <query-filter>low &lt; price &amp;&amp; price &lt high</query-filter>
   <query-ordering>price ascending</query-ordering>
</finder>

Example 3

This query returns all players having a higher salary than the player with the specified name. It defines a query parameter for the name java.lang.String name. Furthermore, it defines a variable to which the player’s salary is compared. It has the type of the persistence capable class that corresponds to the bean:

    mypackage.PlayerEJB_170160966_JDOState player

The filter compares the salary of the current player denoted by the this keyword with the salary of the player with the specified name:

    (this.salary > player.salary) && (player.name == name)

The finder element of the glassfish-ejb-jar.xml file looks like this:

<finder>
   <method-name>findByHigherSalary</method-name>
   <query-params>java.lang.String name</query-params>
   <query-filter>
      (this.salary &gt; player.salary) &amp;&amp; (player.name == name)
   </query-filter>
   <query-variables>
      mypackage.PlayerEJB_170160966_JDOState player
   </query-variables>
</finder>