# Class DataContext

java.lang.Object
org.apache.cayenne.access.DataContext

All Implemented Interfaces:
  `Serializable, DataChannel, ObjectContext`

Direct Known Subclasses:
  `BaseContext`

public class DataContext extends Object implements ObjectContext
The most common implementation of `ObjectContext`. DataContext is an isolated container of an object graph, in a sense that any uncommitted changes to persistent objects that are registered with the context, are not visible to the users of other contexts.

See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected DataChannel`
  `channel`
  `protected EntityResolver`
  `entityResolver`
  `protected org.apache.cayenne.access.DataContextGraphAction`
  `graphAction`
  Graph action that handles property changes
  `protected org.apache.cayenne.access.DataContextMergeHandler`
  `mergeHandler`
  `protected ObjectStore`
  `objectStore`
  `protected QueryCache`
  `queryCache`
  `protected static final ThreadLocal<ObjectContext>`
  `threadObjectContext`
  Deprecated, for removal: This API element is subject to removal in a future version.
  `protected Map<String,Object>`
  `userProperties`
  Stores user defined properties associated with this DataContext.
  `protected boolean`
  `usingSharedSnapshotCache`
  `protected boolean`
  `validatingObjectsOnCommit`

  ### Fields inherited from interface DataChannel

  `FLUSH_CASCADE_SYNC, FLUSH_NOCASCADE_SYNC, GRAPH_CHANGED_SUBJECT, GRAPH_FLUSHED_SUBJECT, GRAPH_ROLLEDBACK_SUBJECT, ROLLBACK_CASCADE_SYNC`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DataContext()`
  Creates a new DataContext that is not attached to the Cayenne stack.
  `DataContext(DataChannel channel, ObjectStore objectStore)`
  Creates a new DataContext with parent DataChannel and ObjectStore.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `attachToChannel(DataChannel channel)`
  Attaches to a provided DataChannel.
  `protected void`
  `attachToRuntime(Injector injector)`
  Attaches this context to the CayenneRuntime whose Injector is passed as an argument to this method.
  `protected boolean`
  `attachToRuntimeIfNeeded()`
  Checks whether this context is attached to Cayenne runtime stack and if not, attempts to attach itself to the runtime using Injector returned from the call to `CayenneRuntime.getThreadInjector()`.
  `<T> ResultBatchIterator<T>`
  `batchIterator(Select<T> query, int size)`
  Creates a ResultBatchIterator based on the provided query and batch size.
  `static void`
  `bindThreadObjectContext(ObjectContext context)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  if you are using thread context, you can create your own ThreadLocal
  `void`
  `clearUserProperties()`
  Removes all user-defined properties.
  `void`
  `commitChanges()`
  Synchronizes object graph with the database.
  `void`
  `commitChangesToParent()`
  "Flushes" the changes to the parent `DataChannel`.
  `DataRow`
  `currentSnapshot(Persistent object)`
  Returns a `DataRow` reflecting current, possibly uncommitted, object state.
  `Collection<?>`
  `deletedObjects()`
  Returns a list of objects that are registered with this DataContext and have a state `PersistenceState.DELETED`
  `void`
  `deleteObject(Object object)`
  Schedules deletion of a persistent object.
  `void`
  `deleteObjects(Collection<?> objects)`
  Schedules deletion of a collection of persistent objects.
  `<T> void`
  `deleteObjects(T... objects)`
  Schedules deletion of one or more persistent objects.
  `protected void`
  `fireDataChannelChanged(Object postedBy, GraphDiff changes)`
  `protected void`
  `fireDataChannelCommitted(Object postedBy, GraphDiff changes)`
  `protected void`
  `fireDataChannelRolledback(Object postedBy, GraphDiff changes)`
  `DataContextDelegate`
  `getDelegate()`
  Returns a delegate currently associated with this DataContext.
  `EntityResolver`
  `getEntityResolver()`
  Returns EntityResolver that stores all mapping information accessible by this ObjectContext.
  `EventManager`
  `getEventManager()`
  Returns EventManager associated with the ObjectStore.
  `GraphManager`
  `getGraphManager()`
  Returns this context's ObjectStore.
  `ObjectStore`
  `getObjectStore()`
  Returns ObjectStore associated with this DataContext.
  `DataChannel`
  `getParent()`
  Returns the parent channel of this channel in the DataChannel stack, or null if this is a root channel (such as a `DataDomain`).
  `DataDomain`
  `getParentDataDomain()`
  Returns a DataDomain used by this DataContext.
  `QueryCache`
  `getQueryCache()`
  `static ObjectContext`
  `getThreadObjectContext()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  if you are using thread context, you can create your own ThreadLocal
  `protected Map<String,Object>`
  `getUserProperties()`
  Returns a map of user-defined properties associated with this DataContext.
  `Object`
  `getUserProperty(String key)`
  Returns a user-defined property previously set via 'setUserProperty'.
  `boolean`
  `hasChanges()`
  Returns `true` if there are any modified, deleted or new objects registered with this DataContext, `false` otherwise.
  `void`
  `invalidateObjects(Collection<?> objects)`
  Invalidates a Collection of persistent objects.
  `<T> void`
  `invalidateObjects(T... objects)`
  Invalidates one or more persistent objects.
  `boolean`
  `isUsingSharedSnapshotCache()`
  Returns `true` if the ObjectStore uses shared cache of a parent DataDomain.
  `boolean`
  `isValidatingObjectsOnCommit()`
  Returns whether this ObjectContext performs object validation before commit is executed.
  `<T> void`
  `iterate(Select<T> query, ResultIteratorCallback<T> callback)`
  Creates a ResultIterator based on the provided query and passes it to a callback for processing.
  `<T> ResultIterator<T>`
  `iterator(Select<T> query)`
  Performs a single database select query returning result as a `ResultIterator`.
  `<T extends Persistent>
  T`
  `localObject(T objectFromAnotherContext)`
  Returns a local copy of 'objectFromAnotherContext' object.
  `Collection<?>`
  `modifiedObjects()`
  Returns a list of objects that are registered with this DataContext and have a state `PersistenceState.MODIFIED`
  `<T> T`
  `newObject(Class<T> persistentClass)`
  Creates and registers a new persistent object.
  `Persistent`
  `newObject(String entityName)`
  Instantiates a new object and registers it with this context.
  `Collection<?>`
  `newObjects()`
  Returns a list of objects that are registered with this DataContext and have a state PersistenceState.NEW
  `<T extends Persistent>
  T`
  `objectFromDataRow(Class<T> objectClass, DataRow dataRow)`
  Creates a Persistent from DataRow.
  `Persistent`
  `objectFromDataRow(String entityName, DataRow dataRow)`
  Creates a Persistent from DataRow.
  `List`
  `objectsFromDataRows(ClassDescriptor descriptor, List<? extends DataRow> dataRows)`
  Converts a list of DataRows to a List of Persistent registered with this DataContext.
  `protected GraphDiff`
  `onContextFlush(ObjectContext originatingContext, GraphDiff changes, boolean cascade)`
  `QueryResponse`
  `onQuery(ObjectContext context, Query query)`
  An implementation of a `DataChannel` method that is used by child contexts to execute queries.
  `GraphDiff`
  `onSync(ObjectContext originatingContext, GraphDiff changes, int syncType)`
  Processes synchronization request from a child ObjectContext, returning a GraphDiff that describes changes to objects made on the receiving end as a result of synchronization.
  `QueryResponse`
  `performGenericQuery(Query query)`
  Executes a query returning a generic response.
  `ResultIterator`
  `performIteratedQuery(Query query)`
  Performs a single database select query returning result as a `ResultIterator`.
  `int[]`
  `performNonSelectingQuery(String queryName)`
  Performs a named mapped query that does not select rows.
  `int[]`
  `performNonSelectingQuery(String queryName, Map<String,?> parameters)`
  Performs a named mapped non-selecting query using a map of parameters.
  `int[]`
  `performNonSelectingQuery(Query query)`
  Performs a single database query that does not select rows.
  `List<?>`
  `performQuery(String queryName, boolean expireCachedLists)`
  Returns a list of objects or DataRows for a named query stored in one of the DataMaps.
  `List<?>`
  `performQuery(String queryName, Map<String,?> parameters, boolean expireCachedLists)`
  Returns a list of objects or DataRows for a named query stored in one of the DataMaps.
  `List`
  `performQuery(Query query)`
  Performs a single selecting query.
  `void`
  `prepareForAccess(Persistent object, String property, boolean lazyFaulting)`
  A callback method that child Persistent objects are expected to call before accessing property values.
  `void`
  `propertyChanged(Persistent object, String property, Object oldValue, Object newValue)`
  A callback method that child Persistent objects are expected to call from inside the setter after modifying a value of a persistent property, including "simple" and "arc" properties.
  `void`
  `registerNewObject(Object object)`
  Registers a transient object with the context, recursively registering all transient persistent objects attached to this object via relationships.
  `void`
  `removeUserProperty(String key)`
  Removes a user-defined property.
  `void`
  `rollbackChanges()`
  Reverts any changes that have occurred to objects registered with DataContext; also performs cascading rollback of all parent DataContexts.
  `void`
  `rollbackChangesLocally()`
  If the parent channel is a DataContext, reverts local changes to make this context look like the parent, if the parent channel is a DataDomain, reverts all changes.
  `<T> List<T>`
  `select(Select<T> query)`
  Executes a selecting query, returning a list of persistent objects or data rows.
  `<T> T`
  `selectFirst(Select<T> query)`
  Selects a single object using provided query.
  `<T> T`
  `selectOne(Select<T> query)`
  Executes a selecting query, returning either NULL if query matched no objects, or a single object.
  `void`
  `setChannel(DataChannel channel)`
  Sets a new DataChannel for this context.
  `void`
  `setDelegate(DataContextDelegate delegate)`
  Sets a DataContextDelegate for this context.
  `void`
  `setEntityResolver(EntityResolver entityResolver)`
  `void`
  `setQueryCache(QueryCache queryCache)`
  Sets a QueryCache to be used for storing cached query results.
  `void`
  `setUserProperty(String key, Object value)`
  Sets a user-defined property.
  `void`
  `setUsingSharedSnapshotCache(boolean flag)`
  `void`
  `setValidatingObjectsOnCommit(boolean flag)`
  Sets the property defining whether this ObjectContext should perform object validation before commit is executed.
  `Collection<?>`
  `uncommittedObjects()`
  Returns a collection of all uncommitted registered objects.
  `void`
  `unregisterObjects(Collection<?> objects)`
  Unregisters a Collection of Persistent objects from the DataContext and the underlying ObjectStore.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface ObjectContext

  `getChannel`

- ## Field Details

  - ### threadObjectContext

    @Deprecated(since="5.0", forRemoval=true) protected static final ThreadLocal<ObjectContext> threadObjectContext
    Deprecated, for removal: This API element is subject to removal in a future version.
    A holder of a ObjectContext bound to the current thread.
    Since:
      3.0

  - ### usingSharedSnapshotCache

    protected boolean usingSharedSnapshotCache

  - ### objectStore

    protected ObjectStore objectStore

  - ### graphAction

    protected org.apache.cayenne.access.DataContextGraphAction graphAction
    Graph action that handles property changes
    Since:
      3.1

  - ### userProperties

    protected volatile Map<String,Object> userProperties
    Stores user defined properties associated with this DataContext.
    Since:
      3.0

  - ### channel

    protected transient DataChannel channel

  - ### queryCache

    protected transient QueryCache queryCache

  - ### entityResolver

    protected transient EntityResolver entityResolver

  - ### mergeHandler

    protected transient org.apache.cayenne.access.DataContextMergeHandler mergeHandler

  - ### validatingObjectsOnCommit

    protected boolean validatingObjectsOnCommit

- ## Constructor Details

  - ### DataContext

    public DataContext()
    Creates a new DataContext that is not attached to the Cayenne stack.

  - ### DataContext

    public DataContext(DataChannel channel, ObjectStore objectStore)
    Creates a new DataContext with parent DataChannel and ObjectStore.
    Since:
      1.2

- ## Method Details

  - ### getThreadObjectContext

    @Deprecated(since="5.0", forRemoval=true) public static ObjectContext getThreadObjectContext() throws IllegalStateException
    Deprecated, for removal: This API element is subject to removal in a future version.
    if you are using thread context, you can create your own ThreadLocal
    Returns the ObjectContext bound to the current thread.
    Returns:
      the ObjectContext associated with caller thread.
    Throws:
      `IllegalStateException` - if there is no ObjectContext bound to the current thread.
    Since:
      3.0

  - ### bindThreadObjectContext

    @Deprecated(since="5.0", forRemoval=true) public static void bindThreadObjectContext(ObjectContext context)
    Deprecated, for removal: This API element is subject to removal in a future version.
    if you are using thread context, you can create your own ThreadLocal
    Binds a ObjectContext to the current thread. ObjectContext can later be retrieved by users in the same thread by calling `getThreadObjectContext()`. Using null parameter will unbind currently bound ObjectContext.
    Since:
      3.0

  - ### attachToRuntimeIfNeeded

    protected boolean attachToRuntimeIfNeeded()
    Checks whether this context is attached to Cayenne runtime stack and if not, attempts to attach itself to the runtime using Injector returned from the call to `CayenneRuntime.getThreadInjector()`. If thread Injector is not available and the context is not attached, throws CayenneRuntimeException.

    This method is called internally by the context before access to transient variables to allow the context to attach to the stack lazily following deserialization.

    Returns:
      true if the context successfully attached to the thread runtime, false - if it was already attached.
    Since:
      3.1

  - ### attachToRuntime

    protected void attachToRuntime(Injector injector)
    Attaches this context to the CayenneRuntime whose Injector is passed as an argument to this method.
    Since:
      3.1

  - ### attachToChannel

    protected void attachToChannel(DataChannel channel)
    Attaches to a provided DataChannel.
    Since:
      3.1

  - ### getParent

    public DataChannel getParent()
    Description copied from interface: `DataChannel`
    Returns the parent channel of this channel in the DataChannel stack, or null if this is a root channel (such as a `DataDomain`).
    Specified by:
      `getParent` in interface `DataChannel`

  - ### setChannel

    public void setChannel(DataChannel channel)
    Sets a new DataChannel for this context.
    Since:
      3.1

  - ### getEntityResolver

    public EntityResolver getEntityResolver()
    Description copied from interface: `ObjectContext`
    Returns EntityResolver that stores all mapping information accessible by this ObjectContext.
    Specified by:
      `getEntityResolver` in interface `DataChannel`
    Specified by:
      `getEntityResolver` in interface `ObjectContext`

  - ### setEntityResolver

    public void setEntityResolver(EntityResolver entityResolver)
    Since:
      3.1

  - ### getParentDataDomain

    public DataDomain getParentDataDomain()
    Returns a DataDomain used by this DataContext. DataDomain is looked up in the DataChannel hierarchy. If the final channel is not a DataDomain, null is returned.
    Returns:
      DataDomain that is a direct or indirect parent of this DataContext in the DataChannel hierarchy.
    Since:
      1.1

  - ### setDelegate

    public void setDelegate(DataContextDelegate delegate)
    Sets a DataContextDelegate for this context. Delegate is notified of certain events in the DataContext lifecycle and can customize DataContext behavior.
    Since:
      1.1

  - ### getDelegate

    public DataContextDelegate getDelegate()
    Returns a delegate currently associated with this DataContext.
    Since:
      1.1

  - ### getObjectStore

    public ObjectStore getObjectStore()
    Returns ObjectStore associated with this DataContext.

  - ### hasChanges

    public boolean hasChanges()
    Returns `true` if there are any modified, deleted or new objects registered with this DataContext, `false` otherwise.
    Specified by:
      `hasChanges` in interface `ObjectContext`

  - ### newObjects

    public Collection<?> newObjects()
    Returns a list of objects that are registered with this DataContext and have a state PersistenceState.NEW
    Specified by:
      `newObjects` in interface `ObjectContext`

  - ### deletedObjects

    public Collection<?> deletedObjects()
    Returns a list of objects that are registered with this DataContext and have a state `PersistenceState.DELETED`
    Specified by:
      `deletedObjects` in interface `ObjectContext`

  - ### deleteObject

    public void deleteObject(Object object) throws DeleteDenyException
    Description copied from interface: `ObjectContext`
    Schedules deletion of a persistent object.
    Specified by:
      `deleteObject` in interface `ObjectContext`
    Throws:
      `DeleteDenyException` - if a `DeleteRule.DENY` delete rule is applicable for object deletion.

  - ### deleteObjects

    public <T> void deleteObjects(T... objects) throws DeleteDenyException
    Description copied from interface: `ObjectContext`
    Schedules deletion of one or more persistent objects. Same as `ObjectContext.deleteObjects(Collection)` only with a vararg argument list for easier deletion of individual objects.
    Specified by:
      `deleteObjects` in interface `ObjectContext`
    Throws:
      `DeleteDenyException` - if a `DeleteRule.DENY` delete rule is applicable for object deletion.
    Since:
      3.1

  - ### deleteObjects

    public void deleteObjects(Collection<?> objects) throws DeleteDenyException
    Description copied from interface: `ObjectContext`
    Schedules deletion of a collection of persistent objects.
    Specified by:
      `deleteObjects` in interface `ObjectContext`
    Throws:
      `DeleteDenyException` - if a `DeleteRule.DENY` delete rule is applicable for object deletion.

  - ### modifiedObjects

    public Collection<?> modifiedObjects()
    Returns a list of objects that are registered with this DataContext and have a state `PersistenceState.MODIFIED`
    Specified by:
      `modifiedObjects` in interface `ObjectContext`

  - ### uncommittedObjects

    public Collection<?> uncommittedObjects()
    Returns a collection of all uncommitted registered objects.
    Specified by:
      `uncommittedObjects` in interface `ObjectContext`
    Since:
      1.2

  - ### getQueryCache

    public QueryCache getQueryCache()

  - ### setQueryCache

    public void setQueryCache(QueryCache queryCache)
    Sets a QueryCache to be used for storing cached query results.

  - ### getEventManager

    public EventManager getEventManager()
    Returns EventManager associated with the ObjectStore.
    Specified by:
      `getEventManager` in interface `DataChannel`
    Since:
      1.2

  - ### fireDataChannelCommitted

    protected void fireDataChannelCommitted(Object postedBy, GraphDiff changes)
    Since:
      1.2

  - ### fireDataChannelRolledback

    protected void fireDataChannelRolledback(Object postedBy, GraphDiff changes)
    Since:
      1.2

  - ### localObject

    public <T extends Persistent> T localObject(T objectFromAnotherContext)
    Description copied from interface: `ObjectContext`
    Returns a local copy of 'objectFromAnotherContext' object. "Local" means that the returned object is registered in this context. If the local object hasn't been previously cached in this context, a hollow object is created and returned to the caller. No DB query is performed to resolve an object.

    Note that passing an object with a non-existing id, may later result in FaultFailureException on attempt to read returned object properties.

    Specified by:
      `localObject` in interface `ObjectContext`
    Since:
      3.1

  - ### currentSnapshot

    public DataRow currentSnapshot(Persistent object)
    Returns a `DataRow` reflecting current, possibly uncommitted, object state.

    Warning: This method will return a partial snapshot if an object or one of its related objects that propagate their keys to this object have temporary ids. DO NOT USE this method if you expect a DataRow to represent a complete object state.

    Parameters:
      `object` - persistent object to create snapshot for
    Returns:
      current snapshot of the persistent object
    Since:
      1.1

  - ### prepareForAccess

    public void prepareForAccess(Persistent object, String property, boolean lazyFaulting)
    Description copied from interface: `ObjectContext`
    A callback method that child Persistent objects are expected to call before accessing property values. This callback allows ObjectContext to "inflate" unresolved objects on demand and also resolve properties that rely on lazy faulting.
    Specified by:
      `prepareForAccess` in interface `ObjectContext`

  - ### objectsFromDataRows

    public List objectsFromDataRows(ClassDescriptor descriptor, List<? extends DataRow> dataRows)
    Converts a list of DataRows to a List of Persistent registered with this DataContext.
    Since:
      3.0

  - ### objectFromDataRow

    public <T extends Persistent> T objectFromDataRow(Class<T> objectClass, DataRow dataRow)
    Creates a Persistent from DataRow.
    Since:
      3.1
    See Also:
      - `DataRow`

  - ### objectFromDataRow

    public Persistent objectFromDataRow(String entityName, DataRow dataRow)
    Creates a Persistent from DataRow. This variety of the 'objectFromDataRow' method is normally used for generic classes.
    Since:
      3.1, 5.0 returns `Persistent` instead of the deprecated DataObject
    See Also:
      - `DataRow`

  - ### newObject

    public <T> T newObject(Class<T> persistentClass)
    Creates and registers a new persistent object.
    Specified by:
      `newObject` in interface `ObjectContext`
    Since:
      1.2

  - ### newObject

    public Persistent newObject(String entityName)
    Instantiates a new object and registers it with this context. Object class is determined from the mapped entity. Object class must have a default constructor.

    Note: in most cases `newObject(Class)` method should be used, however this method is helpful when generic persistent classes are used.

    Since:
      3.0

  - ### registerNewObject

    public void registerNewObject(Object object)
    Registers a transient object with the context, recursively registering all transient persistent objects attached to this object via relationships.

    Note that since 3.0 this method takes Object as an argument instead of a `Persistent`.

    Specified by:
      `registerNewObject` in interface `ObjectContext`
    Parameters:
      `object` - new object that needs to be made persistent.

  - ### unregisterObjects

    public void unregisterObjects(Collection<?> objects)
    Unregisters a Collection of Persistent objects from the DataContext and the underlying ObjectStore. This operation also unsets DataContext for each object and changes its state to `PersistenceState.TRANSIENT`
    See Also:
      - `invalidateObjects(Collection)`

  - ### invalidateObjects

    public void invalidateObjects(Collection<?> objects)
    Description copied from interface: `ObjectContext`
    Invalidates a Collection of persistent objects. This operation only applies to the objects already committed to the database and does nothing to the NEW objects. It would remove each object's snapshot from caches and change object's state to HOLLOW. On the next access to this object, the object will be refetched.
    Specified by:
      `invalidateObjects` in interface `ObjectContext`

  - ### invalidateObjects

    public <T> void invalidateObjects(T... objects)
    Description copied from interface: `ObjectContext`
    Invalidates one or more persistent objects. Same as `ObjectContext.invalidateObjects(Collection)` only with a vararg argument list for easier invalidation of individual objects. If no arguments are passed to this method, it does nothing.
    Specified by:
      `invalidateObjects` in interface `ObjectContext`
    Since:
      3.1

  - ### propertyChanged

    public void propertyChanged(Persistent object, String property, Object oldValue, Object newValue)
    Description copied from interface: `ObjectContext`
    A callback method that child Persistent objects are expected to call from inside the setter after modifying a value of a persistent property, including "simple" and "arc" properties.
    Specified by:
      `propertyChanged` in interface `ObjectContext`

  - ### rollbackChangesLocally

    public void rollbackChangesLocally()
    If the parent channel is a DataContext, reverts local changes to make this context look like the parent, if the parent channel is a DataDomain, reverts all changes.
    Specified by:
      `rollbackChangesLocally` in interface `ObjectContext`
    Since:
      1.2

  - ### rollbackChanges

    public void rollbackChanges()
    Reverts any changes that have occurred to objects registered with DataContext; also performs cascading rollback of all parent DataContexts.
    Specified by:
      `rollbackChanges` in interface `ObjectContext`

  - ### commitChangesToParent

    public void commitChangesToParent()
    "Flushes" the changes to the parent `DataChannel`. If the parent channel is a DataContext, it updates its objects with this context's changes, without a database update. If it is a DataDomain (the most common case), the changes are written to the database. To cause cascading commit all the way to the database, one must use `commitChanges()` .
    Specified by:
      `commitChangesToParent` in interface `ObjectContext`
    Since:
      1.2
    See Also:
      - `commitChanges()`

  - ### commitChanges

    public void commitChanges() throws CayenneRuntimeException
    Synchronizes object graph with the database. Executes needed insert, update and delete queries (generated internally).
    Specified by:
      `commitChanges` in interface `ObjectContext`
    Throws:
      `CayenneRuntimeException`

  - ### onContextFlush

    protected GraphDiff onContextFlush(ObjectContext originatingContext, GraphDiff changes, boolean cascade)

  - ### select

    public <T> List<T> select(Select<T> query)
    Description copied from interface: `ObjectContext`
    Executes a selecting query, returning a list of persistent objects or data rows.
    Specified by:
      `select` in interface `ObjectContext`
    Since:
      4.0

  - ### selectOne

    public <T> T selectOne(Select<T> query)
    Description copied from interface: `ObjectContext`
    Executes a selecting query, returning either NULL if query matched no objects, or a single object. If query matches more than one object, `CayenneRuntimeException` is thrown.
    Specified by:
      `selectOne` in interface `ObjectContext`
    Since:
      4.0

  - ### selectFirst

    public <T> T selectFirst(Select<T> query)
    Description copied from interface: `ObjectContext`
    Selects a single object using provided query. The query itself can match any number of objects, but will return only the first one. It returns null if no objects were matched.

    If it matched more than one object, the first object from the list is returned. This makes 'selectFirst' different from `ObjectContext.selectOne(Select)`, which would throw in this situation. 'selectFirst' is useful e.g. when the query is ordered and we only want to see the first object (e.g. "most recent news article"), etc.

    Selecting the first object via "Select.selectFirst(ObjectContext)" is more comprehensible than selecting via "ObjectContext.selectFirst(Select)", because implementations of "Select" set fetch size limit to one.

    Specified by:
      `selectFirst` in interface `ObjectContext`
    Since:
      4.0

  - ### iterate

    public <T> void iterate(Select<T> query, ResultIteratorCallback<T> callback)
    Description copied from interface: `ObjectContext`
    Creates a ResultIterator based on the provided query and passes it to a callback for processing. The caller does not need to worry about closing the iterator. This method takes care of it.
    Specified by:
      `iterate` in interface `ObjectContext`
    Since:
      4.0

  - ### iterator

    public <T> ResultIterator<T> iterator(Select<T> query)
    Performs a single database select query returning result as a `ResultIterator`.

    It is caller's responsibility to explicitly close the `ResultIterator`. A failure to do so will result in a database connection not being released. Another side effect of an open `ResultIterator` is that an internal Cayenne transaction that originated in this method stays open until the iterator is closed. So users should normally close the iterator within the same thread that opened it.

    Specified by:
      `iterator` in interface `ObjectContext`

  - ### performIteratedQuery

    public ResultIterator performIteratedQuery(Query query)
    Performs a single database select query returning result as a `ResultIterator`.

    It is caller's responsibility to explicitly close the `ResultIterator`. A failure to do so will result in a database connection not being released. Another side effect of an open `ResultIterator` is that an internal Cayenne transaction that originated in this method stays open until the iterator is closed. So users should normally close the iterator within the same thread that opened it.

    Note that `performIteratedQuery` always returns `ResultIterator` over DataRows.

    Use `iterate(Select, org.apache.cayenne.ResultIteratorCallback)` to get access to objects.

  - ### performGenericQuery

    public QueryResponse performGenericQuery(Query query)
    Executes a query returning a generic response.
    Specified by:
      `performGenericQuery` in interface `ObjectContext`
    Since:
      1.2

  - ### performQuery

    public List performQuery(Query query)
    Performs a single selecting query. Various query setting control the behavior of this method and the results returned:
    - Query caching policy defines whether the results are retrieved from cache or fetched from the database. Note that queries that use caching must have a name that is used as a caching key.
    - Query refreshing policy controls whether to refresh existing data objects and ignore any cached values.
    - Query data rows policy defines whether the result should be returned as Persistent objects or DataRows.

    Since 1.2 takes any Query parameter, not just GenericSelectQuery

    Specified by:
      `performQuery` in interface `ObjectContext`
    Returns:
      A list of Persistent objects or a DataRows, depending on the value returned by `QueryMetadata.isFetchingDataRows()`. Сan also return an iterator if the query is an instance of iteratedQuery.

  - ### onQuery

    public QueryResponse onQuery(ObjectContext context, Query query)
    An implementation of a `DataChannel` method that is used by child contexts to execute queries. Not intended for direct use.
    Specified by:
      `onQuery` in interface `DataChannel`
    Parameters:
      `context` - an ObjectContext that originated the query, used to register result objects.
    Returns:
      a generic response object that encapsulates result of the execution.
    Since:
      1.2

  - ### onSync

    public GraphDiff onSync(ObjectContext originatingContext, GraphDiff changes, int syncType)
    Description copied from interface: `DataChannel`
    Processes synchronization request from a child ObjectContext, returning a GraphDiff that describes changes to objects made on the receiving end as a result of synchronization.
    Specified by:
      `onSync` in interface `DataChannel`
    Parameters:
      `originatingContext` - an ObjectContext that initiated the sync. Can be null.
      `changes` - diff from the context that initiated the sync.
      `syncType` - One of `DataChannel.FLUSH_NOCASCADE_SYNC`, `DataChannel.FLUSH_CASCADE_SYNC`, `DataChannel.ROLLBACK_CASCADE_SYNC`.

  - ### performNonSelectingQuery

    public int[] performNonSelectingQuery(Query query)
    Performs a single database query that does not select rows. Returns an array of update counts.
    Since:
      1.1

  - ### performNonSelectingQuery

    public int[] performNonSelectingQuery(String queryName)
    Performs a named mapped query that does not select rows. Returns an array of update counts.
    Since:
      1.1

  - ### performNonSelectingQuery

    public int[] performNonSelectingQuery(String queryName, Map<String,?> parameters)
    Performs a named mapped non-selecting query using a map of parameters. Returns an array of update counts.
    Since:
      1.1

  - ### performQuery

    public List<?> performQuery(String queryName, boolean expireCachedLists)
    Returns a list of objects or DataRows for a named query stored in one of the DataMaps. Internally Cayenne uses a caching policy defined in the named query. If refresh flag is true, a refresh is forced no matter what the caching policy is.
    Parameters:
      `queryName` - a name of a GenericSelectQuery defined in one of the DataMaps. If no such query is defined, this method will throw a CayenneRuntimeException.
      `expireCachedLists` - A flag that determines whether refresh of cached lists is required in case a query uses caching.
    Since:
      1.1

  - ### performQuery

    public List<?> performQuery(String queryName, Map<String,?> parameters, boolean expireCachedLists)
    Returns a list of objects or DataRows for a named query stored in one of the DataMaps. Internally Cayenne uses a caching policy defined in the named query. If refresh flag is true, a refresh is forced no matter what the caching policy is.
    Parameters:
      `queryName` - a name of a GenericSelectQuery defined in one of the DataMaps. If no such query is defined, this method will throw a CayenneRuntimeException.
      `parameters` - A map of parameters to use with stored query.
      `expireCachedLists` - A flag that determines whether refresh of cached lists is required in case a query uses caching.
    Since:
      1.1

  - ### isUsingSharedSnapshotCache

    public boolean isUsingSharedSnapshotCache()
    Returns `true` if the ObjectStore uses shared cache of a parent DataDomain.
    Since:
      1.1

  - ### setUsingSharedSnapshotCache

    public void setUsingSharedSnapshotCache(boolean flag)
    Since:
      3.1

  - ### getGraphManager

    public GraphManager getGraphManager()
    Returns this context's ObjectStore.
    Specified by:
      `getGraphManager` in interface `ObjectContext`
    Since:
      1.2

  - ### fireDataChannelChanged

    protected void fireDataChannelChanged(Object postedBy, GraphDiff changes)
    Since:
      1.2

  - ### batchIterator

    public <T> ResultBatchIterator<T> batchIterator(Select<T> query, int size)
    Description copied from interface: `ObjectContext`
    Creates a ResultBatchIterator based on the provided query and batch size. It is usually backed by an open result set and is useful for processing of large data sets, preserving a constant memory footprint. The caller must wrap iteration in try/finally (or try-with-resources for Java 1.7 and higher) and close the ResultBatchIterator explicitly.
    Specified by:
      `batchIterator` in interface `ObjectContext`

  - ### isValidatingObjectsOnCommit

    public boolean isValidatingObjectsOnCommit()
    Returns whether this ObjectContext performs object validation before commit is executed.
    Since:
      1.1

  - ### setValidatingObjectsOnCommit

    public void setValidatingObjectsOnCommit(boolean flag)
    Sets the property defining whether this ObjectContext should perform object validation before commit is executed.
    Since:
      1.1

  - ### getUserProperties

    protected Map<String,Object> getUserProperties()
    Returns a map of user-defined properties associated with this DataContext.
    Since:
      3.0

  - ### getUserProperty

    public Object getUserProperty(String key)
    Returns a user-defined property previously set via 'setUserProperty'. Note that it is a caller responsibility to synchronize access to properties.
    Specified by:
      `getUserProperty` in interface `ObjectContext`
    Since:
      3.0

  - ### setUserProperty

    public void setUserProperty(String key, Object value)
    Sets a user-defined property. Note that it is a caller responsibility to synchronize access to properties.
    Specified by:
      `setUserProperty` in interface `ObjectContext`
    Since:
      3.0

  - ### removeUserProperty

    public void removeUserProperty(String key)
    Removes a user-defined property.
    Specified by:
      `removeUserProperty` in interface `ObjectContext`
    Since:
      5.0

  - ### clearUserProperties

    public void clearUserProperties()
    Removes all user-defined properties.
    Specified by:
      `clearUserProperties` in interface `ObjectContext`
    Since:
      5.0