cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aadamc...@apache.org
Subject svn commit: r1425991 [2/4] - in /cayenne/main/trunk/docs/docbook: cayenne-guide/src/docbkx/ getting-started-rop/src/docbkx/ getting-started/src/docbkx/ stylesheets/
Date Wed, 26 Dec 2012 18:55:53 GMT
Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/expressions.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/expressions.xml?rev=1425991&r1=1425990&r2=1425991&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/expressions.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/expressions.xml Wed Dec 26 18:55:53 2012
@@ -1,249 +1,250 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
-	version="5.0" xml:id="expressions">
-	<title>Expressions</title>
-	<section xml:id="expressions-overview">
-		<title>Expressions Overview</title>
-		<para>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.</para>
-	</section>
-	<section xml:id="path-expressions">
-		<title>Path Expressions</title>
-		<para>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:<programlisting> [db:]segment[+][.segment[+]...]</programlisting><itemizedlist>
-				<listitem>
-					<para>"db:" is an optional prefix indicating that the following path is a DB
-						path. Otherwise it is an object path.</para>
-				</listitem>
-				<listitem>
-					<para>"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 (".").</para>
-				</listitem>
-				<listitem>
-					<para>"+" An "OUTER JOIN" path component. Currently "+" only has effect when
-						translated to SQL as OUTER JOIN. When evaluating expressions in memory, it
-						is ignored.</para>
-				</listitem>
-			</itemizedlist></para>
-		<para>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:</para>
-		<para>
-			<itemizedlist>
-				<listitem>
-					<para>"name" - can be used to navigate (read) the "name" property of a Person
-						(or any other type of object that has a "name" property).</para>
-				</listitem>
-				<listitem>
-					<para>"artist.exhibits.closingDate" - can be used to navigate to a closing date
-						of any of the exhibits of a Painting's Artist object.</para>
-				</listitem>
-				<listitem>
-					<para>"artist.exhibits+.closingDate" - same as the previous example, but when
-						translated into SQL, an OUTER JOIN will be used for "exhibits".</para>
-				</listitem>
-			</itemizedlist>
-		</para>
-		<para>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:<itemizedlist>
-				<listitem>
-					<para>"db:NAME" - can be used to navigate to the value of "NAME" column of some
-						unspecified table.</para>
-				</listitem>
-				<listitem>
-					<para>"db:artist.artistExhibits.exhibit.CLOSING_DATE" - can be used to match a
-						closing date of any of the exhibits of a related artist record.</para>
-				</listitem>
-			</itemizedlist></para>
-		<para>Cayenne supports "aliases" in path Expressions. E.g. the same expression can be
-			written using explicit path or an alias:<itemizedlist>
-				<listitem>
-					<para>"artist.exhibits.closingDate" - full path</para>
-				</listitem>
-				<listitem>
-					<para>"e.closingDate" - alias "e" is used for "artist.exhibits".</para>
-				</listitem>
-			</itemizedlist>SelectQuery using the second form of the path expression must be made
-			aware of the alias via <emphasis role="italic"
-				>"SelectQuery.aliasPathSplits(..)"</emphasis>, 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.</para>
-	</section>
-	<section xml:id="expressions-from-strings">
-		<title>Creating Expressions from Strings </title>
-		<para>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>Expression.fromString</code>
-			static method. Here is an
-			example:<programlisting>String expString = "name like 'A%' and price &lt; 1000";
+    version="5.0" xml:id="expressions">
+    <title>Expressions</title>
+    <section xml:id="expressions-overview">
+        <title>Expressions Overview</title>
+        <para>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.</para>
+    </section>
+    <section xml:id="path-expressions">
+        <title>Path Expressions</title>
+        <para>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:<programlisting> [db:]segment[+][.segment[+]...]</programlisting><itemizedlist>
+                <listitem>
+                    <para>&quot;db:&quot; is an optional prefix indicating that the following path is a DB
+                        path. Otherwise it is an object path.</para>
+                </listitem>
+                <listitem>
+                    <para>&quot;segment&quot; 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 (&quot;.&quot;).</para>
+                </listitem>
+                <listitem>
+                    <para>&quot;+&quot; An &quot;OUTER JOIN&quot; path component. Currently &quot;+&quot; only has effect when
+                        translated to SQL as OUTER JOIN. When evaluating expressions in memory, it
+                        is ignored.</para>
+                </listitem>
+            </itemizedlist></para>
+        <para>An object path expression represents a chain of property names rooted in a certain
+            (unspecified during expression creation) object and &quot;navigating&quot; to its related value.
+            E.g. a path expression &quot;artist.name&quot; 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:</para>
+        <para>
+            <itemizedlist>
+                <listitem>
+                    <para>&quot;name&quot; - can be used to navigate (read) the &quot;name&quot; property of a Person
+                        (or any other type of object that has a &quot;name&quot; property).</para>
+                </listitem>
+                <listitem>
+                    <para>&quot;artist.exhibits.closingDate&quot; - can be used to navigate to a closing date
+                        of any of the exhibits of a Painting&apos;s Artist object.</para>
+                </listitem>
+                <listitem>
+                    <para>&quot;artist.exhibits+.closingDate&quot; - same as the previous example, but when
+                        translated into SQL, an OUTER JOIN will be used for &quot;exhibits&quot;.</para>
+                </listitem>
+            </itemizedlist>
+        </para>
+        <para>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 -  &quot;db:dbrelationshipX.dbrelationshipY.COLUMN_Z&quot;. More specific examples:<itemizedlist>
+                <listitem>
+                    <para>&quot;db:NAME&quot; - can be used to navigate to the value of &quot;NAME&quot; column of some
+                        unspecified table.</para>
+                </listitem>
+                <listitem>
+                    <para>&quot;db:artist.artistExhibits.exhibit.CLOSING_DATE&quot; - can be used to match a
+                        closing date of any of the exhibits of a related artist record.</para>
+                </listitem>
+            </itemizedlist></para>
+        <para>Cayenne supports &quot;aliases&quot; in path Expressions. E.g. the same expression can be
+            written using explicit path or an alias:<itemizedlist>
+                <listitem>
+                    <para>&quot;artist.exhibits.closingDate&quot; - full path</para>
+                </listitem>
+                <listitem>
+                    <para>&quot;e.closingDate&quot; - alias &quot;e&quot; is used for &quot;artist.exhibits&quot;.</para>
+                </listitem>
+            </itemizedlist>SelectQuery using the second form of the path expression must be made
+            aware of the alias via <emphasis role="italic">
+                &quot;SelectQuery.aliasPathSplits(..)&quot;</emphasis>, 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.</para>
+    </section>
+    <section xml:id="expressions-from-strings">
+        <title>Creating Expressions from Strings </title>
+        <para>While in most cases users are likely to rely on API from the following section for
+            expression creation, we&apos;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>Expression.fromString</code>
+            static method. Here is an
+            example:<programlisting>String expString = &quot;name like &apos;A%&apos; and price &lt; 1000&quot;;
 Expression exp = Expression.fromString(expString);</programlisting>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... </para>
-		<para><emphasis role="italic">Character constants</emphasis> that are not paths or numeric values
-			should be enclosed in single or double quotes. Two of the expressions below are
-			equivalent:<programlisting>name = 'ABC'
+            particular expression may be used to match Paintings with names that start with &quot;A&quot; and
+            a price less than $1000. While this example is pretty self-explanatory, there are a few
+            points worth mentioning. &quot;name&quot; and &quot;price&quot; 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 &quot;may be used to match Paintings&quot;, we are implying that there
+            may be other entities, for which this expression is valid. Now the expression details... </para>
+        <para><emphasis role="italic">Character constants</emphasis> that are not paths or numeric values
+            should be enclosed in single or double quotes. Two of the expressions below are
+            equivalent:<programlisting>name = &apos;ABC&apos;
 
 // double quotes are escaped inside Java Strings of course
-name = \"ABC\"</programlisting></para>
-		<para><emphasis role="italic">Case sensitivity.</emphasis> Expression operators are all case
-			sensitive and are usually lowercase. Complex words follow the java camel-case
-			style:<programlisting>// valid
-name likeIgnoreCase 'A%'
+name = \&quot;ABC\&quot;</programlisting></para>
+        <para><emphasis role="italic">Case sensitivity.</emphasis> Expression operators are all case
+            sensitive and are usually lowercase. Complex words follow the java camel-case
+            style:<programlisting>// valid
+name likeIgnoreCase &apos;A%&apos;
 
 // invalid - will throw a parse exception
-name LIKEIGNORECASE 'A%'</programlisting></para>
-		<para><emphasis role="italic">Grouping with
-			parenthesis</emphasis>:<programlisting>value = (price + 250.00) * 3</programlisting></para>
-		<para><emphasis role="italic">Path prefixes.</emphasis> 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:<programlisting>// object path
-name = 'Salvador Dali'
+name LIKEIGNORECASE &apos;A%&apos;</programlisting></para>
+        <para><emphasis role="italic">Grouping with parenthesis:</emphasis>
+            <programlisting>value = (price + 250.00) * 3</programlisting>
+        </para>
+        <para><emphasis role="italic">Path prefixes.</emphasis> Object expressions are unquoted strings,
+            optionally prefixed by &quot;obj:&quot; (usually they are not prefixed at all actually). Database
+            expressions are always prefixed with &quot;db:&quot;. A special kind of prefix, not discussed yet
+            is &quot;enum:&quot; that prefixes an enumeration
+            constant:<programlisting>// object path
+name = &apos;Salvador Dali&apos;
 
 // same object path - a rarely used form
-obj:name = 'Salvador Dali'
+obj:name = &apos;Salvador Dali&apos;
 
 // multi-segment object path
-artist.name = 'Salvador Dali'
+artist.name = &apos;Salvador Dali&apos;
 
 // db path
-db:NAME = 'Salvador Dali'
+db:NAME = &apos;Salvador Dali&apos;
 
 // enumeration constant
 name = enum:org.foo.EnumClass.VALUE1</programlisting></para>
-		<para>
-			<emphasis role="italic">Binary conditions</emphasis> 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:<programlisting>name like 'A%'</programlisting><emphasis role="italic"
-				>Named parameters.</emphasis> 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:<programlisting>Expression template = Expression.fromString("name = $name");
+        <para>
+            <emphasis role="italic">Binary conditions</emphasis> 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:<programlisting>name like &apos;A%&apos;</programlisting>
+            <emphasis role="italic">Named parameters.</emphasis> Expressions can have named parameters (names that
+            start with &quot;$&quot;). Parameterized expressions allow to create reusable expression
+            templates. Also if an Expression contains a complex object that doesn&apos;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:<programlisting>Expression template = Expression.fromString(&quot;name = $name&quot;);
 ...
-Map p1 = Collections.singletonMap("name", "Salvador Dali");
+Map p1 = Collections.singletonMap(&quot;name&quot;, &quot;Salvador Dali&quot;);
 Expression qualifier1 = template.expWithParameters(p1);
 ...
-Map p2 = Collections.singletonMap("name", "Monet");
+Map p2 = Collections.singletonMap(&quot;name&quot;, &quot;Monet&quot;);
 Expression qualifier2 = template.expWithParameters(p2);</programlisting>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:<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:<programlisting>Expression template = Expression.fromString(&quot;name like $name&quot;);
 ...
-Map p1 = Collections.singletonMap("name", "Salvador%");
+Map p1 = Collections.singletonMap(&quot;name&quot;, &quot;Salvador%&quot;);
 Expression qualifier1 = template.expWithParameters(p1);</programlisting>When
-			matching on a relationship, parameters can be Persistent objects or
-			ObjectIds:<programlisting>Expression template = Expression.fromString("artist = $artist");
+            matching on a relationship, parameters can be Persistent objects or
+            ObjectIds:<programlisting>Expression template = Expression.fromString(&quot;artist = $artist&quot;);
 ...
 Artist dali = // asume we fetched this one already
-Map p1 = Collections.singletonMap("artist", dali);
+Map p1 = Collections.singletonMap(&quot;artist&quot;, dali);
 Expression qualifier1 = template.expWithParameters(p1);</programlisting>Uninitialized
-			parameters will be automatically pruned from expressions, so a user can omit some
-			parameters when creating an expression from a parameterized
-			template:<programlisting>Expression template = Expression.fromString("name like $name and dateOfBirth > $date");
+            parameters will be automatically pruned from expressions, so a user can omit some
+            parameters when creating an expression from a parameterized
+            template:<programlisting>Expression template = Expression.fromString(&quot;name like $name and dateOfBirth &gt; $date&quot;);
 ...
-Map p1 = Collections.singletonMap("name", "Salvador%");
+Map p1 = Collections.singletonMap(&quot;name&quot;, &quot;Salvador%&quot;);
 Expression qualifier1 = template.expWithParameters(p1);
 
-// qualifier1 is now equals to "name like 'Salvador%'", the 'dateOfBirth' condition was 
+// qualifier1 is now equals to &quot;name like &apos;Salvador%&apos;&quot;, the &apos;dateOfBirth&apos; condition was
 // pruned, as no value was specified for the $date parameter</programlisting></para>
-		<para><emphasis role="italic">Null handling.</emphasis> 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.</para>
-		<para>
-			<note>
-				<para>A formal definition of all possible valid expressions in a form of JavaCC
-					grammar is provided in Appendix C</para>
-			</note>
-		</para>
-	</section>
-	<section xml:id="expressions-with-expressionfactory">
-		<title>Creating Expressions with API</title>
-		<para>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. </para>
-		<para>The following code recreates the expression from the previous chapter, but now using
-			expression
-			API:<programlisting language="java">// String expression: name like 'A%' and price &lt; 1000
-Expression e1 = ExpressionFactory.likeExp(Painting.NAME_PROPERTY, "A%");
+        <para><emphasis role="italic">Null handling.</emphasis> 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), &quot;=&quot; and &quot;!=&quot; expressions can be used directly with null
+            values. It is up to Cayenne to translate expressions with nulls to the valid SQL.</para>
+        <para>
+            <note>
+                <para>A formal definition of all possible valid expressions in a form of JavaCC
+                    grammar is provided in Appendix C</para>
+            </note>
+        </para>
+    </section>
+    <section xml:id="expressions-with-expressionfactory">
+        <title>Creating Expressions with API</title>
+        <para>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&apos;t be going over all of them in detail, but will rather show a few
+            general examples and some gotchas. </para>
+        <para>The following code recreates the expression from the previous chapter, but now using
+            expression
+            API:<programlisting>// String expression: name like &apos;A%&apos; and price &lt; 1000
+Expression e1 = ExpressionFactory.likeExp(Painting.NAME_PROPERTY, &quot;A%&quot;);
 Expression e2 = ExpressionFactory.lessExp(Painting.PRICE_PROPERTY, 1000);
 Expression finalExp = e1.andExp(e2); </programlisting>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.<note>
-				<para>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.</para>
-			</note></para>
-		<para>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:<programlisting language="java">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.<note>
+                <para>The last line in the example above shows how to create a new expression by
+                    &quot;chaining&quot; 2 other epxressions. A common error when chaining expressions is to
+                    assume that &quot;andExp&quot; and &quot;orExp&quot; append another expression to the current
+                    expression. In fact a new expression is created. I.e. Expression API treats
+                    existing expressions as immutable.</para>
+            </note></para>
+        <para>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 &quot;split&quot; match paths into individual joins if
+            needed:<programlisting>Expression matchAllExp(String path, Collection values)
 Expression matchAllExp(String path, Object... values)</programlisting></para>
-		<para>"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.</para>
-	</section>
-	<section xml:id="expressions-in-memory">
-		<title>Evaluating Expressions in Memory</title>
-		<para>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. </para>
-		<para>Checking whether an object satisfies an
-			expression:<programlisting language="java">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
+        <para>&quot;Path&quot; argument to both of these methods can use a split character (a pipe symbol &apos;|&apos;)
+            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. &quot;|exhibits.paintings&quot;,
+            &quot;exhibits|paintings&quot;, etc. Internally Cayenne would generate distinct aliases for each
+            of the split expressions, forcing separate joins.</para>
+    </section>
+    <section xml:id="expressions-in-memory">
+        <title>Evaluating Expressions in Memory</title>
+        <para>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. </para>
+        <para>Checking whether an object satisfies an
+            expression:<programlisting>Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, &quot;John&quot;, &quot;Bob&quot;);
 User user = ...
 if(e.match(user)) {
    ...
 }</programlisting>Reading
-			property
-			value:<programlisting language="java">Expression e = Expression.fromString(User.NAME_PROPERTY);
+            property
+            value:<programlisting>Expression e = Expression.fromString(User.NAME_PROPERTY);
 String name = e.evaluate(user);</programlisting></para>
-		<para>Filtering a list of
-			objects:<programlisting language="java">Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, "John", "Bob");
-List&lt;User> unfiltered = ...
-List&lt;User> filtered = e.filterObjects(unfiltered);</programlisting></para>
-		<para>
-			<note>
-				<para>Current limitation of in-memory expressions is that no collections are
-					permitted in the property path.</para>
-			</note>
-		</para>
-	</section>
+        <para>Filtering a list of
+            objects:<programlisting>Expression e = ExpressionFactory.inExp(User.NAME_PROPERTY, &quot;John&quot;, &quot;Bob&quot;);
+List&lt;User&gt; unfiltered = ...
+List&lt;User&gt; filtered = e.filterObjects(unfiltered);</programlisting></para>
+        <para>
+            <note>
+                <para>Current limitation of in-memory expressions is that no collections are
+                    permitted in the property path.</para>
+            </note>
+        </para>
+    </section>
 </chapter>

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml?rev=1425991&r1=1425990&r2=1425991&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/implementing-rop-server.xml Wed Dec 26 18:55:53 2012
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
-	version="5.0" xml:id="implementing-rop-server">
-	<title>Implementing ROP Server</title>
+    version="5.0" xml:id="implementing-rop-server">
+    <title>Implementing ROP Server</title>
 </chapter>

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml?rev=1425991&r1=1425990&r2=1425991&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/including-cayenne-in-project.xml Wed Dec 26 18:55:53 2012
@@ -1,245 +1,241 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
-	version="5.0" xml:id="including-cayenne-in-project">
-	<title>Including Cayenne in a Project</title>
-	<section xml:id="jar-files-and-depdendencies">
-		<title>Jar Files and Dependencies</title>
-		<para>Cayenne distribution contains the following core runtime jars in the distribution
-				<code>lib</code> directory: <itemizedlist>
-				<listitem>
-					<para><emphasis role="italic">cayenne-server-x.x.jar</emphasis> - contains full
-						Cayenne runtime (DI, adapters, DB access classes, etc.). Most applications
-						will use only this file.</para>
-				</listitem>
-				<listitem>
-					<para>cayenne-client-x.x.jar - a subset of cayenne-server.jar trimmed for use on
-						the client in an ROP application.</para>
-				</listitem>
-				<listitem>
-					<para>Other cayenne-* jars - various Cayenne extensions.</para>
-				</listitem>
-			</itemizedlist></para>
-		<para>When using <code>cayenne-server-x.x.jar</code> you'll need a few third party jars (all
-			included in <code>lib/third-party</code> directory of the distribution): <itemizedlist>
-				<listitem>
-					<para><link xlink:href="http://velocity.apache.org/">Apache Velocity
-							Template Engine</link>, version 1.6.x (and all its dependencies bundled
-						with velocity-dep)</para>
-				</listitem>
-				<listitem>
-					<para><link xlink:href="http://commons.apache.org/collections/">Apache Commons
-							Collections</link>, version 3.2.1</para>
-				</listitem>
-				<listitem>
-					<para><link xlink:href="http://commons.apache.org/logging/">Apache
-							Commons Logging</link>, version 1.1</para>
-				</listitem>
-			</itemizedlist></para>
-		<para>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.</para>
-	</section>
-	<section xml:id="maven-projects">
-		<title>Maven Projects</title>
-		<para>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:<programlisting>&lt;dependency>
+    version="5.0" xml:id="including-cayenne-in-project">
+    <title>Including Cayenne in a Project</title>
+    <section xml:id="jar-files-and-depdendencies">
+        <title>Jar Files and Dependencies</title>
+        <para>Cayenne distribution contains the following core runtime jars in the distribution
+                <code>lib</code> directory: <itemizedlist>
+                <listitem>
+                    <para><emphasis role="italic">cayenne-server-x.x.jar</emphasis> - contains full
+                        Cayenne runtime (DI, adapters, DB access classes, etc.). Most applications
+                        will use only this file.</para>
+                </listitem>
+                <listitem>
+                    <para>cayenne-client-x.x.jar - a subset of cayenne-server.jar trimmed for use on
+                        the client in an ROP application.</para>
+                </listitem>
+                <listitem>
+                    <para>Other cayenne-* jars - various Cayenne extensions.</para>
+                </listitem>
+            </itemizedlist></para>
+        <para>When using <code>cayenne-server-x.x.jar</code> you'll need a few third party jars (all
+            included in <code>lib/third-party</code> directory of the distribution): <itemizedlist>
+                <listitem>
+                    <para><link xlink:href="http://velocity.apache.org/">Apache Velocity
+                            Template Engine</link>, version 1.6.x (and all its dependencies bundled
+                        with velocity-dep)</para>
+                </listitem>
+                <listitem>
+                    <para><link xlink:href="http://commons.apache.org/collections/">Apache Commons
+                            Collections</link>, version 3.2.1</para>
+                </listitem>
+                <listitem>
+                    <para><link xlink:href="http://commons.apache.org/logging/">Apache
+                            Commons Logging</link>, version 1.1</para>
+                </listitem>
+            </itemizedlist></para>
+        <para>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.</para>
+    </section>
+    <section xml:id="maven-projects">
+        <title>Maven Projects</title>
+        <para>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:<programlisting>&lt;dependency>
    &lt;groupId>org.apache.cayenne&lt;/groupId>
    &lt;artifactId>cayenne-server&lt;/artifactId>
    &lt;version>X.Y.Z&lt;/version>
 &lt;/dependency></programlisting></para>
-		<para>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>org.apache.cayenne.plugins:maven-cayenne-plugin</code>.</para>
-		<section xml:id="mvn-cgen">
-			<title>cgen</title>
-			<para><code>cgen</code> is a <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. </para>
-			<para>By creating custom templates, you can use cgen to generate other output (such as
-				web pages, reports, specialized code templates) based on DataMap information.</para>
-			<para>
-                <div class="table">
-				<table frame="void">
-					<caption>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>map</code>
-							</td>
-							<td>File</td>
-							<td>DataMap XML file which serves as a source of metadata for class
-								generation. E.g.
-									<code>${project.basedir}/src/main/resources/my.map.xml</code></td>
-						</tr>
-						<tr>
-							<td><code>destDir</code></td>
-							<td>File</td>
-							<td>Root destination directory for Java classes (ignoring their package
-								names).</td>
-						</tr>
-					</tbody>
-				</table>
-                </div>
-                <div class="table">
-				<table frame="void">
-					<caption>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>
-                </div>
+        <para>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>org.apache.cayenne.plugins:maven-cayenne-plugin</code>.</para>
+        <section xml:id="mvn-cgen">
+            <title>cgen</title>
+            <para><code>cgen</code> is a <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. </para>
+            <para>By creating custom templates, you can use cgen to generate other output (such as
+                web pages, reports, specialized code templates) based on DataMap information.</para>
+            <para>
+                <table frame="void">
+                    <caption>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>map</code>
+                            </td>
+                            <td>File</td>
+                            <td>DataMap XML file which serves as a source of metadata for class
+                                generation. E.g.
+                                    <code>${project.basedir}/src/main/resources/my.map.xml</code></td>
+                        </tr>
+                        <tr>
+                            <td><code>destDir</code></td>
+                            <td>File</td>
+                            <td>Root destination directory for Java classes (ignoring their package
+                                names).</td>
+                        </tr>
+                    </tbody>
+                </table>
+                <table frame="void">
+                    <caption>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>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>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>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>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>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>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>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>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>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>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>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>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>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>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>
                 Example - a typical class generation scenario, where pairs of classes are
-				generated, and superclasses are placed in a separate package:
-				<programlisting>&lt;plugin>
-	&lt;groupId>org.apache.cayenne.plugins&lt;/groupId>
-	&lt;artifactId>maven-cayenne-plugin&lt;/artifactId>
-	&lt;version>X.Y.Z&lt;/version>
+                generated, and superclasses are placed in a separate package:
+                <programlisting>&lt;plugin>
+    &lt;groupId>org.apache.cayenne.plugins&lt;/groupId>
+    &lt;artifactId>maven-cayenne-plugin&lt;/artifactId>
+    &lt;version>X.Y.Z&lt;/version>
 
-	&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.
-	-->
-	&lt;configuration>
-		&lt;map>${project.basedir}/src/main/resources/my.map.xml&lt;/map>
-		&lt;destDir>${project.basedir}/src/main/java&lt;/destDir>
-		&lt;superPkg>org.example.model.auto&lt;/superPkg>
-	&lt;/configuration>
+    -->
+    &lt;configuration>
+        &lt;map>${project.basedir}/src/main/resources/my.map.xml&lt;/map>
+        &lt;destDir>${project.basedir}/src/main/java&lt;/destDir>
+        &lt;superPkg>org.example.model.auto&lt;/superPkg>
+    &lt;/configuration>
 
-	&lt;executions>
-		&lt;execution>
-			&lt;goals>
-				&lt;goal>cgen&lt;/goal>
-			&lt;/goals>
-		&lt;/execution>
-	&lt;/executions>
+    &lt;executions>
+        &lt;execution>
+            &lt;goals>
+                &lt;goal>cgen&lt;/goal>
+            &lt;/goals>
+        &lt;/execution>
+    &lt;/executions>
 &lt;/plugin></programlisting></para>
 		</section>
 		<section xml:id="mvn-cdbgen">
@@ -346,24 +342,23 @@
 			</para>
 			<para>Example - creating a DB schema on a local HSQLDB
 				database:<programlisting>&lt;plugin>
-	&lt;groupId>org.apache.cayenne.plugins&lt;/groupId>
-	&lt;artifactId>maven-cayenne-plugin&lt;/artifactId>
-	&lt;version>X.Y.Z&lt;/version>
-
-	&lt;executions>
-		&lt;execution>
-			&lt;configuration>
-				&lt;map>${project.basedir}/src/main/resources/my.map.xml&lt;/map>
-				&lt;url>jdbc:hsqldb:hsql://localhost/testdb&lt;/url>
-				&lt;adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter&lt;/adapter>
-				&lt;driver>org.hsqldb.jdbcDriver&lt;/driver>                        
-				&lt;username>sa&lt;/username>
-			&lt;/configuration>
-			&lt;goals>
-				&lt;goal>cdbgen&lt;/goal>
-			&lt;/goals>
-		&lt;/execution>
-	&lt;/executions>
+    &lt;groupId>org.apache.cayenne.plugins&lt;/groupId>
+    &lt;artifactId>maven-cayenne-plugin&lt;/artifactId>
+    &lt;version>X.Y.Z&lt;/version>
+    &lt;executions>
+        &lt;execution>
+            &lt;configuration>
+                &lt;map>${project.basedir}/src/main/resources/my.map.xml&lt;/map>
+                &lt;url>jdbc:hsqldb:hsql://localhost/testdb&lt;/url>
+                &lt;adapter>org.apache.cayenne.dba.hsqldb.HSQLDBAdapter&lt;/adapter>
+                &lt;driver>org.hsqldb.jdbcDriver&lt;/driver>
+                &lt;username>sa&lt;/username>
+            &lt;/configuration>
+            &lt;goals>
+                &lt;goal>cdbgen&lt;/goal>
+            &lt;/goals>
+        &lt;/execution>
+    &lt;/executions>
 &lt;/plugin></programlisting></para>
 		</section>
 		<section xml:id="mvn-cdbimport">
@@ -538,44 +533,44 @@
 			<para>Example - loading a DB schema from a local HSQLDB database (essentially a reverse operation
 				compared to the cdbgen example above)
 				:<programlisting>&lt;plugin>
-	&lt;groupId>org.apache.cayenne.plugins&lt;/groupId>
-	&lt;artifactId>maven-cayenne-plugin&lt;/artifactId>
-	&lt;version>X.Y.Z&lt;/version>
+    &lt;groupId>org.apache.cayenne.plugins&lt;/groupId>
+    &lt;artifactId>maven-cayenne-plugin&lt;/artifactId>
+    &lt;version>X.Y.Z&lt;/version>
 
-	&lt;executions>
-		&lt;execution>
-			&lt;configuration>
-				&lt;map>${project.basedir}/src/main/resources/my.map.xml&lt;/map>
-				&lt;url>jdbc:mysql://127.0.0.1/mydb&lt;/url>
-				&lt;driver>com.mysql.jdbc.Driver&lt;/driver>                        
-				&lt;username>sa&lt;/username>
-				&lt;defaultPackage>com.example.cayenne&lt;/defaultPackage>
-			&lt;/configuration>
-			&lt;goals>
-				&lt;goal>cdbimport&lt;/goal>
-			&lt;/goals>
-		&lt;/execution>
-	&lt;/executions>
+    &lt;executions>
+        &lt;execution>
+            &lt;configuration>
+                &lt;map>${project.basedir}/src/main/resources/my.map.xml&lt;/map>
+                &lt;url>jdbc:mysql://127.0.0.1/mydb&lt;/url>
+                &lt;driver>com.mysql.jdbc.Driver&lt;/driver>                        
+                &lt;username>sa&lt;/username>
+                &lt;defaultPackage>com.example.cayenne&lt;/defaultPackage>
+            &lt;/configuration>
+            &lt;goals>
+                &lt;goal>cdbimport&lt;/goal>
+            &lt;/goals>
+        &lt;/execution>
+    &lt;/executions>
 &lt;/plugin></programlisting></para>
-		</section>
-	</section>
-	<section xml:id="ant-projects">
-		<title>Ant Projects</title>
-		<section xml:id="ant-cgen">
-			<title>cgen</title>
-		</section>
-		<section xml:id="ant-cdbgen">
-			<title>cdbgen</title>
-		</section>
-		<section xml:id="ant-cdbimport">
-			<title>cdbimport</title>
-			<para>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:<programlisting> &lt;cdbimport map="${context.dir}/WEB-INF/my.map.xml"
+        </section>
+    </section>
+    <section xml:id="ant-projects">
+        <title>Ant Projects</title>
+        <section xml:id="ant-cgen">
+            <title>cgen</title>
+        </section>
+        <section xml:id="ant-cdbgen">
+            <title>cdbgen</title>
+        </section>
+        <section xml:id="ant-cdbimport">
+            <title>cdbimport</title>
+            <para>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:<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"
-	defaultPackage="com.example.cayenne"/> </programlisting>
+    defaultPackage="com.example.cayenne"/> </programlisting>
 			</para>
 		</section>
 		<section xml:id="ant-cdataport">

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/index.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/index.xml?rev=1425991&r1=1425990&r2=1425991&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/index.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/index.xml Wed Dec 26 18:55:53 2012
@@ -1,31 +1,31 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
-	xml:id="cayenne-guide" xmlns:xi="http://www.w3.org/2001/XInclude">
-	<info>
-		<title>Cayenne Guide</title>
-		<copyright>
-			<year>2011-2012</year>
-			<holder>Apache Software Foundation and individual authors</holder>
-		</copyright>
-		<legalnotice>
-			<title>License</title>
-			<para>Licensed to the Apache Software Foundation (ASF) under one or more contributor
-				license agreements. See the NOTICE file distributed with this work for additional
-				information regarding copyright ownership. The ASF licenses this file to you under
-				the Apache License, Version 2.0 (the "License"); you may not use this file except in
-				compliance with the License. You may obtain a copy of the License at
-				http://www.apache.org/licenses/LICENSE-2.0</para>
+    xml:id="cayenne-guide" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <info>
+        <title>Cayenne Guide</title>
+        <copyright>
+            <year>2011-2012</year>
+            <holder>Apache Software Foundation and individual authors</holder>
+        </copyright>
+        <legalnotice>
+            <title>License</title>
+            <para>Licensed to the Apache Software Foundation (ASF) under one or more contributor
+                license agreements. See the NOTICE file distributed with this work for additional
+                information regarding copyright ownership. The ASF licenses this file to you under
+                the Apache License, Version 2.0 (the "License"); you may not use this file except in
+                compliance with the License. You may obtain a copy of the License at
+                http://www.apache.org/licenses/LICENSE-2.0</para>
 
-			<para>Unless required by applicable law or agreed to in writing, software distributed
-				under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-				CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
-				language governing permissions and limitations under the License.</para>
-		</legalnotice>
-	</info>
-	<xi:include href="part1.xml"/>
-	<xi:include href="part2.xml"/>
-	<xi:include href="part3.xml"/>
-	<xi:include href="appendix-a.xml"/>
-	<xi:include href="appendix-b.xml"/>
-	<xi:include href="appendix-c.xml"/>
+            <para>Unless required by applicable law or agreed to in writing, software distributed
+                under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+                CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
+                language governing permissions and limitations under the License.</para>
+        </legalnotice>
+    </info>
+    <xi:include href="part1.xml"/>
+    <xi:include href="part2.xml"/>
+    <xi:include href="part3.xml"/>
+    <xi:include href="appendix-a.xml"/>
+    <xi:include href="appendix-b.xml"/>
+    <xi:include href="appendix-c.xml"/>
 </book>

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/introduction-to-rop.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/introduction-to-rop.xml?rev=1425991&r1=1425990&r2=1425991&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/introduction-to-rop.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/introduction-to-rop.xml Wed Dec 26 18:55:53 2012
@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
-	version="5.0" xml:id="introduction-to-rop">
-	<title>Introduction to ROP</title>
-	<section xml:id="what-is-rop">
-		<title>What is ROP</title>
-	</section>
-	<section xml:id="main-features">
-		<title>Main Features</title>
-	</section>
+    version="5.0" xml:id="introduction-to-rop">
+    <title>Introduction to ROP</title>
+    <section xml:id="what-is-rop">
+        <title>What is ROP</title>
+    </section>
+    <section xml:id="main-features">
+        <title>Main Features</title>
+    </section>
 </chapter>

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml?rev=1425991&r1=1425990&r2=1425991&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/lifecycle-events.xml Wed Dec 26 18:55:53 2012
@@ -1,20 +1,20 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
-	version="5.0" xml:id="lifecycle-events">
-	<title>Lifecycle Events</title>
-	<section xml:id="types-of-lifecycle-events">
-		<title>Types of Lifecycle Events</title>
-	</section>
-	<section xml:id="lifecycle-callbacks-listeners">
-		<title>Lifecycle Callbacks and Listeners</title>
-		<section xml:id="callback-listener-method-semantics">
-			<title>Callback and Listener Methods Semantics</title>
-		</section>
-		<section xml:id="registering-callbacks-listeners">
-			<title>Registering Callbacks and Listeners</title>
-		</section>
-		<section xml:id="comining-listeners-with-datachannelfilters">
-			<title>Combining Listeners with DataChannelFilters</title>
-		</section>
-	</section>
+    version="5.0" xml:id="lifecycle-events">
+    <title>Lifecycle Events</title>
+    <section xml:id="types-of-lifecycle-events">
+        <title>Types of Lifecycle Events</title>
+    </section>
+    <section xml:id="lifecycle-callbacks-listeners">
+        <title>Lifecycle Callbacks and Listeners</title>
+        <section xml:id="callback-listener-method-semantics">
+            <title>Callback and Listener Methods Semantics</title>
+        </section>
+        <section xml:id="registering-callbacks-listeners">
+            <title>Registering Callbacks and Listeners</title>
+        </section>
+        <section xml:id="comining-listeners-with-datachannelfilters">
+            <title>Combining Listeners with DataChannelFilters</title>
+        </section>
+    </section>
 </chapter>

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/orderings.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/orderings.xml?rev=1425991&r1=1425990&r2=1425991&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/orderings.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/orderings.xml Wed Dec 26 18:55:53 2012
@@ -1,16 +1,16 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
-	version="5.0" xml:id="orderings">
-	<title>Orderings</title>
-		<para>An Ordering object defines how a list of objects should be ordered. Orderings are
-			essentially path expressions combined with a sorting strategy. Creating an Ordering:
-			<programlisting language="java">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASENDING);</programlisting></para>
-		<para>Like expressions, orderings are translated into SQL as parts of queries (and the sorting
-		occurs in the database). Also like expressions, orderings can be used in memory, naturally -
-		to sort
-		objects:<programlisting language="java">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASCENDING_INSENSITIVE);
+    version="5.0" xml:id="orderings">
+    <title>Orderings</title>
+        <para>An Ordering object defines how a list of objects should be ordered. Orderings are
+            essentially path expressions combined with a sorting strategy. Creating an Ordering:
+            <programlisting language="java">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASENDING);</programlisting></para>
+        <para>Like expressions, orderings are translated into SQL as parts of queries (and the sorting
+        occurs in the database). Also like expressions, orderings can be used in memory, naturally -
+        to sort
+        objects:<programlisting language="java">Ordering o = new Ordering(Painting.NAME_PROPERTY, SortOrder.ASCENDING_INSENSITIVE);
 List&lt;Painting> list = ...
 o.orderList(list);</programlisting>Note
-		that unlike filtering with Expressions, ordering is performed in-place. This list object is
-		reordered and no new list is created.</para>
+        that unlike filtering with Expressions, ordering is performed in-place. This list object is
+        reordered and no new list is created.</para>
 </chapter>

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/part2.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/part2.xml?rev=1425991&r1=1425990&r2=1425991&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/part2.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/part2.xml Wed Dec 26 18:55:53 2012
@@ -1,14 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
-	xml:id="cayenne-guide-part2" xmlns:xi="http://www.w3.org/2001/XInclude">
-	<title>Cayenne Framework</title>
-	<xi:include href="including-cayenne-in-project.xml"/>
-	<xi:include href="starting-cayenne.xml"/>
-	<xi:include href="persistent-objects-objectcontext.xml"/>
-	<xi:include href="expressions.xml"/>
-	<xi:include href="orderings.xml"/>
-	<xi:include href="queries.xml"/>
-	<xi:include href="lifecycle-events.xml"/>
-	<xi:include href="performance-tuning.xml"/>
-	<xi:include href="customizing-cayenne-runtime.xml"/>
+    xml:id="cayenne-guide-part2" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <title>Cayenne Framework</title>
+    <xi:include href="including-cayenne-in-project.xml"/>
+    <xi:include href="starting-cayenne.xml"/>
+    <xi:include href="persistent-objects-objectcontext.xml"/>
+    <xi:include href="expressions.xml"/>
+    <xi:include href="orderings.xml"/>
+    <xi:include href="queries.xml"/>
+    <xi:include href="lifecycle-events.xml"/>
+    <xi:include href="performance-tuning.xml"/>
+    <xi:include href="customizing-cayenne-runtime.xml"/>
 </part>

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/part3.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/part3.xml?rev=1425991&r1=1425990&r2=1425991&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/part3.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/part3.xml Wed Dec 26 18:55:53 2012
@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
-	xml:id="cayenne-guide-part3" xmlns:xi="http://www.w3.org/2001/XInclude">
-	<title>Cayenne Framework - Remote Object Persistence </title>
-	<xi:include href="introduction-to-rop.xml"/>
-	<xi:include href="rop-setup.xml"/>
-	<xi:include href="implementing-rop-server.xml"/>
-	<xi:include href="implementing-rop-client.xml"/>
-	<xi:include href="rop-deployment.xml"/>
-	<xi:include href="current-limitations.xml"/>
+    xml:id="cayenne-guide-part3" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <title>Cayenne Framework - Remote Object Persistence </title>
+    <xi:include href="introduction-to-rop.xml"/>
+    <xi:include href="rop-setup.xml"/>
+    <xi:include href="implementing-rop-server.xml"/>
+    <xi:include href="implementing-rop-client.xml"/>
+    <xi:include href="rop-deployment.xml"/>
+    <xi:include href="current-limitations.xml"/>
 </part>

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml?rev=1425991&r1=1425990&r2=1425991&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml Wed Dec 26 18:55:53 2012
@@ -1,16 +1,16 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
-	version="5.0" xml:id="performance-tuning">
-	<title>Performance Tuning</title>
-	<section xml:id="prefetching">
-		<title>Prefetching</title>
-		<para>Prefetching is a technique that allows to bring back in one query not only the queried
-			objects, but also objects related to them. In other words it is a controlled eager
-			relationship resolving mechanism. Prefetching is discussed in the "Performance Tuning"
-			chapter, as it is a powerful performance optimization method. Another common application
-			of prefetching is for refreshing stale object relationships.</para>
-		<para>Prefetching example:
-			<programlisting language="java">SelectQuery query = new SelectQuery(Artist.class);
+    version="5.0" xml:id="performance-tuning">
+    <title>Performance Tuning</title>
+    <section xml:id="prefetching">
+        <title>Prefetching</title>
+        <para>Prefetching is a technique that allows to bring back in one query not only the queried
+            objects, but also objects related to them. In other words it is a controlled eager
+            relationship resolving mechanism. Prefetching is discussed in the "Performance Tuning"
+            chapter, as it is a powerful performance optimization method. Another common application
+            of prefetching is for refreshing stale object relationships.</para>
+        <para>Prefetching example:
+            <programlisting language="java">SelectQuery query = new SelectQuery(Artist.class);
 
 // this instructs Cayenne to prefetch one of Artist's relationships
 query.addPrefetch("paintings");
@@ -18,104 +18,104 @@ query.addPrefetch("paintings");
 // query is expecuted as usual, but the resulting Artists will have
 // their paintings "inflated"
 List&lt;Artist> artists = context.performQuery(query);</programlisting>
-			All types of relationships can be preftetched - to-one, to-many, flattened. </para>
-		<para>A prefetch can span multiple relationships:
-			<programlisting language="java"> query.addPrefetch("paintings.gallery");</programlisting></para>
-		<para>A query can have multiple
-			prefetches:<programlisting language="java">query.addPrefetch("paintings");
+            All types of relationships can be preftetched - to-one, to-many, flattened. </para>
+        <para>A prefetch can span multiple relationships:
+            <programlisting language="java"> query.addPrefetch("paintings.gallery");</programlisting></para>
+        <para>A query can have multiple
+            prefetches:<programlisting language="java">query.addPrefetch("paintings");
 query.addPrefetch("paintings.gallery"); </programlisting></para>
-		<para>If a query is fetching DataRows, all "disjoint" prefetches are ignored, only "joint"
-			prefetches are executed (see prefetching semantics discussion below for what disjoint and
-			joint prefetches mean).</para>
-		
-		<section xml:id="prefetching-semantics">
-			<title>Prefetching Semantics</title>
-			<para>Prefetching semantics defines a strategy to prefetch relationships. Depending on
-				it, Cayenne would generate different types of queries. The end result is the same -
-				query root objects with related objects fully resolved. However semantics can affect
-				preformance, in some cases significantly. There are 3 types of prefetch semantics,
-				all defined as constants in
-				org.apache.cayenne.query.PrefetchTreeNode:<programlisting language="java">PrefetchTreeNode.JOINT_PREFETCH_SEMANTICS
+        <para>If a query is fetching DataRows, all "disjoint" prefetches are ignored, only "joint"
+            prefetches are executed (see prefetching semantics discussion below for what disjoint and
+            joint prefetches mean).</para>
+
+        <section xml:id="prefetching-semantics">
+            <title>Prefetching Semantics</title>
+            <para>Prefetching semantics defines a strategy to prefetch relationships. Depending on
+                it, Cayenne would generate different types of queries. The end result is the same -
+                query root objects with related objects fully resolved. However semantics can affect
+                preformance, in some cases significantly. There are 3 types of prefetch semantics,
+                all defined as constants in
+                org.apache.cayenne.query.PrefetchTreeNode:<programlisting language="java">PrefetchTreeNode.JOINT_PREFETCH_SEMANTICS
 PrefetchTreeNode.DISJOINT_PREFETCH_SEMANTICS
 PrefetchTreeNode.DISJOINT_BY_ID_PREFETCH_SEMANTICS</programlisting></para>
-			<para>Each query has a default prefetch semantics, so generally users do not have to
-				worry about changing it, except when performance is a concern, or a few special
-				cases when a default sematics can't produce the correct result. SelectQuery uses
-				DISJOINT_PREFETCH_SEMANTICS by default. Semantics can be changed as
-				follows:<programlisting language="java">SelectQuery query = new SelectQuery(Artist.class);
+            <para>Each query has a default prefetch semantics, so generally users do not have to
+                worry about changing it, except when performance is a concern, or a few special
+                cases when a default sematics can't produce the correct result. SelectQuery uses
+                DISJOINT_PREFETCH_SEMANTICS by default. Semantics can be changed as
+                follows:<programlisting language="java">SelectQuery query = new SelectQuery(Artist.class);
 query.addPrefetch("paintings").setSemantics(
                 PrefetchTreeNode.JOINT_PREFETCH_SEMANTICS); </programlisting></para>
-			<para>There's no limitation on mixing different types of semantics in the same
-				SelectQuery. Multiple prefetches each can have its own semantics. </para>
-			<para>SQLTemplate and ProcedureQuery are both using JOINT_PREFETCH_SEMANTICS and it can
-				not be changed due to the nature of these two queries.</para>
-		</section>
-		<section xml:id="disjoint-prefetch-semantics">
-			<title>Disjoint Prefetching Semantics</title>
-			<para>This semantics (only applicable to SelectQuery) results in Cayenne generating one SQL
-				statement for the main objects, and a separate statement for each prefetch path
-				(hence "disjoint" - related objects are not fetched with the main query). Each
-				additional SQL statement uses a qualifier of the main query plus a set of joins
-				traversing the prefetch path between the main and related entity. </para>
-			<para>This strategy has an advantage of efficient JVM memory use, and faster overall
-				result processing by Cayenne, but it requires (1+N) SQL statements to be executed,
-				where N is the number of prefetched relationships.</para>
-			
-		</section>
-		<section xml:id="disjoint-by-id-prefetch-semantics">
-			<title>Disjoint-by-ID Prefetching Semantics</title>
-			<para>This is a variation of disjoint prefetch where related objects are matched against
-				a set of IDs derived from the fetched main objects (or intermediate objects in a
-				multi-step prefetch). Cayenne limits the size of the generated WHERE clause, as most
-				DBs can't parse arbitrary large SQL. So prefetch queries are broken into smaller
-				queries. The size of  is controlled by the DI property
-				Constants.SERVER_MAX_ID_QUALIFIER_SIZE_PROPERTY (the default number of conditions in
-				the generated WHERE clause is 10000). Cayenne will generate (1 + N * M) SQL
-				statements for each query using disjoint-by-ID prefetches, where N is the number of
-				relationships to prefetch, and M is the number of queries for a given prefetch that
-				is dependent on the number of objects in the result (ideally M = 1).</para>
-			<para>The advantage of this type of prefetch is that matching database rows by ID may be
-				much faster than matching the qualifier of the original query. Moreover this is
-					<emphasis role="bold">the only type of prefetch</emphasis> that can handle
-				SelectQueries with <emphasis role="bold">fetch limit</emphasis>. Both joint and
-				regular disjoint prefetches may produce invalid results or generate inefficient
-				fetch-the-entire table SQL when fetch limit is in effect. </para>
-			<para>The disadvantage is that query SQL can get unwieldy for large result sets, as each
-				object will have to have its own condition in the WHERE clause of the generated
-				SQL.</para>
-		</section>
-		<section xml:id="joint-prefetch-semantics">
-			<title>Joint Prefetching Semantics</title>
-			<para>Joint semantics results in a single SQL statement for root objects and any number of
-				jointly prefetched paths. Cayenne processes in memory a cartesian product of the
-				entities involved, converting it to an object tree. It uses OUTER joins to connect
-				prefetched entities.</para>
-			<para>Joint is the most efficient prefetch type of the three as far as generated SQL
-				goes. There's always just 1 SQL query generated. Its downsides are the potentially
-				increased amount of data that needs to get across the network between the
-				application server and the database, and more data processing that needs to be done
-				on the Cayenne side.</para>
-		</section>
-	</section>
-	<section xml:id="datarows">
-		<title>Data Rows</title>
-	</section>
-	<section xml:id="iterated-queries">
-		<title>Iterated Queries</title>
-	</section>
-	<section xml:id="paginated-queries">
-		<title>Paginated Queries</title>
-	</section>
-	<section xml:id="caching-and-fresh-data">
-		<title>Caching and Fresh Data</title>
-		<section xml:id="object-caching">
-			<title>Object Caching</title>
-		</section>
-		<section xml:id="query-result-caching">
-			<title>Query Result Caching</title>
-		</section>
-	</section>
-	<section xml:id="turning-off-synchronization-of-objectcontexts">
-		<title>Turning off Synchronization of ObjectContexts</title>
-	</section>
+            <para>There's no limitation on mixing different types of semantics in the same
+                SelectQuery. Multiple prefetches each can have its own semantics. </para>
+            <para>SQLTemplate and ProcedureQuery are both using JOINT_PREFETCH_SEMANTICS and it can
+                not be changed due to the nature of these two queries.</para>
+        </section>
+        <section xml:id="disjoint-prefetch-semantics">
+            <title>Disjoint Prefetching Semantics</title>
+            <para>This semantics (only applicable to SelectQuery) results in Cayenne generatiing one
+                SQL statement for the main objects, and a separate statement for each prefetch path
+                (hence "disjoint" - related objects are not fetched with the main query). Each
+                additional SQL statement uses a qualifier of the main query plus a set of joins
+                traversing the preftech path between the main and related entity. </para>
+            <para>This strategy has an advantage of efficient JVM memory use, and faster overall
+                result processing by Cayenne, but it requires (1+N) SQL statements to be executed,
+                where N is the number of prefetched relationships.</para>
+
+        </section>
+        <section xml:id="disjoint-by-id-prefetch-semantics">
+            <title>Disjoint-by-ID Prefetching Semantics</title>
+            <para>This is a variation of disjoint prefetch where related objects are matched against
+                a set of IDs derived from the fetched main objects (or intermediate objects in a
+                multi-step prefetch). Cayenne limits the size of the generated WHERE clause, as most
+                DBs can't parse arbitrary large SQL. So prefetch queries are broken into smaller
+                queries. The size of  is controlled by the DI property
+                Constants.SERVER_MAX_ID_QUALIFIER_SIZE_PROPERTY (the default number of conditions in
+                the generated WHERE clause is 10000). Cayenne will generate (1 + N * M) SQL
+                statements for each query using disjoint-by-ID prefetches, where N is the number of
+                relationships to prefetch, and M is the number of queries for a given prefetch that
+                is dependent on the number of objects in the result (ideally M = 1).</para>
+            <para>The advantage of this type of prefetch is that matching database rows by ID may be
+                much faster than matching the qualifier of the original query. Moreover this is
+                    <emphasis role="bold">the only type of prefetch</emphasis> that can handle
+                SelectQueries with <emphasis role="bold">fetch limit</emphasis>. Both joint and
+                regular disjoint prefetches may produce invalid results or generate inefficient
+                fetch-the-entire table SQL when fetch limit is in effect. </para>
+            <para>The disadvantage is that query SQL can get unwieldy for large result sets, as each
+                object will have to have its own condition in the WHERE clause of the generated
+                SQL.</para>
+        </section>
+        <section xml:id="joint-prefetch-semantics">
+            <title>Joint Prefetching Semantics</title>
+            <para>Joint senantics results in a single SQL statement for root objects and any number
+                of jointly prefetched paths. Cayenne processes in memory a cartesian product of the
+                entities involved, converting it to an object tree. It uses OUTER joins to connect
+                prefetched entities.</para>
+            <para>Joint is the most efficient prefetch type of the three as far as generated SQL
+                goes. There's always just 1 SQL query generated. Its downsides are the potentially
+                increased amount of data that needs to get across the network between the
+                application server and the database, and more data processing that needs to be done
+                on the Cayenne side.</para>
+        </section>
+    </section>
+    <section xml:id="datarows">
+        <title>Data Rows</title>
+    </section>
+    <section xml:id="iterated-queries">
+        <title>Iterated Queries</title>
+    </section>
+    <section xml:id="paginated-queries">
+        <title>Paginated Queries</title>
+    </section>
+    <section xml:id="caching-and-fresh-data">
+        <title>Caching and Fresh Data</title>
+        <section xml:id="object-caching">
+            <title>Object Caching</title>
+        </section>
+        <section xml:id="query-result-caching">
+            <title>Query Result Caching</title>
+        </section>
+    </section>
+    <section xml:id="turning-off-synchronization-of-objectcontexts">
+        <title>Turning off Synchronization of ObjectContexts</title>
+    </section>
 </chapter>



Mime
View raw message