com.solarmetric.kodo.runtime.datacache
Class DataCacheStoreManager

java.lang.Object
  |
  +--com.solarmetric.kodo.runtime.datacache.DataCacheStoreManager

All Implemented Interfaces:

StoreManager

public class DataCacheStoreManager

extends Object

implements StoreManager

StoreManager proxy that delegates to a data cache when possible.

Field Summary

static String	DEFAULT_DATA_CACHE The key under which the default data cache is stored in the internal map of caches.
static String	TIMEOUT_EXTENSION The key under which a class's cache timeout value is stored.

Constructor Summary

DataCacheStoreManager(StoreManager sm, Map caches, QueryCache queryCache)
Constructor.

Method Summary

void	begin(boolean lock) Begin a data store transaction.
void	beginOptimistic() Notification that an optimistic transaction has started.
protected Set	bitSetToFieldSet(ClassMetaData meta, BitSet bits)
static boolean	canCache(ClassMetaData meta) Return true if the specified class can be cached.
boolean	checkVersion(StateManagerImpl sm) Determine whether the given StateManager is the same version as the datastore version.
void	close() Close any resources used by this store manager.
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.
protected BitSet	fieldSetToBitSet(ClassMetaData meta, Set fields)
Collection	flush(Collection states) Flush the given state manager collection to the datastore, returning a collection of user exceptions encountered during flushing.
DataCache	getDataCache() Return the default cache.
DataCache	getDataCache(ClassMetaData meta) Returns the DataCache associated with the persistence-capable class identified by meta, or null if meta is not cacheable.
DataCache	getDataCache(String name) Return the cache whose name is name.
Object	getDatastoreConnection() Returns a connection to the data store suitable for use with StoreManager APIs that require a conneciton argument.
Class	getDataStoreIdClass(ClassMetaData meta) Return the class used by this StoreManager for datastore identity values.
PersistenceManagerImpl	getPersistenceManager()
QueryCache	getQueryCache() Return the query cache in use.
StoreManager	getStoreManager() Return the internal store manager.
long	getTimeout(ClassMetaData meta) Returns the number of milliseconds that the specified class is valid for.
boolean	handlesMarkingFlushedFields() Returns true if this store manager implementation takes responsibility for marking which fields are successfully flushed during flush(java.util.Collection); otherwise returns false.
boolean	initialize(StateManagerImpl sm, JDOState state, Object conn, Set fields) Initialize the given StateManager.
boolean	isActive() Returns true if this store manager has an active transaction associated with it.
boolean	isLocking() Returns true if data loaded through this store manager will be locked on the data store side.
boolean	isOnline() Returns true if this store manager currently has a dedicated connection to the data store that it will keep until a well-defined boundary (transaction commit or PersistenceManager commit).
void	load(StateManagerImpl sm, Object conn, Set fields, boolean setVersion) Load the given StateManager.
static DataCache	newDataCache(String cacheName, Configuration conf) Create a new DataCache object with the given name.
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.
KodoExtent	newExtent(Class clazz, boolean subclasses) Return an extent of the given candidate class, optionally including subclasses.
KodoExtent	newExtent(ClassMetaData meta, boolean subclasses) Return an extent of the given candidate class, optionally including subclasses.
protected PCData	newPCData(StateManagerImpl sm)
com.solarmetric.kodo.query.KodoQuery	newQuery(String language, Object template) Return a query implementation suitable for this runtime.
void	releaseDatastoreConnection(Object o) Releases a connection obtained through an invocation of getDatastoreConnection().
void	rollback() Rollback the current data store transaction.
void	setPersistenceManager(PersistenceManagerImpl pm) Set a reference to the corresponding PersistenceManager.
protected PCData	wrapPCData(PCData data, ClassMetaData meta)

Methods inherited from class java.lang.Object

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

Field Detail

TIMEOUT_EXTENSION

public static final String TIMEOUT_EXTENSION

The key under which a class's cache timeout value is stored. The value of this string is cache-timeout.

DEFAULT_DATA_CACHE

public static final String DEFAULT_DATA_CACHE

The key under which the default data cache is stored in the internal map of caches. Invoking getDataCache() is equivalent to getDataCache(DEFAULT_DATA_CACHE). The value of this string is default.

Constructor Detail

DataCacheStoreManager

public DataCacheStoreManager(StoreManager sm,
                             Map caches,
                             QueryCache queryCache)

Constructor.

Parameters:

sm - the store manager to delegate to

caches - the map of caches to access for shared objects

queryCache - the cache to use for storing query results

Method Detail

getStoreManager

public StoreManager getStoreManager()

Return the internal store manager.

getDataCache

public DataCache getDataCache()

Return the default cache. Equivalent to getDataCache(DEFAULT_DATA_CACHE).

getDataCache

public DataCache getDataCache(String name)

Return the cache whose name is name.

Since:

2.5.0

getQueryCache

public QueryCache getQueryCache()

Return the query cache in use.

Since:

2.5.0

getPersistenceManager

public PersistenceManagerImpl getPersistenceManager()

setPersistenceManager

public void setPersistenceManager(PersistenceManagerImpl pm)

Description copied from interface: StoreManager

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

Specified by:

setPersistenceManager in interface StoreManager

beginOptimistic

public void beginOptimistic()

Description copied from interface: StoreManager

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

Specified by:

beginOptimistic in interface StoreManager

begin

public void begin(boolean lock)

Description copied from interface: StoreManager

Begin a data store transaction. If lock is true, designate that any data loaded through the store manager should be locked on the data store side. Otherwise, data loaded from the store manager will not be locked. After this method is invoked, any operations performed on this data store are considered to be performed within a single transactional context, and it should be possible to commit or roll back these changes at a later time.

This method should be invoked before attempts to flush any data to the data store, at the latest. It is permissible for a store manager implementation to throw an exception in StoreManager.flush(java.util.Collection) if this method has not been invoked since the store manager was created or since the last StoreManager.commit() or StoreManager.rollback() invocation, whichever happened later.

If optimistic transactions are in use, this method will not be called until the store manager needs to maintain a transactionally consistent connection to the data store. 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.

Specified by:

begin in interface StoreManager

commit

public void commit()

Description copied from interface: StoreManager

Commit the current data store transaction.

Specified by:

commit in interface StoreManager

rollback

public void rollback()

Description copied from interface: StoreManager

Rollback the current data store transaction.

Specified by:

rollback in interface StoreManager

isActive

public boolean isActive()

Description copied from interface: StoreManager

Returns true if this store manager has an active transaction associated with it.

Specified by:

isActive in interface StoreManager

isLocking

public boolean isLocking()

Description copied from interface: StoreManager

Returns true if data loaded through this store manager will be locked on the data store side.

Specified by:

isLocking in interface StoreManager

isOnline

public boolean isOnline()

Description copied from interface: StoreManager

Returns true if this store manager currently has a dedicated connection to the data store that it will keep until a well-defined boundary (transaction commit or PersistenceManager commit).

Specified by:

isOnline in interface StoreManager

getDatastoreConnection

public Object getDatastoreConnection()

Description copied from interface: StoreManager

Returns a connection to the data store suitable for use with StoreManager APIs that require a conneciton argument. If a transaction is not currently in progress, then the connection may not be associated with this store manager's transaction. If a transaction is in progress, it is guaranteed that the returned connection will be the same as that currently being used by the transaction.

Specified by:

getDatastoreConnection in interface StoreManager

releaseDatastoreConnection

public void releaseDatastoreConnection(Object o)

Description copied from interface: StoreManager

Releases a connection obtained through an invocation of StoreManager.getDatastoreConnection(). If this store manager has a reserved connection, and the Connection argument is the same as the Connection that is currently in use, then no action will be taken. Otherwise, the connection will be closed.

Specified by:

releaseDatastoreConnection in interface StoreManager

exists

public boolean exists(Object oid,
                      ClassMetaData meta)

Description copied from interface: StoreManager

Verify that the given instance exists in the data store.

Specified by:

exists in interface StoreManager

checkVersion

public boolean checkVersion(StateManagerImpl sm)

Description copied from interface: StoreManager

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

Specified by:

checkVersion in interface StoreManager

Following copied from interface: com.solarmetric.kodo.runtime.StoreManager

Parameters:

sm - the instance to check

Returns:

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

initialize

public boolean initialize(StateManagerImpl sm,
                          JDOState state,
                          Object conn,
                          Set fields)

Description copied from interface: StoreManager

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

Specified by:

initialize in interface StoreManager

Following copied from interface: com.solarmetric.kodo.runtime.StoreManager

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

fields - the fields to load. 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

Returns:

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

load

public void load(StateManagerImpl sm,
                 Object conn,
                 Set fields,
                 boolean setVersion)

Description copied from interface: StoreManager

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.

Specified by:

load in interface StoreManager

Following copied from interface: com.solarmetric.kodo.runtime.StoreManager

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

fieldSetToBitSet

protected BitSet fieldSetToBitSet(ClassMetaData meta,
                                  Set fields)

bitSetToFieldSet

protected Set bitSetToFieldSet(ClassMetaData meta,
                               BitSet bits)

flush

public Collection flush(Collection states)

Description copied from interface: StoreManager

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

If StoreManager.handlesMarkingFlushedFields() returns true, then this method is responsible for marking which fields are successfully flushed to the data store. Otherwise, the PersistenceManagerImpl will mark all dirty fields in all flushed objects as flushed upon successful completion of this method. See StoreManager.handlesMarkingFlushedFields() for details.

Specified by:

flush in interface StoreManager

handlesMarkingFlushedFields

public boolean handlesMarkingFlushedFields()

Description copied from interface: StoreManager

Returns true if this store manager implementation takes responsibility for marking which fields are successfully flushed during StoreManager.flush(java.util.Collection); otherwise returns false.

It is preferable for implementations to return true from this method. If the store manager can mark those fields that are successfully flushed, then exceptions returned from StoreManager.flush(java.util.Collection) can be ignored, as the state of the objects will be consistent with the data store.

If this method returns false, then the PersistenceManagerImpl will mark all dirty fields in all flushed objects as flushed after successful completion of StoreManager.flush(java.util.Collection). If an exception is thrown during the flush, then the PersistenceManagerImpl will throw a JDOFatalDataStoreException and the transaction will be rolled back. The post-rollback values of the unsuccessfully flushed objects will be defined by the normal behavior of a rollback during a transaction commit.

Specified by:

handlesMarkingFlushedFields in interface StoreManager

getDataStoreIdClass

public Class getDataStoreIdClass(ClassMetaData meta)

Description copied from interface: StoreManager

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

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(ClassMetaData meta)

Description copied from interface: StoreManager

Create a new unique datastore identity for the given type.

Specified by:

newDataStoreId in interface StoreManager

newDataStoreId

public Object newDataStoreId(String str,
                             ClassMetaData meta)

Description copied from interface: StoreManager

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

Specified by:

newDataStoreId in interface StoreManager

newExtent

public KodoExtent newExtent(ClassMetaData meta,
                            boolean subclasses)

Description copied from interface: StoreManager

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.

Specified by:

newExtent in interface StoreManager

newExtent

public KodoExtent newExtent(Class clazz,
                            boolean subclasses)

Description copied from interface: StoreManager

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.

Specified by:

newExtent in interface StoreManager

newQuery

public com.solarmetric.kodo.query.KodoQuery newQuery(String language,
                                                     Object template)

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: com.solarmetric.kodo.runtime.StoreManager

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

close

public void close()

Description copied from interface: StoreManager

Close any resources used by this store manager. After this method has been invoked, all database resources held by the store manager will be released. However, it is still possible to use this StoreManager for nontransactional operations, potentially using different connection resources than were used for earlier operations.

Specified by:

close in interface StoreManager

newPCData

protected PCData newPCData(StateManagerImpl sm)

wrapPCData

protected PCData wrapPCData(PCData data,
                            ClassMetaData meta)

getTimeout

public long getTimeout(ClassMetaData meta)

Returns the number of milliseconds that the specified class is valid for. Returns -1 if this class does not have a timeout, and no default is set for the system.

Since:

2.5.0

getDataCache

public DataCache getDataCache(ClassMetaData meta)

Returns the DataCache associated with the persistence-capable class identified by meta, or null if meta is not cacheable. If no cache exists for meta, one will be created here.

If type A's superclass is not cacheable, then A cannot be cacheable either. This is because we need to be able to look up the object in the class knowing only the least-derived class information.

Similarly, all subclasses of a type B must be in the same cache as B's cache.

Since:

2.5.0

newDataCache

public static DataCache newDataCache(String cacheName,
                                     Configuration conf)

Create a new DataCache object with the given name. This implementation creates a new instance of the type specified in the DataCache configuration property, passing the DataCacheProperties to it for initial configuration.

Since:

2.5.0

canCache

public static boolean canCache(ClassMetaData meta)

Return true if the specified class can be cached.