10.7. Query Extensions
Prev | Chapter 10. JDO Runtime Extensions | Next

## 10.7. Query Extensions

JDOQL is a powerful, easy-to-use query language, but you may occasionally find it limiting in some way. To circumvent the limitations of JDOQL, Kodo provides alternatives and extensions to standard JDO queries. This section discusses JDOQL query extensions. For a discussion of subqueries, direct SQL queries and custom query execution, see Chapter 13, Enterprise Edition.

### 10.7.1. JDOQL Extensions

JDOQL extensions are custom methods that you can use in your query filter, having, ordering, and result strings. Kodo JDO provides some built-in JDOQL extensions, and you can develop your own custom extensions as needed. You can optionally preface all JDOQL extensions with `ext:` in your JDOQL query. For example, the following example uses a hypothetical `firstThreeChars` extension to search for cities whose name begins with the 3 characters 'H', 'a', 'r'.

Example 10.1. Basic JDOQL Extension

    Query query = pm.newQuery (City.class);
    queryq.setFilter ("name.ext:firstThreeChars () == 'Har')");
    Collection results = (Collection) query.execute ();

Note that it is perfectly OK to chain together extensions. For example, let's modify our search above to be case-insensitive using another hypothetical extension, `equalsIgnoreCase`:

Example 10.2. Chaining JDOQL Extensions

    Query query = pm.newQuery (City.class);
    query.setFilter ("name.ext:firstThreeChars ().ext:equalsIgnoreCase ('Har')");
    Collection c = (Collection) query.execute ();

Finally, when using JDOQL extensions you must be aware that any SQL-specific extensions can only execute against the database, and cannot be used for in-memory queries (recall that JDO executes queries in-memory when you supply a candidate collection rather than an extent/class, or when you set the `IgnoreCache` and `FlushBeforeQueries` properties to `false` and you execute a query within a transaction in which you've modified some persistent objects).

#### 10.7.1.1. Included JDOQL Extensions

Kodo includes two default JDOQL extensions to enhance the power of JDOQL. Note that Kodo natively supports all of the JDOQL methods defined in the JDO 2 early draft specification, so those methods are not listed here as extensions. See Chapter 11, Query for a primer on JDO 2 queries.

- `getColumn`: Places the proper alias for the given column name into the SELECT statement that is issued. This filter cannot be used for in-memory queries. When traversing relations, the column is assumed to be in the primary table of the related type. To get a column of the candidate class, use `this` as the extension target, as shown in the second example below.

      query.setFilter ("company.address.ext:getColumn ('JDOIDX') == 5");
      query.setFilter ("this.ext:getColumn ('LEGACY_DATA') == 'foo'");

- `sql`: Embeds the given SQL argument into the SELECT statement that is issued. This filter cannot be used for in-memory queries.

      query.setFilter ("price < ext:sql ('(SELECT AVG(PRICE) FROM PRODUCTS)')");

  This extension replaces `sqlVal` and `sqlExp`, which are now deprecated.

#### 10.7.1.2. Developing Custom JDOQL Extensions

You can write your own extensions by implementing the `kodo.jdbc.query.JDBCFilterListener` interface. View the Javadoc documentation for details. Additionally, the source for all of Kodo's built-in query extensions is included in your Kodo download to get you started. The built-in extensions reside in the `kodo.query` and `kodo.jdbc.query` packages.

#### 10.7.1.3. Configuring JDOQL Extensions

There are two ways to register your custom JDOQL extensions with Kodo:

- Registration by properties: You can register custom JDOQL extensions by setting the `kodo.FilterListeners` configuration property to a comma-separated list of plugin strings describing your extensions classes. Extensions registered in this fashion must be able to be instantiated via reflection (they must have a public no-args constructor). They must also be thread safe, because they will be shared across all queries.

- Per-query registration: You can register JDOQL extensions for an individual query through the `KodoQuery.addFilterListener` method. You might use per-query registration for very specific extensions that do not apply globally.

### 10.7.2. Aggregate Extensions

Just as you can write your own JDOQL methods, you can write your own query aggregates by implementing the `kodo.jdbc.query.JDBCAggregateListener` interface. View the Javadoc documentation for details. When using your custom aggregates in result or having strings, you can optinally prefix the function name with `ext:` to identify it as an extension.

#### 10.7.2.1. Configuring Query Aggregates

There are two ways to register your custom query aggregates with Kodo:

- Registration by properties: You can register custom query aggregates by setting the `kodo.AggregateListeners` configuration property to a comma-separated list of plugin strings describing your aggregate implementation. Aggregates registered in this fashion must be able to be instantiated via reflection (they must have a public no-args constructor). They must also be thread safe, because they will be shared across all queries.

- Per-query registration: You can register query aggregates for an individual query through the `KodoQuery.addAggregateListener` method. You might use per-query registration for very specific aggregates that do not apply globally.

Prev | Up | Next
10.6. KodoHelper | Home | 10.8. Object Locking