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(boolean lock) 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	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.
Collection	flush(Collection states) Flush the given state manager collection to the datastore, returning a collection of user exceptions encountered during flushing.
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.
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 connection, 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 connection, Set 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.
KodoExtent	newExtent(Class candidate, boolean subclasses) Return an extent of the given candidate class, optionally including subclasses.
KodoExtent	newExtent(ClassMetaData meta, boolean subclasses) Deprecated. use newExtent(java.lang.Class,boolean) instead
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.

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(boolean) method, which will still be called when a true data store transaction should begin.

begin

public void begin(boolean lock)

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 flush(java.util.Collection) if this method has not been invoked since the store manager was created or since the last commit() or 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.

Since:

2.5.0

commit

public void commit()

Commit the current data store transaction.

rollback

public void rollback()

Rollback the current data store transaction.

isActive

public boolean isActive()

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

Since:

2.5.0

isLocking

public boolean isLocking()

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

Since:

2.5.0

isOnline

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

Since:

2.5.0

getDatastoreConnection

public Object getDatastoreConnection()

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.

releaseDatastoreConnection

public void releaseDatastoreConnection(Object o)

Releases a connection obtained through an invocation of 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.

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,
                          JDOState state,
                          Object connection,
                          Set fields)

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.

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 connection,
                 Set 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. 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 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 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 handlesMarkingFlushedFields() for details.

handlesMarkingFlushedFields

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

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

Since:

2.5.0

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 KodoExtent newExtent(ClassMetaData meta,
                            boolean subclasses)

Deprecated. use newExtent(java.lang.Class,boolean) instead

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.

newExtent

public KodoExtent newExtent(Class candidate,
                            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.

Since:

2.5

newQuery

public com.solarmetric.kodo.query.KodoQuery 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

close

public void close()

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.

Since:

2.5.0