One of the goals of the ObjectContext is to provide an isolated area where local object changes can be performed without affecting other similar areas or the underlying storage. At some point in time users would either commit changes to the underlying storage or undo them (roll them back).
If a DataContext is directly attached to the DataDomain, a call to DataContext.commitChanges() results in changes written to the database. On the other hand if DataContext's direct parent in the access stack is not a DataDomain, but another DataContext, changes can be saved to the parent without saving them to the database. Such child context is often called "nested".
Same thing is true when ObjectContext is used via ROP. Committing changes to a nested ROP ObjectContext (CayenneContext) locally will not result in sending data to a server.
 | ROP Nested contexts are available in Cayenne ROP (three tier) only from version 3.0M6. |
Nested contexts are useful in many situations, such as nested UI dialogs, complicated workflows, etc.
Creating Nested Contexts
| Deprecation Since 3.0M6 a new method, ObjectContext.createChildContext() was introduced, so DataContext.createChildDataContext() is now deprecated. Please update your code properly. |
ObjectContext parent = ... ObjectContext child = context.createChildContext();
child object will be instance of the same class, as parent is - DataContext or CayenneContext.
When creating a nested DataContext, note that if there was a DataContextFactory configured for the DataDomain at the top of the context hierarchy, such factory will be used internally by createChildDataContext method. Also child DataContext inherits parent's "ValidatingObjectsOnCommit" property.
Using Nested Contexts
A nested context does everything a parent context can do, i.e. perform queries, register new objects, delete objects, etc. A specific behavior is the ability to choose between a cascading or one-level commit or rollback.
Regular "commitChanges" call does a cascading commit through the stack of parents all the way to the database:
child.commitChanges();
However it is possible to commit to parent, without triggering a DB commit:
child.commitChangesToParent();
Same thing with rollback, "rollbackChanges" does a cascading rollback:
child.rollbackChanges();
While "rollbackChangesLocally" only affects the nested context, and not even sent to the parent:
child.rollbackChangesLocally();
From the child context, you may want to get a reference to the parent context. Use child.getChannel() to get the parent context, and if called from the top level context context.getChannel() will return the DataDomain.
Nested Contexts Performance
All cascading operations (such as a select query or a cascading update) initiated by a nested context will have to travel through the stack of parent contexts, incurring certain delay at each stack level. The delay is due to the fact that each context has to update its own objects during most operations. So nesting should only be used when application specifics require to do so. Also nesting of more than a few levels should be avoided.