cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r843922 [2/5] - in /websites/staging/cayenne/trunk/content: ./ docs/3.1/cayenne-guide/ docs/3.1/cayenne-guide/css/ docs/3.1/tutorial/ docs/3.1/tutorial/css/
Date Wed, 26 Dec 2012 19:20:35 GMT
Modified: websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/expressions.html
==============================================================================
--- websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/expressions.html (original)
+++ websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/expressions.html Wed Dec 26 19:20:35 2012
@@ -1,73 +1,75 @@
 <html><head>
       <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>Chapter&nbsp;7.&nbsp;Expressions</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part2.html" title="Part&nbsp;II.&nbsp;Cayenne Framework"><link rel="prev" href="persistent-objects-objectcontext.html" title="Chapter&nbsp;6.&nbsp;Persistent Objects and ObjectContext"><link rel="next" href="orderings.html" title="Chapter&nbsp;8.&nbsp;Orderings"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;7.&nbsp;Expressions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="persistent-objects-objectcontext.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;II.&nbsp;Cayenne Framework</th><td width="20%" align="righ
 t">&nbsp;<a accesskey="n" href="orderings.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter&nbsp;7.&nbsp;Expressions"><div class="titlepage"><div><div><h2 class="title"><a name="expressions"></a>Chapter&nbsp;7.&nbsp;Expressions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="expressions.html#expressions-overview">Expressions Overview</a></span></dt><dt><span class="section"><a href="expressions.html#path-expressions">Path Expressions</a></span></dt><dt><span class="section"><a href="expressions.html#expressions-from-strings">Creating Expressions from Strings </a></span></dt><dt><span class="section"><a href="expressions.html#expressions-with-expressionfactory">Creating Expressions with API</a></span></dt><dt><span class="section"><a href="expressions.html#expressions-in-memory">Evaluating Expressions in Memory</a></span></dt></dl></div><div class="section" title="Expressions Overview"><d
 iv class="titlepage"><div><div><h2 class="title"><a name="expressions-overview"></a>Expressions Overview</h2></div></div></div><p>Cayenne provides a simple yet powerful object-based expression language. The most common
-			usese of expressions are to build qualifiers and orderings of queries that are later
-			converted to SQL by Cayenne and to evaluate in-memory against specific objects (to
-			access certain values in the object graph or to perform in-memory object filtering and
-			sorting). Cayenne provides API to build expressions in the code and a parser to create
-			expressions from strings.</p></div><div class="section" title="Path Expressions"><div class="titlepage"><div><div><h2 class="title"><a name="path-expressions"></a>Path Expressions</h2></div></div></div><p>Before 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 and database, used for navigating graphs of connected objects or
-			joined DB tables respectively. Object paths are much more commonly used, as after all
-			Cayenne is supposed to provide a degree of isolation of the object model from the
-			database. However database paths are helpful in certain situations. General structure of
-			path expressions is the following:</p><pre class="programlisting"> [db:]segment[+][.segment[+]...]</pre><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"db:" is an optional prefix indicating that the following path is a DB
-						path. Otherwise it is an object path.</p></li><li class="listitem"><p>"segment" is a name of a property (relationship or attribute in Cayenne
-						terms) in the path. Path must have at least one segment; segments are
-						separated by dot (".").</p></li><li class="listitem"><p>"+" An "OUTER JOIN" path component. Currently "+" only has effect when
-						translated to SQL as OUTER JOIN. When evaluating expressions in memory, it
-						is ignored.</p></li></ul></div><p>An object path expression represents a chain of property names rooted in a certain
-			(unspecified during expression creation) object and "navigating" to its related value.
-			E.g. a path expression "artist.name" might be a property path starting from a Painting
-			object, pointing to the related Artist object, and then to its name attribute. A few
-			more examples:</p><p>
-			</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"name" - can be used to navigate (read) the "name" property of a Person
-						(or any other type of object that has a "name" property).</p></li><li class="listitem"><p>"artist.exhibits.closingDate" - can be used to navigate to a closing date
-						of any of the exhibits of a Painting's Artist object.</p></li><li class="listitem"><p>"artist.exhibits+.closingDate" - same as the previous example, but when
-						translated into SQL, an OUTER JOIN will be used for "exhibits".</p></li></ul></div><p>
-		</p><p>Similarly a database path expression is a dot-separated path through DB table joins
-			and columns. In Cayenne joins are mapped as DbRelationships with some symbolic names
-			(the closest concept to DbRelationship name in the DB world is a named foreign key
-			constraint. But DbRelationship names are usually chosen arbitrarily, without regard to
-			constraints naming or even constraints presence). A database path therefore might look
-			like this -  "db:dbrelationshipX.dbrelationshipY.COLUMN_Z". More specific examples:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"db:NAME" - can be used to navigate to the value of "NAME" column of some
-						unspecified table.</p></li><li class="listitem"><p>"db:artist.artistExhibits.exhibit.CLOSING_DATE" - can be used to match a
-						closing date of any of the exhibits of a related artist record.</p></li></ul></div><p>Cayenne supports "aliases" in path Expressions. E.g. the same expression can be
-			written using explicit path or an alias:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"artist.exhibits.closingDate" - full path</p></li><li class="listitem"><p>"e.closingDate" - alias "e" is used for "artist.exhibits".</p></li></ul></div><p>SelectQuery using the second form of the path expression must be made
-			aware of the alias via <span class="italic">"SelectQuery.aliasPathSplits(..)"</span>, 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></div><div class="section" title="Creating Expressions from Strings"><div class="titlepage"><div><div><h2 class="title"><a name="expressions-from-strings"></a>Creating Expressions from Strings </h2></div></div></div><p>While in most cases users are likely to rely on API from the following section for
-			expression creation, we'll start by showing String expressions, as this will help
-			understanding the semantics. A Cayenne expression can be represented as a String, which
-			can be later converted to an expression object using <code class="code">Expression.fromString</code>
-			static method. Here is an
-			example:</p><pre class="programlisting">String expString = "name like 'A%' and price &lt; 1000";
+            usese of expressions are to build qualifiers and orderings of queries that are later
+            converted to SQL by Cayenne and to evaluate in-memory against specific objects (to
+            access certain values in the object graph or to perform in-memory object filtering and
+            sorting). Cayenne provides API to build expressions in the code and a parser to create
+            expressions from strings.</p></div><div class="section" title="Path Expressions"><div class="titlepage"><div><div><h2 class="title"><a name="path-expressions"></a>Path Expressions</h2></div></div></div><p>Before 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 and database, used for navigating graphs of connected objects or
+            joined DB tables respectively. Object paths are much more commonly used, as after all
+            Cayenne is supposed to provide a degree of isolation of the object model from the
+            database. However database paths are helpful in certain situations. General structure of
+            path expressions is the following:</p><pre class="programlisting"> [db:]segment[+][.segment[+]...]</pre><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"db:" is an optional prefix indicating that the following path is a DB
+                        path. Otherwise it is an object path.</p></li><li class="listitem"><p>"segment" is a name of a property (relationship or attribute in Cayenne
+                        terms) in the path. Path must have at least one segment; segments are
+                        separated by dot (".").</p></li><li class="listitem"><p>"+" An "OUTER JOIN" path component. Currently "+" only has effect when
+                        translated to SQL as OUTER JOIN. When evaluating expressions in memory, it
+                        is ignored.</p></li></ul></div><p>An object path expression represents a chain of property names rooted in a certain
+            (unspecified during expression creation) object and "navigating" to its related value.
+            E.g. a path expression "artist.name" might be a property path starting from a Painting
+            object, pointing to the related Artist object, and then to its name attribute. A few
+            more examples:</p><p>
+            </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"name" - can be used to navigate (read) the "name" property of a Person
+                        (or any other type of object that has a "name" property).</p></li><li class="listitem"><p>"artist.exhibits.closingDate" - can be used to navigate to a closing date
+                        of any of the exhibits of a Painting's Artist object.</p></li><li class="listitem"><p>"artist.exhibits+.closingDate" - same as the previous example, but when
+                        translated into SQL, an OUTER JOIN will be used for "exhibits".</p></li></ul></div><p>
+        </p><p>Similarly a database path expression is a dot-separated path through DB table joins
+            and columns. In Cayenne joins are mapped as DbRelationships with some symbolic names
+            (the closest concept to DbRelationship name in the DB world is a named foreign key
+            constraint. But DbRelationship names are usually chosen arbitrarily, without regard to
+            constraints naming or even constraints presence). A database path therefore might look
+            like this -  "db:dbrelationshipX.dbrelationshipY.COLUMN_Z". More specific examples:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"db:NAME" - can be used to navigate to the value of "NAME" column of some
+                        unspecified table.</p></li><li class="listitem"><p>"db:artist.artistExhibits.exhibit.CLOSING_DATE" - can be used to match a
+                        closing date of any of the exhibits of a related artist record.</p></li></ul></div><p>Cayenne supports "aliases" in path Expressions. E.g. the same expression can be
+            written using explicit path or an alias:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>"artist.exhibits.closingDate" - full path</p></li><li class="listitem"><p>"e.closingDate" - alias "e" is used for "artist.exhibits".</p></li></ul></div><p>SelectQuery using the second form of the path expression must be made
+            aware of the alias via <span class="italic">
+                "SelectQuery.aliasPathSplits(..)"</span>, 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></div><div class="section" title="Creating Expressions from Strings"><div class="titlepage"><div><div><h2 class="title"><a name="expressions-from-strings"></a>Creating Expressions from Strings </h2></div></div></div><p>While in most cases users are likely to rely on API from the following section for
+            expression creation, we'll start by showing String expressions, as this will help
+            understanding the semantics. A Cayenne expression can be represented as a String, which
+            can be later converted to an expression object using <code class="code">Expression.fromString</code>
+            static method. Here is an
+            example:</p><pre class="programlisting">String expString = "name like 'A%' and price &lt; 1000";
 Expression exp = Expression.fromString(expString);</pre><p>This
-			particular expression may be used to match Paintings with names that start with "A" and
-			a price less than $1000. While this example is pretty self-explanatory, there are a few
-			points worth mentioning. "name" and "price" here are object paths discussed earlier. As
-			always, paths themselves are not attached to a specific root entity and can be applied
-			to any entity that has similarly named attributes or relationships. So when we are
-			saying that this expression "may be used to match Paintings", we are implying that there
-			may be other entities, for which this expression is valid. Now the expression details... </p><p><span class="italic">Character constants</span> that are not paths or numeric values
-			should be enclosed in single or double quotes. Two of the expressions below are
-			equivalent:</p><pre class="programlisting">name = 'ABC'
+            particular expression may be used to match Paintings with names that start with "A" and
+            a price less than $1000. While this example is pretty self-explanatory, there are a few
+            points worth mentioning. "name" and "price" here are object paths discussed earlier. As
+            always, paths themselves are not attached to a specific root entity and can be applied
+            to any entity that has similarly named attributes or relationships. So when we are
+            saying that this expression "may be used to match Paintings", we are implying that there
+            may be other entities, for which this expression is valid. Now the expression details... </p><p><span class="italic">Character constants</span> that are not paths or numeric values
+            should be enclosed in single or double quotes. Two of the expressions below are
+            equivalent:</p><pre class="programlisting">name = 'ABC'
 
 // double quotes are escaped inside Java Strings of course
 name = \"ABC\"</pre><p><span class="italic">Case sensitivity.</span> Expression operators are all case
-			sensitive and are usually lowercase. Complex words follow the java camel-case
-			style:</p><pre class="programlisting">// valid
+            sensitive and are usually lowercase. Complex words follow the java camel-case
+            style:</p><pre class="programlisting">// valid
 name likeIgnoreCase 'A%'
 
 // invalid - will throw a parse exception
-name LIKEIGNORECASE 'A%'</pre><p><span class="italic">Grouping with
-			parenthesis</span>:</p><pre class="programlisting">value = (price + 250.00) * 3</pre><p><span class="italic">Path prefixes.</span> Object expressions are unquoted strings,
-			optionally prefixed by "obj:" (usually they are not prefixed at all actually). Database
-			expressions are always prefixed with "db:". A special kind of prefix, not discussed yet
-			is "enum:" that prefixes an enumeration
-			constant:</p><pre class="programlisting">// object path
+name LIKEIGNORECASE 'A%'</pre><p><span class="italic">Grouping with parenthesis:</span>
+            </p><pre class="programlisting">value = (price + 250.00) * 3</pre><p>
+        </p><p><span class="italic">Path prefixes.</span> Object expressions are unquoted strings,
+            optionally prefixed by "obj:" (usually they are not prefixed at all actually). Database
+            expressions are always prefixed with "db:". A special kind of prefix, not discussed yet
+            is "enum:" that prefixes an enumeration
+            constant:</p><pre class="programlisting">// object path
 name = 'Salvador Dali'
 
 // same object path - a rarely used form
@@ -81,88 +83,89 @@ db:NAME = 'Salvador Dali'
 
 // enumeration constant
 name = enum:org.foo.EnumClass.VALUE1</pre><p>
-			<span class="italic">Binary conditions</span> are expressions that contain a path
-			on the left, a value on the right, and some operation between them, such as equals,
-			like, etc. They can be used as qualifiers in
-				SelectQueries:</p><pre class="programlisting">name like 'A%'</pre><p><span class="italic">Named parameters.</span> Expressions can have named parameters (names that
-			start with "$"). Parameterized expressions allow to create reusable expression
-			templates. Also if an Expression contains a complex object that doesn't have a simple
-			String representation (e.g. a Date, a DataObject, an ObjectId), parameterizing such
-			expression is the only way to represent it as String. Here are some
-			examples:</p><pre class="programlisting">Expression template = Expression.fromString("name = $name");
+            <span class="italic">Binary conditions</span> are expressions that contain a path
+            on the left, a value on the right, and some operation between them, such as equals,
+            like, etc. They can be used as qualifiers in
+                SelectQueries:</p><pre class="programlisting">name like 'A%'</pre><p>
+            <span class="italic">Named parameters.</span> Expressions can have named parameters (names that
+            start with "$"). Parameterized expressions allow to create reusable expression
+            templates. Also if an Expression contains a complex object that doesn't have a simple
+            String representation (e.g. a Date, a DataObject, an ObjectId), parameterizing such
+            expression is the only way to represent it as String. Here are some
+            examples:</p><pre class="programlisting">Expression template = Expression.fromString("name = $name");
 ...
 Map p1 = Collections.singletonMap("name", "Salvador Dali");
 Expression qualifier1 = template.expWithParameters(p1);
 ...
 Map p2 = Collections.singletonMap("name", "Monet");
 Expression qualifier2 = template.expWithParameters(p2);</pre><p>To
-			create a named parameterized expression with a LIKE clause, SQL wildcards must be part
-			of the values in the Map and not the expression string
-			itself:</p><pre class="programlisting">Expression template = Expression.fromString("name like $name");
+            create a named parameterized expression with a LIKE clause, SQL wildcards must be part
+            of the values in the Map and not the expression string
+            itself:</p><pre class="programlisting">Expression template = Expression.fromString("name like $name");
 ...
 Map p1 = Collections.singletonMap("name", "Salvador%");
 Expression qualifier1 = template.expWithParameters(p1);</pre><p>When
-			matching on a relationship, parameters can be Persistent objects or
-			ObjectIds:</p><pre class="programlisting">Expression template = Expression.fromString("artist = $artist");
+            matching on a relationship, parameters can be Persistent objects or
+            ObjectIds:</p><pre class="programlisting">Expression template = Expression.fromString("artist = $artist");
 ...
 Artist dali = // asume we fetched this one already
 Map p1 = Collections.singletonMap("artist", dali);
 Expression qualifier1 = template.expWithParameters(p1);</pre><p>Uninitialized
-			parameters will be automatically pruned from expressions, so a user can omit some
-			parameters when creating an expression from a parameterized
-			template:</p><pre class="programlisting">Expression template = Expression.fromString("name like $name and dateOfBirth &gt; $date");
+            parameters will be automatically pruned from expressions, so a user can omit some
+            parameters when creating an expression from a parameterized
+            template:</p><pre class="programlisting">Expression template = Expression.fromString("name like $name and dateOfBirth &gt; $date");
 ...
 Map p1 = Collections.singletonMap("name", "Salvador%");
 Expression qualifier1 = template.expWithParameters(p1);
 
-// qualifier1 is now equals to "name like 'Salvador%'", the 'dateOfBirth' condition was 
+// qualifier1 is now equals to "name like 'Salvador%'", the 'dateOfBirth' condition was
 // pruned, as no value was specified for the $date parameter</pre><p><span class="italic">Null handling.</span> Handling of Java nulls as operands
-			is no different from normal values. Instead of using special conditional operators, like
-			SQL does (IS NULL, IS NOT NULL), "=" and "!=" expressions can be used directly with null
-			values. It is up to Cayenne to translate expressions with nulls to the valid SQL.</p><p>
-			</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>A formal definition of all possible valid expressions in a form of JavaCC
-					grammar is provided in Appendix C</p></div><p>
-		</p></div><div class="section" title="Creating Expressions with API"><div class="titlepage"><div><div><h2 class="title"><a name="expressions-with-expressionfactory"></a>Creating Expressions with API</h2></div></div></div><p>Creating expressions from Strings is a powerful and dynamic approach, however a safer
-			alternative is to use Java API. It provides some degree of compile-time checking of
-			expressions validity. The API is cenetred around ExpressionFactory class, and the
-			Expression class. ExpressionFactory contains a number of rather self-explanatory factory
-			methods. We won't be going over all of them in detail, but will rather show a few
-			general examples and some gotchas. </p><p>The following code recreates the expression from the previous chapter, but now using
-			expression
-			API:</p><pre class="programlisting">// String expression: name like 'A%' and price &lt; 1000
+            is no different from normal values. Instead of using special conditional operators, like
+            SQL does (IS NULL, IS NOT NULL), "=" and "!=" expressions can be used directly with null
+            values. It is up to Cayenne to translate expressions with nulls to the valid SQL.</p><p>
+            </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>A formal definition of all possible valid expressions in a form of JavaCC
+                    grammar is provided in Appendix C</p></div><p>
+        </p></div><div class="section" title="Creating Expressions with API"><div class="titlepage"><div><div><h2 class="title"><a name="expressions-with-expressionfactory"></a>Creating Expressions with API</h2></div></div></div><p>Creating expressions from Strings is a powerful and dynamic approach, however a safer
+            alternative is to use Java API. It provides some degree of compile-time checking of
+            expressions validity. The API is cenetred around ExpressionFactory class, and the
+            Expression class. ExpressionFactory contains a number of rather self-explanatory factory
+            methods. We won't be going over all of them in detail, but will rather show a few
+            general examples and some gotchas. </p><p>The following code recreates the expression from the previous chapter, but now using
+            expression
+            API:</p><pre class="programlisting">// String expression: name like 'A%' and price &lt; 1000
 Expression e1 = ExpressionFactory.likeExp(Painting.NAME_PROPERTY, "A%");
 Expression e2 = ExpressionFactory.lessExp(Painting.PRICE_PROPERTY, 1000);
 Expression finalExp = e1.andExp(e2); </pre><p>This
-			is more verbose than creating it from String, but it is also more resilient to the
-			entity properties renaming and precludes semantic errors in the expression String.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The last line in the example above shows how to create a new expression by
-					"chaining" 2 other epxressions. A common error when chaining expressions is to
-					assume that "andExp" and "orExp" append another expression to the current
-					expression. In fact a new expression is created. I.e. Expression API treats
-					existing expressions as immutable.</p></div><p>As discussed 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><pre class="programlisting">Expression matchAllExp(String path, Collection values)
+            is more verbose than creating it from String, but it is also more resilient to the
+            entity properties renaming and precludes semantic errors in the expression String.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The last line in the example above shows how to create a new expression by
+                    "chaining" 2 other epxressions. A common error when chaining expressions is to
+                    assume that "andExp" and "orExp" append another expression to the current
+                    expression. In fact a new expression is created. I.e. Expression API treats
+                    existing expressions as immutable.</p></div><p>As discussed 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><pre class="programlisting">Expression matchAllExp(String path, Collection values)
 Expression matchAllExp(String path, Object... values)</pre><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. "|exhibits.paintings",
-			"exhibits|paintings", etc. Internally Cayenne would generate distinct aliases for each
-			of the split expressions, forcing separate joins.</p></div><div class="section" title="Evaluating Expressions in Memory"><div class="titlepage"><div><div><h2 class="title"><a name="expressions-in-memory"></a>Evaluating Expressions in Memory</h2></div></div></div><p>When used in a query, an expression is converted to SQL WHERE clause (or ORDER BY
-			clause) by Cayenne during query execution. Thus the actual evaluation against the data
-			is done by the database engine. However the same expressions can also be used for
-			accessing object properties, calculating values, in-memory filtering. </p><p>Checking whether an object satisfies an
-			expression:</p><pre class="programlisting">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
+            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. "|exhibits.paintings",
+            "exhibits|paintings", etc. Internally Cayenne would generate distinct aliases for each
+            of the split expressions, forcing separate joins.</p></div><div class="section" title="Evaluating Expressions in Memory"><div class="titlepage"><div><div><h2 class="title"><a name="expressions-in-memory"></a>Evaluating Expressions in Memory</h2></div></div></div><p>When used in a query, an expression is converted to SQL WHERE clause (or ORDER BY
+            clause) by Cayenne during query execution. Thus the actual evaluation against the data
+            is done by the database engine. However the same expressions can also be used for
+            accessing object properties, calculating values, in-memory filtering. </p><p>Checking whether an object satisfies an
+            expression:</p><pre class="programlisting">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
 User user = ...
 if(e.match(user)) {
    ...
 }</pre><p>Reading
-			property
-			value:</p><pre class="programlisting">Expression e = Expression.fromString(User.NAME_PROPERTY);
+            property
+            value:</p><pre class="programlisting">Expression e = Expression.fromString(User.NAME_PROPERTY);
 String name = e.evaluate(user);</pre><p>Filtering a list of
-			objects:</p><pre class="programlisting">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
+            objects:</p><pre class="programlisting">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
 List&lt;User&gt; unfiltered = ...
 List&lt;User&gt; filtered = e.filterObjects(unfiltered);</pre><p>
-			</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Current limitation of in-memory expressions is that no collections are
-					permitted in the property path.</p></div><p>
-		</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="persistent-objects-objectcontext.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="orderings.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;6.&nbsp;Persistent Objects and ObjectContext&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;8.&nbsp;Orderings</td></tr></table></div></body></html>
\ No newline at end of file
+            </p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Current limitation of in-memory expressions is that no collections are
+                    permitted in the property path.</p></div><p>
+        </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="persistent-objects-objectcontext.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="orderings.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;6.&nbsp;Persistent Objects and ObjectContext&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;8.&nbsp;Orderings</td></tr></table></div></body></html>
\ No newline at end of file

Modified: websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/including-cayenne-in-project.html
==============================================================================
--- websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/including-cayenne-in-project.html (original)
+++ websites/staging/cayenne/trunk/content/docs/3.1/cayenne-guide/including-cayenne-in-project.html Wed Dec 26 19:20:35 2012
@@ -1,356 +1,363 @@
 <html><head>
       <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>Chapter&nbsp;4.&nbsp;Including Cayenne in a Project</title><link rel="stylesheet" type="text/css" href="css/cayenne-doc.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="index.html" title="Cayenne Guide"><link rel="up" href="cayenne-guide-part2.html" title="Part&nbsp;II.&nbsp;Cayenne Framework"><link rel="prev" href="cayenne-guide-part2.html" title="Part&nbsp;II.&nbsp;Cayenne Framework"><link rel="next" href="starting-cayenne.html" title="Chapter&nbsp;5.&nbsp;Starting Cayenne"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter&nbsp;4.&nbsp;Including Cayenne in a Project</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="cayenne-guide-part2.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;II.&nbsp;Cayenne Framework</th><td width="20%" align=
 "right">&nbsp;<a accesskey="n" href="starting-cayenne.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter&nbsp;4.&nbsp;Including Cayenne in a Project"><div class="titlepage"><div><div><h2 class="title"><a name="including-cayenne-in-project"></a>Chapter&nbsp;4.&nbsp;Including Cayenne in a Project</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="including-cayenne-in-project.html#jar-files-and-depdendencies">Jar Files and Dependencies</a></span></dt><dt><span class="section"><a href="including-cayenne-in-project.html#maven-projects">Maven Projects</a></span></dt><dt><span class="section"><a href="including-cayenne-in-project.html#ant-projects">Ant Projects</a></span></dt></dl></div><div class="section" title="Jar Files and Dependencies"><div class="titlepage"><div><div><h2 class="title"><a name="jar-files-and-depdendencies"></a>Jar Files and Dependencies</h2></div></div></div><p>Cayenne distri
 bution contains the following core runtime jars in the distribution
-				<code class="code">lib</code> directory: </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="italic">cayenne-server-x.x.jar</span> - contains full
-						Cayenne runtime (DI, adapters, DB access classes, etc.). Most applications
-						will use only this file.</p></li><li class="listitem"><p>cayenne-client-x.x.jar - a subset of cayenne-server.jar trimmed for use on
-						the client in an ROP application.</p></li><li class="listitem"><p>Other cayenne-* jars - various Cayenne extensions.</p></li></ul></div><p>When using <code class="code">cayenne-server-x.x.jar</code> you'll need a few third party jars (all
-			included in <code class="code">lib/third-party</code> directory of the distribution): </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><a class="link" href="http://velocity.apache.org/" target="_top">Apache Velocity
-							Template Engine</a>, version 1.6.x (and all its dependencies bundled
-						with velocity-dep)</p></li><li class="listitem"><p><a class="link" href="http://commons.apache.org/collections/" target="_top">Apache Commons
-							Collections</a>, version 3.2.1</p></li><li class="listitem"><p><a class="link" href="http://commons.apache.org/logging/" target="_top">Apache
-							Commons Logging</a>, version 1.1</p></li></ul></div><p>Cayenne integrates with various caching, clustering and other frameworks. These
-			optional integrations will require other third-party jars that the users will need to
-			obtain on their own.</p></div><div class="section" title="Maven Projects"><div class="titlepage"><div><div><h2 class="title"><a name="maven-projects"></a>Maven Projects</h2></div></div></div><p>If you are using Maven, you won't have to deal with figuring out the dependencies. You
-			can simply include cayenne-server artifact in your
-			POM:</p><pre class="programlisting">&lt;dependency&gt;
+                <code class="code">lib</code> directory: </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><span class="italic">cayenne-server-x.x.jar</span> - contains full
+                        Cayenne runtime (DI, adapters, DB access classes, etc.). Most applications
+                        will use only this file.</p></li><li class="listitem"><p>cayenne-client-x.x.jar - a subset of cayenne-server.jar trimmed for use on
+                        the client in an ROP application.</p></li><li class="listitem"><p>Other cayenne-* jars - various Cayenne extensions.</p></li></ul></div><p>When using <code class="code">cayenne-server-x.x.jar</code> you'll need a few third party jars (all
+            included in <code class="code">lib/third-party</code> directory of the distribution): </p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><a class="link" href="http://velocity.apache.org/" target="_top">Apache Velocity
+                            Template Engine</a>, version 1.6.x (and all its dependencies bundled
+                        with velocity-dep)</p></li><li class="listitem"><p><a class="link" href="http://commons.apache.org/collections/" target="_top">Apache Commons
+                            Collections</a>, version 3.2.1</p></li><li class="listitem"><p><a class="link" href="http://commons.apache.org/logging/" target="_top">Apache
+                            Commons Logging</a>, version 1.1</p></li></ul></div><p>Cayenne integrates with various caching, clustering and other frameworks. These
+            optional integrations will require other third-party jars that the users will need to
+            obtain on their own.</p></div><div class="section" title="Maven Projects"><div class="titlepage"><div><div><h2 class="title"><a name="maven-projects"></a>Maven Projects</h2></div></div></div><p>If you are using Maven, you won't have to deal with figuring out the dependencies. You
+            can simply include cayenne-server artifact in your
+            POM:</p><pre class="programlisting">&lt;dependency&gt;
    &lt;groupId&gt;org.apache.cayenne&lt;/groupId&gt;
    &lt;artifactId&gt;cayenne-server&lt;/artifactId&gt;
    &lt;version&gt;X.Y.Z&lt;/version&gt;
 &lt;/dependency&gt;</pre><p>Additionally Cayenne provides a Maven plugin with a set of goals to perform various project
-			tasks, such as synching generated Java classes with the mapping, described in the
-			following subsection. The full plugin name is
-				<code class="code">org.apache.cayenne.plugins:maven-cayenne-plugin</code>.</p><div class="section" title="cgen"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cgen"></a>cgen</h3></div></div></div><p><code class="code">cgen</code> is a <code class="code">maven-cayenne-plugin</code> goal that generates and maintains
-				source (.java) files of persistent objects based on a DataMap. By default, it is
-				bound to the generate-sources phase. If "makePairs" is set to "true" (which is the
-				recommended default), this task will generate a pair of classes
-				(superclass/subclass) for each ObjEntity in the DataMap. Superclasses should not be
-				changed manually, since they are always overwritten. Subclasses are never
-				overwritten and may be later customized by the user. If "makePairs" is set to
-				"false", a single class will be generated for each ObjEntity. </p><p>By creating custom templates, you can use cgen to generate other output (such as
-				web pages, reports, specialized code templates) based on DataMap information.</p><p>
-				</p><table frame="void" id="d0e226"><caption>Table&nbsp;4.1.&nbsp;cgen required parameters</caption><col width="14%"><col width="6%"><col width="80%"><thead><tr>
-							<th>Name</th>
-							<th>Type</th>
-							<th>Description</th>
-						</tr></thead><tbody><tr>
-							<td><code class="code">map</code>
-							</td>
-							<td>File</td>
-							<td>DataMap XML file which serves as a source of metadata for class
-								generation. E.g.
-									<code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
-						</tr><tr>
-							<td><code class="code">destDir</code></td>
-							<td>File</td>
-							<td>Root destination directory for Java classes (ignoring their package
-								names).</td>
-						</tr></tbody></table><p>
-				</p><table frame="void" id="d0e273"><caption>Table&nbsp;4.2.&nbsp;cgen optional parameters</caption><col width="33%"><col width="8%"><col width="59%"><thead><tr>
-							<th>Name</th>
-							<th>Type</th>
-							<th>Description</th>
-						</tr></thead><tbody><tr>
-							<td><code class="code">additionalMaps</code>
-							</td>
-							<td>File</td>
-							<td>A directory that contains additional DataMap XML files that may be
-								needed to resolve cross-DataMap relationships for the the main
-								DataMap, for which class generation occurs.</td>
-						</tr><tr>
-							<td><code class="code">client</code></td>
-							<td>boolean</td>
-							<td>Whether we are generating classes for the client tier in a Remote
-								Object Persistence application. "False" by default.</td>
-						</tr><tr>
-							<td><code class="code">embeddableTemplate</code></td>
-							<td>String</td>
-							<td>Location of a custom Velocity template file for Embeddable class
-								generation. If omitted, default template is used.</td>
-						</tr><tr>
-							<td><code class="code">embeddableSuperTemplate</code></td>
-							<td>String</td>
-							<td>Location of a custom Velocity template file for Embeddable
-								superclass generation. Ignored unless "makepairs" set to "true". If
-								omitted, default template is used.</td>
-						</tr><tr>
-							<td><code class="code">encoding</code></td>
-							<td>String</td>
-							<td>Generated files encoding if different from the default on current
-								platform. Target encoding must be supported by the JVM running the
-								build. Standard encodings supported by Java on all platforms are
-								US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See
-								javadocs for java.nio.charset.Charset for more information.</td>
-						</tr><tr>
-							<td><code class="code">excludeEntities</code></td>
-							<td>String</td>
-							<td>A comma-separated list of ObjEntity patterns (expressed as a perl5
-								regex) to exclude from template generation. By default none of the
-								DataMap entities are excluded.</td>
-						</tr><tr>
-							<td><code class="code">includeEntities</code></td>
-							<td>String</td>
-							<td>A comma-separated list of ObjEntity patterns (expressed as a perl5
-								regex) to include from template generation. By default all DataMap
-								entities are included.</td>
-						</tr><tr>
-							<td><code class="code">makePairs</code></td>
-							<td>boolean</td>
-							<td>If "true" (a recommended default), will generate subclass/superclass
-								pairs, with all generated code placed in superclass.</td>
-						</tr><tr>
-							<td><code class="code">mode</code></td>
-							<td>String</td>
-							<td>Specifies class generator iteration target. There are three possible
-								values: "entity" (default), "datamap", "all". "entity" performs one
-								generator iteration for each included ObjEntity, applying either
-								standard to custom entity templates. "datamap" performs a single
-								iteration, applying DataMap templates. "All" is a combination of
-								entity and datamap.</td>
-						</tr><tr>
-							<td><code class="code">overwrite</code></td>
-							<td>boolean</td>
-							<td>Only has effect when "makePairs" is set to "false". If "overwrite"
-								os "true", will overwrite older versions of generated classes.</td>
-						</tr><tr>
-							<td><code class="code">superPkg</code></td>
-							<td>String</td>
-							<td>Java package name of generated superclasses. Only has effect if
-								"makepairs" and "usePkgPath" are set to "true" (both are true by
-								default). Defines a common package for all generated Java classes.
-								If omitted, each superclass will be placed in the same package as
-								subclass.</td>
-						</tr><tr>
-							<td><code class="code">superTemplate</code></td>
-							<td>String</td>
-							<td>Location of a custom Velocity template file for ObjEntity superclass
-								generation. Only has effect if "makepairs" set to "true". If
-								omitted, default template is used.</td>
-						</tr><tr>
-							<td><code class="code">template</code></td>
-							<td>String</td>
-							<td>Location of a custom Velocity template file for ObjEntity class
-								generation. If omitted, default template is used.</td>
-						</tr><tr>
-							<td><code class="code">usePkgPath</code></td>
-							<td>boolean</td>
-							<td>If set to "true" (default), a directory tree will be generated in
-								"destDir" corresponding to the class package structure, if set to
-								"false", classes will be generated in "destDir" ignoring their
-								package.</td>
-						</tr></tbody></table><p>Example - a typical class generation scenario, where pairs of classes are
-				generated, and superclasses are placed in a separate package:
-				</p><pre class="programlisting">&lt;plugin&gt;
-	&lt;groupId&gt;org.apache.cayenne.plugins&lt;/groupId&gt;
-	&lt;artifactId&gt;maven-cayenne-plugin&lt;/artifactId&gt;
-	&lt;version&gt;X.Y.Z&lt;/version&gt;
+            tasks, such as synching generated Java classes with the mapping, described in the
+            following subsection. The full plugin name is
+                <code class="code">org.apache.cayenne.plugins:maven-cayenne-plugin</code>.</p><div class="section" title="cgen"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cgen"></a>cgen</h3></div></div></div><p><code class="code">cgen</code> is a <code class="code">maven-cayenne-plugin</code> goal that generates and maintains
+                source (.java) files of persistent objects based on a DataMap. By default, it is
+                bound to the generate-sources phase. If "makePairs" is set to "true" (which is the
+                recommended default), this task will generate a pair of classes
+                (superclass/subclass) for each ObjEntity in the DataMap. Superclasses should not be
+                changed manually, since they are always overwritten. Subclasses are never
+                overwritten and may be later customized by the user. If "makePairs" is set to
+                "false", a single class will be generated for each ObjEntity. </p><p>By creating custom templates, you can use cgen to generate other output (such as
+                web pages, reports, specialized code templates) based on DataMap information.</p><p>
+                </p><table frame="void" id="d0e226"><caption>Table&nbsp;4.1.&nbsp;cgen required parameters</caption><col width="14%"><col width="6%"><col width="80%"><thead><tr>
+                            <th>Name</th>
+                            <th>Type</th>
+                            <th>Description</th>
+                        </tr></thead><tbody><tr>
+                            <td><code class="code">map</code>
+                            </td>
+                            <td>File</td>
+                            <td>DataMap XML file which serves as a source of metadata for class
+                                generation. E.g.
+                                    <code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
+                        </tr><tr>
+                            <td><code class="code">destDir</code></td>
+                            <td>File</td>
+                            <td>Root destination directory for Java classes (ignoring their package
+                                names).</td>
+                        </tr></tbody></table><p>
+                </p><table frame="void" id="d0e273"><caption>Table&nbsp;4.2.&nbsp;cgen optional parameters</caption><col width="33%"><col width="8%"><col width="59%"><thead><tr>
+                            <th>Name</th>
+                            <th>Type</th>
+                            <th>Description</th>
+                        </tr></thead><tbody><tr>
+                            <td><code class="code">additionalMaps</code>
+                            </td>
+                            <td>File</td>
+                            <td>A directory that contains additional DataMap XML files that may be
+                                needed to resolve cross-DataMap relationships for the the main
+                                DataMap, for which class generation occurs.</td>
+                        </tr><tr>
+                            <td><code class="code">client</code></td>
+                            <td>boolean</td>
+                            <td>Whether we are generating classes for the client tier in a Remote
+                                Object Persistence application. "False" by default.</td>
+                        </tr><tr>
+                            <td><code class="code">embeddableTemplate</code></td>
+                            <td>String</td>
+                            <td>Location of a custom Velocity template file for Embeddable class
+                                generation. If omitted, default template is used.</td>
+                        </tr><tr>
+                            <td><code class="code">embeddableSuperTemplate</code></td>
+                            <td>String</td>
+                            <td>Location of a custom Velocity template file for Embeddable
+                                superclass generation. Ignored unless "makepairs" set to "true". If
+                                omitted, default template is used.</td>
+                        </tr><tr>
+                            <td><code class="code">encoding</code></td>
+                            <td>String</td>
+                            <td>Generated files encoding if different from the default on current
+                                platform. Target encoding must be supported by the JVM running the
+                                build. Standard encodings supported by Java on all platforms are
+                                US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, UTF-16. See
+                                javadocs for java.nio.charset.Charset for more information.</td>
+                        </tr><tr>
+                            <td><code class="code">excludeEntities</code></td>
+                            <td>String</td>
+                            <td>A comma-separated list of ObjEntity patterns (expressed as a perl5
+                                regex) to exclude from template generation. By default none of the
+                                DataMap entities are excluded.</td>
+                        </tr><tr>
+                            <td><code class="code">includeEntities</code></td>
+                            <td>String</td>
+                            <td>A comma-separated list of ObjEntity patterns (expressed as a perl5
+                                regex) to include from template generation. By default all DataMap
+                                entities are included.</td>
+                        </tr><tr>
+                            <td><code class="code">makePairs</code></td>
+                            <td>boolean</td>
+                            <td>If "true" (a recommended default), will generate subclass/superclass
+                                pairs, with all generated code placed in superclass.</td>
+                        </tr><tr>
+                            <td><code class="code">mode</code></td>
+                            <td>String</td>
+                            <td>Specifies class generator iteration target. There are three possible
+                                values: "entity" (default), "datamap", "all". "entity" performs one
+                                generator iteration for each included ObjEntity, applying either
+                                standard to custom entity templates. "datamap" performs a single
+                                iteration, applying DataMap templates. "All" is a combination of
+                                entity and datamap.</td>
+                        </tr><tr>
+                            <td><code class="code">overwrite</code></td>
+                            <td>boolean</td>
+                            <td>Only has effect when "makePairs" is set to "false". If "overwrite"
+                                os "true", will overwrite older versions of generated classes.</td>
+                        </tr><tr>
+                            <td><code class="code">superPkg</code></td>
+                            <td>String</td>
+                            <td>Java package name of generated superclasses. Only has effect if
+                                "makepairs" and "usePkgPath" are set to "true" (both are true by
+                                default). Defines a common package for all generated Java classes.
+                                If omitted, each superclass will be placed in the same package as
+                                subclass.</td>
+                        </tr><tr>
+                            <td><code class="code">superTemplate</code></td>
+                            <td>String</td>
+                            <td>Location of a custom Velocity template file for ObjEntity superclass
+                                generation. Only has effect if "makepairs" set to "true". If
+                                omitted, default template is used.</td>
+                        </tr><tr>
+                            <td><code class="code">template</code></td>
+                            <td>String</td>
+                            <td>Location of a custom Velocity template file for ObjEntity class
+                                generation. If omitted, default template is used.</td>
+                        </tr><tr>
+                            <td><code class="code">usePkgPath</code></td>
+                            <td>boolean</td>
+                            <td>If set to "true" (default), a directory tree will be generated in
+                                "destDir" corresponding to the class package structure, if set to
+                                "false", classes will be generated in "destDir" ignoring their
+                                package.</td>
+                        </tr></tbody></table><p>
+                Example - a typical class generation scenario, where pairs of classes are
+                generated, and superclasses are placed in a separate package:
+                </p><pre class="programlisting">&lt;plugin&gt;
+    &lt;groupId&gt;org.apache.cayenne.plugins&lt;/groupId&gt;
+    &lt;artifactId&gt;maven-cayenne-plugin&lt;/artifactId&gt;
+    &lt;version&gt;X.Y.Z&lt;/version&gt;
 
-	&lt;!-- 
-	There's an intermittent problem when using Maven/cgen in Eclipse with  m2eclipse plugin that
+    &lt;!--
+    There's an intermittent problem when using Maven/cgen in Eclipse with  m2eclipse plugin that
     requires placing "configuration" section at the plugin level, instead of execution
     level.
-	--&gt;
-	&lt;configuration&gt;
-		&lt;map&gt;${project.basedir}/src/main/resources/my.map.xml&lt;/map&gt;
-		&lt;destDir&gt;${project.basedir}/src/main/java&lt;/destDir&gt;
-		&lt;superPkg&gt;org.example.model.auto&lt;/superPkg&gt;
-	&lt;/configuration&gt;
+    --&gt;
+    &lt;configuration&gt;
+        &lt;map&gt;${project.basedir}/src/main/resources/my.map.xml&lt;/map&gt;
+        &lt;destDir&gt;${project.basedir}/src/main/java&lt;/destDir&gt;
+        &lt;superPkg&gt;org.example.model.auto&lt;/superPkg&gt;
+    &lt;/configuration&gt;
 
-	&lt;executions&gt;
-		&lt;execution&gt;
-			&lt;goals&gt;
-				&lt;goal&gt;cgen&lt;/goal&gt;
-			&lt;/goals&gt;
-		&lt;/execution&gt;
-	&lt;/executions&gt;
+    &lt;executions&gt;
+        &lt;execution&gt;
+            &lt;goals&gt;
+                &lt;goal&gt;cgen&lt;/goal&gt;
+            &lt;/goals&gt;
+        &lt;/execution&gt;
+    &lt;/executions&gt;
 &lt;/plugin&gt;</pre></div><div class="section" title="cdbgen"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cdbgen"></a>cdbgen</h3></div></div></div><p><code class="code">cdbgen</code> is a <code class="code">maven-cayenne-plugin</code> goal that drops and/or generates
-				tables in a database on Cayenne DataMap. By default, it is bound to the
-				pre-integration-test phase.</p><table frame="void" id="d0e474"><caption>Table&nbsp;4.3.&nbsp;cdbgen required parameters</caption><col width="14%"><col width="6%"><col width="80%"><thead><tr>
-							<th>Name</th>
-							<th>Type</th>
-							<th>Description</th>
-						</tr></thead><tbody><tr>
-							<td><code class="code">map</code>
-							</td>
-							<td>File</td>
-							<td>DataMap XML file which serves as a source of metadata for DB schema
-								generation. E.g.
-									<code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
-						</tr><tr>
-							<td><code class="code">driver</code></td>
-							<td>String</td>
-							<td>A class of JDBC driver to use for the target database.</td>
-						</tr><tr>
-							<td><code class="code">url</code></td>
-							<td>String</td>
-							<td>JDBC connection URL of a target database.</td>
-						</tr></tbody></table><p>
-				</p><table frame="void" width="792" id="d0e534"><caption>Table&nbsp;4.4.&nbsp;cdbgen optional parameters</caption><col width="18%"><col width="7%"><col width="79%"><thead><tr>
-							<th>Name</th>
-							<th>Type</th>
-							<th>Description</th>
-						</tr></thead><tbody><tr>
-							<td><code class="code">adapter</code>
-							</td>
-							<td>String</td>
-							<td>Java class name implementing org.apache.cayenne.dba.DbAdapter. While
-								this attribute is optional (a generic JdbcAdapter is used if not
-								set), it is highly recommended to specify correct target
-								adapter.</td>
-						</tr><tr>
-							<td><code class="code">createFK</code></td>
-							<td>boolean</td>
-							<td>Indicates whether cdbgen should create foreign key constraints. Default is "true".</td>
-						</tr><tr>
-							<td><code class="code">createPK</code></td>
-							<td>boolean</td>
-							<td>Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is
-								"true".</td>
-						</tr><tr>
-							<td><code class="code">createTables</code></td>
-							<td>boolean</td>
-							<td>Indicates whether cdbgen should create new tables. Default is "true".</td>
-						</tr><tr>
-							<td><code class="code">dropPK</code></td>
-							<td>boolean</td>
-							<td>Indicates whether cdbgen should drop Cayenne primary key support objects. Default is
-								"false".</td>
-						</tr><tr>
-							<td><code class="code">dropTables</code></td>
-							<td>boolean</td>
-							<td>Indicates whether cdbgen should drop the tables before attempting to create new ones.
-								Default is "false".</td>
-						</tr><tr>
-							<td><code class="code">password</code></td>
-							<td>String</td>
-							<td>Database user password.</td>
-						</tr><tr>
-							<td><code class="code">username</code></td>
-							<td>String</td>
-							<td>Database user name.</td>
-						</tr></tbody></table><p>
-			</p><p>Example - creating a DB schema on a local HSQLDB
-				database:</p><pre class="programlisting">&lt;plugin&gt;
-	&lt;groupId&gt;org.apache.cayenne.plugins&lt;/groupId&gt;
-	&lt;artifactId&gt;maven-cayenne-plugin&lt;/artifactId&gt;
-	&lt;version&gt;X.Y.Z&lt;/version&gt;
+                tables in a database on Cayenne DataMap. By default, it is bound to the
+                pre-integration-test phase.</p><table frame="void" id="d0e474"><caption>Table&nbsp;4.3.&nbsp;cdbgen required parameters</caption><col width="14%"><col width="10%"><col width="76%"><thead><tr>
+                            <th>Name</th>
+                            <th>Type</th>
+                            <th>Description</th>
+                        </tr></thead><tbody><tr>
+                            <td><code class="code">map</code>
+                            </td>
+                            <td>File</td>
+                            <td>DataMap XML file which serves as a source of metadata for DB schema
+                                generation. E.g.
+                                    <code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
+                        </tr><tr>
+                            <td><code class="code">driver</code></td>
+                            <td>String</td>
+                            <td>A class of JDBC driver to use for the target database.</td>
+                        </tr><tr>
+                            <td><code class="code">url</code></td>
+                            <td>String</td>
+                            <td>JDBC connection URL of a target database.</td>
+                        </tr></tbody></table><p>
+                </p><table frame="void" id="d0e534"><caption>Table&nbsp;4.4.&nbsp;cdbgen optional parameters</caption><col width="18%"><col width="11%"><col width="75%"><thead><tr>
+                            <th>Name</th>
+                            <th>Type</th>
+                            <th>Description</th>
+                        </tr></thead><tbody><tr>
+                            <td><code class="code">adapter</code>
+                            </td>
+                            <td>String</td>
+                            <td>Java class name implementing org.apache.cayenne.dba.DbAdapter. While
+                                this attribute is optional (a generic JdbcAdapter is used if not
+                                set), it is highly recommended to specify correct target
+                                adapter.</td>
+                        </tr><tr>
+                            <td><code class="code">createFK</code></td>
+                            <td>boolean</td>
+                            <td>Indicates whether cdbgen should create foreign key constraints. Default is "true".</td>
+                        </tr><tr>
+                            <td><code class="code">createPK</code></td>
+                            <td>boolean</td>
+                            <td>Indicates whether cdbgen should create Cayenne-specific auto PK objects. Default is
+                                "true".</td>
+                        </tr><tr>
+                            <td><code class="code">createTables</code></td>
+                            <td>boolean</td>
+                            <td>Indicates whether cdbgen should create new tables. Default is "true".</td>
+                        </tr><tr>
+                            <td><code class="code">dropPK</code></td>
+                            <td>boolean</td>
+                            <td>Indicates whether cdbgen should drop Cayenne primary key support objects. Default is
+                                "false".</td>
+                        </tr><tr>
+                            <td><code class="code">dropTables</code></td>
+                            <td>boolean</td>
+                            <td>Indicates whether cdbgen should drop the tables before attempting to create new ones.
+                                Default is "false".</td>
+                        </tr><tr>
+                            <td><code class="code">password</code></td>
+                            <td>String</td>
+                            <td>Database user password.</td>
+                        </tr><tr>
+                            <td><code class="code">username</code></td>
+                            <td>String</td>
+                            <td>Database user name.</td>
+                        </tr></tbody></table><p>
+            </p><p>Example - creating a DB schema on a local HSQLDB
+                database:</p><pre class="programlisting">&lt;plugin&gt;
+    &lt;groupId&gt;org.apache.cayenne.plugins&lt;/groupId&gt;
+    &lt;artifactId&gt;maven-cayenne-plugin&lt;/artifactId&gt;
+    &lt;version&gt;X.Y.Z&lt;/version&gt;
 
-	&lt;executions&gt;
-		&lt;execution&gt;
-			&lt;configuration&gt;
-				&lt;map&gt;${project.basedir}/src/main/resources/my.map.xml&lt;/map&gt;
-				&lt;url&gt;jdbc:hsqldb:hsql://localhost/testdb&lt;/url&gt;
-				&lt;adapter&gt;org.apache.cayenne.dba.hsqldb.HSQLDBAdapter&lt;/adapter&gt;
-				&lt;driver&gt;org.hsqldb.jdbcDriver&lt;/driver&gt;                        
-				&lt;username&gt;sa&lt;/username&gt;
-			&lt;/configuration&gt;
-			&lt;goals&gt;
-				&lt;goal&gt;cdbgen&lt;/goal&gt;
-			&lt;/goals&gt;
-		&lt;/execution&gt;
-	&lt;/executions&gt;
+    &lt;executions&gt;
+        &lt;execution&gt;
+            &lt;configuration&gt;
+                &lt;map&gt;${project.basedir}/src/main/resources/my.map.xml&lt;/map&gt;
+                &lt;url&gt;jdbc:hsqldb:hsql://localhost/testdb&lt;/url&gt;
+                &lt;adapter&gt;org.apache.cayenne.dba.hsqldb.HSQLDBAdapter&lt;/adapter&gt;
+                &lt;driver&gt;org.hsqldb.jdbcDriver&lt;/driver&gt;
+                &lt;username&gt;sa&lt;/username&gt;
+            &lt;/configuration&gt;
+            &lt;goals&gt;
+                &lt;goal&gt;cdbgen&lt;/goal&gt;
+            &lt;/goals&gt;
+        &lt;/execution&gt;
+    &lt;/executions&gt;
 &lt;/plugin&gt;</pre></div><div class="section" title="cdbimport"><div class="titlepage"><div><div><h3 class="title"><a name="mvn-cdbimport"></a>cdbimport</h3></div></div></div><p><code class="code">cdbimport</code> is a <code class="code">maven-cayenne-plugin</code> goal that generates
-				a DataMap based on an existing database schema. By default, it is bound to the
-				generate-sources phase. This allows you to generate your DataMap prior to building
-				your project, which may be necessary if you are also using the cgen task.</p><table frame="void" id="d0e665"><caption>Table&nbsp;4.5.&nbsp;cdbimport required parameters</caption><col width="14%"><col width="6%"><col width="80%"><thead><tr>
-							<th>Name</th>
-							<th>Type</th>
-							<th>Description</th>
-						</tr></thead><tbody><tr>
-							<td><code class="code">map</code>
-							</td>
-							<td>File</td>
-							<td>DataMap XML file which is the destination of the schema import.
-								Maybe an existing file. If this file does not exist, it is created
-								when cdbimport is executed. E.g.
-									<code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
-						</tr><tr>
-							<td><code class="code">driver</code></td>
-							<td>String</td>
-							<td>A class of JDBC driver to use for the target database.</td>
-						</tr><tr>
-							<td><code class="code">url</code></td>
-							<td>String</td>
-							<td>JDBC connection URL of a target database.</td>
-						</tr></tbody></table><p>
-				</p><table frame="void" width="822" id="d0e725"><caption>Table&nbsp;4.6.&nbsp;cdbimport optional parameters</caption><col width="24%"><col width="7%"><col width="79%"><thead><tr>
-							<th>Name</th>
-							<th>Type</th>
-							<th>Description</th>
-						</tr></thead><tbody><tr>
-							<td><code class="code">adapter</code>
-							</td>
-							<td>String</td>
-							<td>Java class name implementing org.apache.cayenne.dba.DbAdapter. While
-								this attribute is optional (a generic JdbcAdapter is used if not
-								set), it is highly recommended to specify correct target
-								adapter.</td>
-						</tr><tr>
-							<td><code class="code">importProcedures</code></td>
-							<td>boolean</td>
-							<td>Indicates whether stored procedures should be imported from the
-								database. Default is false. </td>
-						</tr><tr>
-							<td><code class="code">meaningfulPk</code></td>
-							<td>boolean</td>
-							<td>Indicates whether primary keys should be mapped as attributes of the
-								ObjEntity. Default is false. </td>
-						</tr><tr>
-							<td><code class="code">namingStrategy</code></td>
-							<td>String</td>
-							<td>The naming strategy used for mapping database names to object entity
-								names. Default is
-									<code class="code">org.apache.cayenne.map.naming.SmartNamingStrategy</code>.
-							</td>
-						</tr><tr>
-							<td><code class="code">overwriteExisting</code></td>
-							<td>boolean</td>
-							<td>Indicates whether existing DB and object entities should be
-								overwritten. This is an all-or-nothing setting. If you need finer
-								granularity, use the CayenneModeler. Default is "true". </td>
-						</tr><tr>
-							<td><code class="code">password</code></td>
-							<td>String</td>
-							<td>Database user password.</td>
-						</tr><tr>
-							<td><code class="code">procedurePattern</code></td>
-							<td>String</td>
-							<td>Pattern to match stored procedure names against for import. Default
-								is to match all stored procedures. This value is only meaningful if
-								importProcedures is true. </td>
-						</tr><tr>
-							<td><code class="code">schemaName</code></td>
-							<td>String</td>
-							<td>Database schema to import tables/stored procedures from. </td>
-						</tr><tr>
-							<td><code class="code">tablePattern</code></td>
-							<td>String</td>
-							<td>Pattern to match table names against for import. Default is to match
-								all tables. </td>
-						</tr><tr>
-							<td><code class="code">username</code></td>
-							<td>String</td>
-							<td>Database user name.</td>
-						</tr></tbody></table><p>
-			</p><p>Example - loading a DB schema from a local HSQLDB database (essentially a reverse
-				operation compared to the cdbgen example above)
-				:</p><pre class="programlisting">&lt;plugin&gt;
-	&lt;groupId&gt;org.apache.cayenne.plugins&lt;/groupId&gt;
-	&lt;artifactId&gt;maven-cayenne-plugin&lt;/artifactId&gt;
-	&lt;version&gt;X.Y.Z&lt;/version&gt;
+                a DataMap based on an existing database schema. By default, it is bound to the
+                generate-sources phase. This allows you to generate your DataMap prior to building
+                your project, which may be necessary if you are also using the cgen task.</p><table frame="void" id="d0e665"><caption>Table&nbsp;4.5.&nbsp;cdbimport required parameters</caption><col width="14%"><col width="10%"><col width="76%"><thead><tr>
+                            <th>Name</th>
+                            <th>Type</th>
+                            <th>Description</th>
+                        </tr></thead><tbody><tr>
+                            <td><code class="code">map</code>
+                            </td>
+                            <td>File</td>
+                            <td>DataMap XML file which is the destination of the schema import.
+                                Maybe an existing file. If this file does not exist, it is created
+                                when cdbimport is executed. E.g.
+                                    <code class="code">${project.basedir}/src/main/resources/my.map.xml</code></td>
+                        </tr><tr>
+                            <td><code class="code">driver</code></td>
+                            <td>String</td>
+                            <td>A class of JDBC driver to use for the target database.</td>
+                        </tr><tr>
+                            <td><code class="code">url</code></td>
+                            <td>String</td>
+                            <td>JDBC connection URL of a target database.</td>
+                        </tr></tbody></table><p>
+                </p><table frame="void" id="d0e725"><caption>Table&nbsp;4.6.&nbsp;cdbimport optional parameters</caption><col width="25%"><col width="10%"><col width="65%"><thead><tr>
+                            <th>Name</th>
+                            <th>Type</th>
+                            <th>Description</th>
+                        </tr></thead><tbody><tr>
+                            <td><code class="code">adapter</code>
+                            </td>
+                            <td>String</td>
+                            <td>Java class name implementing org.apache.cayenne.dba.DbAdapter. While
+                                this attribute is optional (a generic JdbcAdapter is used if not
+                                set), it is highly recommended to specify correct target
+                                adapter.</td>
+                        </tr><tr>
+                            <td><code class="code">importProcedures</code></td>
+                            <td>boolean</td>
+                            <td>Indicates whether stored procedures should be imported from the
+                                database. Default is false. </td>
+                        </tr><tr>
+                            <td><code class="code">meaningfulPk</code></td>
+                            <td>boolean</td>
+                            <td>Indicates whether primary keys should be mapped as attributes of the
+                                ObjEntity. Default is false. </td>
+                        </tr><tr>
+                            <td><code class="code">namingStrategy</code></td>
+                            <td>String</td>
+                            <td>The naming strategy used for mapping database names to object entity
+                                names. Default is
+                                    <code class="code">org.apache.cayenne.map.naming.SmartNamingStrategy</code>.
+                            </td>
+                        </tr><tr>
+                            <td><code class="code">overwriteExisting</code></td>
+                            <td>boolean</td>
+                            <td>Indicates whether existing DB and object entities should be
+                                overwritten. This is an all-or-nothing setting. If you need finer
+                                granularity, use the CayenneModeler. Default is "true". </td>
+                        </tr><tr>
+                            <td><code class="code">password</code></td>
+                            <td>String</td>
+                            <td>Database user password.</td>
+                        </tr><tr>
+                            <td><code class="code">procedurePattern</code></td>
+                            <td>String</td>
+                            <td>Pattern to match stored procedure names against for import. Default
+                                is to match all stored procedures. This value is only meaningful if
+                                importProcedures is true. </td>
+                        </tr><tr>
+                            <td><code class="code">schemaName</code></td>
+                            <td>String</td>
+                            <td>Database schema to import tables/stored procedures from. </td>
+                        </tr><tr>
+                            <td><code class="code">tablePattern</code></td>
+                            <td>String</td>
+                            <td>Pattern to match table names against for import. Default is to match
+                                all tables. </td>
+                        </tr><tr>
+                            <td><code class="code">username</code></td>
+                            <td>String</td>
+                            <td>Database user name.</td>
+                        </tr></tbody></table><p>
+            </p><p>Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation
+                compared to the cdbgen example above)
+                :</p><pre class="programlisting">&lt;plugin&gt;
+    &lt;groupId&gt;org.apache.cayenne.plugins&lt;/groupId&gt;
+    &lt;artifactId&gt;maven-cayenne-plugin&lt;/artifactId&gt;
+    &lt;version&gt;X.Y.Z&lt;/version&gt;
 
-	&lt;executions&gt;
-		&lt;execution&gt;
-			&lt;configuration&gt;
-				&lt;map&gt;${project.basedir}/src/main/resources/my.map.xml&lt;/map&gt;
-				&lt;url&gt;jdbc:hsqldb:hsql://localhost/testdb&lt;/url&gt;
-				&lt;adapter&gt;org.apache.cayenne.dba.hsqldb.HSQLDBAdapter&lt;/adapter&gt;
-				&lt;driver&gt;org.hsqldb.jdbcDriver&lt;/driver&gt;                        
-				&lt;username&gt;sa&lt;/username&gt;
-			&lt;/configuration&gt;
-			&lt;goals&gt;
-				&lt;goal&gt;cdbimport&lt;/goal&gt;
-			&lt;/goals&gt;
-		&lt;/execution&gt;
-	&lt;/executions&gt;
-&lt;/plugin&gt;</pre></div></div><div class="section" title="Ant Projects"><div class="titlepage"><div><div><h2 class="title"><a name="ant-projects"></a>Ant Projects</h2></div></div></div><div class="section" title="cgen"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cgen"></a>cgen</h3></div></div></div></div><div class="section" title="cdbgen"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdbgen"></a>cdbgen</h3></div></div></div></div><div class="section" title="cdbimport"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdbimport"></a>cdbimport</h3></div></div></div></div><div class="section" title="cdataport"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdataport"></a>cdataport</h3></div></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cayenne-guide-part2.html">Prev</a>&nbsp;</td><td width="20
 %" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="starting-cayenne.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part&nbsp;II.&nbsp;Cayenne Framework&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;5.&nbsp;Starting Cayenne</td></tr></table></div></body></html>
\ No newline at end of file
+    &lt;executions&gt;
+        &lt;execution&gt;
+            &lt;configuration&gt;
+                &lt;map&gt;${project.basedir}/src/main/resources/my.map.xml&lt;/map&gt;
+                &lt;url&gt;jdbc:mysql://127.0.0.1/mydb&lt;/url&gt;
+                &lt;adapter&gt;org.apache.cayenne.dba.hsqldb.HSQLDBAdapter&lt;/adapter&gt;
+                &lt;driver&gt;com.mysql.jdbc.Driver&lt;/driver&gt;
+                &lt;username&gt;sa&lt;/username&gt;
+            &lt;/configuration&gt;
+            &lt;goals&gt;
+                &lt;goal&gt;cdbimport&lt;/goal&gt;
+            &lt;/goals&gt;
+        &lt;/execution&gt;
+    &lt;/executions&gt;
+&lt;/plugin&gt;</pre></div></div><div class="section" title="Ant Projects"><div class="titlepage"><div><div><h2 class="title"><a name="ant-projects"></a>Ant Projects</h2></div></div></div><div class="section" title="cgen"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cgen"></a>cgen</h3></div></div></div></div><div class="section" title="cdbgen"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdbgen"></a>cdbgen</h3></div></div></div></div><div class="section" title="cdbimport"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdbimport"></a>cdbimport</h3></div></div></div><p>This is an Ant counterpart of "cdbimport" goal of maven-cayenne-plugin described
+                above. It has exactly the same properties. Here is a usage
+                example:</p><pre class="programlisting"> &lt;cdbimport map="${context.dir}/WEB-INF/my.map.xml"
+    driver="com.mysql.jdbc.Driver" 
+    url="jdbc:mysql://127.0.0.1/mydb" 
+    username="sa"/&gt; </pre><p>
+            </p></div><div class="section" title="cdataport"><div class="titlepage"><div><div><h3 class="title"><a name="ant-cdataport"></a>cdataport</h3></div></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cayenne-guide-part2.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="cayenne-guide-part2.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="starting-cayenne.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part&nbsp;II.&nbsp;Cayenne Framework&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;5.&nbsp;Starting Cayenne</td></tr></table></div></body></html>
\ No newline at end of file



Mime
View raw message