svn commit: r1382266 - /cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml

[aa...@apache.org]

Author: aadamchik
Date: Sat Sep  8 09:25:17 2012
New Revision: 1382266

URL: http://svn.apache.org/viewvc?rev=1382266&view=rev
Log:
docs

nested contexts

(cherry picked from commit e19de604899a5807a79a272fde09ed683941ba85)

Modified:
    cayenne/main/branches/STABLE-3.1/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml

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=1382266&r1=1382265&r2=1382266&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 Sat Sep  8 09:25:17 2012
@@ -160,6 +160,40 @@ context.deleteObjects(artist2, artist3, 
 	</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>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>// merges nested context changes into the parent context
+nested.commitChangesToParent();
+
+// regular 'commitChanges' cascades commit through the chain 
+// of parent contexts all the way to the database
+nested.commitChanges();</programlisting><programlisting>// unrolls all local changes, getting context in a state identical to parent
+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>