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 > Path Expressions
Date Wed, 13 Jan 2010 10:18: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/Path+Expressions">Path
Expressions</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~ari">Ari
Maniatis</a>
    </h4>
     clarifying joins
          <div id="versionComment" class="noteMacro" style="display:none; padding: 5px;">
     clarifying joins<br />
     </div>
          <br/>
     <div class="notificationGreySide">
         <p>Before we start discussing how to build expressions, it is important to
understand one group of expressions widely used in Cayenne: <em>path expressions</em>.
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:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>[db:]segment[+][.segment[+]...]</pre>
</div></div>

<ul>
	<li>"db:" an optional prefix indicating the the following path is a DB path.</li>
	<li>"segment" - a name of a relationship or an attribute in the path. Path must have
at least one segment; segments are separated by dot (".").</li>
	<li>"+" - 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.</li>
</ul>


<h3><a name="PathExpressions-ObjectPathExpressions"></a>Object Path Expressions</h3>
<p>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:</p>

<ul>
	<li><tt>paintingTitle</tt> Can be used to navigate to the value of "paintingTitle"
property of the Painting class.</li>
	<li><tt>toArtist.exhibitArray.closingDate</tt> 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".</li>
	<li><tt>toArtist.exhibitArray+.closingDate</tt> 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".</li>
</ul>


<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>What Does
'navigation' Means</b><br />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.</td></tr></table></div>

<h3><a name="PathExpressions-DatabasePathExpressions"></a>Database Path
Expressions</h3>
<p>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:</p>

<ul>
	<li><tt>db:PAINTING_TITLE</tt> Can be used to match the value of "PAINTING_TITLE"
column of a PAINTING table.</li>
	<li><tt>db:toArtist.artistExhibitArray.toExhibit.CLOSING_DATE</tt> Can
be used to match a closing date of any of the exhibits of a related artist record.</li>
</ul>


<p>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.</p>

<h3><a name="PathExpressions-AliasesinPathExpressions"></a>Aliases in Path
Expressions</h3>

<p>Cayenne supports "aliases" in path Expressions. E.g. the same expression can be written
using explicit path or an alias:</p>

<ul>
	<li>Full path: <tt>toArtist.exhibitArray.closingDate</tt></li>
	<li>Using alias "e": <tt>e.closingDate</tt></li>
</ul>


<p>SelectQuery using the second form of the path expression must be made aware of the
alias via <tt>"SelectQuery.aliasPathSplits(..)"</tt>, otherwise an Exception will
be thrown. The main use of aliases is to allow users to control how SQL joins are generated
if the same path is encountered more than once in any given Expression. Each alias for any
given path would result in a separate join. Without aliases, a single join will be used for
a group of matching paths.</p>

<h3><a name="PathExpressions-MatchingPathExpressions"></a>Matching Path
Expressions</h3>

<p>As described in the following chapters a path expression is usually matched against
some value (see for example <a href="/confluence/display/CAYDOC/Expression+Factory+Utilities"
title="Expression Factory Utilities">ExpressionFactory API</a> - the first argument
to each method is a path, and a second - an object value that is matched against the path).
A type of such value must be compatible with the type of the property pointed to by the path.
E.g. <tt>toArtist.artistName</tt> can only be matched against a <tt>String</tt>,
and <tt>toArtist</tt> - against instances of <tt>Artist</tt>.</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/Path+Expressions">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=10663&revisedVersion=8&originalVersion=7">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/CAYDOC/Path+Expressions?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message