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. General form of path expressions is the following:

[db:]segment[+][.segment[+]...]
  • "db:" an optional prefix indicating the the following path is a DB path.
  • "segment" - a name of a relationship or an attribute in the path. Path must have at least one segment; segments are separated by dot (".").
  • "+" - LEFT OUTER JOIN indicator: a plus sign at the end of a segment name indicates that when a JOIN is created for the path, it will be a LEFT OUTER JOIN.

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. When used in a query, it means "find all paintings by any artist who has an exhibition closing on date x".
  • toArtist.exhibitArray+.closingDate When used in a query, artists who have a NULL relation to exhibits (that is, who have no exhibits) will not be excluded from the query. So, "find all paintings by any artist who has an exhibition closing on date x, and also find all paintings by artists with no exhibitions".
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:

  • db:PAINTING_TITLE Can be used to match the value of "PAINTING_TITLE" column of a PAINTING table.
  • db: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. Although there are a few cases when their explicit use is justified.

Aliases in Path Expressions

When Cayenne is performing a database query which uses more than one path expression with common elements, those expressions will be merged automatically. This improves database query speed and simplifies the SQL, but when your path expression is one-to-many it may not give you what you expect.

Expression e1 = ExpressionFactory.like("toArtist.exhibitArray.title", "foo");
Expression e2 = ExpressionFactory.like("toArtist.exhibitArray.title", "bar");
Expression e = e1.andExp(e2);
q = new SelectQuery(Painting.class, e);

This will always give you no results because the query will look for exhibits which are titled 'foo' AND 'bar'. Of course there is no exhibit which has both names.

Cayenne supports "aliases" in path Expressions to solve this.

Expression e1 = ExpressionFactory.like("exhibitAlias1.title", "foo");
Expression e2 = ExpressionFactory.like("exhibitAlias2.title", "bar");
Expression e = e1.andExp(e2);
q = new SelectQuery(Painting.class, e);
q.aliasPathSplits("toArtist.exhibitArray.title", "exhibitAlias1", "exhibitAlias2");

That last command tells the select query how to interpret the alias. Because the aliases are different, the SQL generated will have two completely separate set of joins. In other words you will "find all paintings by any artist who has at least one exhibition titled 'foo' and at least one exhibition titled 'bar'". This is called a "split path".

Using Path Expressions

On their own path expressions are just strings. You'll want to create an Expression to do something useful.