cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aadamc...@apache.org
Subject svn commit: r1425988 [3/4] - in /cayenne/main/branches/STABLE-3.1/docs/docbook: cayenne-guide/src/docbkx/ getting-started-rop/src/docbkx/ getting-started/src/docbkx/ stylesheets/
Date Wed, 26 Dec 2012 18:38:18 GMT
Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/part2.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/part2.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/part2.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/part2.xml Wed Dec 26 18:38:17 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/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/part3.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/part3.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/part3.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/part3.xml Wed Dec 26 18:38:17 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/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/performance-tuning.xml Wed Dec 26 18:38:17 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>

Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml Wed Dec 26 18:38:17 2012
@@ -1,197 +1,197 @@
 <?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="persistent-objects-objectcontext">
-	<title>Persistent Objects and ObjectContext</title>
-	<section xml:id="objectcontext">
-		<title>ObjectContext</title>
-		<para>ObjectContext is an interface that users normally work with to access the database. It
-			provides the API to execute database operations and to manage persistent objects. A
-			context is obtained from the
-			ServerRuntime:<programlisting language="java">ObjectContext context = runtime.getContext();</programlisting></para>
-		<para>The call above creates a new instance of ObjectContext that can access the database via this
-			runtime. ObjectContext is a single "work area" in Cayenne, storing persistent objects.
-			ObjectContext guarantees that for each database row with a unique ID it will contain at
-			most one instance of an object, thus ensuring object graph consistency between multiple
-			selects (a feature called "uniquing"). At the same time different ObjectContexts will
-			have independent copies of objects for each unique database row. This allows users to
-			isolate object changes from one another by using separate ObjectContexts.</para>
-		<para>These properties directly affect the strategies for scoping and sharing (or not
-			sharing) ObjectContexts. Contexts that are only used to fetch objects from the database
-			and whose objects are never modified by the application can be shared between mutliple
-			users (and multiple threads). Contexts that store modified objects should be accessed
-			only by a single user (e.g. a web application user might reuse a context instance
-			between multiple web requests in the same HttpSession, thus carrying uncommitted changes
-			to objects from request to request, until he decides to commit or rollback them). Even
-			for a single user it might make sense to use mutliple ObjectContexts (e.g.
-			request-scoped contexts to allow concurrent requests from the browser that change and
-			commit objects independently).</para>
-		<para>ObjectContext is serializable and does not permanently hold to any of the application
-			resources. So it does not have to be closed. If the context is not used anymore, it
-			should simply be allowed to go out of scope and get garbage collected, just like any
-			other Java object.</para>
-	</section>
-	<section xml:id="persistent-lifecycle">
-		<title>Persistent Object and its Lifecycle</title>
-		<para>Cayenne can persist Java objects that implement <code>org.apache.cayenne.Persistent</code>
-			interface. Generally persistent classes are generated from the model as described above,
-			so users do not have to worry about superclass and property implementation details. </para>
-		<para>Persistent interface provides access to 3 persistence-related properties - objectId,
-			persistenceState and objectContext. All 3 are initialized by Cayenne runtime framework.
-			Application code should not attempt to change them them. However it is allowed to read
-			them, which provides valuable runtime information. E.g. ObjectId can be used for quick
-			equality check of 2 objects, knowing persistence state would allow highlighting changed
-			objects, etc.</para>
-		<para>Each persistent object belongs to a single ObjectContext, and can be in one of the following
-			persistence states (as defined in <code>org.apache.cayenne.PersistenceState</code>)
-				:<table frame="void">
-				<caption>Persistence States</caption>
-				<col width="16%"/>
-				<col width="84%"/>
-				<tbody>
-					<tr>
-						<td>TRANSIENT</td>
-						<td>The object is not registered with an ObjectContext and will not be
-							persisted.</td>
-					</tr>
-					<tr>
-						<td>NEW</td>
-						<td>The object is freshly registered in an ObjectContext, but has not been
-							saved to the database yet and there is no matching database row.</td>
-					</tr>
-					<tr>
-						<td>COMMITTED</td>
-						<td>The object is registered in an ObjectContext, there is a row in the
-							database corresponding to this object, and the object state corresponds
-							to the last known state of the matching database row.</td>
-					</tr>
-					<tr>
-						<td>MODIFIED</td>
-						<td>The object is registered in an ObjectContext, there is a row in the
-							database corresponding to this object, but the object in-memory state
-							has diverged from the last known state of the matching database
-							row.</td>
-					</tr>
-					<tr>
-						<td>HOLLOW</td>
-						<td>The object is registered in an ObjectContext, there is a row in the
-							database corresponding to this object, but the object state is unknown.
-							Whenever an application tries to access a property of such object,
-							Cayenne attempts reading its values from the database and "inflate" the
-							object, turning it to COMMITED.</td>
-					</tr>
-					<tr>
-						<td>DELETED</td>
-						<td>The object is registered in an ObjectContext and has been marked for
-							deletion in-memory. The corresponding row in the database will get
-							deleted upon ObjectContext commit, and the object state will be turned
-							into TRANSIENT.</td>
-					</tr>
-				</tbody>
-			</table></para>
-	</section>
-	<section xml:id="persistent-operations">
-		<title>ObjectContext Persistence API</title>
-		<para>One of the first things users usually want to do with an ObjectContext is to select
-			some objects from a database. This is done by calling "<emphasis role="italic"
-				>performQuery</emphasis>"
-			method:<programlisting language="java">SelectQuery query = new SelectQuery(Artist.class);
+    version="5.0" xml:id="persistent-objects-objectcontext">
+    <title>Persistent Objects and ObjectContext</title>
+    <section xml:id="objectcontext">
+        <title>ObjectContext</title>
+        <para>ObjectContext is an interface that users normally work with to access the database. It
+            provides the API to execute database operations and to manage persistent objects. A
+            context is obtained from the
+            ServerRuntime:<programlisting language="java">ObjectContext context = runtime.getContext();</programlisting></para>
+        <para>The call above creates a new instance of ObjectContext that can access the database via this
+            runtime. ObjectContext is a single "work area" in Cayenne, storing persistent objects.
+            ObjectContext guarantees that for each database row with a unique ID it will contain at
+            most one instance of an object, thus ensuring object graph consistency between multiple
+            selects (a feature called "uniquing"). At the same time different ObjectContexts will
+            have independent copies of objects for each unique database row. This allows users to
+            isolate object changes from one another by using separate ObjectContexts.</para>
+        <para>These properties directly affect the strategies for scoping and sharing (or not
+            sharing) ObjectContexts. Contexts that are only used to fetch objects from the database
+            and whose objects are never modified by the application can be shared between mutliple
+            users (and multiple threads). Contexts that store modified objects should be accessed
+            only by a single user (e.g. a web application user might reuse a context instance
+            between multiple web requests in the same HttpSession, thus carrying uncommitted changes
+            to objects from request to request, until he decides to commit or rollback them). Even
+            for a single user it might make sense to use mutliple ObjectContexts (e.g.
+            request-scoped contexts to allow concurrent requests from the browser that change and
+            commit objects independently).</para>
+        <para>ObjectContext is serializable and does not permanently hold to any of the application
+            resources. So it does not have to be closed. If the context is not used anymore, it
+            should simply be allowed to go out of scope and get garbage collected, just like any
+            other Java object.</para>
+    </section>
+    <section xml:id="persistent-lifecycle">
+        <title>Persistent Object and its Lifecycle</title>
+        <para>Cayenne can persist Java objects that implement <code>org.apache.cayenne.Persistent</code>
+            interface. Generally persistent classes are generated from the model as described above,
+            so users do not have to worry about superclass and property implementation details. </para>
+        <para>Persistent interface provides access to 3 persistence-related properties - objectId,
+            persistenceState and objectContext. All 3 are initialized by Cayenne runtime framework.
+            Application code should not attempt to change them them. However it is allowed to read
+            them, which provides valuable runtime information. E.g. ObjectId can be used for quick
+            equality check of 2 objects, knowing persistence state would allow highlighting changed
+            objects, etc.</para>
+        <para>Each persistent object belongs to a single ObjectContext, and can be in one of the following
+            persistence states (as defined in <code>org.apache.cayenne.PersistenceState</code>)
+                :<table frame="void">
+                <caption>Persistence States</caption>
+                <col width="16%"/>
+                <col width="84%"/>
+                <tbody>
+                    <tr>
+                        <td>TRANSIENT</td>
+                        <td>The object is not registered with an ObjectContext and will not be
+                            persisted.</td>
+                    </tr>
+                    <tr>
+                        <td>NEW</td>
+                        <td>The object is freshly registered in an ObjectContext, but has not been
+                            saved to the database yet and there is no matching database row.</td>
+                    </tr>
+                    <tr>
+                        <td>COMMITTED</td>
+                        <td>The object is registered in an ObjectContext, there is a row in the
+                            database corresponding to this object, and the object state corresponds
+                            to the last known state of the matching database row.</td>
+                    </tr>
+                    <tr>
+                        <td>MODIFIED</td>
+                        <td>The object is registered in an ObjectContext, there is a row in the
+                            database corresponding to this object, but the object in-memory state
+                            has diverged from the last known state of the matching database
+                            row.</td>
+                    </tr>
+                    <tr>
+                        <td>HOLLOW</td>
+                        <td>The object is registered in an ObjectContext, there is a row in the
+                            database corresponding to this object, but the object state is unknown.
+                            Whenever an application tries to access a property of such object,
+                            Cayenne attempts reading its values from the database and "inflate" the
+                            object, turning it to COMMITED.</td>
+                    </tr>
+                    <tr>
+                        <td>DELETED</td>
+                        <td>The object is registered in an ObjectContext and has been marked for
+                            deletion in-memory. The corresponding row in the database will get
+                            deleted upon ObjectContext commit, and the object state will be turned
+                            into TRANSIENT.</td>
+                    </tr>
+                </tbody>
+            </table></para>
+    </section>
+    <section xml:id="persistent-operations">
+        <title>ObjectContext Persistence API</title>
+        <para>One of the first things users usually want to do with an ObjectContext is to select
+            some objects from a database. This is done by calling "<emphasis role="italic"
+                >performQuery</emphasis>"
+            method:<programlisting language="java">SelectQuery query = new SelectQuery(Artist.class);
 List&lt;Artist> artists = context.performQuery(query);</programlisting>We'll
-			discuss queries in some detail in the following chapters. The example above is
-			self-explanatory - we create a SelectQuery that matches all Artist objects present in
-			the database, and then call "performQuery", getting a list of Artist objects.</para>
-		<para>Some queries can be quite complex, returning multiple result sets or even updating the
-			database. For such queries ObjectContext provides "<emphasis role="italic"
-				>performGenericQuery</emphasis>"method. While not nearly as commonly-used as
-			"performQuery", it is nevertheless important in some situations.
-			E.g.:<programlisting language="java">Collection&lt;Query> queries = ... // multiple queries that need to be run together
+            discuss queries in some detail in the following chapters. The example above is
+            self-explanatory - we create a SelectQuery that matches all Artist objects present in
+            the database, and then call "performQuery", getting a list of Artist objects.</para>
+        <para>Some queries can be quite complex, returning multiple result sets or even updating the
+            database. For such queries ObjectContext provides "<emphasis role="italic"
+                >performGenericQuery</emphasis>"method. While not nearly as commonly-used as
+            "performQuery", it is nevertheless important in some situations.
+            E.g.:<programlisting language="java">Collection&lt;Query> queries = ... // multiple queries that need to be run together
 QueryChain query = new QueryChain(queries);
 
 QueryResponse response = context.performGenericQuery(query);</programlisting></para>
-		<para>An application might modify selected objects. E.g.:</para>
-		<programlisting language="java">Artist selectedArtist = artists.get(0);
+        <para>An application might modify selected objects. E.g.:</para>
+        <programlisting language="java">Artist selectedArtist = artists.get(0);
 selectedArtist.setName("Dali");</programlisting>
-		<para>The first time the object property is changed, the object's state is automatically set
-			to "MODIFIED" by Cayenne. Cayenne tracks all in-memory changes until a user calls
-				"<emphasis role="italic"
-			>commitChanges</emphasis>":<programlisting language="java">context.commitChanges();</programlisting>At
-			this point all in-memory changes are analyzed and a minimal set of SQL statements is
-			issued in a single transaction to synchronize the database with the in-memory state. In
-			our example "commitChanges" commits just one object, but generally it can be any number
-			of objects. </para>
-		<para>If instead of commit, we wanted to reset all changed objects to the previously
-			committed state, we'd call <emphasis>rollbackChanges</emphasis>
-			instead:<programlisting language="java">context.rollbackChanges();</programlisting></para>
-		<para>"<emphasis role="italic">newObject</emphasis>" method call creates a persistent object
-			and sets its state to
-			"NEW":<programlisting language="java">Artist newArtist = context.newObject(Artist.class);
+        <para>The first time the object property is changed, the object's state is automatically set
+            to "MODIFIED" by Cayenne. Cayenne tracks all in-memory changes until a user calls
+                "<emphasis role="italic"
+            >commitChanges</emphasis>":<programlisting language="java">context.commitChanges();</programlisting>At
+            this point all in-memory changes are analyzed and a minimal set of SQL statements is
+            issued in a single transaction to synchronize the database with the in-memory state. In
+            our example "commitChanges" commits just one object, but generally it can be any number
+            of objects. </para>
+        <para>If instead of commit, we wanted to reset all changed objects to the previously
+            committed state, we'd call <emphasis>rollbackChanges</emphasis>
+            instead:<programlisting language="java">context.rollbackChanges();</programlisting></para>
+        <para>"<emphasis role="italic">newObject</emphasis>" method call creates a persistent object
+            and sets its state to
+            "NEW":<programlisting language="java">Artist newArtist = context.newObject(Artist.class);
 newArtist.setName("Picasso");</programlisting></para>
-		<para>It will only exist in memory until "commitChanges" is issued. On commit Cayenne might
-			generate a new primary key (unless a user set it explicitly, or a PK was inferred from a
-			relationship) and issue an INSERT SQL statement to permanently store the object.</para>
-		<para><emphasis>deleteObjects</emphasis> method takes one or more Persistent objects and
-			marks them as
-			"DELETED":<programlisting language="java">context.deleteObjects(artist1);
+        <para>It will only exist in memory until "commitChanges" is issued. On commit Cayenne might
+            generate a new primary key (unless a user set it explicitly, or a PK was inferred from a
+            relationship) and issue an INSERT SQL statement to permanently store the object.</para>
+        <para><emphasis>deleteObjects</emphasis> method takes one or more Persistent objects and
+            marks them as
+            "DELETED":<programlisting language="java">context.deleteObjects(artist1);
 context.deleteObjects(artist2, artist3, artist4);</programlisting>Additionally
-			"deleteObjects" processes all  delete rules modeled for the affected objects. This may
-			result in implicitly deleting or modifying extra related objects. Same as insert and
-			update, delete operations are sent to the database only when "commitChanges" is called.
-			Similarly "rollbackChanges" will undo the effect of "newObject" and
-			"deleteObjects".</para>
-		<para><emphasis>localObject</emphasis> returns a copy of a given persistent object that is
-			"local" to a given ObjectContext:</para>
-		<para>Since an application often works with more than one context, "localObject" is a rather
-			common operation. E.g. to improve performance a user might utilize a single shared
-			context to select and cache data, and then occasionally transfer some selected objects
-			to another context to modify and commit
-			them:<programlisting language="java">ObjectContext editingContext = runtime.getContext();
+            "deleteObjects" processes all  delete rules modeled for the affected objects. This may
+            result in implicitly deleting or modifying extra related objects. Same as insert and
+            update, delete operations are sent to the database only when "commitChanges" is called.
+            Similarly "rollbackChanges" will undo the effect of "newObject" and
+            "deleteObjects".</para>
+        <para><emphasis>localObject</emphasis> returns a copy of a given persistent object that is
+            "local" to a given ObjectContext:</para>
+        <para>Since an application often works with more than one context, "localObject" is a rather
+            common operation. E.g. to improve performance a user might utilize a single shared
+            context to select and cache data, and then occasionally transfer some selected objects
+            to another context to modify and commit
+            them:<programlisting language="java">ObjectContext editingContext = runtime.getContext();
 Artist localArtist = editingContext.localObject(artist);</programlisting></para>
-		<para>Often an appliction needs to inspect mapping metadata. This information is stored in
-			the EntityResolver object, accessible via the
-			ObjectContext:<programlisting language="java">EntityResolver resolver = objectContext.getEntityResolver();</programlisting></para>
-		<para>Here we discussed the most commonly used subset of the ObjectContext API. There are
-			other useful methods, e.g. those allowing to inspect registered objects state en bulk,
-			etc. Check the latest JavaDocs for details.</para>
-	</section>
-	<section xml:id="cayenne-helper-class">
-		<title>Cayenne Helper Class</title>
-		<para>There is a useful helper class called "Cayenne" (fully-qualified name
-				<code>"org.apache.cayenne.Cayenne"</code>) that builds on ObjectContext API to
-			provide a number of very common operations. E.g. get a primary key (most entities do not
-			model PK as an object property)
-			:<programlisting language="java">long pk = Cayenne.longPKForObject(artist);</programlisting></para>
-		<para>It also provides the reverse operation - finding an object given a known
-			PK:<programlisting language="java">Artist artist = Cayenne.objectForPK(context, Artist.class, 34579);</programlisting></para>
-		<para>If a query is expected to return 0 or 1 object, Cayenne helper class can be used to find
-			this object. It throws an exception if more than one object matched the
-			query:<programlisting language="java">Artist artist = (Artist) Cayenne.objectForQuery(context, new SelectQuery(Artist.class));</programlisting></para>
-		<para>Feel free to explore Cayenne class API for other useful methods.</para>
-	</section>
-	<section xml:id="objectcontext-nesting">
-		<title>ObjectContext Nesting</title>
-		<para>In all the examples shown so far an ObjectContext would directly connect to a database
-			to select data or synchronize its state (either via commit or rollback). However another
-			context can be used in all these scenarios instead of a database. This concept is called
-			ObjectContext "nesting". Nesting is a parent/child relationship between two contexts,
-			where child is a nested context and selects or commits its objects via a parent. </para>
-		<para>Nesting is useful to create isolated object editing areas (child contexts) that need
-			to all be committed to an intermediate in-memory store (parent context), or rolled back
-			without affecting changes already recorded in the parent. Think cascading GUI dialogs,
-			or parallel AJAX requests coming to the same session.</para>
-		<para>In theory Cayenne supports any number of nesting levels, however applications should
-			generally stay with one or two, as deep hierarchies will most certainly degrade the
-			performance of the deeply nested child contexts. This is due to the fact that each
-			context in a nesting chain has to update its own objects during most operations. </para>
-		<para>Cayenne ROP is an extreme case of nesting when a child context is located in a
-			separate JVM and communicates with its parent via a web service. ROP is discussed in
-			details in the following chapters. Here we concentrate on the same-VM nesting.</para>
-		<para>To create a nested context, use an instance of ServerRuntime, passing it the desired
-			parent:<programlisting language="java">ObjectContext parent = runtime.getContext();
+        <para>Often an appliction needs to inspect mapping metadata. This information is stored in
+            the EntityResolver object, accessible via the
+            ObjectContext:<programlisting language="java">EntityResolver resolver = objectContext.getEntityResolver();</programlisting></para>
+        <para>Here we discussed the most commonly used subset of the ObjectContext API. There are
+            other useful methods, e.g. those allowing to inspect registered objects state en bulk,
+            etc. Check the latest JavaDocs for details.</para>
+    </section>
+    <section xml:id="cayenne-helper-class">
+        <title>Cayenne Helper Class</title>
+        <para>There is a useful helper class called "Cayenne" (fully-qualified name
+                <code>"org.apache.cayenne.Cayenne"</code>) that builds on ObjectContext API to
+            provide a number of very common operations. E.g. get a primary key (most entities do not
+            model PK as an object property)
+            :<programlisting language="java">long pk = Cayenne.longPKForObject(artist);</programlisting></para>
+        <para>It also provides the reverse operation - finding an object given a known
+            PK:<programlisting language="java">Artist artist = Cayenne.objectForPK(context, Artist.class, 34579);</programlisting></para>
+        <para>If a query is expected to return 0 or 1 object, Cayenne helper class can be used to find
+            this object. It throws an exception if more than one object matched the
+            query:<programlisting language="java">Artist artist = (Artist) Cayenne.objectForQuery(context, new SelectQuery(Artist.class));</programlisting></para>
+        <para>Feel free to explore Cayenne class API for other useful methods.</para>
+    </section>
+    <section xml:id="objectcontext-nesting">
+        <title>ObjectContext Nesting</title>
+        <para>In all the examples shown so far an ObjectContext would directly connect to a database
+            to select data or synchronize its state (either via commit or rollback). However another
+            context can be used in all these scenarios instead of a database. This concept is called
+            ObjectContext "nesting". Nesting is a parent/child relationship between two contexts,
+            where child is a nested context and selects or commits its objects via a parent. </para>
+        <para>Nesting is useful to create isolated object editing areas (child contexts) that need
+            to all be committed to an intermediate in-memory store (parent context), or rolled back
+            without affecting changes already recorded in the parent. Think cascading GUI dialogs,
+            or parallel AJAX requests coming to the same session.</para>
+        <para>In theory Cayenne supports any number of nesting levels, however applications should
+            generally stay with one or two, as deep hierarchies will most certainly degrade the
+            performance of the deeply nested child contexts. This is due to the fact that each
+            context in a nesting chain has to update its own objects during most operations. </para>
+        <para>Cayenne ROP is an extreme case of nesting when a child context is located in a
+            separate JVM and communicates with its parent via a web service. ROP is discussed in
+            details in the following chapters. Here we concentrate on the same-VM nesting.</para>
+        <para>To create a nested context, use an instance of ServerRuntime, passing it the desired
+            parent:<programlisting language="java">ObjectContext parent = runtime.getContext();
 ObjectContext nested = runtime.getContext((DataChannel) parent);</programlisting>From
-			here a nested context operates just like a regular context (you can perform queries,
-			create and delete objects, etc.). The only difference is that commit and rollback
-			operations can either be limited to synchronization with the parent, or cascade all the
-			way to the
-			database:<programlisting language="java">// merges nested context changes into the parent context
+            here a nested context operates just like a regular context (you can perform queries,
+            create and delete objects, etc.). The only difference is that commit and rollback
+            operations can either be limited to synchronization with the parent, or cascade all the
+            way to the
+            database:<programlisting language="java">// merges nested context changes into the parent context
 nested.commitChangesToParent();
 
 // regular 'commitChanges' cascades commit through the chain 
@@ -202,58 +202,58 @@ nested.rollbackChangesLocally();
 // regular 'rollbackChanges' cascades rollback through the chain of contexts 
 // all the way to the topmost parent
 nested.rollbackChanges();</programlisting></para>
-	</section>
-	<section xml:id="generic-persistent-objects">
-		<title>Generic Persistent Objects</title>
-		<para>As described in the CayenneModeler chapter, Cayenne supports mapping of completely
-			generic classes to specific entities. Although for conveniece most applications should
-			stick with entity-specific class mappings, the generic feature offers some interesting
-			possibilities, such as creating mappings completely on the fly in a running application,
-			etc.</para>
-		<para>Generic objects are first class citizens in Cayenne, and all common persistent
-			operations apply to them as well. There are some pecularities however, described
-			below.</para>
-		<para>When creating a new generic object, either cast your ObjectContext to DataContext
-			(that provides "newObject(String)" API), or provide your object with an explicit
-			ObjectId:<programlisting language="java">DataObject generic = ((DataContext) context).newObject("GenericEntity");</programlisting><programlisting language="java">DataObject generic = new CayenneDataObject();
+    </section>
+    <section xml:id="generic-persistent-objects">
+        <title>Generic Persistent Objects</title>
+        <para>As described in the CayenneModeler chapter, Cayenne supports mapping of completely
+            generic classes to specific entities. Although for conveniece most applications should
+            stick with entity-specific class mappings, the generic feature offers some interesting
+            possibilities, such as creating mappings completely on the fly in a running application,
+            etc.</para>
+        <para>Generic objects are first class citizens in Cayenne, and all common persistent
+            operations apply to them as well. There are some pecularities however, described
+            below.</para>
+        <para>When creating a new generic object, either cast your ObjectContext to DataContext
+            (that provides "newObject(String)" API), or provide your object with an explicit
+            ObjectId:<programlisting language="java">DataObject generic = ((DataContext) context).newObject("GenericEntity");</programlisting><programlisting language="java">DataObject generic = new CayenneDataObject();
 generic.setObjectId(new ObjectId("GenericEntity"));
 context.registerNewObject(generic);</programlisting>SelectQuery
-			for generic object should be created passing entity name String in constructor, instead
-			of a Java
-			class:<programlisting language="java">SelectQuery query = new SelectQuery("GenericEntity");</programlisting>Use
-			DataObject API to access and modify properties of a generic
-			object:<programlisting language="java">String name = (String) generic.readProperty("name");
+            for generic object should be created passing entity name String in constructor, instead
+            of a Java
+            class:<programlisting language="java">SelectQuery query = new SelectQuery("GenericEntity");</programlisting>Use
+            DataObject API to access and modify properties of a generic
+            object:<programlisting language="java">String name = (String) generic.readProperty("name");
 generic.writeProperty("name", "New Name");</programlisting>This
-			is how an application can obtain entity name of a generic
-			object:<programlisting language="java">String entityName = generic.getObjectId().getEntityName();</programlisting></para>
-	</section>
-	<section xml:id="transactions">
-		<title>Transactions</title>
-		<para>Considering how much attention is given to managing transactions in most other ORMs,
-			transactions have been conspicuously absent from the ObjectContext discussion till now.
-			The reason is that transactions are seamless in Cayenne in all but a few special cases.
-			ObjectContext is an in-memory container of objects that is disconnected from the
-			database, except when it needs to run an operation. So it does not care about any
-			surrounding transaction scope. Sure enough all database operations are transactional, so
-			when an application does a commit, all SQL execution is wrapped in a database
-			transaction. But this is done behind the scenes and is rarely a concern to the
-			application code.</para>
-		<para>Two cases where transactions need to be taken into consideration are container-managed
-			and application-managed transactions. </para>
-		<para>If you are using an EJB container (or some other JTA environment), you'll likely need
-			to switch Cayenne runtime into "external transactions mode".  This is either done in the
-			Modeler (check DataDomain > 'Container-Managed Transactions' checkbox), or in the
-			code:<programlisting language="java">runtime.getDataDomain().setUsingExternalTransactions(true);</programlisting>In
-			this case Cayenne assumes that JDBC Connections obtained by runtime whenever that might
-			happen are all coming from a transactional DataSource managed by the container. In this
-			case Cayenne does not attempt to commit or rollback the connections, leaving it up to
-			the container to do that when appropriate.</para>
-		<para>In the second scenario, an application might need to define its own transaction scope
-			that spans more than one Cayenne operation. E.g. two sequential commits that need to be
-			rolled back together in case of failure. This can be done with an explicit thread-bound
-			transaction that surrounds a set of operations. Application is responsible for
-			committing or rolling it
-			back:<programlisting language="java">Transaction tx = runtime.getDataDomain().createTransaction();
+            is how an application can obtain entity name of a generic
+            object:<programlisting language="java">String entityName = generic.getObjectId().getEntityName();</programlisting></para>
+    </section>
+    <section xml:id="transactions">
+        <title>Transactions</title>
+        <para>Considering how much attention is given to managing transactions in most other ORMs,
+            transactions have been conspicuously absent from the ObjectContext discussion till now.
+            The reason is that transactions are seamless in Cayenne in all but a few special cases.
+            ObjectContext is an in-memory container of objects that is disconnected from the
+            database, except when it needs to run an operation. So it does not care about any
+            surrounding transaction scope. Sure enough all database operations are transactional, so
+            when an application does a commit, all SQL execution is wrapped in a database
+            transaction. But this is done behind the scenes and is rarely a concern to the
+            application code.</para>
+        <para>Two cases where transactions need to be taken into consideration are container-managed
+            and application-managed transactions. </para>
+        <para>If you are using an EJB container (or some other JTA environment), you'll likely need
+            to switch Cayenne runtime into "external transactions mode".  This is either done in the
+            Modeler (check DataDomain > 'Container-Managed Transactions' checkbox), or in the
+            code:<programlisting language="java">runtime.getDataDomain().setUsingExternalTransactions(true);</programlisting>In
+            this case Cayenne assumes that JDBC Connections obtained by runtime whenever that might
+            happen are all coming from a transactional DataSource managed by the container. In this
+            case Cayenne does not attempt to commit or rollback the connections, leaving it up to
+            the container to do that when appropriate.</para>
+        <para>In the second scenario, an application might need to define its own transaction scope
+            that spans more than one Cayenne operation. E.g. two sequential commits that need to be
+            rolled back together in case of failure. This can be done with an explicit thread-bound
+            transaction that surrounds a set of operations. Application is responsible for
+            committing or rolling it
+            back:<programlisting language="java">Transaction tx = runtime.getDataDomain().createTransaction();
 Transaction.bindThreadTransaction(tx);
 
 try {
@@ -281,5 +281,5 @@ finally {
         }
     }
 } </programlisting></para>
-	</section>
+    </section>
 </chapter>

Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/queries.xml Wed Dec 26 18:38:17 2012
@@ -1,61 +1,61 @@
 <?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="queries">
-	<title>Queries</title>
-	<para>Queries are Java objects used by the application to communicate with the database. Cayenne
-		knows how to translate queries into SQL statements appropriate for a particular database
-		engine. Most often queries are used to find objects matching certain criteria, but there are
-		other types of queries too. E.g. those allowing to run native SQL, call DB stored
-		procedures, etc. When committing objects, Cayenne itself creates special queries to
-		insert/update/delete rows in the dabase.</para>
-	<para>There is a number of built-in queries in Cayenne, described later in this chapter. Users can
-		also define their own query types to abstract certain DB interactions that for whatever
-		reason can not be adequately described by the built-in set. </para>
-	<para>Queries can be roughly categorized as "object" and "native". Object queries (most notably
-		SelectQuery and EJBQLQuery) are built with abstractions originating in the object model (the
-		"object" side in the "object-relational" divide). E.g. SelectQuery is assembled from a Java
-		class of the objects to fetch, a qualifier expression, orderings, etc. - all of this
-		expressed in terms of the object model.</para>
-	<para>Native queries describe a desired DB operation as SQL code (SQLTemplate query) or a reference
-		to a stored procedure (ProcedureQuery), etc. The results of native queries are usually
-		presented as Lists of Maps, with each map representing a row in the DB. They can potentially
-		be converted to objects, however often it takes a considerable effort to do so. Native
-		queries are also less (if at all) portable across databases than object queries. </para>
-	<section xml:id="selectquery">
-		<title>SelectQuery</title>
-		<para>SelectQuery is the most commonly used query in user applications. It returns a list of
-			persistent objects of a certain type specified in the
-			query:<programlisting language="java">SelectQuery query = new SelectQuery(Artist.class);
+    version="5.0" xml:id="queries">
+    <title>Queries</title>
+    <para>Queries are Java objects used by the application to communicate with the database. Cayenne
+        knows how to translate queries into SQL statements appropriate for a particular database
+        engine. Most often queries are used to find objects matching certain criteria, but there are
+        other types of queries too. E.g. those allowing to run native SQL, call DB stored
+        procedures, etc. When committing objects, Cayenne itself creates special queries to
+        insert/update/delete rows in the dabase.</para>
+    <para>There is a number of built-in queries in Cayenne, described later in this chapter. Users can
+        also define their own query types to abstract certain DB interactions that for whatever
+        reason can not be adequately described by the built-in set. </para>
+    <para>Queries can be roughly categorized as "object" and "native". Object queries (most notably
+        SelectQuery and EJBQLQuery) are built with abstractions originating in the object model (the
+        "object" side in the "object-relational" divide). E.g. SelectQuery is assembled from a Java
+        class of the objects to fetch, a qualifier expression, orderings, etc. - all of this
+        expressed in terms of the object model.</para>
+    <para>Native queries describe a desired DB operation as SQL code (SQLTemplate query) or a reference
+        to a stored procedure (ProcedureQuery), etc. The results of native queries are usually
+        presented as Lists of Maps, with each map representing a row in the DB. They can potentially
+        be converted to objects, however often it takes a considerable effort to do so. Native
+        queries are also less (if at all) portable across databases than object queries. </para>
+    <section xml:id="selectquery">
+        <title>SelectQuery</title>
+        <para>SelectQuery is the most commonly used query in user applications. It returns a list of
+            persistent objects of a certain type specified in the
+            query:<programlisting language="java">SelectQuery query = new SelectQuery(Artist.class);
 List&lt;Artist> objects = context.performQuery(query);</programlisting>This
-			returned all rows in the "ARTIST" table. If the logs were turned on, you might see the
-			following SQL
-			printed:<programlisting>INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0
+            returned all rows in the "ARTIST" table. If the logs were turned on, you might see the
+            following SQL
+            printed:<programlisting>INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0
 INFO: === returned 5 row. - took 5 ms.</programlisting></para>
-		<para>This SQL was generated by Cayenne from the SelectQuery above. SelectQuery can use a
-			qualifier to select only the data that you care about. Qualifier is simply an Expression
-			(Expressions where discussed in the previous chapter). If you only want artists whose
-			name begins with 'Pablo', you might use the following qualifier expression:
-			<programlisting language="java">SelectQuery query = new SelectQuery(Artist.class,
+        <para>This SQL was generated by Cayenne from the SelectQuery above. SelectQuery can use a
+            qualifier to select only the data that you care about. Qualifier is simply an Expression
+            (Expressions where discussed in the previous chapter). If you only want artists whose
+            name begins with 'Pablo', you might use the following qualifier expression:
+            <programlisting language="java">SelectQuery query = new SelectQuery(Artist.class,
         ExpressionFactory.likeExp(Artist.NAME_PROPERTY, "Pablo%"));
 List&lt;Artist> objects = context.performQuery(query);</programlisting>The
-			SQL will look different this
-			time:<programlisting>INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 WHERE t0.NAME LIKE ? 
+            SQL will look different this
+            time:<programlisting>INFO: SELECT t0.DATE_OF_BIRTH, t0.NAME, t0.ID FROM ARTIST t0 WHERE t0.NAME LIKE ?
 [bind: 1->NAME:'Pablo%']
 INFO: === returned 1 row. - took 6 ms.</programlisting></para>
-	</section>
-	<section xml:id="ejbqlquery">
-		<title>EJBQLQuery</title>
-	</section>
-	<section xml:id="sqltemplate">
-		<title>SQLTemplateQuery</title>
-	</section>
-	<section xml:id="procedurequery">
-		<title>ProcedureQuery</title>
-	</section>
-	<section xml:id="namedquery">
-		<title>NamedQuery</title>
-	</section>
-	<section xml:id="custom-queries">
-		<title>Custom Queries</title>
-	</section>
+    </section>
+    <section xml:id="ejbqlquery">
+        <title>EJBQLQuery</title>
+    </section>
+    <section xml:id="sqltemplate">
+        <title>SQLTemplateQuery</title>
+    </section>
+    <section xml:id="procedurequery">
+        <title>ProcedureQuery</title>
+    </section>
+    <section xml:id="namedquery">
+        <title>NamedQuery</title>
+    </section>
+    <section xml:id="custom-queries">
+        <title>Custom Queries</title>
+    </section>
 </chapter>

Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/rop-deployment.xml Wed Dec 26 18:38:17 2012
@@ -1,32 +1,32 @@
 <?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="rop-deployment">
-	<title>ROP Deployment</title>
-	<section xml:id="deploying-rop-server">
-		<title>Deploying ROP Server</title>
-		
-		<note><para>Recent versions of Tomcat and Jetty containers (e.g. Tomcat 6 and 7, Jetty 8) contain code
-				addressing a security concern related to "session fixation problem" by resetting the
-				existing session ID of any request that requires BASIC authentcaition. If ROP
-				service is protected with declarative security (see the the ROP tutorial and the
-				following chapters on security), this feature prevents the ROP client from attaching
-				to its session, resulting in MissingSessionExceptions. To solve that you will need
-				to either switch to an alternative security mechanism, or disable "session fixation
-				problem" protections of the container. E.g. the later can be achieved in Tomcat 7 by
-				adding the following <emphasis>context.xml</emphasis> file to the webapp's META-INF/
-				directory:
-				<programlisting>&lt;Context>
-	&lt;Valve className="org.apache.catalina.authenticator.BasicAuthenticator" 
-			changeSessionIdOnAuthentication="false" />
+    version="5.0" xml:id="rop-deployment">
+    <title>ROP Deployment</title>
+    <section xml:id="deploying-rop-server">
+        <title>Deploying ROP Server</title>
+
+        <note><para>Recent versions of Tomcat and Jetty containers (e.g. Tomcat 6 and 7, Jetty 8) contain code
+                addressing a security concern related to "session fixation problem" by resetting the
+                existing session ID of any request that requires BASIC authentcaition. If ROP
+                service is protected with declarative security (see the the ROP tutorial and the
+                following chapters on security), this feature prevents the ROP client from attaching
+                to its session, resulting in MissingSessionExceptions. To solve that you will need
+                to either switch to an alternative security mechanism, or disable "session fixation
+                problem" protections of the container. E.g. the later can be achieved in Tomcat 7 by
+                adding the following <emphasis>context.xml</emphasis> file to the webapp's META-INF/
+                directory:
+                <programlisting>&lt;Context>
+    &lt;Valve className="org.apache.catalina.authenticator.BasicAuthenticator"
+            changeSessionIdOnAuthentication="false" />
 &lt;/Context></programlisting>(The
-				&lt;Valve> tag can also be placed within the &lt;Context> in any other locations
-				used by Tomcat to load context configurations)</para></note>
-		
-	</section>
-	<section xml:id="deploying-rop-client">
-		<title>Deploying ROP Client</title>
-	</section>
-	<section xml:id="rop-security">
-		<title>Security</title>
-	</section>
+                &lt;Valve> tag can also be placed within the &lt;Context> in any other locations
+                used by Tomcat to load context configurations)</para></note>
+
+    </section>
+    <section xml:id="deploying-rop-client">
+        <title>Deploying ROP Client</title>
+    </section>
+    <section xml:id="rop-security">
+        <title>Security</title>
+    </section>
 </chapter>

Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/rop-setup.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/rop-setup.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/rop-setup.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/rop-setup.xml Wed Dec 26 18:38:17 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="rop-setup">
-	<title>ROP Setup</title>
-	<section xml:id="rop-system-requirements">
-		<title>System Requirements</title>
-	</section>
-	<section xml:id="rop-jar-files-dependencies">
-		<title>Jar Files and Dependencies</title>
-	</section>
+    version="5.0" xml:id="rop-setup">
+    <title>ROP Setup</title>
+    <section xml:id="rop-system-requirements">
+        <title>System Requirements</title>
+    </section>
+    <section xml:id="rop-jar-files-dependencies">
+        <title>Jar Files and Dependencies</title>
+    </section>
 </chapter>

Modified: cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/setup.xml
URL: http://svn.apache.org/viewvc/cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/setup.xml?rev=1425988&r1=1425987&r2=1425988&view=diff
==============================================================================
--- cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/setup.xml (original)
+++ cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/setup.xml Wed Dec 26 18:38:17 2012
@@ -1,59 +1,59 @@
 <?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="setup">
-	<title>Setup</title>
-	<section xml:id="system-requirements">
-		<title>System Requirements</title>
-		<para>
-			<itemizedlist>
-				<listitem>
-					<para><emphasis role="italic">Java</emphasis>: Cayenne runtime framework and
-						CayenneModeler GUI tool are written in 100% Java, and run on any
-						Java-compatible platform. Required JDK version is 1.5 or higher. The last
-						version of Cayenne compatible with JDK 1.4 is 1.2.x/2.0.x and JDK 1.3 is 1.1.x</para>
-				</listitem>
-			</itemizedlist>
-			<itemizedlist>
-				<listitem>
-					<para><emphasis role="italic">JDBC Driver:</emphasis> An appropriate DB-specific
-						JDBC driver is needed to access the database. It can be included in the
-						application or used in web container DataSource configuration.</para>
-				</listitem>
-			</itemizedlist>
-			<itemizedlist>
-				<listitem>
-					<para><emphasis role="italic">Third-party Libraries:</emphasis> Cayenne runtime
-						framework has a minimal set of required and a few more optional dependencies
-						on third-party open source packages. See "Including Cayenne in a Project"
-						chapter for details.</para>
-				</listitem>
-			</itemizedlist>
-		</para>
-	</section>
-	<section xml:id="running-cayennemodeler">
-		<title>Running CayenneModeler</title>
-		<para>CayenneModeler GUI tool is intended to work with object relational mapping projects. While
-			you can edit your XML by hand, it is rarely needed, as the Modeler is a pretty advanced
-			tool included in Cayenne distribution. To obtain CayenneModeler, download Cayenne
-			distribution archive from <link xlink:href="http://cayenne.apache.org/download.html"
-				>http://cayenne.apache.org/download.html</link> matching the OS you are using. Of
-			course Java needs to be installed on the machine where you are going to run the
-			Modeler.</para>
-		<para>OS X distribution contains CayenneModeler.app at the root of the distribution disk
-			image.</para>
-		<para>Windows distribution contains CayenneModeler.exe file in the <code>bin</code>
-			directory.</para>
-		<para>Cross-platform distribution (targeting Linux, but as the name implies, compatible with any
-			OS) contains a runnable CayenneModeler.jar in the <code>bin</code> directory. It can be
-			executed either by double-clicking, or if the environment is not configured to execute
-			jars, by running from command-line:</para>
-		<programlisting>java -jar CayenneModeler.jar</programlisting>
-		<para>The Modeler can also be started from Maven. While it may look like an exotic way to start a
-			GUI application, it has its benefits - no need to download Cayenne distribution, the
-			version of the Modeler always matches the version of the framework, the plugin can find
-			mapping files in the project automatically. So is an attractive option to some
-			developers. Maven option requires a declaration in the
-			POM:<programlisting>&lt;build>
+    version="5.0" xml:id="setup">
+    <title>Setup</title>
+    <section xml:id="system-requirements">
+        <title>System Requirements</title>
+        <para>
+            <itemizedlist>
+                <listitem>
+                    <para><emphasis role="italic">Java</emphasis>: Cayenne runtime framework and
+                        CayenneModeler GUI tool are written in 100% Java, and run on any
+                        Java-compatible platform. Required JDK version is 1.5 or higher. The last
+                        version of Cayenne compatible with JDK 1.4 is 1.2.x/2.0.x and JDK 1.3 is 1.1.x</para>
+                </listitem>
+            </itemizedlist>
+            <itemizedlist>
+                <listitem>
+                    <para><emphasis role="italic">JDBC Driver:</emphasis> An appropriate DB-specific
+                        JDBC driver is needed to access the database. It can be included in the
+                        application or used in web container DataSource configuration.</para>
+                </listitem>
+            </itemizedlist>
+            <itemizedlist>
+                <listitem>
+                    <para><emphasis role="italic">Third-party Libraries:</emphasis> Cayenne runtime
+                        framework has a minimal set of required and a few more optional dependencies
+                        on third-party open source packages. See "Including Cayenne in a Project"
+                        chapter for details.</para>
+                </listitem>
+            </itemizedlist>
+        </para>
+    </section>
+    <section xml:id="running-cayennemodeler">
+        <title>Running CayenneModeler</title>
+        <para>CayenneModeler GUI tool is intended to work with object relational mapping projects. While
+            you can edit your XML by hand, it is rarely needed, as the Modeler is a pretty advanced
+            tool included in Cayenne distribution. To obtain CayenneModeler, download Cayenne
+            distribution archive from <link xlink:href="http://cayenne.apache.org/download.html"
+                >http://cayenne.apache.org/download.html</link> matching the OS you are using. Of
+            course Java needs to be installed on the machine where you are going to run the
+            Modeler.</para>
+        <para>OS X distribution contains CayenneModeler.app at the root of the distribution disk
+            image.</para>
+        <para>Windows distribution contains CayenneModeler.exe file in the <code>bin</code>
+            directory.</para>
+        <para>Cross-platform distribution (targeting Linux, but as the name implies, compatible with any
+            OS) contains a runnable CayenneModeler.jar in the <code>bin</code> directory. It can be
+            executed either by double-clicking, or if the environment is not configured to execute
+            jars, by running from command-line:</para>
+        <programlisting>java -jar CayenneModeler.jar</programlisting>
+        <para>The Modeler can also be started from Maven. While it may look like an exotic way to start a
+            GUI application, it has its benefits - no need to download Cayenne distribution, the
+            version of the Modeler always matches the version of the framework, the plugin can find
+            mapping files in the project automatically. So is an attractive option to some
+            developers. Maven option requires a declaration in the
+            POM:<programlisting>&lt;build>
     &lt;plugins>
         &lt;plugin>
             &lt;groupId>org.apache.cayenne.plugins&lt;/groupId>
@@ -62,6 +62,6 @@
         &lt;/plugin>
     &lt;/plugins>
 &lt;/build></programlisting></para>
-		<para>And then can be run as <programlisting>mvn cayenne-modeler:run</programlisting></para>
-	</section>
+        <para>And then can be run as <programlisting>mvn cayenne-modeler:run</programlisting></para>
+    </section>
 </chapter>



Mime
View raw message