Before we start discussing how to build expressions, it is important to understand one group of expressions widely used in Cayenne: path expressions. There are two types of path expressions: object path used to navigate graphs of Java objects that follow Java Bean property naming conventions and database path used to navigate the database schema.

Object Path Expressions

An Object Path Expression is a property navigation path. Such path is represented by a String made of dot-separated names of properties of a Java Bean class. E.g. a path expression "toArtist.artistName" is a valid property path for a Painting class, pointing to the name of the Artist who created a given Painting. A few more examples:

  • paintingTitle
    Can be used to navigate to the value of "paintingTitle" property of the Painting class.
  • toArtist.exhibitArray.closingDate
    Can be used to navigate to a closing date of any of the exhibits of a Painting's Artist object.
What Does 'navigation' Means
The term "navigation" in the description above could mean different things depending on the context. For instance, when evaluating an expression in memory, "navigating" an object path would simply return the value of a corresponding object property. When the same expression is used in a select query qualifier, it resolves to the name of a table column used in a WHERE clause of a generated SQL statement.

Database Path Expressions

Database Path Expressions provide an easy way to navigate through DB table joins. Instead of complex join semantics such expressions utilize the names of DbRelationships defined in Cayenne DataMap. Translating the above object path examples into the DB realm, database path expressions might look like this:

    Can be used to match the value of "PAINTING_TITLE" column of a PAINTING table.
  • toArtist.artistExhibitArray.toExhibit.CLOSING_DATE
    Can be used to match a closing date of any of the exhibits of a related artist record.

Though database path expressions are widely used by Cayenne framework internally, they are rarely used in applications. There are only a few cases when their explicit use is justified.

Matching Path Expressions

As described in the following chapters a path expression is usually matched against some value (see for example ExpressionFactory API - the first argument to each method is a path, and a second - an Object value that is matched against the path). Such value type must be compatible with the type of the property pointed to by the path. E.g. toArtist.artistName can only be matched against a String, and toArtist - against instances of Artist.