Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Developer's Guide

- Previous: Configuring the CMP Resource
- Next: Performance-Related Features

# Configuring Queries for 1.1 Finders

This section contains the following topics:

- About JDOQL Queries

- Query Filter Expression

- Query Parameters

- Query Variables

- JDOQL Examples

## About JDOQL Queries

The Enterprise JavaBeans Specification, v1.1 spec does not specify the format of the finder method description. The Application Server uses an extension of Java Data Objects Query Language (JDOQL) queries to implement finder and selector methods. (For EJB 2.0 and later, the container automatically maps an EJB QL query to JDOQL.) 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 Application Server specific deployment descriptor (`sun-ejb-jar.xml`) provides the following elements to store the EJB 1.1 finder method settings:

`query-filterquery-paramsquery-variablesquery-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 (see 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:

  - =, +=, etc.

  - pre- and post-increment

  - pre- and post-decrement

- Methods, including object construction, are not supported, except for:

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

  In addition, the Application 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`.

Note –

Comparisons between floating point values are by nature inexact. Therefore, equality comparisons (== and !=) with floating point values should be used with caution. Identifiers in the expression are considered to be in the name space of the candidate class, with the addition of declared parameters and variables. As in the Java language, `this` is a reserved word, and refers to the current instance being evaluated.

The following expressions are supported:

- Operators applied to all types where they are defined in the Java language:

  - relational operators (==, !=, >, <, >=, <=)

  - boolean operators (&, &&, |, ||, ~, !)

  - arithmetic operators (+, -, *, /)

  String concatenation is supported 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 (see the numeric promotions of the Java language specification) extended by BigDecimal, BigInteger, and numeric wrapper classes.

## 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 `sun-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 `sun-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 `sun-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>

- Previous: Configuring the CMP Resource
- Next: Performance-Related Features

- © 2010, Oracle Corporation and/or its affiliates