ObjectContext (cayenne-doc: Cayenne Documentation 5.0-M2 API)
Description: declaration: package: org.apache.cayenne, interface: ObjectContext

# Interface ObjectContext

All Superinterfaces:
  `DataChannel, Serializable`

All Known Implementing Classes:
  `BaseContext, DataContext`

public interface ObjectContext extends DataChannel, Serializable
A Cayenne object facade to a persistent store. Instances of ObjectContext are used in the application code to access Cayenne persistence features.

Since:
  1.2

- ## Field Summary

  ### Fields inherited from interface DataChannel

  `FLUSH_CASCADE_SYNC, FLUSH_NOCASCADE_SYNC, GRAPH_CHANGED_SUBJECT, GRAPH_FLUSHED_SUBJECT, GRAPH_ROLLEDBACK_SUBJECT, ROLLBACK_CASCADE_SYNC`
  Modifier and Type
  Field
  Description
  `static final int`
  `FLUSH_CASCADE_SYNC`
  A synchronization type that results in changes from an ObjectContext to be recorded in the parent DataChannel.
  `static final int`
  `FLUSH_NOCASCADE_SYNC`
  A synchronization type that results in changes from an ObjectContext to be recorded in the parent DataChannel.
  `static final EventSubject`
  `GRAPH_CHANGED_SUBJECT`
  `static final EventSubject`
  `GRAPH_FLUSHED_SUBJECT`
  `static final EventSubject`
  `GRAPH_ROLLEDBACK_SUBJECT`
  `static final int`
  `ROLLBACK_CASCADE_SYNC`
  A synchronization type that results in cascading rollback of changes through the DataChannel stack.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<T> ResultBatchIterator<T>`
  `batchIterator(Select<T> query, int size)`
  Creates a ResultBatchIterator based on the provided query and batch size.
  `void`
  `clearUserProperties()`
  Removes all user-defined properties.
  `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.
  `void`
  `commitChangesToParent()`
  Flushes all changes to objects in this context to the parent DataChannel.
  `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.
  `DataChannel`
  `getChannel()`
  Returns an DataChannel used by this context.
  `EntityResolver`
  `getEntityResolver()`
  Returns EntityResolver that stores all mapping information accessible by this ObjectContext.
  `GraphManager`
  `getGraphManager()`
  Returns GraphManager that manages object graph associated with this context.
  `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 ObjectContext, `false` otherwise.
  `void`
  `invalidateObjects(Collection<?> objects)`
  Invalidates a Collection of persistent objects.
  `<T> void`
  `invalidateObjects(T... objects)`
  Invalidates one or more persistent objects.
  `<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)`
  Creates a ResultIterator based on the provided query.
  `<T extends Persistent>
  T`
  `localObject(T objectFromAnotherContext)`
  Returns a local copy of 'objectFromAnotherContext' object.
  `Collection<?>`
  `modifiedObjects()`
  Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.MODIFIED
  `<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.
  `Collection<?>`
  `newObjects()`
  Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.NEW
  `QueryResponse`
  `performGenericQuery(Query query)`
  Executes any kind of query providing the result in a form of QueryResponse.
  `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.
  `void`
  `registerNewObject(Object object)`
  Registers a transient object with the context.
  `void`
  `removeUserProperty(String key)`
  Removes a user-defined property.
  `void`
  `rollbackChanges()`
  Resets all uncommitted changes made to the objects in this ObjectContext, cascading rollback operation all the way through the stack.
  `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`
  `setUserProperty(String key, Object value)`
  Sets a user-defined property.
  `Collection<?>`
  `uncommittedObjects()`
  Returns a collection of MODIFIED, DELETED or NEW objects.

  ### Methods inherited from interface DataChannel

  `getEventManager, onQuery, onSync`
  Modifier and Type
  Method
  Description
  `EventManager`
  `getEventManager()`
  Returns an EventManager associated with this channel.
  `QueryResponse`
  `onQuery(ObjectContext originatingContext, Query query)`
  Executes a query, using provided context to register persistent objects if query returns any objects.
  `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.

- ## Method Details

  - ### getEntityResolver

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

  - ### newObjects

    Collection<?> newObjects()
    Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.NEW

  - ### deletedObjects

    Collection<?> deletedObjects()
    Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.DELETED

  - ### modifiedObjects

    Collection<?> modifiedObjects()
    Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.MODIFIED

  - ### uncommittedObjects

    Collection<?> uncommittedObjects()
    Returns a collection of MODIFIED, DELETED or NEW objects.

  - ### localObject

    <T extends Persistent> T localObject(T objectFromAnotherContext)
    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.

    Since:
      3.1

  - ### newObject

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

  - ### registerNewObject

    void registerNewObject(Object object)
    Registers a transient object with the context. The difference with `newObject(Class)` is that a user creates an object herself, before attaching it to the context, instead of relying on Cayenne to do that.
    Parameters:
      `object` - new object that needs to be made persistent.
    Since:
      3.0

  - ### deleteObject

    void deleteObject(Object object) throws DeleteDenyException
    Schedules deletion of a persistent object.
    Throws:
      `DeleteDenyException` - if a `DeleteRule.DENY` delete rule is applicable for object deletion.

  - ### deleteObjects

    void deleteObjects(Collection<?> objects) throws DeleteDenyException
    Schedules deletion of a collection of persistent objects.
    Throws:
      `DeleteDenyException` - if a `DeleteRule.DENY` delete rule is applicable for object deletion.

  - ### deleteObjects

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

  - ### prepareForAccess

    void prepareForAccess(Persistent object, String property, boolean lazyFaulting)
    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.
    Since:
      3.0

  - ### propertyChanged

    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.

  - ### commitChanges

    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.

  - ### commitChangesToParent

    void commitChangesToParent()
    Flushes all changes to objects in this context to the parent DataChannel. Same as `commitChanges()`, but no cascading flush occurs.

  - ### rollbackChanges

    void rollbackChanges()
    Resets all uncommitted changes made to the objects in this ObjectContext, cascading rollback operation all the way through the stack.

  - ### rollbackChangesLocally

    void rollbackChangesLocally()
    Resets all uncommitted changes made to the objects in this ObjectContext. Same as `rollbackChanges()`, but rollback is local to this context and no cascading changes undoing occurs.

  - ### performQuery

    List performQuery(Query query)
    Executes a selecting query, returning a list of persistent objects or data rows.

  - ### select

    <T> List<T> select(Select<T> query)
    Executes a selecting query, returning a list of persistent objects or data rows.
    Since:
      4.0

  - ### selectOne

    <T> T selectOne(Select<T> query)
    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.
    Since:
      4.0

  - ### selectFirst

    <T> T selectFirst(Select<T> query)
    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 `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.

    Since:
      4.0

  - ### iterate

    <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. The caller does not need to worry about closing the iterator. This method takes care of it.
    Since:
      4.0

  - ### iterator

    <T> ResultIterator<T> iterator(Select<T> query)
    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 `iterate(Select, ResultIteratorCallback)` as an alternative.
    Since:
      4.0

  - ### batchIterator

    <T> ResultBatchIterator<T> batchIterator(Select<T> query, int size)
    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.
    Since:
      4.0

  - ### performGenericQuery

    QueryResponse performGenericQuery(Query query)
    Executes any kind of query providing the result in a form of QueryResponse.

  - ### getGraphManager

    GraphManager getGraphManager()
    Returns GraphManager that manages object graph associated with this context.

  - ### getChannel

    DataChannel getChannel()
    Returns an DataChannel used by this context.

  - ### hasChanges

    boolean hasChanges()
    Returns `true` if there are any modified, deleted or new objects registered with this ObjectContext, `false` otherwise.
    Since:
      3.0

  - ### invalidateObjects

    void invalidateObjects(Collection<?> objects)
    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.

  - ### invalidateObjects

    <T> void invalidateObjects(T... objects)
    Invalidates one or more persistent objects. Same as `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.
    Since:
      3.1

  - ### getUserProperty

    Object getUserProperty(String key)
    Returns a user-defined property previously set via 'setUserProperty'. Concurrent access to properties does not require any special synchronization
    Since:
      3.0

  - ### setUserProperty

    void setUserProperty(String key, Object value)
    Sets a user-defined property. Concurrent access to properties does not require any special synchronization
    Since:
      3.0

  - ### removeUserProperty

    void removeUserProperty(String key)
    Removes a user-defined property.
    Since:
      5.0

  - ### clearUserProperties

    void clearUserProperties()
    Removes all user-defined properties.
    Since:
      5.0