kodo.abstractstore
Class AbstractStoreManager

java.lang.Object
  |
  +--kodo.abstractstore.AbstractStoreManager

All Implemented Interfaces:

com.solarmetric.util.Closeable, StoreManager

Direct Known Subclasses:

XMLStoreManager

public abstract class AbstractStoreManager

extends Object

implements StoreManager

Abstract store manager implementation to ease development of custom Kodo back-ends. A concrete subclass must define implementations for the following methods:

• StoreManager.exists(kodo.runtime.KodoStateManager, java.lang.Object)
• initialize(kodo.runtime.KodoStateManager, kodo.runtime.JDOState, kodo.runtime.FetchConfiguration, java.lang.Object)
• load(kodo.runtime.KodoStateManager, java.util.BitSet, kodo.runtime.FetchConfiguration, int, java.lang.Object)
• flush(Collection,Collection,Collection,Collection,Collection)
• newExtent(java.lang.Class, boolean)

Additionally, subclasses should not attempt to acquire resources until open() has been called. Store manager instances might be created to call metadata methods such as newConfiguration() or getUnsupportedOptions() and never opened. These instances should not consume any data store resources.

Notes:

• The StoreManager.initialize(kodo.runtime.KodoStateManager, kodo.runtime.JDOState, kodo.runtime.FetchConfiguration, java.lang.Object) method is responsible for creating new instances of objects freshly loaded from the database. The method will be invoked with a KodoStateManager that the newly-loaded object should be associated with. To create the new object and set up this association correctly, the implementation should use the #newInstance method.
• If your data store supports some sort of transaction or unit of work, you should override the begin(), commit(), and rollback() methods.
• This class provides no infrastructure support for optimistic transactions. To provide optimistic transaction support:
  • Override beginOptimistic(), rollbackOptimistic(), and synchVersion(kodo.runtime.KodoStateManager, java.lang.Object).
  • Override getUnsupportedOptions() to not include JDOConfiguration.OPTION_OPTIMISTIC in the list of unsupported options.
  • Ensure that your flush implementation sets the next version for each modified object via the KodoStateManager.setNextVersion(java.lang.Object) method.
  • If your version object does not implement Comparable, override compareVersion(kodo.runtime.KodoStateManager, java.lang.Object, java.lang.Object), which relies on the Comparable.compareTo(java.lang.Object) method.
• If your data store supports a mechanism for automatically generating and managing identity values (or if you want to provide that facility on top of your data store), implement the getSequenceGenerator(kodo.meta.ClassMetaData) method if you want to use a long as your datastore identity type and are happy with Kodo's Id class. To use another datastore identity type, override getPersistenceCapableClass(java.lang.Object), getDataStoreIdClass(kodo.meta.ClassMetaData), copyDataStoreId(java.lang.Object, kodo.meta.ClassMetaData), and assignDataStoreId(kodo.runtime.KodoStateManager) instead. In either case, override getUnsupportedOptions() to not include JDOConfiguration.OPTION_ID_DATASTORE in the list of unsupported options.
• If your data store does not support queries (or if you do not want to convert Kodo's JDOQL parse tree into a datastore-specific query), you still have two options in terms of query execution:
  • In-memory execution: If you execute a query against an extent or a class, Kodo will automatically load the full extent of objects into memory and execute the query in memory.
  • kodo.MethodQL: MethodQL allows you to use the JDO query APIs to execute a method that finds data in your back-end and returns that data as a ResultList. For more details on MethodQL, see the Kodo JDO Reference Guide.

Since:

3.1

Fields inherited from interface kodo.runtime.StoreManager

FORCE_LOAD_ALL, FORCE_LOAD_DFG, FORCE_LOAD_NONE, FORCE_LOAD_REFRESH, VERSION_DIFFERENT, VERSION_EARLIER, VERSION_LATER, VERSION_SAME

Constructor Summary

AbstractStoreManager()

Method Summary

protected boolean	assignDataStoreId(KodoStateManager sm) Assign a new datastore identity to the given instance.
boolean	assignObjectId(KodoStateManager sm) Assign an object id to the given new instance.
void	begin() Kodo assumes that after this method is invoked, all data accesses through this store manager will be part of a single unit of work that can be rolled back.
void	beginOptimistic() No-op implementation.
boolean	cancelAll() Returns false.
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() This is a no-op implementation.
int	compareVersion(KodoStateManager state, Object v1, Object v2) Casts v1 and v2 to Comparable, and invokes v1.compareTo (v2).
Object	copyDataStoreId(Object oid, ClassMetaData meta) Copy the given object id value.
Collection	flush(Collection states) Breaks down states based on the objects' current JDO states, and delegates to flush(Collection,Collection,Collection,Collection,Collection).
protected abstract Collection	flush(Collection pNew, Collection pNewUpdated, Collection pNewFlushedDeleted, Collection pDirty, Collection pDeleted) Responsible for writing modifications happened back to the data store.
Object	getConnection() Returns null.
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.
protected KodoPersistenceManagerSPI	getPersistenceManager() Returns the KodoPersistenceManagerSPI that this store manager is associated with.
protected String	getPlatform() Returns a string name to identify the platform of this store manager.
SequenceGenerator	getSequenceGenerator(ClassMetaData forClass) Throws a javax.jdo.JDOUnsupportedOptionException.
protected Collection	getUnsupportedOptions() Returns a set of JDO option names that this store manager does not support.
boolean	hasConnection() Returns false.
abstract boolean	initialize(KodoStateManager sm, JDOState state, FetchConfiguration fetch, Object context) This method is invoked when Kodo needs to load an object whose identity is known but which has not yet been loaded from the data store.
abstract boolean	load(KodoStateManager sm, BitSet fields, FetchConfiguration fetch, int lockLevel, Object context) This method is invoked when Kodo needs to load additional data into an object that has already been at least partially loaded by a previous initialize(kodo.runtime.KodoStateManager, kodo.runtime.JDOState, kodo.runtime.FetchConfiguration, java.lang.Object) invocation.
Collection	loadAll(Collection sms, JDOState state, int load, FetchConfiguration fetch, Object context) This implementation just delegates to the proper singular method (StoreManager.initialize(kodo.runtime.KodoStateManager, kodo.runtime.JDOState, kodo.runtime.FetchConfiguration, java.lang.Object) or StoreManager.load(kodo.runtime.KodoStateManager, java.util.BitSet, kodo.runtime.FetchConfiguration, int, java.lang.Object)) depending on each state manager's state.
protected JDOConfiguration	newConfiguration() Return a new configuration instance for this runtime.
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).
abstract KodoExtent	newExtent(Class type, boolean subclasses) Create an KodoExtent capable of loading all instances of type, optionally including subclasses as defined by subclasses.
FetchConfiguration	newFetchConfiguration() Return a fetch configuration suitable for this runtime.
KodoQuery	newQuery(String language) Return a query implementation suitable for this runtime.
protected void	open() No-op implementation.
void	rollback() This is a no-op implementation.
void	rollbackOptimistic() No-op implementation.
void	setPersistenceManager(KodoPersistenceManager pm) Set a reference to the corresponding PersistenceManager.
boolean	synchVersion(KodoStateManager sm, Object context) Since this store manager does not provide optimistic locking support, this method always returns true.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface kodo.runtime.StoreManager

exists

Constructor Detail

AbstractStoreManager

public AbstractStoreManager()

Method Detail

setPersistenceManager

public final void setPersistenceManager(KodoPersistenceManager pm)

Description copied from interface: StoreManager

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.

Specified by:

setPersistenceManager in interface StoreManager

open

protected void open()

No-op implementation. Ready this store manager for persistent operations.

beginOptimistic

public void beginOptimistic()

No-op implementation. Override this method to provide optimistic locking semantics for your data store if you need notification of the beginning of an optimistic transaction.

Specified by:

beginOptimistic in interface StoreManager

rollbackOptimistic

public void rollbackOptimistic()

No-op implementation. Override this method to provide optimistic locking semantics for your data store if you need notification of a rollback of an optimistic transaction before begin() is invoked.

Specified by:

rollbackOptimistic in interface StoreManager

begin

public void begin()

Kodo assumes that after this method is invoked, all data accesses through this store manager will be part of a single unit of work that can be rolled back.

This is a no-op implementation. If your data store does not support any concept of locking or transactions, you need not override this method.

Specified by:

begin in interface StoreManager

commit

public void commit()

This is a no-op implementation. If your data store does not have a concept of transactions or a unit of work, you need not override this method. If it does, then override this method to notify the data store that the current transaction should be committed.

Specified by:

commit in interface StoreManager

rollback

public void rollback()

This is a no-op implementation. If your data store does not have a concept of transactions or a unit of work, you need not override this method. If it does, then override this method to notify the data store that the current transaction should be rolled back.

Specified by:

rollback in interface StoreManager

synchVersion

public boolean synchVersion(KodoStateManager sm,
                            Object context)

Since this store manager does not provide optimistic locking support, this method always returns true.

Specified by:

synchVersion in interface StoreManager

Following copied from interface: kodo.runtime.StoreManager

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 abstract boolean initialize(KodoStateManager sm,
                                   JDOState state,
                                   FetchConfiguration fetch,
                                   Object context)

This method is invoked when Kodo needs to load an object whose identity is known but which has not yet been loaded from the data store. sm is a partially-set-up state manager for this object. The ID and least-derived type information for the instance to load can be obtained by invoking sm.getObjectId() and sm.getMetaData().

When implementing this method, load the data for this object from the data store, determine the most-derived subclass of the newly-loaded data, and then use the #newInstance method to populate sm with a new instance of the appropriate type. Once #newInstance has been invoked, proceed to load field data into sm as in the load(kodo.runtime.KodoStateManager, java.util.BitSet, kodo.runtime.FetchConfiguration, int, java.lang.Object) method, by using KodoStateManager.store(int, java.lang.Object) (or the appropriate KodoStateManager.storetype method) to put the data into the object.

Specified by:

initialize in interface StoreManager

Following copied from interface: kodo.runtime.StoreManager

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 abstract boolean load(KodoStateManager sm,
                             BitSet fields,
                             FetchConfiguration fetch,
                             int lockLevel,
                             Object context)

This method is invoked when Kodo needs to load additional data into an object that has already been at least partially loaded by a previous initialize(kodo.runtime.KodoStateManager, kodo.runtime.JDOState, kodo.runtime.FetchConfiguration, java.lang.Object) invocation.

Load data into sm by using KodoStateManager.store(int, java.lang.Object) (or the appropriate KodoStateManager.storetype method) to put the data into the object.

Specified by:

load in interface StoreManager

Following copied from interface: kodo.runtime.StoreManager

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)

This implementation just delegates to the proper singular method (StoreManager.initialize(kodo.runtime.KodoStateManager, kodo.runtime.JDOState, kodo.runtime.FetchConfiguration, java.lang.Object) or StoreManager.load(kodo.runtime.KodoStateManager, java.util.BitSet, kodo.runtime.FetchConfiguration, int, java.lang.Object)) depending on each state manager's state. If your data store provides bulk loading APIs, overriding this method to be more clever may be advantageous.

Specified by:

loadAll in interface StoreManager

Following copied from interface: kodo.runtime.StoreManager

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

flush

public Collection flush(Collection states)

Breaks down states based on the objects' current JDO states, and delegates to flush(Collection,Collection,Collection,Collection,Collection).

Specified by:

flush in interface StoreManager

changeJDOState

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

Description copied from interface: StoreManager

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.

Specified by:

changeJDOState in interface StoreManager

getPersistenceCapableClass

public Class getPersistenceCapableClass(Object oid)

Description copied from interface: StoreManager

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

Specified by:

getPersistenceCapableClass in interface StoreManager

assignObjectId

public boolean assignObjectId(KodoStateManager sm)

Description copied from interface: StoreManager

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.

Specified by:

assignObjectId in interface StoreManager

Following copied from interface: kodo.runtime.StoreManager

See Also:

kodo.util.ApplicationIds#create

assignDataStoreId

protected boolean assignDataStoreId(KodoStateManager sm)

Assign a new datastore identity to the given instance.

getDataStoreIdClass

public Class getDataStoreIdClass(ClassMetaData meta)

Description copied from interface: StoreManager

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.

Specified by:

getDataStoreIdClass in interface StoreManager

copyDataStoreId

public Object copyDataStoreId(Object oid,
                              ClassMetaData meta)

Description copied from interface: StoreManager

Copy the given object id value.

Specified by:

copyDataStoreId in interface StoreManager

newDataStoreId

public Object newDataStoreId(Object oidVal,
                             ClassMetaData meta)

Description copied from interface: StoreManager

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

Specified by:

newDataStoreId in interface StoreManager

getConnection

public Object getConnection()

Returns null. If your data store can provide a distinct connection object, return it here.

Specified by:

getConnection in interface StoreManager

hasConnection

public boolean hasConnection()

Returns false. If your data store can provide a distinct connection object, this should return whether or not this store manager has a dedicated connection. For example, after a pessimistic transaction begins, this should return true if possible.

Kodo's automatic query flushing capabilities, among other things, use the return value of this method to determine what to do. So, if it returns false, automatic query flushing will never happen.

Specified by:

hasConnection in interface StoreManager

newExtent

public abstract KodoExtent newExtent(Class type,
                                     boolean subclasses)

Create an KodoExtent capable of loading all instances of type, optionally including subclasses as defined by subclasses.

This will typically return an instance of a class that extends ExtentImpl, defining ExtentImpl.getResultObjectProvider(kodo.meta.ClassMetaData) to return a ResultObjectProvider capable of iterating through all the desired objects for a given ClassMetaData. Note that there might be multiple calls to that method if type identifies an interface or abstract class with multiple persistence-capable implementations.

The implementation of the ExtentImpl.getResultObjectProvider(kodo.meta.ClassMetaData) method will typically execute some sort of data store query to find all the applicable objects, loop through the returned data, extracting object IDs from the data, and invoking #getObjectById(Object,FetchConfiguration,BitSet,Object) on each OID. When invoking this method, the first argument is the OID. The second is the current fetch configuration (this can be null). The third argument is a mask of fields to exclude from loading; it will typically be null. The last argument is an object that will be passed through to initialize(kodo.runtime.KodoStateManager, kodo.runtime.JDOState, kodo.runtime.FetchConfiguration, java.lang.Object) or load(kodo.runtime.KodoStateManager, java.util.BitSet, kodo.runtime.FetchConfiguration, int, java.lang.Object), and typically will contain the actual data to load. For example, for a JDBC-based store manager, this might be the result set that is being iterated over. If this argument is null, then the initialize(kodo.runtime.KodoStateManager, kodo.runtime.JDOState, kodo.runtime.FetchConfiguration, java.lang.Object) or load(kodo.runtime.KodoStateManager, java.util.BitSet, kodo.runtime.FetchConfiguration, int, java.lang.Object) method will have to issue another command to the data store in order to fetch the data to be loaded.

Specified by:

newExtent in interface StoreManager

newQuery

public KodoQuery newQuery(String language)

Description copied from interface: StoreManager

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

Specified by:

newQuery in interface StoreManager

Following copied from interface: kodo.runtime.StoreManager

Parameters:

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

newFetchConfiguration

public FetchConfiguration newFetchConfiguration()

Description copied from interface: StoreManager

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

Specified by:

newFetchConfiguration in interface StoreManager

compareVersion

public int compareVersion(KodoStateManager state,
                          Object v1,
                          Object v2)

Casts v1 and v2 to Comparable, and invokes v1.compareTo (v2). If v1 is less than v2, returns StoreManager.VERSION_EARLIER. If the same, returns StoreManager.VERSION_SAME. Otherwise, returns StoreManager.VERSION_LATER. If either v1 or v2 are null, returns StoreManager.VERSION_DIFFERENT.

Specified by:

compareVersion in interface StoreManager

Following copied from interface: kodo.runtime.StoreManager

Parameters:

state - the state manager for the object

v1 - the first version object to compare

v2 - the second version object to compare

Returns:

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

getSequenceGenerator

public SequenceGenerator getSequenceGenerator(ClassMetaData forClass)

Throws a javax.jdo.JDOUnsupportedOptionException. Override this method to provide datastore identity by using Kodo's Id class, which uses a long as the per-class identifier. To use some other sort of datastore identifier (a GUID, string, or someting of that nature), override getPersistenceCapableClass(java.lang.Object), getDataStoreIdClass(kodo.meta.ClassMetaData), .

Specified by:

getSequenceGenerator in interface StoreManager

cancelAll

public boolean cancelAll()

Returns false. If your data store supports cancelling queries, this method should cancel any currently-running queries and return true if any were cancelled.

Specified by:

cancelAll in interface StoreManager

Following copied from interface: kodo.runtime.StoreManager

Returns:

true if any statements cancelled, false otherwise

close

public void close()

Description copied from interface: StoreManager

Free any resources this store manager is using.

Specified by:

close in interface StoreManager

flush

protected abstract Collection flush(Collection pNew,
                                    Collection pNewUpdated,
                                    Collection pNewFlushedDeleted,
                                    Collection pDirty,
                                    Collection pDeleted)

Responsible for writing modifications happened back to the data store. If you do not remove the JDOConfiguration.OPTION_INC_FLUSH option in getUnsupportedOptions(), this will be called only once at the end of a transaction. Otherwise, it may be called periodically throughout the course of a transaction.

If this store manager supports optimistic transactions, datastore version information should be updated during flush, and the state manager's version indicator should be updated through the KodoStateManager.setNextVersion(java.lang.Object) method.

This method will only be invoked if there are meaningful changes to store. This differs from the behavior of StoreManager.flush(java.util.Collection), which may be invoked with a collection of objects in JDO states that do not require any datastore action (for example, objects in the transient-transactional state).

Parameters:

pNew - Objects that should be added to the store, and that have not previously been flushed.

pNewUpdated - New objects that have been modified since they were initially flushed. These were in persistentNew in an earlier flush invocation.

pNewFlushedDeleted - New objects that have been deleted since they were initially flushed. These were in persistentNew in an earlier flush invocation.

pDirty - Objects that were loaded from the data store and have since been modified.

pDeleted - Objects that were loaded from the data store and have since been deleted. These may have been in a previous flush invocation's persistentDirty list.

Returns:

a collection of OptimisticVerificationExceptions encountered during flushing.

getPersistenceManager

protected KodoPersistenceManagerSPI getPersistenceManager()

Returns the KodoPersistenceManagerSPI that this store manager is associated with.

newConfiguration

protected JDOConfiguration newConfiguration()

Return a new configuration instance for this runtime. Configuration data is maintained at the persistence manager factory level and is available to all Kodo components; therefore it is a good place to maintain shared resources such as connection pools, etc.

getUnsupportedOptions

protected Collection getUnsupportedOptions()

Returns a set of JDO option names that this store manager does not support.

This returns [ "javax.jdo.option.Optimistic", "javax.jdo.option.DatastoreIdentity", "kodo.option.IncrementalFlush" ]

getPlatform

protected String getPlatform()

Returns a string name to identify the platform of this store manager. This will be used by Kodo to assemble a string to put into the return value from PersistenceManagerFactory.getProperties().

Returns the class name of this store manager by default.