Package org.apache.cayenne

## Class BaseContext

- java.lang.Object
- - org.apache.cayenne.BaseContext

- All Implemented Interfaces:
    `Serializable`, `DataChannel`, `ObjectContext`
  Direct Known Subclasses:
    `DataContext`

      public abstract class BaseContext
      extends Object
      implements ObjectContext

  A common base superclass for Cayenne ObjectContext implementors.
  Since:
    3.0
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected DataChannel` | `channel` |
    `protected EntityResolver` | `entityResolver` |
    `protected ObjectContextGraphAction` | `graphAction` | Graph action that handles property changes
    `protected QueryCache` | `queryCache` |
    `protected static ThreadLocal<ObjectContext>` | `threadObjectContext` | A holder of a ObjectContext bound to the current thread.
    `protected Map<String,​Object>` | `userProperties` | Stores user defined properties associated with this DataContext.
    `protected boolean` | `validatingObjectsOnCommit` |

    - ### Fields inherited from interface org.apache.cayenne.DataChannel

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

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `BaseContext()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    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)` | Binds a ObjectContext to the current thread.
    `abstract void` | `commitChanges()` | Flushes all changes to objects in this context to the parent DataChannel, cascading flush operation all the way through the stack, ultimately saving data in the database.
    `abstract void` | `commitChangesToParent()` | Flushes all changes to objects in this context to the parent DataChannel.
    `abstract Collection<?>` | `deletedObjects()` | Returns a collection of objects that are registered with this ObjectContext 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)` |
    `DataChannel` | `getChannel()` | Returns an DataChannel used by this context.
    `EntityResolver` | `getEntityResolver()` | Returns EntityResolver that stores all mapping information accessible by this ObjectContext.
    `EventManager` | `getEventManager()` | Returns EventManager associated with the ObjectStore.
    `abstract GraphManager` | `getGraphManager()` | Returns GraphManager that manages object graph associated with this context.
    `QueryCache` | `getQueryCache()` |
    `static ObjectContext` | `getThreadObjectContext()` | Returns the ObjectContext bound to the current thread.
    `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'.
    `protected void` | `injectInitialValue​(Object obj)` | If ObjEntity qualifier is set, asks it to inject initial value to an object.
    `void` | `invalidateObjects​(Collection<?> objects)` | Invalidates a Collection of persistent objects.
    `<T> void` | `invalidateObjects​(T... objects)` | Invalidates one or more persistent objects.
    `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.
    `abstract <T> ResultIterator<T>` | `iterator​(Select<T> query)` | Creates a ResultIterator based on the provided query.
    `<T extends Persistent> T` | `localObject​(T objectFromAnotherContext)` | Returns a local copy of 'objectFromAnotherContext' object.
    `abstract Collection<?>` | `modifiedObjects()` | Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.MODIFIED
    `abstract <T> T` | `newObject​(Class<T> persistentClass)` | Creates a new persistent object of a given class scheduled to be inserted to the database on next commit.
    `abstract Collection<?>` | `newObjects()` | Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.NEW
    `protected abstract GraphDiff` | `onContextFlush​(ObjectContext originatingContext, GraphDiff changes, boolean cascade)` |
    `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.
    `abstract QueryResponse` | `performGenericQuery​(Query query)` | Executes any kind of query providing the result in a form of QueryResponse.
    `abstract List` | `performQuery​(Query query)` | Executes a selecting query, returning a list of persistent objects or data rows.
    `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.
    `abstract void` | `registerNewObject​(Object object)` | Registers a transient object with the context.
    `abstract void` | `rollbackChanges()` | Resets all uncommitted changes made to the objects in this ObjectContext, cascading rollback operation all the way through the stack.
    `abstract void` | `rollbackChangesLocally()` | Resets all uncommitted changes made to the objects in this ObjectContext.
    `<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` | `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` | `setValidatingObjectsOnCommit​(boolean flag)` | Sets the property defining whether this ObjectContext should perform object validation before commit is executed.
    `abstract Collection<?>` | `uncommittedObjects()` | Returns a collection of MODIFIED, DELETED or NEW objects.

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface org.apache.cayenne.DataChannel

      `onQuery`

    - ### Methods inherited from interface org.apache.cayenne.ObjectContext

      `hasChanges`

- - ### Field Detail

    - #### threadObjectContext

          protected static final ThreadLocal<ObjectContext> threadObjectContext

      A holder of a ObjectContext bound to the current thread.
      Since:
        3.0

    - #### channel

          protected transient DataChannel channel

    - #### queryCache

          protected transient QueryCache queryCache

    - #### entityResolver

          protected transient EntityResolver entityResolver

    - #### validatingObjectsOnCommit

          protected boolean validatingObjectsOnCommit

    - #### graphAction

          protected ObjectContextGraphAction 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

  - ### Constructor Detail

    - #### BaseContext

          protected BaseContext()

  - ### Method Detail

    - #### getThreadObjectContext

          public static ObjectContext getThreadObjectContext()
                                                      throws IllegalStateException

      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

          public static void bindThreadObjectContext​(ObjectContext context)

      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

    - #### commitChanges

          public abstract void commitChanges()

      Description copied from interface: `ObjectContext`
      Flushes all changes to objects in this context to the parent DataChannel, cascading flush operation all the way through the stack, ultimately saving data in the database.
      Specified by:
        `commitChanges` in interface `ObjectContext`

    - #### commitChangesToParent

          public abstract void commitChangesToParent()

      Description copied from interface: `ObjectContext`
      Flushes all changes to objects in this context to the parent DataChannel. Same as `ObjectContext.commitChanges()`, but no cascading flush occurs.
      Specified by:
        `commitChangesToParent` 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.

    - #### deletedObjects

          public abstract Collection<?> deletedObjects()

      Description copied from interface: `ObjectContext`
      Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.DELETED
      Specified by:
        `deletedObjects` in interface `ObjectContext`

    - #### getChannel

          public DataChannel getChannel()

      Description copied from interface: `ObjectContext`
      Returns an DataChannel used by this context.
      Specified by:
        `getChannel` in interface `ObjectContext`

    - #### 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

    - #### 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

    - #### 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

    - #### getGraphManager

          public abstract GraphManager getGraphManager()

      Description copied from interface: `ObjectContext`
      Returns GraphManager that manages object graph associated with this context.
      Specified by:
        `getGraphManager` in interface `ObjectContext`

    - #### modifiedObjects

          public abstract Collection<?> modifiedObjects()

      Description copied from interface: `ObjectContext`
      Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.MODIFIED
      Specified by:
        `modifiedObjects` in interface `ObjectContext`

    - #### newObject

          public abstract <T> T newObject​(Class<T> persistentClass)

      Description copied from interface: `ObjectContext`
      Creates a new persistent object of a given class scheduled to be inserted to the database on next commit.
      Specified by:
        `newObject` in interface `ObjectContext`

    - #### registerNewObject

          public abstract void registerNewObject​(Object object)

      Description copied from interface: `ObjectContext`
      Registers a transient object with the context. The difference with `ObjectContext.newObject(Class)` is that a user creates an object herself, before attaching it to the context, instead of relying on Cayenne to do that.
      Specified by:
        `registerNewObject` in interface `ObjectContext`
      Parameters:
        `object` - new object that needs to be made persistent.

    - #### newObjects

          public abstract Collection<?> newObjects()

      Description copied from interface: `ObjectContext`
      Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.NEW
      Specified by:
        `newObjects` in interface `ObjectContext`

    - #### performGenericQuery

          public abstract QueryResponse performGenericQuery​(Query query)

      Description copied from interface: `ObjectContext`
      Executes any kind of query providing the result in a form of QueryResponse.
      Specified by:
        `performGenericQuery` in interface `ObjectContext`

    - #### performQuery

          public abstract List performQuery​(Query query)

      Description copied from interface: `ObjectContext`
      Executes a selecting query, returning a list of persistent objects or data rows.
      Specified by:
        `performQuery` in interface `ObjectContext`

    - #### 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 abstract <T> ResultIterator<T> iterator​(Select<T> query)

      Description copied from interface: `ObjectContext`
      Creates a ResultIterator based on the provided query. 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 ResultIterator explicitly. Or use `ObjectContext.iterate(Select, ResultIteratorCallback)` as an alternative.
      Specified by:
        `iterator` in interface `ObjectContext`

    - #### 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`

    - #### 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`

    - #### 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`

    - #### rollbackChanges

          public abstract void rollbackChanges()

      Description copied from interface: `ObjectContext`
      Resets all uncommitted changes made to the objects in this ObjectContext, cascading rollback operation all the way through the stack.
      Specified by:
        `rollbackChanges` in interface `ObjectContext`

    - #### rollbackChangesLocally

          public abstract void rollbackChangesLocally()

      Description copied from interface: `ObjectContext`
      Resets all uncommitted changes made to the objects in this ObjectContext. Same as `ObjectContext.rollbackChanges()`, but rollback is local to this context and no cascading changes undoing occurs.
      Specified by:
        `rollbackChangesLocally` in interface `ObjectContext`

    - #### uncommittedObjects

          public abstract Collection<?> uncommittedObjects()

      Description copied from interface: `ObjectContext`
      Returns a collection of MODIFIED, DELETED or NEW objects.
      Specified by:
        `uncommittedObjects` in interface `ObjectContext`

    - #### 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

    - #### 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`.

    - #### onContextFlush

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

    - #### fireDataChannelCommitted

          protected void fireDataChannelCommitted​(Object postedBy,
                                                  GraphDiff changes)

      Since:
        1.2

    - #### fireDataChannelRolledback

          protected void fireDataChannelRolledback​(Object postedBy,
                                                   GraphDiff changes)

      Since:
        1.2

    - #### fireDataChannelChanged

          protected void fireDataChannelChanged​(Object postedBy,
                                                GraphDiff changes)

      Since:
        1.2

    - #### 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

    - #### 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

    - #### injectInitialValue

          protected void injectInitialValue​(Object obj)

      If ObjEntity qualifier is set, asks it to inject initial value to an object. Also performs all Persistent initialization operations

    - #### 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.