(available since 3.0 in both classic and JPA modes; as of June 2007 only a subset of EJBQL syntax is supported)

EJBQL is an object query language that is not unlike SQL, only it operates in terms of the Java object model. In fact "EJB" in its name is entirely misleading - the language is applicable in the non-"enterprise" environments just as well. Standard EJBQL syntax is specified in the JPA specification, still Cayenne supports it in a classic mode, and no JPA runtime is required to execute such queries. This chapter deals specifically with classic mode operation.

EJBQL Syntax

Details of the syntax are available in various JPA literature. Here is an example of an EJBQL query:

select p from Painting p WHERE p.estimatedPrice > 3000

Visually it looks like SQL, only instead of tables, object entities are used; and instead of columns and joins, path expressions are used (not unlike Cayenne path expressions).

(TODO: more examples)

Creating an EJBQLQuery

Creating an EJBQLQuery is simple - just pass a valid EJBQL string to the constructor:

EJBQLQuery query = new EJBQLQuery("select a FROM Artist a");

Further you can use the query object the same way as any other Cayenne query to select objects or to modify the database.

Select objects:

List artists = context.performQuery(query);

EJBQLQuery vs. SelectQuery

TODO: general comparison

Aside from noted different capabilities, EJBQLQuery and SelectQuery differ in some areas where they provide similar functionality. These differences are caused by the need for EJBQL syntax to follow the official specification, so it can't work "the Cayenne way":

  • Null Handling: SelectQuery would translate the expressions matching NULL values to the corresponding "X IS NULL" or "X IS NOT NULL" SQL syntax. EJBQLQuery on the other hand requires explicit "IS NULL" (or "IS NOT NULL") syntax to be used, otherwise the generated SQL will look like "X = NULL" (or "X <> NULL"), which will evaluate differently.
  • Expression Parameters: SelectQuery uses "$" to denote named parameters (e.g. "$myParam"), while EJBQL uses ":" (e.g. ":myParam"). Also EJBQL supports positional parameters denoted by the question mark: "?3".

EJBQLQuery vs. SQLTemplate

TODO: general comparison

  • Null Handling: