ObjectStore (cayenne-doc: Cayenne Documentation 5.0-M2 API)
Description: declaration: package: org.apache.cayenne.access, class: ObjectStore

# Class ObjectStore

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

All Implemented Interfaces:
  `Serializable, EventListener, SnapshotEventListener, GraphChangeHandler, GraphManager`

Direct Known Subclasses:
  `NoSyncObjectStore`

public class ObjectStore extends Object implements Serializable, SnapshotEventListener, GraphManager
ObjectStore stores objects using their ObjectId as a key. It works as a dedicated object cache for a DataContext. Users rarely need to access ObjectStore directly, as DataContext serves as a facade, providing cover methods for most ObjectStore operations.

Since:
  1.0
See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Map<Object, ObjectDiff>`
  `changes`
  `protected DataContext`
  `context`
  The DataContext that owns this ObjectStore.
  `protected DataRowStore`
  `dataRowCache`
  Stores a reference to the DataRowStore.
  `protected boolean`
  `dataRowCacheSet`
  `protected Map<Object, Persistent>`
  `objectMap`
  `protected Map<Object, Map<CayennePath, ObjectId>>`
  `trackedFlattenedPaths`
  Map that tracks flattened paths for given object Id that is present in db.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ObjectStore(DataRowStore dataRowCache, Map<Object, Persistent> objectMap)`
  Creates an ObjectStore with `DataRowStore` and a map to use for storing registered objects.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `arcCreated(Object nodeId, Object targetNodeId, ArcId arcId)`
  Notifies implementing object that a new arc was created between two nodes.
  `void`
  `arcDeleted(Object nodeId, Object targetNodeId, ArcId arcId)`
  Notifies implementing object that an arc between two nodes was deleted.
  `DataRow`
  `getCachedSnapshot(ObjectId oid)`
  Returns a snapshot for ObjectId from the underlying snapshot cache.
  `DataContext`
  `getContext()`
  `DataRowStore`
  `getDataRowCache()`
  Returns a DataRowStore associated with this ObjectStore.
  `ObjectId`
  `getFlattenedId(ObjectId objectId, CayennePath path)`
  `Collection<ObjectId>`
  `getFlattenedIds(ObjectId objectId)`
  `Map<CayennePath, ObjectId>`
  `getFlattenedPathIdMap(ObjectId objectId)`
  `Object`
  `getNode(Object nodeId)`
  Returns a registered Persistent objects or null of no object exists for the ObjectId.
  `Iterator<Persistent>`
  `getObjectIterator()`
  Returns an iterator over the registered objects.
  `DataRow`
  `getSnapshot(ObjectId oid)`
  Returns a snapshot for ObjectId from the underlying snapshot cache.
  `boolean`
  `hasChanges()`
  Returns `true` if there are any modified, deleted or new objects registered with this ObjectStore, `false` otherwise.
  `void`
  `markFlattenedPath(ObjectId objectId, CayennePath path, ObjectId id)`
  Mark that flattened path for object has data row in DB.
  `void`
  `nodeCreated(Object nodeId)`
  Notifies implementing object that a new node was created in the graph.
  `void`
  `nodeIdChanged(Object nodeId, Object newId)`
  Does nothing.
  `void`
  `nodePropertyChanged(Object nodeId, String property, Object oldValue, Object newValue)`
  Records dirty object snapshot.
  `void`
  `nodeRemoved(Object nodeId)`
  Notifies implementing object that a node was removed from the graph.
  `List<Persistent>`
  `objectsInState(int state)`
  Return a subset of registered objects that are in a certain persistence state.
  `void`
  `objectsRolledBack()`
  Reverts changes to all stored uncomitted objects.
  `void`
  `objectsUnregistered(Collection objects)`
  Evicts a collection of Persistent objects from the ObjectStore, invalidates the underlying cache snapshots.
  `void`
  `postprocessAfterCommit(GraphDiff parentChanges)`
  Internal unsynchronized method to process objects state after commit.
  `Collection<Object>`
  `registeredNodes()`
  Returns all registered Persistent objects.
  `int`
  `registeredObjectsCount()`
  Returns a number of objects currently registered with this ObjectStore.
  `void`
  `registerNode(Object nodeId, Object nodeObject)`
  "Registers" a graph node, usually storing the node in some internal map using its id as a key.
  `void`
  `setContext(DataContext context)`
  `void`
  `setDataRowCache(DataRowStore dataRowCache)`
  Sets parent DataRowStore.
  `void`
  `snapshotsChanged(SnapshotEvent event)`
  SnapshotEventListener implementation that processes snapshot change event, updating Persistent objects that have the changes.
  `Object`
  `unregisterNode(Object nodeId)`
  "Unregisters" a graph node, forgetting any information associated with nodeId.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### objectMap

    protected Map<Object, Persistent> objectMap

  - ### changes

    protected Map<Object, ObjectDiff> changes

  - ### trackedFlattenedPaths

    protected Map<Object, Map<CayennePath, ObjectId>> trackedFlattenedPaths
    Map that tracks flattened paths for given object Id that is present in db. Presence of path in this map is used to separate insert from update case of flattened records.
    Since:
      4.1

  - ### dataRowCache

    protected transient DataRowStore dataRowCache
    Stores a reference to the DataRowStore.

    Serialization note: It is up to the owner of this ObjectStore to initialize DataRowStore after deserialization of this object. ObjectStore will not know how to restore the DataRowStore by itself.

  - ### dataRowCacheSet

    protected boolean dataRowCacheSet

  - ### context

    protected DataContext context
    The DataContext that owns this ObjectStore.

- ## Constructor Details

  - ### ObjectStore

    public ObjectStore(DataRowStore dataRowCache, Map<Object, Persistent> objectMap)
    Creates an ObjectStore with `DataRowStore` and a map to use for storing registered objects. Passed map doesn't require any special synchronization behavior, as ObjectStore is synchronized itself.
    Since:
      3.0

- ## Method Details

  - ### registeredObjectsCount

    public int registeredObjectsCount()
    Returns a number of objects currently registered with this ObjectStore.
    Since:
      1.2

  - ### getDataRowCache

    public DataRowStore getDataRowCache()
    Returns a DataRowStore associated with this ObjectStore.

  - ### setDataRowCache

    public void setDataRowCache(DataRowStore dataRowCache)
    Sets parent DataRowStore. Registers to receive SnapshotEvents if the cache is configured to allow ObjectStores to receive such events.

  - ### objectsUnregistered

    public void objectsUnregistered(Collection objects)
    Evicts a collection of Persistent objects from the ObjectStore, invalidates the underlying cache snapshots. Changes objects state to TRANSIENT. This method can be used for manual cleanup of Cayenne cache.

  - ### objectsRolledBack

    public void objectsRolledBack()
    Reverts changes to all stored uncomitted objects.
    Since:
      1.1

  - ### postprocessAfterCommit

    public void postprocessAfterCommit(GraphDiff parentChanges)
    Internal unsynchronized method to process objects state after commit.
    Since:
      1.2

  - ### getCachedSnapshot

    public DataRow getCachedSnapshot(ObjectId oid)
    Returns a snapshot for ObjectId from the underlying snapshot cache. If cache contains no snapshot, a null is returned.
    Since:
      1.1

  - ### getSnapshot

    public DataRow getSnapshot(ObjectId oid)
    Returns a snapshot for ObjectId from the underlying snapshot cache. If cache contains no snapshot, it will attempt fetching it using provided DataNode. If fetch attempt fails or inconsistent data is returned, underlying cache will throw a CayenneRuntimeException.
    Since:
      1.2

  - ### getObjectIterator

    public Iterator<Persistent> getObjectIterator()
    Returns an iterator over the registered objects.

  - ### hasChanges

    public boolean hasChanges()
    Returns `true` if there are any modified, deleted or new objects registered with this ObjectStore, `false` otherwise. This method will treat "phantom" modifications are real ones. I.e. if you "change" an object property to an equivalent value, this method will still think such object is modified. Phantom modifications are only detected and discarded during commit.

  - ### objectsInState

    public List<Persistent> objectsInState(int state)
    Return a subset of registered objects that are in a certain persistence state. Collection is returned by copy.

  - ### snapshotsChanged

    public void snapshotsChanged(SnapshotEvent event)
    SnapshotEventListener implementation that processes snapshot change event, updating Persistent objects that have the changes.

    Implementation note: This method should not attempt to alter the underlying DataRowStore, since it is normally invoked *AFTER* the DataRowStore was modified as a result of some external interaction.

    Specified by:
      `snapshotsChanged` in interface `SnapshotEventListener`
    Since:
      1.1

  - ### getContext

    public DataContext getContext()
    Since:
      1.2

  - ### setContext

    public void setContext(DataContext context)
    Since:
      1.2

  - ### getNode

    public Object getNode(Object nodeId)
    Returns a registered Persistent objects or null of no object exists for the ObjectId.
    Specified by:
      `getNode` in interface `GraphManager`
    Since:
      1.2

  - ### registeredNodes

    public Collection<Object> registeredNodes()
    Returns all registered Persistent objects. List is returned by copy and can be modified by the caller.
    Specified by:
      `registeredNodes` in interface `GraphManager`
    Since:
      1.2

  - ### registerNode

    public void registerNode(Object nodeId, Object nodeObject)
    Description copied from interface: `GraphManager`
    "Registers" a graph node, usually storing the node in some internal map using its id as a key.
    Specified by:
      `registerNode` in interface `GraphManager`
    Since:
      1.2

  - ### unregisterNode

    public Object unregisterNode(Object nodeId)
    Description copied from interface: `GraphManager`
    "Unregisters" a graph node, forgetting any information associated with nodeId.
    Specified by:
      `unregisterNode` in interface `GraphManager`
    Since:
      1.2

  - ### nodeIdChanged

    public void nodeIdChanged(Object nodeId, Object newId)
    Does nothing.
    Specified by:
      `nodeIdChanged` in interface `GraphChangeHandler`
    Since:
      1.2

  - ### nodeCreated

    public void nodeCreated(Object nodeId)
    Description copied from interface: `GraphChangeHandler`
    Notifies implementing object that a new node was created in the graph.
    Specified by:
      `nodeCreated` in interface `GraphChangeHandler`
    Since:
      1.2

  - ### nodeRemoved

    public void nodeRemoved(Object nodeId)
    Description copied from interface: `GraphChangeHandler`
    Notifies implementing object that a node was removed from the graph.
    Specified by:
      `nodeRemoved` in interface `GraphChangeHandler`
    Since:
      1.2

  - ### nodePropertyChanged

    public void nodePropertyChanged(Object nodeId, String property, Object oldValue, Object newValue)
    Records dirty object snapshot.
    Specified by:
      `nodePropertyChanged` in interface `GraphChangeHandler`
    Since:
      1.2

  - ### arcCreated

    public void arcCreated(Object nodeId, Object targetNodeId, ArcId arcId)
    Description copied from interface: `GraphChangeHandler`
    Notifies implementing object that a new arc was created between two nodes.
    Specified by:
      `arcCreated` in interface `GraphChangeHandler`
    Since:
      1.2

  - ### arcDeleted

    public void arcDeleted(Object nodeId, Object targetNodeId, ArcId arcId)
    Description copied from interface: `GraphChangeHandler`
    Notifies implementing object that an arc between two nodes was deleted.
    Specified by:
      `arcDeleted` in interface `GraphChangeHandler`
    Since:
      1.2

  - ### getFlattenedId

    public ObjectId getFlattenedId(ObjectId objectId, CayennePath path)
    Since:
      4.2

  - ### getFlattenedIds

    public Collection<ObjectId> getFlattenedIds(ObjectId objectId)
    Since:
      4.2

  - ### getFlattenedPathIdMap

    public Map<CayennePath, ObjectId> getFlattenedPathIdMap(ObjectId objectId)
    Since:
      5.0

  - ### markFlattenedPath

    public void markFlattenedPath(ObjectId objectId, CayennePath path, ObjectId id)
    Mark that flattened path for object has data row in DB.
    Since:
      4.1