Cayenne User Documentation
Nested DataContexts

One of the goals of the DataContext 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".

Nested contexts are useful in many situations, such as nested UI dialogs, complicated workflows, etc.

### Creating Nested DataContext

    DataContext parent = ...
    DataContext child = context.createChildDataContext();

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 DataContext

A nested DataContext does everything a regular DataContext 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();

### Nested DataContexts Performance

All cascading operations (such as a select query or a cascading update) initiated by a nested DataContext 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 DataContext 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.

.
Copyright ©2001-2008 Apache Software Foundation