org.apache.openjpa.kernel
Interface StoreManager

All Superinterfaces:

Closeable

All Known Implementing Classes:

AbstractStoreManager, DataCacheStoreManager, DelegatingStoreManager, JDBCStoreManager, XMLStoreManager

public interface StoreManager
extends Closeable

Interface to be implemented by data store mechanisms to interact with this runtime.

Author:

Abe White

Field Summary

static int	FORCE_LOAD_ALL
static int	FORCE_LOAD_DFG
static int	FORCE_LOAD_NONE
static int	FORCE_LOAD_REFRESH
static int	VERSION_DIFFERENT
static int	VERSION_EARLIER
static int	VERSION_LATER
static int	VERSION_SAME

Method Summary

boolean	assignField(OpenJPAStateManager sm, int field, boolean preFlush) Assign a value to the given field.
boolean	assignObjectId(OpenJPAStateManager sm, boolean preFlush) Assign an object id to the given new instance.
void	beforeStateChange(OpenJPAStateManager sm, PCState fromState, PCState toState) Notification that the given state manager is about to change its lifecycle state.
void	begin() Begin a data store transaction.
void	beginOptimistic() Notification that an optimistic transaction has started.
boolean	cancelAll() Cancel all pending data store statements.
void	close() Free any resources this store manager is using.
void	commit() Commit the current data store transaction.
int	compareVersion(OpenJPAStateManager state, Object v1, Object v2) Compare the two version objects.
Object	copyDataStoreId(Object oid, ClassMetaData meta) Copy the given object id value.
ResultObjectProvider	executeExtent(ClassMetaData meta, boolean subclasses, FetchConfiguration fetch) Return a provider for all instances of the given candidate class, optionally including subclasses.
boolean	exists(OpenJPAStateManager sm, Object edata) Verify that the given instance exists in the data store; return false if it does not.
Collection	flush(Collection sms) Flush the given state manager collection to the datastore, returning a collection of exceptions encountered during flushing.
Object	getClientConnection() Return a connection to the data store suitable for client use.
Seq	getDataStoreIdSequence(ClassMetaData forClass) Return a sequence that generates datastore identity values for the given class.
Class	getDataStoreIdType(ClassMetaData meta) Return the class used by this StoreManager for datastore identity values.
Class	getManagedType(Object oid) Return the persistent class for the given data store identity value.
Seq	getValueSequence(FieldMetaData forField) Return a sequence that generates values for the given field.
boolean	initialize(OpenJPAStateManager sm, PCState state, FetchConfiguration fetch, Object edata) Initialize the given state manager.
boolean	load(OpenJPAStateManager sm, BitSet fields, FetchConfiguration fetch, int lockLevel, Object edata) Load the given state manager.
Collection	loadAll(Collection sms, PCState state, int load, FetchConfiguration fetch, Object edata) Initialize, load, or validate the existance of all of the given objects.
Object	newDataStoreId(Object oidVal, ClassMetaData meta) Create a new unique datastore identity for the given type from the given oid value (presumably pk, stringified oid, or oid instance).
FetchConfiguration	newFetchConfiguration() Return a fetch configuration suitable for this runtime.
StoreQuery	newQuery(String language) Return a query implementation suitable for this store.
void	releaseConnection() Instruct the store to release a retained connection.
void	retainConnection() Instruct the store to retain a connection for continued use.
void	rollback() Rollback the current data store transaction.
void	rollbackOptimistic() Notification that an optimistic transaction was rolled back before a data store transaction ever began.
void	setContext(StoreContext ctx) Set a reference to the corresponding context.
boolean	syncVersion(OpenJPAStateManager sm, Object edata) Update the version information in the given state manager to the version stored in the data store.

Field Detail

VERSION_LATER

static final int VERSION_LATER

See Also:

Constant Field Values

VERSION_EARLIER

static final int VERSION_EARLIER

See Also:

Constant Field Values

VERSION_SAME

static final int VERSION_SAME

See Also:

Constant Field Values

VERSION_DIFFERENT

static final int VERSION_DIFFERENT

See Also:

Constant Field Values

FORCE_LOAD_NONE

static final int FORCE_LOAD_NONE

See Also:

Constant Field Values

FORCE_LOAD_DFG

static final int FORCE_LOAD_DFG

See Also:

Constant Field Values

FORCE_LOAD_REFRESH

static final int FORCE_LOAD_REFRESH

See Also:

Constant Field Values

FORCE_LOAD_ALL

static final int FORCE_LOAD_ALL

See Also:

Constant Field Values

Method Detail

setContext

void setContext(StoreContext ctx)

Set a reference to the corresponding context. This method will be called before the store manager is used. The store manager is responsible for pulling any necessary configuration data from the context, including the transaction mode and connection retain mode.

beginOptimistic

void beginOptimistic()

Notification that an optimistic transaction has started. This method does not replace the begin() method, which will still be called when a true data store transaction should begin.

rollbackOptimistic

void rollbackOptimistic()

Notification that an optimistic transaction was rolled back before a data store transaction ever began.

begin

void begin()

Begin a data store transaction. After this method is called, it is assumed that all further operations are operating in a single transaction that can be committed or rolled back. If optimistic transactions are in use, this method will only be called when the system requires a transactionally consistent connection due to a user request to flush or commit the transaction. In this case, it is possible that the optimistic transaction does not have the latest versions of all instances (i.e. another transaction has modified the same instances and committed since the optimistic transaction started). On commit, an exception must be thrown on any attempt to overwrite data for an instance with an older version.

Since:

0.2.5

commit

void commit()

Commit the current data store transaction.

rollback

void rollback()

Rollback the current data store transaction.

exists

boolean exists(OpenJPAStateManager sm,
               Object edata)

Verify that the given instance exists in the data store; return false if it does not.

syncVersion

boolean syncVersion(OpenJPAStateManager sm,
                    Object edata)

Update the version information in the given state manager to the version stored in the data store.

Parameters:

sm - the instance to check

edata - the current execution data, or null if not given to the calling method of the context

Returns:

true if the instance still exists in the datastore and is up-to-date, false otherwise

initialize

boolean initialize(OpenJPAStateManager sm,
                   PCState state,
                   FetchConfiguration fetch,
                   Object edata)

Initialize the given state manager. The object id of the state manager will be set, and the state manager's metadata be set to the class of the instance to load, or possibly one of its superclasses. Initialization involves first calling the OpenJPAStateManager.initialize(java.lang.Class, org.apache.openjpa.kernel.PCState) method with a new instance of the correct type constructed with the PCRegistry.newInstance(Class, org.apache.openjpa.enhance.StateManager, boolean) method (this will reset the state manager's metadata if the actual type was a subclass). After instance initialization, load any the fields for the given fetch configuration that can be efficiently retrieved. If any of the configured fields are not loaded in this method, they will be loaded with a subsequent call to load(org.apache.openjpa.kernel.OpenJPAStateManager, java.util.BitSet, org.apache.openjpa.kernel.FetchConfiguration, int, java.lang.Object). If this method is called during a data store transaction, the instance's database record should be locked. Version information can be loaded if desired through the OpenJPAStateManager.setVersion(java.lang.Object) method.

Parameters:

sm - the instance to initialize

state - the lifecycle state to initialize the state manager with

fetch - configuration for how to load the instance

edata - the current execution data, or null if not given to the calling method of the broker

Returns:

true if the matching instance exists in the data store, false otherwise

load

boolean load(OpenJPAStateManager sm,
             BitSet fields,
             FetchConfiguration fetch,
             int lockLevel,
             Object edata)

Load the given state manager. Note that any collection or map types loaded into the state manager will be proxied with the correct type; therefore the store manager does not have to load the same concrete collection/map types as the instance declares. However, array types must be consistent with the array type stored by the persistence capable instance. If this method is called during a data store transaction, the instance should be locked. If the given state manager does not have its version set already, version information can be loaded if desired through the OpenJPAStateManager.setVersion(java.lang.Object) method.

Parameters:

sm - the instance to load

fields - set of fields to load; all field indexes in this set must be loaded; this set is mutable

fetch - the fetch configuration to use when loading related objects

lockLevel - attempt to load simple fields at this lock level; relations should be loaded at the read lock level of the fetch configuration

edata - the current execution data, or null if not given to the calling method of the broker

Returns:

false if the object no longer exists in the database, true otherwise

loadAll

Collection loadAll(Collection sms,
                   PCState state,
                   int load,
                   FetchConfiguration fetch,
                   Object edata)

Initialize, load, or validate the existance of all of the given objects. This method is called from various broker methods that act on multiple objects, such as StoreContext.retrieveAll(java.util.Collection, boolean, org.apache.openjpa.kernel.OpCallbacks). It gives the store manager an opportunity to efficiently batch-load data for several objects. Each of the given state managers will be in one of three states, each requiring a different action:

• stateManager.getO () == null: An uninitialized state manager. Perform the same actions as in initialize(org.apache.openjpa.kernel.OpenJPAStateManager, org.apache.openjpa.kernel.PCState, org.apache.openjpa.kernel.FetchConfiguration, java.lang.Object).
• load != FORCE_LOAD_NONE || stateManager.getPCState () == PCState.HOLLOW: A hollow state manager, or one whose fields must be loaded because this is a refresh or retrieve action. Peform the same actions as in load(org.apache.openjpa.kernel.OpenJPAStateManager, java.util.BitSet, org.apache.openjpa.kernel.FetchConfiguration, int, java.lang.Object), choosing the fields to load based on the fetch configuration, or loading all fields if load == FORCE_LOAD_ALL. Any required fields left unloaded will cause a subsequent invocation of load(org.apache.openjpa.kernel.OpenJPAStateManager, java.util.BitSet, org.apache.openjpa.kernel.FetchConfiguration, int, java.lang.Object) on the individual object in question.
• load == FORCE_LOAD_NONE && stateManager.getPCState () != PCState.HOLLOW: A non-hollow state manager. Perform the same actions as in exists(org.apache.openjpa.kernel.OpenJPAStateManager, java.lang.Object), and load additional state if desired. Non-hollow objects will only be included outside of refresh invocations if a user calls findAll with the validate parameter set to true.

Store managers that cannot efficiently batch load can simply test for these conditions and delegate to the proper methods.

Parameters:

sms - the state manager instances to load

state - the lifecycle state to initialize uninitialized state managers with; may be null if no uninitialized instances are included in sms

load - one of the FORCE_LOAD_* constants describing the fields to force-load if this is a refresh or retrieve action

fetch - the current fetch configuration to use when loading related objects

edata - the current execution data, or null if not given to the calling method of the broker

Returns:

a collection of the state manager identities for which no data store record exists

See Also:

ImplHelper.loadAll(java.util.Collection, org.apache.openjpa.kernel.StoreManager, org.apache.openjpa.kernel.PCState, int, org.apache.openjpa.kernel.FetchConfiguration, java.lang.Object)

beforeStateChange

void beforeStateChange(OpenJPAStateManager sm,
                       PCState fromState,
                       PCState toState)

Notification that the given state manager is about to change its lifecycle state. The store manager is not required to do anything in this method, but some back ends may need to.

Since:

0.3.0

flush

Collection flush(Collection sms)

Flush the given state manager collection to the datastore, returning a collection of exceptions encountered during flushing. The given collection may include states that do not require data store action, such as persistent-clean instances or persistent-dirty instances that have not been modified since they were last flushed. For datastore updates and inserts, the dirty, non-flushed fields of each state should be flushed. New instances without an assigned object id should be given one via OpenJPAStateManager.setObjectId(java.lang.Object). New instances with value-strategy fields that have not been assigned yet should have their fields set. Datastore version information should be updated during flush, and the state manager's version indicator updated through the OpenJPAStateManager.setNextVersion(java.lang.Object) method. The current version will roll over to this next version upon successful commit.

See Also:

org.apache.openjpa.util.ApplicationIds#assign()

assignObjectId

boolean assignObjectId(OpenJPAStateManager sm,
                       boolean preFlush)

Assign an object id to the given new instance. Return false if the instance cannot be assigned an identity because a flush is required (for example, the identity is determined by the datastore on insert). For application identity instances, the assigned object id should be based on field state. The implementation is responsible for using the proper value strategy according to the instance metadata. This method is called the first time a user requests the oid of a new instance before flush.

Parameters:

preFlush - whether this assignment is being requested by the system as part of pre-flush activities, and can be ignored if it is more efficient to assign within flush(java.util.Collection)

Since:

0.3.3

See Also:

ImplHelper.generateFieldValue(org.apache.openjpa.kernel.StoreContext, org.apache.openjpa.meta.FieldMetaData), ImplHelper.generateIdentityValue(org.apache.openjpa.kernel.StoreContext, org.apache.openjpa.meta.ClassMetaData, int), org.apache.openjpa.util.ApplicationIds#assign()

assignField

boolean assignField(OpenJPAStateManager sm,
                    int field,
                    boolean preFlush)

Assign a value to the given field. Return false if the value cannot be assigned because a flush is required (for example, the field value is determined by the datastore on insert). This method is called the first time a user requests the value of a field with a value-strategy on a new instance before flush.

Parameters:

preFlush - whether this assignment is being requested by the system as part of pre-flush activities, and can be ignored if it is more efficient to assign within flush(java.util.Collection)

Since:

0.4.0

See Also:

ImplHelper.generateFieldValue(org.apache.openjpa.kernel.StoreContext, org.apache.openjpa.meta.FieldMetaData)

getManagedType

Class getManagedType(Object oid)

Return the persistent class for the given data store identity value. If the given value is not a datastore identity object, return null.

Since:

0.3.0

getDataStoreIdType

Class getDataStoreIdType(ClassMetaData meta)

Return the class used by this StoreManager for datastore identity values. The given metadata may be null, in which case the return value should the common datastore identity class for all classes, or null if this store manager does not use a common identity class.

copyDataStoreId

Object copyDataStoreId(Object oid,
                       ClassMetaData meta)

Copy the given object id value. Use the described type of the given metadata, which may be a subclass of the given oid's described type.

newDataStoreId

Object newDataStoreId(Object oidVal,
                      ClassMetaData meta)

Create a new unique datastore identity for the given type from the given oid value (presumably pk, stringified oid, or oid instance).

getClientConnection

Object getClientConnection()

Return a connection to the data store suitable for client use. If this method is called during a data store transaction, thie connection must be transactional. If no connection is in use, this method should create one to return.

retainConnection

void retainConnection()

Instruct the store to retain a connection for continued use. This will be invoked automatically based on the user's configured connection retain mode.

releaseConnection

void releaseConnection()

Instruct the store to release a retained connection. This will be invoked automatically based on the user's configured connection retain mode.

cancelAll

boolean cancelAll()

Cancel all pending data store statements.

Returns:

true if any statements cancelled, false otherwise

Since:

0.3.1

executeExtent

ResultObjectProvider executeExtent(ClassMetaData meta,
                                   boolean subclasses,
                                   FetchConfiguration fetch)

Return a provider for all instances of the given candidate class, optionally including subclasses. The given candidate may be an unmapped type with mapped subclasses. If the provider is iterated within a data store transaction, returned instances should be locked.

newQuery

StoreQuery newQuery(String language)

Return a query implementation suitable for this store. If the query is iterated within a data store transaction, returned instances should be locked. Return null if this store does not support native execution of the given language. OpenJPA can execute JPQL in memory even without back end support.

Parameters:

language - the query language

newFetchConfiguration

FetchConfiguration newFetchConfiguration()

Return a fetch configuration suitable for this runtime. Typically will be or extend FetchConfigurationImpl.

compareVersion

int compareVersion(OpenJPAStateManager state,
                   Object v1,
                   Object v2)

Compare the two version objects.

Parameters:

state - the state manager for the object

v1 - the first version object to compare

v2 - the second version object to compare

Returns:

• VERSION_LATER if v1 is later than v2
• VERSION_EARLIER if v1 is earlier than v2
• VERSION_SAME if v1 is the same as v2
• VERSION_DIFFERENT if v1 is different from v2, but the time difference of the versions cannot be determined

getDataStoreIdSequence

Seq getDataStoreIdSequence(ClassMetaData forClass)

Return a sequence that generates datastore identity values for the given class. This method will only be called when the identity strategy for the class is one of:

• ValueStrategies.NATIVE
• ValueStrategies.AUTOASSIGN
• ValueStrategies.INCREMENT

If the identity strategy cannot be represented as a sequence, return null.

Since:

0.4.0

getValueSequence

Seq getValueSequence(FieldMetaData forField)

Return a sequence that generates values for the given field. This method will only be called when the value strategy for the field is one of:

• ValueStrategies.NATIVE
• ValueStrategies.AUTOASSIGN
• ValueStrategies.INCREMENT

If the value strategy cannot be represented as a sequence, return null.

Since:

0.4.0

close

void close()

Free any resources this store manager is using.

Specified by:

close in interface Closeable

Since:

0.2.5