kodo.runtime
Interface StoreManager

All Superinterfaces:

com.solarmetric.util.Closeable

All Known Implementing Classes:

AbstractStoreManager, JDBCStoreManager

public interface StoreManager

extends com.solarmetric.util.Closeable

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

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	assignObjectId(KodoStateManager sm) Assign an object id to the given new instance.
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	changeJDOState(KodoStateManager sm, JDOState fromState, JDOState toState) Notification that the given state manager is about to change its JDO state.
void	close() Free any resources this store manager is using.
void	commit() Commit the current data store transaction.
int	compareVersion(KodoStateManager state, Object v1, Object v2) Compare the two version objects.
Object	copyDataStoreId(Object oid, ClassMetaData meta) Copy the given object id value.
boolean	exists(KodoStateManager sm, Object context) 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	getConnection() Return a connection to the data store.
Class	getDataStoreIdClass(ClassMetaData meta) Return the class used by this StoreManager for datastore identity values.
Class	getPersistenceCapableClass(Object oid) Return the persistent class for the given data store identity value.
SequenceGenerator	getSequenceGenerator(ClassMetaData forClass) Returns a SequenceGenerator for the specified class.
boolean	hasConnection() Return true if this store manager has established a dedicated connection to the data store.
boolean	initialize(KodoStateManager sm, JDOState state, FetchConfiguration fetch, Object context) Initialize the given state manager.
boolean	load(KodoStateManager sm, BitSet fields, FetchConfiguration fetch, int lockLevel, Object context) Load the given state manager.
Collection	loadAll(Collection sms, JDOState state, int load, FetchConfiguration fetch, Object context) 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).
KodoExtent	newExtent(Class type, boolean subclasses) Return an extent of the given candidate class, optionally including subclasses.
FetchConfiguration	newFetchConfiguration() Return a fetch configuration suitable for this runtime.
KodoQuery	newQuery(String language) Return a query implementation suitable for this runtime.
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	setPersistenceManager(KodoPersistenceManager pm) Set a reference to the corresponding PersistenceManager.
boolean	synchVersion(KodoStateManager sm, Object context) Update the version information in the given state manager to the version stored in the data store.

Field Detail

VERSION_LATER

public static final int VERSION_LATER

VERSION_EARLIER

public static final int VERSION_EARLIER

VERSION_SAME

public static final int VERSION_SAME

VERSION_DIFFERENT

public static final int VERSION_DIFFERENT

FORCE_LOAD_NONE

public static final int FORCE_LOAD_NONE

FORCE_LOAD_DFG

public static final int FORCE_LOAD_DFG

FORCE_LOAD_REFRESH

public static final int FORCE_LOAD_REFRESH

FORCE_LOAD_ALL

public static final int FORCE_LOAD_ALL

Method Detail

setPersistenceManager

public void setPersistenceManager(KodoPersistenceManager pm)

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

beginOptimistic

public 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

public void rollbackOptimistic()

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

begin

public 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 JDO 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:

2.5

commit

public void commit()

Commit the current data store transaction.

rollback

public void rollback()

Rollback the current data store transaction.

exists

public boolean exists(KodoStateManager sm,
                      Object context)

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

synchVersion

public boolean synchVersion(KodoStateManager sm,
                            Object context)

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

Parameters:

sm - the instance to check

context - the current context information, or null if not given to the calling method of the persistence manager

Returns:

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

initialize

public boolean initialize(KodoStateManager sm,
                          JDOState state,
                          FetchConfiguration fetch,
                          Object context)

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 KodoStateManager.initialize(javax.jdo.spi.PersistenceCapable, kodo.runtime.JDOState) method with a new instance of the correct type constructed with the JDOImplHelper.newInstance(Class,StateManager,Object) 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(kodo.runtime.KodoStateManager, java.util.BitSet, kodo.runtime.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 KodoStateManager.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

context - the current context information, or null if not given to the calling method of the persistence manager

Returns:

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

load

public boolean load(KodoStateManager sm,
                    BitSet fields,
                    FetchConfiguration fetch,
                    int lockLevel,
                    Object context)

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 stroe 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 KodoStateManager.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

context - the current context information, or null if not given to the calling method of the persistence manager

Returns:

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

loadAll

public Collection loadAll(Collection sms,
                          JDOState state,
                          int load,
                          FetchConfiguration fetch,
                          Object context)

Initialize, load, or validate the existance of all of the given objects. This method is called from various persistence manager methods that act on multiple objects, such as KodoPersistenceManager.getObjectsById(java.lang.Object[], boolean). 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.getPersistenceCapable () == null: An uninitialized state manager. Perform the same actions as in initialize(kodo.runtime.KodoStateManager, kodo.runtime.JDOState, kodo.runtime.FetchConfiguration, java.lang.Object).
• load != FORCE_LOAD_NONE || stateManager.getJDOState () == JDOState.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(kodo.runtime.KodoStateManager, java.util.BitSet, kodo.runtime.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(kodo.runtime.KodoStateManager, java.util.BitSet, kodo.runtime.FetchConfiguration, int, java.lang.Object) on the individual object in question.
• load == FORCE_LOAD_NONE && stateManager.getJDOState () != JDOState.HOLLOW: A non-hollow state manager. Perform the same actions as in exists(kodo.runtime.KodoStateManager, java.lang.Object), and load additional state if desired. Non-hollow objects will only be included outside of refresh invocations if a user calls getObjectsById 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

context - the current context information, or null if not given to the calling method of the persistence manager

Returns:

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

changeJDOState

public void changeJDOState(KodoStateManager sm,
                           JDOState fromState,
                           JDOState toState)

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

Since:

3.0

flush

public 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 KodoStateManager.setObjectId(java.lang.Object). Datastore version information should be updated during flush, and the state manager's version indicator updated through the KodoStateManager.setNextVersion(java.lang.Object) method. The current version will roll over to this next version upon successful commit.

assignObjectId

public boolean assignObjectId(KodoStateManager sm)

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. This method is called the first time a user requests the oid of a new instance before flush.

Since:

3.3

See Also:

kodo.util.ApplicationIds#create

getPersistenceCapableClass

public Class getPersistenceCapableClass(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:

3.0

getDataStoreIdClass

public Class getDataStoreIdClass(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

public Object copyDataStoreId(Object oid,
                              ClassMetaData meta)

Copy the given object id value.

newDataStoreId

public 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).

getConnection

public Object getConnection()

Return a connection to the data store. 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.

hasConnection

public boolean hasConnection()

Return true if this store manager has established a dedicated connection to the data store. This typically depends on the transactional state and KodoPersistenceManager.getConnectionRetainMode().

newExtent

public KodoExtent newExtent(Class type,
                            boolean subclasses)

Return an extent of the given candidate class, optionally including subclasses. If the extent is iterated within a data store transaction, returned instances should be locked.

newQuery

public KodoQuery newQuery(String language)

Return a query implementation suitable for this runtime. If the query is iterated within a data store transaction, returned instances should be locked.

Parameters:

language - the query language; implementations are only required to support javax.jdo.query.JDOQL

newFetchConfiguration

public FetchConfiguration newFetchConfiguration()

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

compareVersion

public int compareVersion(KodoStateManager 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

getSequenceGenerator

public SequenceGenerator getSequenceGenerator(ClassMetaData forClass)

Returns a SequenceGenerator for the specified class.

Since:

3.0.0

cancelAll

public boolean cancelAll()

Cancel all pending data store statements.

Returns:

true if any statements cancelled, false otherwise

Since:

3.1

close

public void close()

Free any resources this store manager is using.

Specified by:

close in interface com.solarmetric.util.Closeable

Since:

2.5