cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Cayenne Documentation > Expression Factory Utilities
Date Sun, 10 Jan 2010 13:08:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=CAYDOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/CAYDOC/Expression+Factory+Utilities">Expression
Factory Utilities</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~andrus">Andrus
Adamchik</a>
    </h4>
     
          <br/>
     <div class="notificationGreySide">
         <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"
rel="nofollow">ExpressionFactory</a> and <a href="http://cayenne.apache.org/doc/api/org/apache/cayenne/exp/Expression.html"
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="/confluence/display/CAYDOC/Path+Expressions" 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="/confluence/display/CAYDOC/Path+Expressions" 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>


     </div>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>

       <a href="http://cwiki.apache.org/confluence/display/CAYDOC/Expression+Factory+Utilities">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=10554&revisedVersion=8&originalVersion=7">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/CAYDOC/Expression+Factory+Utilities?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message