|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.apache.cayenne.access.DataContext
public class DataContext
Class that provides applications with access to Cayenne persistence features. In most cases this is the only access class directly used in the application.
Most common DataContext use pattern is to create one DataContext per session. "Session" may be a an HttpSession in a web application, or any other similar concept in a multiuser application.
DataObjects are registered with DataContext either implicitly when they are fetched via
a query, or read via a relationship from another object, or explicitly via calling
createAndRegisterNewObject(Class)
during new DataObject creation. DataContext
tracks changes made to its DataObjects in memory, and flushes them to the database when
commitChanges()
is called. Until DataContext is committed, changes made to its
objects are not visible in other DataContexts.
Each DataObject can belong only to a single DataContext. To create a replica of an
object from a different DataContext in a local context, use
localObject(ObjectId, Persistent)
method.
For more information see Cayenne User Guide.
Note that all QueryEngine interface methods are deprecated in the DataContext. Since 1.2 release DataContext implements ObjectContext and DataChannel interfaces.
Field Summary | |
---|---|
protected DataChannel |
channel
|
static EventSubject |
DID_COMMIT
|
static EventSubject |
DID_ROLLBACK
|
protected EntityResolver |
entityResolver
|
protected java.lang.String |
lazyInitParentDomainName
Stores the name of parent DataDomain. |
protected org.apache.cayenne.access.DataContextMergeHandler |
mergeHandler
|
protected ObjectStore |
objectStore
|
protected static java.lang.ThreadLocal |
threadDataContext
A holder of a DataContext bound to the current thread. |
protected java.util.Map |
userProperties
Stores user defined properties associated with this DataContext. |
protected boolean |
usingSharedSnaphsotCache
|
protected boolean |
validatingObjectsOnCommit
|
static EventSubject |
WILL_COMMIT
|
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 | |
---|---|
DataContext()
Creates a new DataContext that is not attached to the Cayenne stack. |
|
DataContext(DataChannel channel,
ObjectStore objectStore)
Creates a new DataContext with parent DataChannel and ObjectStore. |
|
DataContext(QueryEngine parent,
ObjectStore objectStore)
Deprecated. since 1.2 - use DataContext(DataChannel, ObjectStore)
constructor instead. Note that DataDomain is both a DataChannel and a
QueryEngine, so you may need to do a cast:
new DataContext((DataChannel) domain, objectStore) . |
Method Summary | |
---|---|
static void |
bindThreadDataContext(DataContext context)
Binds a DataContext to the current thread. |
void |
commitChanges()
Synchronizes object graph with the database. |
void |
commitChanges(org.apache.log4j.Level logLevel)
Deprecated. Since 1.2, use commitChanges() instead. |
void |
commitChangesToParent()
"Flushes" the changes to the parent DataChannel . |
DataObject |
createAndRegisterNewObject(java.lang.Class objectClass)
Instantiates new object and registers it with itself. |
DataObject |
createAndRegisterNewObject(java.lang.String objEntityName)
Instantiates new object and registers it with itself. |
DataContext |
createChildDataContext()
Creates and returns a new child DataContext. |
static DataContext |
createDataContext()
Factory method that creates and returns a new instance of DataContext based on default domain. |
static DataContext |
createDataContext(boolean useSharedCache)
Factory method that creates and returns a new instance of DataContext based on default domain. |
static DataContext |
createDataContext(java.lang.String domainName)
Factory method that creates and returns a new instance of DataContext using named domain as its parent. |
static DataContext |
createDataContext(java.lang.String domainName,
boolean useSharedCache)
Creates and returns new DataContext that will use a named DataDomain as its parent. |
DataRow |
currentSnapshot(DataObject object)
Returns a DataRow reflecting current, possibly uncommitted, object state. |
java.util.Collection |
deletedObjects()
Returns a list of objects that are registered with this DataContext and have a state PersistenceState.DELETED |
void |
deleteObject(Persistent object)
Schedules an object for deletion on the next commit of this DataContext. |
void |
deleteObjects(java.util.Collection objects)
Schedules all objects in the collection for deletion on the next commit of this DataContext. |
DataChannel |
getChannel()
Returns parent DataChannel, that is normally a DataDomain or another DataContext. |
java.util.Collection |
getDataMaps()
Deprecated. since 1.2. Use 'getEntityResolver().getDataMaps()' instead. |
DataContextDelegate |
getDelegate()
Returns a delegate currently associated with this DataContext. |
EntityResolver |
getEntityResolver()
Returns EntityResolver. |
EventManager |
getEventManager()
Returns EventManager associated with the ObjectStore. |
GraphManager |
getGraphManager()
Returns this context's ObjectStore. |
ObjectStore |
getObjectStore()
Returns ObjectStore associated with this DataContext. |
QueryEngine |
getParent()
Deprecated. since 1.2. Use 'getParentDataDomain()' or 'getChannel()' instead. |
DataDomain |
getParentDataDomain()
Returns a DataDomain used by this DataContext. |
static DataContext |
getThreadDataContext()
Returns the DataContext bound to the current thread. |
protected java.util.Map |
getUserProperties()
Returns a map of user-defined properties associated with this DataContext. |
java.lang.Object |
getUserProperty(java.lang.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 DataContext, false otherwise. |
void |
invalidateObjects(java.util.Collection dataObjects)
"Invalidates" a Collection of DataObject. |
boolean |
isTransactionEventsEnabled()
|
boolean |
isUsingSharedSnapshotCache()
Returns true if the ObjectStore uses shared cache of a parent
DataDomain. |
boolean |
isValidatingObjectsOnCommit()
Returns whether this DataContext performs object validation before commit is executed. |
Persistent |
localObject(ObjectId id,
Persistent prototype)
Returns an object local to this DataContext and matching the ObjectId. |
java.util.List |
localObjects(java.util.List objects)
Deprecated. since 1.2 - use localObject(ObjectId, Persistent) to specify
how each local object should be handled. |
DataNode |
lookupDataNode(DataMap dataMap)
Deprecated. since 1.2 DataContext's QueryEngine implementation is replaced by DataChannel. Use "getParentDataDomain().lookupDataNode(..)". |
java.util.Collection |
modifiedObjects()
Returns a list of objects that are registered with this DataContext and have a state PersistenceState.MODIFIED |
Persistent |
newObject(java.lang.Class persistentClass)
Creates and registers new persistent object. |
java.util.Collection |
newObjects()
Returns a list of objects that are registered with this DataContext and have a state PersistenceState.NEW |
DataObject |
objectFromDataRow(java.lang.Class objectClass,
DataRow dataRow,
boolean refresh)
Creates a DataObject from DataRow. |
java.util.List |
objectsFromDataRows(java.lang.Class objectClass,
java.util.List dataRows,
boolean refresh,
boolean resolveInheritanceHierarchy)
Converts a list of DataRows to a List of DataObject registered with this DataContext. |
java.util.List |
objectsFromDataRows(ObjEntity entity,
java.util.List dataRows,
boolean refresh,
boolean resolveInheritanceHierarchy)
Converts a list of data rows to a list of DataObjects. |
QueryResponse |
onQuery(ObjectContext context,
Query query)
An implementation of a DataChannel method that is used by child contexts to
execute queries. |
GraphDiff |
onSync(ObjectContext originatingContext,
GraphDiff changes,
int syncType)
An implementation of a DataChannel method that is used by child contexts to
synchronize state with this context. |
QueryResponse |
performGenericQuery(Query query)
Executes a query returning a generic response. |
ResultIterator |
performIteratedQuery(Query query)
Performs a single database select query returning result as a ResultIterator. |
int[] |
performNonSelectingQuery(Query query)
Performs a single database query that does not select rows. |
int[] |
performNonSelectingQuery(java.lang.String queryName)
Performs a named mapped query that does not select rows. |
int[] |
performNonSelectingQuery(java.lang.String queryName,
java.util.Map parameters)
Performs a named mapped non-selecting query using a map of parameters. |
void |
performQueries(java.util.Collection queries,
OperationObserver callback)
Deprecated. since 1.2 DataContext's QueryEngine implementation is replaced by DataChannel. |
void |
performQueries(java.util.Collection queries,
OperationObserver callback,
Transaction transaction)
Deprecated. since 1.2. Use Transaction.bindThreadTransaction(..) to provide custom transactions, besides DataContext's QueryEngine implementation is replaced by DataChannel. |
java.util.List |
performQuery(Query query)
Performs a single selecting query. |
java.util.List |
performQuery(java.lang.String queryName,
boolean expireCachedLists)
Returns a list of objects or DataRows for a named query stored in one of the DataMaps. |
java.util.List |
performQuery(java.lang.String queryName,
java.util.Map parameters,
boolean expireCachedLists)
Returns a list of objects or DataRows for a named query stored in one of the DataMaps. |
void |
prefetchRelationships(SelectQuery query,
java.util.List objects)
Deprecated. Since 1.2. This is a utility method that handles a very specific case. It shouldn't be in DataContext. |
void |
prepareForAccess(Persistent object,
java.lang.String property)
Resolves object fault if needed. |
void |
propertyChanged(Persistent object,
java.lang.String property,
java.lang.Object oldValue,
java.lang.Object newValue)
Retains DataObject snapshot and changes its state if needed. |
DataObject |
refetchObject(ObjectId oid)
Refetches object data for ObjectId. |
DataObject |
registeredObject(ObjectId id)
Deprecated. since 1.2 use 'localObject(id, null)' |
void |
registerNewObject(DataObject object)
Registers a transient object with the context, recursively registering all transient DataObjects attached to this object via relationships. |
void |
rollbackChanges()
Reverts any changes that have occurred to objects registered with DataContext; also performs cascading rollback of all parent DataContexts. |
void |
rollbackChangesLocally()
If the parent channel is a DataContext, reverts local changes to make this context look like the parent, if the parent channel is a DataDomain, reverts all changes. |
void |
setChannel(DataChannel channel)
|
void |
setDelegate(DataContextDelegate delegate)
Sets a DataContextDelegate for this context. |
void |
setParent(QueryEngine parent)
Deprecated. since 1.2, use setChannel instead. |
void |
setTransactionEventsEnabled(boolean flag)
Enables or disables posting of transaction events by this DataContext. |
static void |
setTransactionEventsEnabledDefault(boolean flag)
Sets default for posting transaction events by new DataContexts. |
void |
setUserProperty(java.lang.String key,
java.lang.Object value)
Sets a user-defined property. |
void |
setValidatingObjectsOnCommit(boolean flag)
Sets the property defining whether this DataContext should perform object validation before commit is executed. |
java.util.Collection |
uncommittedObjects()
Returns a collection of all uncommitted registered objects. |
void |
unregisterObjects(java.util.Collection dataObjects)
Unregisters a Collection of DataObjects from the DataContext and the underlying ObjectStore. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final EventSubject WILL_COMMIT
public static final EventSubject DID_COMMIT
public static final EventSubject DID_ROLLBACK
protected static final java.lang.ThreadLocal threadDataContext
protected boolean usingSharedSnaphsotCache
protected boolean validatingObjectsOnCommit
protected ObjectStore objectStore
protected transient DataChannel channel
protected transient EntityResolver entityResolver
protected transient org.apache.cayenne.access.DataContextMergeHandler mergeHandler
protected java.util.Map userProperties
protected transient java.lang.String lazyInitParentDomainName
Constructor Detail |
---|
public DataContext()
public DataContext(QueryEngine parent, ObjectStore objectStore)
DataContext(DataChannel, ObjectStore)
constructor instead. Note that DataDomain is both a DataChannel and a
QueryEngine, so you may need to do a cast:
new DataContext((DataChannel) domain, objectStore)
.
parent
- parent QueryEngine used to communicate with the data source.objectStore
- ObjectStore used by DataContext.public DataContext(DataChannel channel, ObjectStore objectStore)
Method Detail |
---|
public static DataContext getThreadDataContext() throws java.lang.IllegalStateException
java.lang.IllegalStateException
- if there is no DataContext bound to the current
thread.WebApplicationContextFilter
public static void bindThreadDataContext(DataContext context)
getThreadDataContext()
.
Using null parameter will unbind currently bound DataContext.
public static DataContext createDataContext()
createDataContext(String)
must be used instead. ObjectStore
associated with created DataContext will have a cache stack configured using parent
domain settings.
public static DataContext createDataContext(boolean useSharedCache)
createDataContext(String, boolean)
must be used instead.
ObjectStore associated with newly created DataContext will have a cache stack
configured according to the specified policy, overriding a parent domain setting.
public static DataContext createDataContext(java.lang.String domainName)
public static DataContext createDataContext(java.lang.String domainName, boolean useSharedCache)
protected java.util.Map getUserProperties()
public DataContext createChildDataContext()
public java.lang.Object getUserProperty(java.lang.String key)
public void setUserProperty(java.lang.String key, java.lang.Object value)
public QueryEngine getParent()
public void setParent(QueryEngine parent)
public DataChannel getChannel()
getChannel
in interface ObjectContext
public void setChannel(DataChannel channel)
public DataDomain getParentDataDomain()
public void setDelegate(DataContextDelegate delegate)
public DataContextDelegate getDelegate()
public ObjectStore getObjectStore()
public boolean hasChanges()
true
if there are any modified, deleted or new objects
registered with this DataContext, false
otherwise.
public java.util.Collection newObjects()
newObjects
in interface ObjectContext
public java.util.Collection deletedObjects()
deletedObjects
in interface ObjectContext
public java.util.Collection modifiedObjects()
modifiedObjects
in interface ObjectContext
public java.util.Collection uncommittedObjects()
uncommittedObjects
in interface ObjectContext
public DataObject registeredObject(ObjectId id)
public DataRow currentSnapshot(DataObject object)
Warning: This method will return a partial snapshot if an object or one of its related objects that propagate their keys to this object have temporary ids. DO NOT USE this method if you expect a DataRow to represent a complete object state.
public java.util.List localObjects(java.util.List objects)
localObject(ObjectId, Persistent)
to specify
how each local object should be handled.
Note that the objects in the list do not have to be of the same type or even from the same DataContext.
public java.util.List objectsFromDataRows(ObjEntity entity, java.util.List dataRows, boolean refresh, boolean resolveInheritanceHierarchy)
public java.util.List objectsFromDataRows(java.lang.Class objectClass, java.util.List dataRows, boolean refresh, boolean resolveInheritanceHierarchy)
objectsFromDataRows(ObjEntity,List,boolean,boolean)
.
DataRow
,
DataObject
public DataObject objectFromDataRow(java.lang.Class objectClass, DataRow dataRow, boolean refresh)
objectsFromDataRows(Class,java.util.List,boolean,boolean)
.
DataRow
,
DataObject
public DataObject createAndRegisterNewObject(java.lang.String objEntityName)
Note: preferred way to create new objects is via
createAndRegisterNewObject(Class)
method. It works exactly the same way,
but makes the application type-safe.
createAndRegisterNewObject(Class)
public Persistent newObject(java.lang.Class persistentClass)
newObject
in interface ObjectContext
public DataObject createAndRegisterNewObject(java.lang.Class objectClass)
public void registerNewObject(DataObject object)
object
- new object that needs to be made persistent.public void unregisterObjects(java.util.Collection dataObjects)
invalidateObjects(Collection)
public void invalidateObjects(java.util.Collection dataObjects)
unregisterObjects(Collection)
public void deleteObjects(java.util.Collection objects)
"Nullify" delete rule side effect: passing a collection representing to-many relationship with nullify delete rule may result in objects being removed from collection.
public void deleteObject(Persistent object) throws DeleteDenyException
deleteObject
in interface ObjectContext
object
- a persistent object that we want to delete.
DeleteDenyException
- if a DENY delete rule is applicable for object
deletion.
java.lang.NullPointerException
- if object is null.
DeleteDenyException
public DataObject refetchObject(ObjectId oid)
PersistenceState.HOLLOW
. It can also be
used to refresh certain objects.
CayenneRuntimeException
- if object id doesn't match any records, or if there
is more than one object is fetched.public DataNode lookupDataNode(DataMap dataMap)
lookupDataNode
in interface QueryEngine
public void rollbackChangesLocally()
rollbackChangesLocally
in interface ObjectContext
public void rollbackChanges()
rollbackChanges
in interface ObjectContext
public void commitChangesToParent()
DataChannel
. If the parent channel is
a DataContext, it updates its objects with this context's changes, without a
database update. If it is a DataDomain (the most common case), the changes are
written to the database. To cause cascading commit all the way to the database, one
must use commitChanges()
.
commitChangesToParent
in interface ObjectContext
commitChanges()
public void commitChanges(org.apache.log4j.Level logLevel) throws CayenneRuntimeException
commitChanges()
instead.
CayenneRuntimeException
public void commitChanges() throws CayenneRuntimeException
commitChanges
in interface ObjectContext
CayenneRuntimeException
public EventManager getEventManager()
getEventManager
in interface DataChannel
public GraphDiff onSync(ObjectContext originatingContext, GraphDiff changes, int syncType)
DataChannel
method that is used by child contexts to
synchronize state with this context. Not intended for direct use.
onSync
in interface DataChannel
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
.public ResultIterator performIteratedQuery(Query query) throws CayenneException
CayenneException
public QueryResponse performGenericQuery(Query query)
performGenericQuery
in interface ObjectContext
public java.util.List performQuery(Query query)
Since 1.2 takes any Query parameter, not just GenericSelectQuery
performQuery
in interface ObjectContext
QueryMetadata.isFetchingDataRows()
.public QueryResponse onQuery(ObjectContext context, Query query)
DataChannel
method that is used by child contexts to
execute queries. Not intended for direct use.
onQuery
in interface DataChannel
context
- an ObjectContext that originated the query, used to
register result objects.
public int[] performNonSelectingQuery(Query query)
public int[] performNonSelectingQuery(java.lang.String queryName)
public int[] performNonSelectingQuery(java.lang.String queryName, java.util.Map parameters)
public void performQueries(java.util.Collection queries, OperationObserver callback)
performQueries
in interface QueryEngine
public void performQueries(java.util.Collection queries, OperationObserver callback, Transaction transaction)
performQueries
in interface QueryEngine
public void prefetchRelationships(SelectQuery query, java.util.List objects)
WARNING: Currently supports only "one-step" to one relationships. This is an arbitrary limitation and will be removed eventually.
public java.util.List performQuery(java.lang.String queryName, boolean expireCachedLists)
queryName
- a name of a GenericSelectQuery defined in one of the DataMaps. If
no such query is defined, this method will throw a
CayenneRuntimeException.expireCachedLists
- A flag that determines whether refresh of cached lists
is required in case a query uses caching.public java.util.List performQuery(java.lang.String queryName, java.util.Map parameters, boolean expireCachedLists)
queryName
- a name of a GenericSelectQuery defined in one of the DataMaps. If
no such query is defined, this method will throw a
CayenneRuntimeException.parameters
- A map of parameters to use with stored query.expireCachedLists
- A flag that determines whether refresh of cached lists
is required in case a query uses caching.public EntityResolver getEntityResolver()
getEntityResolver
in interface QueryEngine
getEntityResolver
in interface DataChannel
getEntityResolver
in interface ObjectContext
public static void setTransactionEventsEnabledDefault(boolean flag)
public void setTransactionEventsEnabled(boolean flag)
public boolean isTransactionEventsEnabled()
public boolean isUsingSharedSnapshotCache()
true
if the ObjectStore uses shared cache of a parent
DataDomain.
public boolean isValidatingObjectsOnCommit()
public void setValidatingObjectsOnCommit(boolean flag)
public java.util.Collection getDataMaps()
QueryEngine
getDataMaps
in interface QueryEngine
public void prepareForAccess(Persistent object, java.lang.String property)
prepareForAccess
in interface ObjectContext
public void propertyChanged(Persistent object, java.lang.String property, java.lang.Object oldValue, java.lang.Object newValue)
propertyChanged
in interface ObjectContext
public GraphManager getGraphManager()
getGraphManager
in interface ObjectContext
public Persistent localObject(ObjectId id, Persistent prototype)
prototype
is not null, local object is refreshed with the prototype
values.
In case you pass a non-null second parameter, you are responsible for setting correct persistence state of the returned local object, as generally there is no way for Cayenne to determine the resulting local object state.
localObject
in interface ObjectContext
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |