Interface ObjectContext

All Known Implementing Classes:
DataContext
public interface ObjectContext
The main user-facing persistence API to work with a database. Holds own copy of an object graph. Any uncommitted changes to persistent objects that are registered with the context, are not visible to the users of other contexts.
Since:
1.2

  • Method Summary

    Modifier and Type
    Method
    Description
    default <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.
    default Collection<Persistent>
    deletedObjects()
    Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.DELETED
    default void
    deleteObject(Persistent object)
    Schedules deletion of a persistent object.
    default void
    deleteObjects(Collection<? extends Persistent> objects)
    Schedules deletion of a collection of persistent objects.
    <T extends Persistent>
    void
    deleteObjects(T... objects)
    Schedules deletion of one or more persistent objects.
    List<QueryResult>
    execute(Query query)
    Executes any kind of query, returning all of its result sets, update counts, iterators and OUT parameters as a list of QueryResults in the order they were produced.
    DataChannel
    getChannel()
    Returns a DataChannel that this context uses to access the persistent store.
    EntityResolver
    getEntityResolver()
    Returns EntityResolver that stores all mapping information accessible by this ObjectContext.
    ObjectStore
    getObjectStore()
    Returns the store of persistent objects registered with this context.
    Object
    getUserProperty(String key)
    Returns a user-defined property previously set via 'setUserProperty'.
    default boolean
    hasChanges()
    Returns true if there are any modified, deleted or new objects registered with this ObjectContext, false otherwise.
    void
    invalidateObjects(Collection<? extends Persistent> objects)
    Invalidates a Collection of persistent objects.
    <T extends Persistent>
    void
    invalidateObjects(T... objects)
    Invalidates one or more persistent objects.
    default <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.
    default Collection<Persistent>
    modifiedObjects()
    Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.MODIFIED
    default <T extends Persistent>
    T
    newObject(Class<T> persistentClass)
    Creates a new persistent object of a given class scheduled to be inserted to the database on next commit.
    Persistent
    newObject(String entityName)
    Creates a new persistent object of a given entity scheduled to be inserted to the database on next commit.
    default Collection<Persistent>
    newObjects()
    Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.NEW
    default <T extends Persistent>
    T
    objectForPK(Class<T> type, Object pk)
    Returns an object matching a single-column primary key, or null if there's no such object.
    default <T extends Persistent>
    T
    objectForPK(Class<T> type, Map<String,?> pk)
    Returns an object matching a primary key, or null if there's no such object.
    default Persistent
    objectForPK(String entityName, Object pk)
    Returns an object matching a single-column primary key, or null if there's no such object.
    default Persistent
    objectForPK(String entityName, Map<String,?> pk)
    Returns an object matching a primary key, or null if there's no such object.
    Persistent
    objectForPK(ObjectId id)
    Returns an object matching an ObjectId, or null if there's no such object.
    default List
    performQuery(Query query)
    Deprecated, for removal: This API element is subject to removal in a future version.
    use select(Select).
    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(Persistent 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.
    default <T> T
    selectFirst(Select<T> query)
    Selects a single object using provided query.
    default <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<Persistent>
    uncommittedObjects()
    Returns a collection of MODIFIED, DELETED or NEW objects.

  • Method Details

    • getChannel

      DataChannel getChannel()
      Returns a DataChannel that this context uses to access the persistent store.

    • getEntityResolver

      EntityResolver getEntityResolver()
      Returns EntityResolver that stores all mapping information accessible by this ObjectContext.

    • newObjects

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

    • deletedObjects

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

    • modifiedObjects

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

    • uncommittedObjects

      Collection<Persistent> 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

    • objectForPK

      default <T extends Persistent> T objectForPK(Class<T> type, Object pk)
      Returns an object matching a single-column primary key, or null if there's no such object. If the entity is mapped with a compound PK, CayenneRuntimeException is thrown.

      A resolved object registered in this context is returned without a query. Otherwise the object is looked up in the caches down the DataChannel stack, and then in the database.

      Since:
      5.0

    • objectForPK

      default <T extends Persistent> T objectForPK(Class<T> type, Map<String,?> pk)
      Returns an object matching a primary key, or null if there's no such object. The PK map parameter should use database PK column names as keys.

      A resolved object registered in this context is returned without a query. Otherwise the object is looked up in the caches down the DataChannel stack, and then in the database.

      Since:
      5.0

    • objectForPK

      default Persistent objectForPK(String entityName, Object pk)
      Returns an object matching a single-column primary key, or null if there's no such object. If the entity is mapped with a compound PK, CayenneRuntimeException is thrown.

      A resolved object registered in this context is returned without a query. Otherwise the object is looked up in the caches down the DataChannel stack, and then in the database.

      Since:
      5.0

    • objectForPK

      default Persistent objectForPK(String entityName, Map<String,?> pk)
      Returns an object matching a primary key, or null if there's no such object. The PK map parameter should use database PK column names as keys.

      A resolved object registered in this context is returned without a query. Otherwise the object is looked up in the caches down the DataChannel stack, and then in the database.

      Since:
      5.0

    • objectForPK

      Persistent objectForPK(ObjectId id)
      Returns an object matching an ObjectId, or null if there's no such object. The id may be that of a superentity of the actual object entity.

      A resolved object registered in this context is returned without a query. Otherwise the object is looked up in the caches down the DataChannel stack, and then in the database.

      Throws:
      FaultFailureException - if more than one row matches the id.
      Since:
      5.0

    • newObject

      default <T extends Persistent> T newObject(Class<T> persistentClass)
      Creates a new persistent object of a given class scheduled to be inserted to the database on next commit.

    • newObject

      Persistent newObject(String entityName)
      Creates a new persistent object of a given entity scheduled to be inserted to the database on next commit. The object class is determined from the mapped entity. In most cases newObject(Class) should be used instead, but this method is helpful when generic persistent classes are used.
      Since:
      5.0

    • registerNewObject

      void registerNewObject(Persistent 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

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

    • deleteObjects

      default void deleteObjects(Collection<? extends Persistent> 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 extends Persistent> void deleteObjects(T... objects) throws DeleteDenyException
      Schedules deletion of one or more persistent 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

      @Deprecated(since="5.0", forRemoval=true) default List performQuery(Query query)
      Deprecated, for removal: This API element is subject to removal in a future version.
      use select(Select). All selecting queries implement Select.
      Executes a selecting query, returning a list of persistent objects or data rows.
      Throws:
      ClassCastException - if the query does not implement Select

    • 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

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

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

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

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

    • execute

      List<QueryResult> execute(Query query)
      Executes any kind of query, returning all of its result sets, update counts, iterators and OUT parameters as a list of QueryResults in the order they were produced.

    • getObjectStore

      ObjectStore getObjectStore()
      Returns the store of persistent objects registered with this context.
      Since:
      5.0

    • hasChanges

      default 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<? extends Persistent> 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 extends Persistent> 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