com.solarmetric.kodo.runtime
Interface StoreManager

All Known Implementing Classes:

JDBCStoreManager, DataCacheStoreManager

public interface StoreManager

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

Method Summary

void	begin() Begin a data store transaction.
void	beginOptimistic() Notification that an optimistic transaction has started.
boolean	checkVersion(StateManagerImpl sm) Determine whether the given StateManager is the same version as the datastore version.
void	commit() Commit the current data store transaction.
Object	copyDataStoreId(Object oid, ClassMetaData meta) Copy the given object id value.
boolean	exists(Object oid, ClassMetaData meta) Verify that the given instance exists in the data store.
Collection	flush(Collection states) Flush the given state manager collection to the datastore, returning a collection of user exceptions encountered during flushing.
Class	getDataStoreIdClass(ClassMetaData meta) Return the class used by this StoreManager for datastore identity values.
boolean	initialize(StateManagerImpl sm, com.solarmetric.kodo.runtime.JDOState state, Object connection) Initialize the given StateManager.
void	load(StateManagerImpl sm, Object connection, BitSet fields, boolean setVersion) Load the given StateManager.
Object	newDataStoreId(ClassMetaData meta) Create a new unique datastore identity for the given type.
Object	newDataStoreId(String str, ClassMetaData meta) Create a new unique datastore identity for the given type from the given string.
Extent	newExtent(ClassMetaData meta, boolean subclasses) Return an extent of the given candidate class, optionally including subclasses.
com.solarmetric.kodo.query.FilterExtensions	newFilterExtensions() Return a FilterExtensions implementation for use in queries.
Query	newQuery(String language, Object template) Return a query implementation suitable for this runtime.
void	rollback() Rollback the current data store transaction.
void	setPersistenceManager(PersistenceManagerImpl pm) Set a reference to the corresponding PersistenceManager.

Method Detail

setPersistenceManager

public void setPersistenceManager(PersistenceManagerImpl pm)

Set a reference to the corresponding PersistenceManager. This method will be called before the StoreManager is used.

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.

begin

public void begin()

Begin a data store transaction. If optimistic transactions are in use, this method will only be called when the user is ready to commit the transaction. At this time, the PersistenceManager will call this begin method, will store all modified data, and will call the commit method in succession, minimizing the length of the actual data store 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.

commit

public void commit()

Commit the current data store transaction.

rollback

public void rollback()

Rollback the current data store transaction.

exists

public boolean exists(Object oid,
                      ClassMetaData meta)

Verify that the given instance exists in the data store.

checkVersion

public boolean checkVersion(StateManagerImpl sm)

Determine whether the given StateManager is the same version as the datastore version.

Parameters:

sm - the instance to check

Returns:

true if the instance is up-to-date, false otherwise

initialize

public boolean initialize(StateManagerImpl sm,
                          com.solarmetric.kodo.runtime.JDOState state,
                          Object connection)

Initialize the given StateManager. The oid of the StateManager will be set, and the meta field of the StateManager will be set to the class of the instance to load, or possibly one of its superclasses. Initialization involves first calling the StateManagerImpl#setPersistenceCapable method with a new instance of the correct type constructed with the JDOImplHelper#newInstance(Class,StateManager,Object) method (this will reset the meta field of the StateManager if the actual type was a subclass), then possibly loading any fields if desired. The version information for the StateManager should also be set via the StateManagerImpl.setVersion(java.lang.Object) method. If this method is called during a data store transaction, the instance should be locked.

Parameters:

sm - the instance to initialize

state - the JDO state to pass through to the state manager's initialize method

connection - the current connection 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 void load(StateManagerImpl sm,
                 Object connection,
                 BitSet fields,
                 boolean setVersion)

Load the given StateManager. Note that any collection or map types loaded into the StateManager will be proxied with the correct type; therefore the StoreManager 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 PersistenceCapable instance. If this method is called during a data store transaction, the instance should be locked.

Parameters:

sm - the instance to load

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

fields - the fields to load; the field corrsponding to the metadata field at each set bit position should be loaded; additional fields can be loaded if desired; attempting to load an additional field that has been dirtied will cause the load to be ignored; this bit set should not be modified

setVersion - if true, the version information should also be loaded from the db and set in the instance via the StateManagerImpl.setVersion(java.lang.Object) method

flush

public Collection flush(Collection states)

Flush the given state manager collection to the datastore, returning a collection of user exceptions encountered during flushing. The given state collection may include states that do not require data store action, such as persistent-clean instances. For datastore updates and inserts, the dirty fields of each state should be flushed. Datastore version information should be updated during flush, and the state manager's version indicator updated through the StateManagerImpl.setNextVersion(java.lang.Object) method. The current version will roll over to this next version upon successful commit.

getDataStoreIdClass

public Class getDataStoreIdClass(ClassMetaData meta)

Return the class used by this StoreManager for datastore identity values.

copyDataStoreId

public Object copyDataStoreId(Object oid,
                              ClassMetaData meta)

Copy the given object id value.

newDataStoreId

public Object newDataStoreId(ClassMetaData meta)

Create a new unique datastore identity for the given type.

newDataStoreId

public Object newDataStoreId(String str,
                             ClassMetaData meta)

Create a new unique datastore identity for the given type from the given string.

newExtent

public Extent newExtent(ClassMetaData meta,
                        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 Query newQuery(String language,
                      Object template)

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

Parameters:

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

a - template query instance also from this StoreManager; this instance may be null; if not null, the filter, variables, parameters, imports, and candidate class should be copied from the template to the returned Query instance

newFilterExtensions

public com.solarmetric.kodo.query.FilterExtensions newFilterExtensions()

Return a FilterExtensions implementation for use in queries. To return no extensions, do:
return FilterExtensions.DefaultExtensions.newExtensions ()