docs/2.0/expression-factory-utilities.html

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://incubator.apache.org/cayenne/2_0/api/cayenne/org/apache/cayenne/exp/ExpressionFactory.html" class="external-link" rel="nofollow">ExpressionFactory</A> and <A href="http://incubator.apache.org/cayenne/2_0/api/cayenne/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 &quot;path/value&quot; 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>public static Expression <B>matchDbExp</B>(String pathSpec, Object value)</LI>
	<LI>public static Expression <B>lessExp</B>(String pathSpec, Object value)</LI>
	<LI>public static Expression <B>lessOrEqualExp</B>(String pathSpec, Object value)</LI>
	<LI>public static Expression <B>greaterExp</B>(String pathSpec, Object value)</LI>
	<LI>public static Expression <B>greaterOrEqualExp</B>(String pathSpec, Object value)</LI>
	<LI>public static Expression <B>inExp</B>(String pathSpec, Object[] values)</LI>
	<LI>public static Expression <B>inExp</B>(String pathSpec, java.util.List values)</LI>
	<LI>public static Expression <B>betweenExp</B>(String pathSpec, Object value1, Object value2)</LI>
	<LI>public static Expression <B>likeExp</B>(String pathSpec, Object value)</LI>
	<LI>public static Expression <B>likeIgnoreCaseExp</B>(String pathSpec, Object value)</LI>
	<LI>public static Expression <B>notInExp</B>(String pathSpec, Object value)</LI>
	<LI>public static Expression <B>notBetweenExp</B>(String pathSpec, Object value)</LI>
	<LI>public static Expression <B>notLikeExp</B>(String pathSpec, Object value)</LI>
	<LI>public static Expression <B>notLikeIgnoreCaseExp</B>(String pathSpec, Object value)</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 DataObjects, thus removing the need to know PK or FK values 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">&quot;toArtist&quot;</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">&quot;D&quot;</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">&quot;dateOfBirth&quot;</SPAN>, <SPAN class="code-keyword">new</SPAN> Date());

<SPAN class="code-comment">// 1. chain expressions, note the assignment back to <SPAN class="code-quote">&quot;qual&quot;</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">&quot;dateOfBirth&quot;</SPAN>, <SPAN class="code-keyword">null</SPAN>));

<SPAN class="code-comment">// 2. <SPAN class="code-quote">&quot;AND&quot;</SPAN> applies to a combined earlier criteria
</SPAN>qual =
   qual.andExp(ExpressionFactory.likeIgnoreCaseExp(<SPAN class="code-quote">&quot;artistName&quot;</SPAN>, <SPAN class="code-quote">&quot;D%&quot;</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 &quot;path&quot; 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">HashMap map = <SPAN class="code-keyword">new</SPAN> HashMap();
map.put(<SPAN class="code-quote">&quot;login&quot;</SPAN>, <SPAN class="code-quote">&quot;joeuser&quot;</SPAN>);
map.put(<SPAN class="code-quote">&quot;password&quot;</SPAN>, <SPAN class="code-quote">&quot;secret&quot;</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>