cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aadamc...@apache.org
Subject svn commit: r1382260 - /cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml
Date Sat, 08 Sep 2012 09:18:50 GMT
Author: aadamchik
Date: Sat Sep  8 09:18:50 2012
New Revision: 1382260

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

nested contexts

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

Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml?rev=1382260&r1=1382259&r2=1382260&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml
(original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml
Sat Sep  8 09:18:50 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>



Mime
View raw message