org.apache.openjpa.kernel
Interface StoreContext

All Known Subinterfaces:
Broker
All Known Implementing Classes:
BrokerImpl, DelegatingBroker, DistributedBrokerImpl, FinalizingBrokerImpl

public interface StoreContext

Represents a set of managed objects and their environment.

Since:
0.4.0
Author:
Abe White

Field Summary
static BitSet EXCLUDE_ALL
          Marker bitset to indicate that all field loads should be excluded in the find methods of this interface.
static int OID_ALLOW_NEW
           
static int OID_COPY
           
static int OID_NODELETED
           
static int OID_NOVALIDATE
           
 
Method Summary
 void beginStore()
          Begin a data store transaction.
 OpenJPAStateManager embed(Object obj, Object id, OpenJPAStateManager owner, ValueMetaData ownerMeta)
          Make the given instance embedded.
 Iterator extentIterator(Class cls, boolean subs, FetchConfiguration fetch, boolean ignoreChanges)
          Return an iterator over all instances of the given type.
 Object find(Object oid, boolean validate, FindCallbacks call)
          Find the persistence object with the given oid.
 Object find(Object oid, FetchConfiguration fetch, BitSet exclude, Object edata, int flags)
          Return the object with the given oid.
 Object[] findAll(Collection oids, boolean validate, FindCallbacks call)
          Return the objects with the given oids.
 Object[] findAll(Collection oids, FetchConfiguration fetch, BitSet exclude, Object edata, int flags)
          Return the objects with the given oids.
 Object findCached(Object oid, FindCallbacks call)
          Return the cached instance for the given oid/object, or null if not cached.
 Broker getBroker()
          Return the broker for this context, if possible.
 ClassLoader getClassLoader()
          Return the current thread's class loader at the time this context was obtained.
 OpenJPAConfiguration getConfiguration()
          Return the configuration associated with this context.
 Object getConnection()
          Return the connection in use by the context, or a new connection if none.
 String getConnectionPassword()
          Return the connection password.
 String getConnectionUserName()
          Return the connection user name.
 Collection getDeletedTypes()
          Return the set of classes that have been deleted in the current transaction.
 int getDetachState()
          Detach mode constant to determine which fields are part of the detached graph.
 Collection getDirtyObjects()
          Return a list of current dirty instances.
 FetchConfiguration getFetchConfiguration()
          Return the (mutable) fetch configuration for loading objects from this context.
 int getLockLevel(Object obj)
          Return the lock level of the specified object.
 LockManager getLockManager()
          Return the lock manager in use.
 Collection getManagedObjects()
          Return a list of all managed instances.
 Object getObjectId(Object obj)
          Return the oid of the given instance.
 Class getObjectIdType(Class cls)
          Return the application or datastore identity class the given persistent class uses for object ids.
 boolean getOrderDirtyObjects()
          Whether to maintain the order in which objects are dirtied for getDirtyObjects().
 Collection getPendingTransactionalObjects()
          Return a list of instances which will become transactional upon the next transaction.
 Collection getPersistedTypes()
          Return the set of classes that have been made persistent in the current transaction.
 boolean getPopulateDataCache()
          Whether objects accessed during this transaction will be added to the store cache.
 OpenJPAStateManager getStateManager(Object obj)
          Return the state manager for the given instance.
 DelegatingStoreManager getStoreManager()
          Return the store manager in use.
 Collection getTransactionalObjects()
          Return a list of current transaction instances.
 Collection getUpdatedTypes()
          Return the set of classes for objects that have been modified in the current transaction.
 Object getVersion(Object obj)
          Returns the current version indicator for o.
 boolean hasConnection()
          Whether the broker has a dedicated connection based on the configured connection retain mode and transaction status.
 boolean isActive()
          Whether a logical transaction is active.
 boolean isDeleted(Object obj)
          Return whether the given object is deleted.
 boolean isDirty(Object obj)
          Return whether the given object is dirty.
 boolean isManaged()
          Whether this context is using managed transactions.
 boolean isNew(Object obj)
          Return whether the given object is a newly-created instance registered with broker.
 boolean isPersistent(Object obj)
          Return whether the given object is persistent.
 boolean isStoreActive()
          Whether a data store transaction is active.
 boolean isTrackChangesByType()
          Whether memory usage is reduced during this transaction at the expense of tracking changes at the type level instead of the instance level, resulting in more aggressive cache invalidation.
 boolean isTransactional(Object obj)
          Return whether the given object is transactional.
 void lock()
          Synchronizes on an internal lock if the Multithreaded flag is set to true.
 Object newObjectId(Class cls, Object val)
          Create a new object id instance from the given value.
 void nontransactional(Object pc, OpCallbacks call)
          Make the given object nontransactional.
 void nontransactionalAll(Collection objs, OpCallbacks call)
          Make the given objects nontransactional.
 void popFetchConfiguration()
          Pops the fetch configuration from the top of the stack, making the next one down the active one.
 FetchConfiguration pushFetchConfiguration()
          Pushes a new fetch configuration that inherits from the current fetch configuration onto a stack, and makes the new configuration the active one.
 void retrieve(Object pc, boolean fgOnly, OpCallbacks call)
          Immediately load the given object's persistent fields.
 void retrieveAll(Collection objs, boolean fgOnly, OpCallbacks call)
          Retrieve the given objects' persistent state.
 void setDetachState(int mode)
          Detach mode constant to determine which fields are part of the detached graph.
 void setOrderDirtyObjects(boolean order)
          Whether to maintain the order in which objects are dirtied for getDirtyObjects().
 void setPopulateDataCache(boolean cache)
          Whether to populate the store cache with objects used by this transaction.
 void setTrackChangesByType(boolean largeTransaction)
          If a large number of objects will be created, modified, or deleted during this transaction setting this option to true will reduce memory usage if you perform periodic flushes by tracking changes at the type level instead of the instance level, resulting in more aggressive cache invalidation.
 void transactional(Object pc, boolean updateVersion, OpCallbacks call)
          Make the given object transactional.
 void transactionalAll(Collection objs, boolean updateVersion, OpCallbacks call)
          Make the given objects transactional.
 void unlock()
          Releases the internal lock.
 

Field Detail

EXCLUDE_ALL

static final BitSet EXCLUDE_ALL
Marker bitset to indicate that all field loads should be excluded in the find methods of this interface.


OID_NOVALIDATE

static final int OID_NOVALIDATE
See Also:
Constant Field Values

OID_NODELETED

static final int OID_NODELETED
See Also:
Constant Field Values

OID_COPY

static final int OID_COPY
See Also:
Constant Field Values

OID_ALLOW_NEW

static final int OID_ALLOW_NEW
See Also:
Constant Field Values
Method Detail

getBroker

Broker getBroker()
Return the broker for this context, if possible. Note that a broker will be unavailable in remote contexts, and this method may return null.


getConfiguration

OpenJPAConfiguration getConfiguration()
Return the configuration associated with this context.


getFetchConfiguration

FetchConfiguration getFetchConfiguration()
Return the (mutable) fetch configuration for loading objects from this context.


pushFetchConfiguration

FetchConfiguration pushFetchConfiguration()
Pushes a new fetch configuration that inherits from the current fetch configuration onto a stack, and makes the new configuration the active one.

Returns:
the new fetch configuration
Since:
1.1.0

popFetchConfiguration

void popFetchConfiguration()
Pops the fetch configuration from the top of the stack, making the next one down the active one. This returns void to avoid confusion, since fetch configurations tend to be used in method-chaining patterns often.

Throws:
UserException - if the fetch configuration stack is empty
Since:
1.1.0

getClassLoader

ClassLoader getClassLoader()
Return the current thread's class loader at the time this context was obtained.


getLockManager

LockManager getLockManager()
Return the lock manager in use.


getStoreManager

DelegatingStoreManager getStoreManager()
Return the store manager in use. This will be a wrapper around the native store manager, which you can retrieve via DelegatingStoreManager.getInnermostDelegate().


getConnectionUserName

String getConnectionUserName()
Return the connection user name.


getConnectionPassword

String getConnectionPassword()
Return the connection password.


findCached

Object findCached(Object oid,
                  FindCallbacks call)
Return the cached instance for the given oid/object, or null if not cached.

Parameters:
oid - the object's id
Returns:
the cached object, or null if not cached

find

Object find(Object oid,
            boolean validate,
            FindCallbacks call)
Find the persistence object with the given oid. If validate is true, the broker will check the store for the object, and return null if it does not exist. If validate is false, this method never returns null. The broker will either return its cached instance, attempt to create a hollow instance, or throw an ObjectNotFoundException if unable to return a hollow instance.

Parameters:
validate - if true, validate that the instance exists in the store and load fetch group fields, otherwise return any cached or hollow instance

findAll

Object[] findAll(Collection oids,
                 boolean validate,
                 FindCallbacks call)
Return the objects with the given oids.

Parameters:
oids - the oids of the objects to return
Returns:
the objects that were looked up, in the same order as the oids parameter
See Also:
find(Object,boolean,FindCallbacks)

find

Object find(Object oid,
            FetchConfiguration fetch,
            BitSet exclude,
            Object edata,
            int flags)
Return the object with the given oid. If present, the cached instance will be returned. Otherwise, the instance will be initialized through the store as usual; however, in this case the store will be passed the given execution data, and the system will load the object according to the given fetch configuratiion (or the context's configuration, if the given one is null). Fields can optionally be excluded from required loading using the exclude mask. By default this method does not find new unflushed instances, validates, and does not throw an exception if a cached instance has been deleted concurrently. These options are controllable through the given OID_XXX flags.


findAll

Object[] findAll(Collection oids,
                 FetchConfiguration fetch,
                 BitSet exclude,
                 Object edata,
                 int flags)
Return the objects with the given oids.

See Also:
find(Object,FetchConfiguration,BitSet,Object,int)

extentIterator

Iterator extentIterator(Class cls,
                        boolean subs,
                        FetchConfiguration fetch,
                        boolean ignoreChanges)
Return an iterator over all instances of the given type. The iterator should be closed with ImplHelper.close(java.lang.Object) when no longer needed. This method delegates to StoreManager.executeExtent(org.apache.openjpa.meta.ClassMetaData, boolean, org.apache.openjpa.kernel.FetchConfiguration).


retrieve

void retrieve(Object pc,
              boolean fgOnly,
              OpCallbacks call)
Immediately load the given object's persistent fields. One might use this action to make sure that an instance's fields are loaded before transitioning it to transient. Note that this action is not recursive. Any related objects that are loaded will not necessarily have their fields loaded. Unmanaged target is ignored.

Parameters:
fgOnly - indicator as to whether to retrieve only fields in the current fetch groups, or all fields
See Also:
retrieve(java.lang.Object, boolean, org.apache.openjpa.kernel.OpCallbacks)

retrieveAll

void retrieveAll(Collection objs,
                 boolean fgOnly,
                 OpCallbacks call)
Retrieve the given objects' persistent state. Unmanaged targets are ignored.

Parameters:
fgOnly - indicator as to whether to retrieve only fields
See Also:
retrieve(java.lang.Object, boolean, org.apache.openjpa.kernel.OpCallbacks)

embed

OpenJPAStateManager embed(Object obj,
                          Object id,
                          OpenJPAStateManager owner,
                          ValueMetaData ownerMeta)
Make the given instance embedded.

Parameters:
obj - the instance to embed; may be null to create a new instance
id - the id to give the embedded state manager; may be null for default
owner - the owning state manager
ownerMeta - the value in which the object is embedded
Returns:
the state manager for the embedded instance

getObjectIdType

Class getObjectIdType(Class cls)
Return the application or datastore identity class the given persistent class uses for object ids.


newObjectId

Object newObjectId(Class cls,
                   Object val)
Create a new object id instance from the given value.

Parameters:
cls - the persitent class that uses this identity value
val - an object id instance, stringified object id, or primary key value

getPersistedTypes

Collection getPersistedTypes()
Return the set of classes that have been made persistent in the current transaction.

Since:
0.3.4

getDeletedTypes

Collection getDeletedTypes()
Return the set of classes that have been deleted in the current transaction.

Since:
0.3.4

getUpdatedTypes

Collection getUpdatedTypes()
Return the set of classes for objects that have been modified in the current transaction.

Since:
0.3.4

getManagedObjects

Collection getManagedObjects()
Return a list of all managed instances.


getTransactionalObjects

Collection getTransactionalObjects()
Return a list of current transaction instances.


getPendingTransactionalObjects

Collection getPendingTransactionalObjects()
Return a list of instances which will become transactional upon the next transaction.


getDirtyObjects

Collection getDirtyObjects()
Return a list of current dirty instances.


getOrderDirtyObjects

boolean getOrderDirtyObjects()
Whether to maintain the order in which objects are dirtied for getDirtyObjects(). Default is the store manager's decision.


setOrderDirtyObjects

void setOrderDirtyObjects(boolean order)
Whether to maintain the order in which objects are dirtied for getDirtyObjects(). Default is the store manager's decision.


getStateManager

OpenJPAStateManager getStateManager(Object obj)
Return the state manager for the given instance. Includes objects made persistent in the current transaction. If obj is not a managed type or is managed by another context, throw an exception.


getLockLevel

int getLockLevel(Object obj)
Return the lock level of the specified object.


getVersion

Object getVersion(Object obj)
Returns the current version indicator for o.


isDirty

boolean isDirty(Object obj)
Return whether the given object is dirty.


isTransactional

boolean isTransactional(Object obj)
Return whether the given object is transactional.


transactional

void transactional(Object pc,
                   boolean updateVersion,
                   OpCallbacks call)
Make the given object transactional.

Parameters:
pc - instance to make transactional
updateVersion - if true, the instance's version will be incremented at the next flush

transactionalAll

void transactionalAll(Collection objs,
                      boolean updateVersion,
                      OpCallbacks call)
Make the given objects transactional.

Parameters:
objs - instances to make transactional
updateVersion - if true, the instance's version will be incremented at the next flush

nontransactional

void nontransactional(Object pc,
                      OpCallbacks call)
Make the given object nontransactional.


nontransactionalAll

void nontransactionalAll(Collection objs,
                         OpCallbacks call)
Make the given objects nontransactional.


isPersistent

boolean isPersistent(Object obj)
Return whether the given object is persistent.


isNew

boolean isNew(Object obj)
Return whether the given object is a newly-created instance registered with broker.


isDeleted

boolean isDeleted(Object obj)
Return whether the given object is deleted.


getObjectId

Object getObjectId(Object obj)
Return the oid of the given instance.


getDetachState

int getDetachState()
Detach mode constant to determine which fields are part of the detached graph. Defaults to DetachState.DETACH_LOADED.


setDetachState

void setDetachState(int mode)
Detach mode constant to determine which fields are part of the detached graph. Defaults to DetachState.DETACH_LOADED.


getPopulateDataCache

boolean getPopulateDataCache()
Whether objects accessed during this transaction will be added to the store cache. Defaults to true.

Since:
0.3.4

setPopulateDataCache

void setPopulateDataCache(boolean cache)
Whether to populate the store cache with objects used by this transaction. Defaults to true.

Since:
0.3.4

isTrackChangesByType

boolean isTrackChangesByType()
Whether memory usage is reduced during this transaction at the expense of tracking changes at the type level instead of the instance level, resulting in more aggressive cache invalidation.

Since:
1.0.0

setTrackChangesByType

void setTrackChangesByType(boolean largeTransaction)
If a large number of objects will be created, modified, or deleted during this transaction setting this option to true will reduce memory usage if you perform periodic flushes by tracking changes at the type level instead of the instance level, resulting in more aggressive cache invalidation. Upon transaction commit the data cache will have to more aggressively flush objects. The store cache will have to flush instances of objects for each class of object modified during the transaction. A side benefit of large transaction mode is that smaller update messages can be used for RemoteCommitEvents. Defaults to false.

Since:
1.0.0

isManaged

boolean isManaged()
Whether this context is using managed transactions.


isActive

boolean isActive()
Whether a logical transaction is active.


isStoreActive

boolean isStoreActive()
Whether a data store transaction is active.


beginStore

void beginStore()
Begin a data store transaction.


hasConnection

boolean hasConnection()
Whether the broker has a dedicated connection based on the configured connection retain mode and transaction status.


getConnection

Object getConnection()
Return the connection in use by the context, or a new connection if none.


lock

void lock()
Synchronizes on an internal lock if the Multithreaded flag is set to true. Make sure to call unlock() in a finally clause of the same method.


unlock

void unlock()
Releases the internal lock.



Copyright © 2006-2008 Apache Software Foundation. All Rights Reserved.