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>
