org.apache.cayenne
Interface ObjectContext

All Superinterfaces:

Serializable

All Known Implementing Classes:

BaseContext, CayenneContext, DataContext

public interface ObjectContext
extends 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

Method Summary

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.
ObjectContext	createChildContext() Creates and returns a new child ObjectContext.
Collection<?>	deletedObjects() Returns a collection of objects that are registered with this ObjectContext and have a state PersistenceState.DELETED
void	deleteObject(Object object) Schedules a persistent object for deletion on next commit.
void	deleteObjects(Collection<?> objects) Deletes a collection of objects by repeatedly calling deleteObject safely (avoiding a concurrent modification exception).
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.
Persistent	localObject(ObjectId id, Object prototype) Returns an object local to this ObjectContext and matching the ObjectId.
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) Deprecated. since 3.0 use prepareForAccess(Persistent, String, boolean).
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	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.
void	setUserProperty(String key, Object value) Sets a user-defined property.
Collection<?>	uncommittedObjects() Returns a collection of MODIFIED, DELETED or NEW objects.

Method Detail

getEntityResolver

EntityResolver getEntityResolver()

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

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

Persistent localObject(ObjectId id,
                       Object prototype)

Returns an object local to this ObjectContext and matching the ObjectId. If prototype is not null, local object is refreshed with the prototype values.

This method can do both "mapping" (i.e. finding an object with the same id in this context) and "synchronization" (i.e. updating the state of the found object with the state of the prototype object).

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 a persistent object for deletion on next commit.

Throws:

DeleteDenyException - if a DeleteRule.DENY delete rule is applicable for object deletion.

deleteObjects

void deleteObjects(Collection<?> objects)
                   throws DeleteDenyException

Deletes a collection of objects by repeatedly calling deleteObject safely (avoiding a concurrent modification exception).

Throws:

DeleteDenyException

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

prepareForAccess

@Deprecated
void prepareForAccess(Persistent object,
                                 String property)

Deprecated. since 3.0 use prepareForAccess(Persistent, String, boolean).

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.

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.

createChildContext

ObjectContext createChildContext()

Creates and returns a new child ObjectContext.

Since:

3.0

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.

See Also:

RefreshQuery

getUserProperty

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.

Since:

3.0

setUserProperty

void setUserProperty(String key,
                     Object value)

Sets a user-defined property. Note that it is a caller responsibility to synchronize access to properties.

Since:

3.0