| Title: Expression Factory Utilities |
| |
| <P>Sometimes there is a need to build an expression by combining other existing expressions. Also quiet often it is desirable to use strongly typed API instead of interpreted string expressions. The following sections describe <A href="http://cayenne.apache.org/doc/api/org/apache/cayenne/exp/ExpressionFactory.html" class="external-link" rel="nofollow">ExpressionFactory</A> and <A href="http://cayenne.apache.org/doc/api/org/apache/cayenne/exp/Expression.html" class="external-link" rel="nofollow">Expression</A> methods that allow to construct expressions step by step via API calls.</P> |
| |
| <H3><A name="ExpressionFactoryUtilities-Path%2FValueExpressions"></A>Path/Value Expressions</H3> |
| |
| <P>The most simple expressions are the ones that match an object property path with a value or a list of values. ExpressionFactory provides a set of methods to build such "path/value" expressions:</P> |
| <UL> |
| <LI>public static Expression <B>matchExp</B>(String pathSpec, Object value)</LI> |
| <LI>public static Expression <B>noMatchExp</B>(String pathSpec, Object value),</LI> |
| <LI>etc.. <EM>(check JavaDocs of ExpressionFactory for all available factory methods)</EM></LI> |
| </UL> |
| |
| |
| <P>As was mentioned <A href="path-expressions.html" title="Path Expressions">earlier</A>, the type of a second Object argument depends on the type of property path points to. It is important to mention that paths that end with a relationship name (both to-one and to-many) can be matched against Persistent objects, thus absolving you from the need to know a PK or FK when building expressions. This behavior is not specific to ExpressionFactory, it works the same way with Expression.fromString(..) as well.</P> |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-java"> |
| <SPAN class="code-keyword">import</SPAN> org.apache.cayenne.exp.Expression; |
| <SPAN class="code-keyword">import</SPAN> org.apache.cayenne.exp.ExpressionFactory; |
| <SPAN class="code-keyword">import</SPAN> org.apache.cayenne.query.SelectQuery; |
| ... |
| |
| <SPAN class="code-comment">// find artist paintings (<SPAN class="code-keyword">if</SPAN> we don't want to use relationship <SPAN class="code-keyword">for</SPAN> whatever reason) |
| </SPAN> |
| Artist a = ...; |
| Expression qual = ExpressionFactory.matchExp(<SPAN class="code-quote">"toArtist"</SPAN>, a); |
| SelectQuery select = <SPAN class="code-keyword">new</SPAN> SelectQuery(Painting.class, qual);</PRE> |
| </DIV></DIV> |
| |
| <H3><A name="ExpressionFactoryUtilities-ChainingExpressions"></A>Chaining Expressions</H3> |
| |
| <P>Expression class itself provides a set of convenience methods to chain expressions as they are built from smaller parts. Note that each of these methods does not modify the original expression, rather it builds and returns a new instance of the expression.</P> |
| <UL> |
| <LI>public Expression <B>joinExp</B>(int type, Expression exp)<BR> |
| Creates and returns a new expression that joins this object with another expression, using specified join type. This is a shorter equivalent of ExpressionFactory.binaryExpression(type, this, exp).</LI> |
| <LI>public Expression <B>andExp</B>(Expression exp)<BR> |
| A shorter equivalent for joinExp(Expression.AND, exp).</LI> |
| <LI>public Expression <B>orExp</B>(Expression exp)<BR> |
| A shorter equivalent for joinExp(Expression.OR, exp).</LI> |
| </UL> |
| |
| |
| <P>Example of using chaining:</P> |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-java"> |
| <SPAN class="code-keyword">import</SPAN> org.apache.cayenne.exp.Expression; |
| <SPAN class="code-keyword">import</SPAN> org.apache.cayenne.exp.ExpressionFactory; |
| <SPAN class="code-keyword">import</SPAN> org.apache.cayenne.query.SelectQuery; |
| ... |
| |
| <SPAN class="code-comment">// find artists whose name starts with <SPAN class="code-quote">"D"</SPAN> |
| </SPAN><SPAN class="code-comment">// with invalid or <SPAN class="code-keyword">null</SPAN> date of birth |
| </SPAN> |
| Expression qual = ExpressionFactory.greaterOrEqualExp(<SPAN class="code-quote">"dateOfBirth"</SPAN>, <SPAN class="code-keyword">new</SPAN> Date()); |
| |
| <SPAN class="code-comment">// 1. chain expressions, note the assignment back to <SPAN class="code-quote">"qual"</SPAN>, |
| </SPAN><SPAN class="code-comment">// since a <SPAN class="code-keyword">new</SPAN> instance is created |
| </SPAN>qual = qual.orExp(ExpressionFactory.matchExp(<SPAN class="code-quote">"dateOfBirth"</SPAN>, <SPAN class="code-keyword">null</SPAN>)); |
| |
| <SPAN class="code-comment">// 2. <SPAN class="code-quote">"AND"</SPAN> applies to a combined earlier criteria |
| </SPAN>qual = |
| qual.andExp(ExpressionFactory.likeIgnoreCaseExp(<SPAN class="code-quote">"artistName"</SPAN>, <SPAN class="code-quote">"D%"</SPAN>)); |
| |
| SelectQuery select = <SPAN class="code-keyword">new</SPAN> SelectQuery(Artist.class, qual); |
| </PRE> |
| </DIV></DIV> |
| |
| <H3><A name="ExpressionFactoryUtilities-CreatingComplexExpressions"></A>Creating Complex Expressions</H3> |
| |
| <P>There is a way to create complex expressions either from the Lists of expressions or from the Maps containing values using "path" Strings as keys. This approach significantly simplifies connecting Cayenne queries to the UI, and reduces the number of steps needed to create expressions in other cases. ExpressionFactory provides the following methods:</P> |
| <UL> |
| <LI>public static Expression <B>joinExp</B>(int type, java.util.List expressions)<BR> |
| Joins all expressions into a single expression. type is used as an expression type for expressions joining each one of the items on the list. type is normally AND or OR.</LI> |
| <LI>public static Expression <B>matchAllExp</B>(java.util.Map map, int type)<BR> |
| Creates an expression that matches all path/value pairs in map. Path is OBJ_PATH.</LI> |
| <LI>public static Expression <B>matchAllDbExp</B>(java.util.Map map, int type)<BR> |
| Same as above, but path is interpreted to be DB_PATH.</LI> |
| <LI>public static Expression <B>matchAnyExp</B>(java.util.Map map, int type)<BR> |
| Creates an expression that matches any of the path/value pairs in map. Path is OBJ_PATH.</LI> |
| <LI>public static Expression <B>matchAnyDbExp</B>(java.util.Map map, int type)<BR> |
| Same as above, but path is interpreted to be DB_PATH.</LI> |
| </UL> |
| |
| |
| <P>Example of creating complex expressions:</P> |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-java">Map map = <SPAN class="code-keyword">new</SPAN> HashMap(); |
| map.put(<SPAN class="code-quote">"login"</SPAN>, <SPAN class="code-quote">"joeuser"</SPAN>); |
| map.put(<SPAN class="code-quote">"password"</SPAN>, <SPAN class="code-quote">"secret"</SPAN>); |
| |
| <SPAN class="code-comment">// the last parameter refers to the operation inside each key/value pair. |
| </SPAN> |
| Expression qual = ExpressionFactory.matchAllExp(map, Expression.EQUAL_TO);</PRE> |
| </DIV></DIV> |
| |
| <H3><A name="ExpressionFactoryUtilities-SplitExpressionswith%7B%7BmatchAllExp%28%29%7D%7D"></A>Split Expressions with <TT>matchAllExp()</TT></H3> |
| |
| <P>As <A href="path-expressions.html" title="Path Expressions">discussed</A> earlier, Cayenne supports "aliases" in path Expressions, allowing to control how SQL joins are generated if the same path is encountered more than once in the same Expression. Two ExpressionFactory methods allow to implicitly generate aliases to "split" match paths into individual joins if needed:</P> |
| |
| <UL> |
| <LI>Expression <B>matchAllExp</B>(String path, Collection values)</LI> |
| <LI>Expression <B>matchAllExp</B>(String path, Object... values)</LI> |
| </UL> |
| |
| |
| <P>"Path" argument to both of these methods can use a split character (a pipe symbol '|') instead of dot to indicate that relationship following a path should be split into a separate set of joins, one per collection value. There can only be one split at most in any given path. Split must always precede a relationship. E.g. <TT>"|exhibits.paintings"</TT>, <TT>"exhibits|paintings"</TT>, etc. Internally Cayenne would generate distinct aliases for each of the split expressions, forcing separate joins.</P> |
| |
| |
