kodo.jdbc.runtime
Class JDBCStoreManager

java.lang.Object
  |
  +--kodo.jdbc.runtime.JDBCStoreManager

All Implemented Interfaces:

com.solarmetric.util.Closeable, StoreManager

public class JDBCStoreManager

extends Object

implements StoreManager

StoreManager plugin that uses JDBC to store persistent data in a relational data store.

Fields inherited from interface kodo.runtime.StoreManager

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

Constructor Summary

JDBCStoreManager()

Method Summary

Object	attachVersion(KodoStateManager state, Serializable version) Convert the specified externalized form of the version into a Kodo version object.
void	begin(boolean lock) Begin a data store transaction.
void	beginOptimistic() Notification that an optimistic transaction has started.
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	closeConnection(Object conn) Close the given connection if needed.
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.
Serializable	detachVersion(KodoStateManager state) Returns a serializable external form of the specified internal version state.
boolean	exists(KodoStateManager sm, Object connection) Verify that the given instance exists in the data store; return false if it does not.
Collection	flush(Collection states) Flush the given state manager collection to the datastore, returning a collection of optimistic exceptions encountered during flushing.
JDBCConfiguration	getConfiguration() Return the configuration for this runtime.
Object	getConnection() Return a connection to the data store.
int	getCount(Select sel) Return the count for the given query.
Class	getDataStoreIdClass(ClassMetaData meta) Return the class used by this StoreManager for datastore identity values.
Connection	getJDBCConnection() Return a SQL connection to the database.
Class	getPersistenceCapableClass(Object oid) Return the persistent class for the given data store identity value.
KodoPersistenceManager	getPersistenceManager() Return the PersistenceManager this StoreManager is owned by.
SelectResult	getResult(Select sel) Return the result of executing the given query using a forward- only result set type.
SelectResult	getResult(Select sel, JDBCFetchConfiguration fetch) Return the result of executing the given query using a result set type based on the give fetch configuration, or the default if null.
SequenceGenerator	getSequenceGenerator(Class 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 connection) Initialize the given state manager.
boolean	isActive() Return true if there is a data store transaction in progress.
boolean	isLocking() Return true if data loaded through this store manager will be locked on the data store side.
Object	load(ClassMapping mapping, JDBCFetchConfiguration fetch, Result result) Load the object in the current row of the given result.
boolean	load(KodoStateManager sm, Collection fields, FetchConfiguration fetch, Object connection) Load the given state manager.
Object	load(Object oid, JDBCFetchConfiguration fetch) Load the object with the given oid.
Collection	loadAll(Collection sms, JDOState state, int load, FetchConfiguration fetch, Object connection) Initialize, load, or validate the existance of all of the given objects.
void	loadSubclasses(ClassMapping mapping) Makes sure all subclasses of the given type are loaded in the JVM.
Object	newDataStoreId(PersistenceCapable pc, ClassMetaData meta) Create a new unique datastore identity for the given instance.
Object	newDataStoreId(String str, ClassMetaData meta) Create a new unique datastore identity for the given type from the given string.
KodoExtent	newExtent(Class cls, boolean subclasses) Return an extent of the given candidate class, optionally including subclasses.
KodoQuery	newQuery(String language, Object copy) Return a query implementation suitable for this runtime.
Select	newSelect() Return a new select for queries.
void	rollback() Rollback the current data store transaction.
void	setPersistenceManager(KodoPersistenceManager pm) Set the PersistenceManager this StoreManager is owned by.
boolean	synchVersion(KodoStateManager sm, Object connection) Update the version information in the given state manager to the version stored in the data store.

Methods inherited from class java.lang.Object

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

Constructor Detail

JDBCStoreManager

public JDBCStoreManager()

Method Detail

getPersistenceManager

public KodoPersistenceManager getPersistenceManager()

Return the PersistenceManager this StoreManager is owned by.

setPersistenceManager

public void setPersistenceManager(KodoPersistenceManager pm)

Set the PersistenceManager this StoreManager is owned by.

Specified by:

setPersistenceManager in interface StoreManager

getConfiguration

public JDBCConfiguration getConfiguration()

Return the configuration for this runtime.

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, loaded data should be locked in the data store. 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.

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

Return true if there is a data store transaction in progress. This typically means that StoreManager.begin(boolean) has been called more recently than StoreManager.commit() or StoreManager.rollback().

Specified by:

isActive in interface StoreManager

isLocking

public boolean isLocking()

Description copied from interface: StoreManager

Return true if data loaded through this store manager will be locked on the data store side. This typically means that a transaction is in progress and StoreManager.begin(boolean) was called with lock set to true.

Specified by:

isLocking in interface StoreManager

getConnection

public Object getConnection()

Description copied from interface: StoreManager

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.

Specified by:

getConnection in interface StoreManager

hasConnection

public boolean hasConnection()

Description copied from interface: StoreManager

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

Specified by:

hasConnection in interface StoreManager

closeConnection

public void closeConnection(Object conn)

Description copied from interface: StoreManager

Close the given connection if needed. Code that does not know the API of the native connection object or that deals with native connection objects that have no obvious close method can use this method to signal to the store manager that it is done with the given connection.

Specified by:

closeConnection in interface StoreManager

exists

public boolean exists(KodoStateManager sm,
                      Object connection)

Description copied from interface: StoreManager

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

Specified by:

exists in interface StoreManager

synchVersion

public boolean synchVersion(KodoStateManager sm,
                            Object connection)

Description copied from interface: StoreManager

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

Specified by:

synchVersion in interface StoreManager

Following copied from interface: kodo.runtime.StoreManager

Parameters:

sm - the instance to check

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

Returns:

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

detachVersion

public Serializable detachVersion(KodoStateManager state)

Description copied from interface: StoreManager

Returns a serializable external form of the specified internal version state. The external form must not contain any implementation-specific classes; only java.* classes may be used.

Specified by:

detachVersion in interface StoreManager

Following copied from interface: kodo.runtime.StoreManager

See Also:

KodoStateManager.getVersion()

attachVersion

public Object attachVersion(KodoStateManager state,
                            Serializable version)

Description copied from interface: StoreManager

Convert the specified externalized form of the version into a Kodo version object.

Specified by:

attachVersion in interface StoreManager

Following copied from interface: kodo.runtime.StoreManager

See Also:

StoreManager.detachVersion(kodo.runtime.KodoStateManager), KodoStateManager.getVersion()

compareVersion

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

Description copied from interface: StoreManager

Compare the two version objects.

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

initialize

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

Description copied from interface: StoreManager

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 the fields for the given fetch configuration. If any of the configured fields are not loaded in this method, they will be loaded with a subsequent call to StoreManager.load(kodo.runtime.KodoStateManager, java.util.Collection, kodo.runtime.FetchConfiguration, 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.

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

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 boolean load(KodoStateManager sm,
                    Collection fields,
                    FetchConfiguration fetch,
                    Object connection)

Description copied from interface: StoreManager

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

Specified by:

load in interface StoreManager

Following copied from interface: kodo.runtime.StoreManager

Parameters:

sm - the instance to load

fields - immutable set of fields to load; all fields in this set must be loaded; the fields are in JDO order

fetch - the fetch configuration to use when loading related objects

connection - the current connection 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 connection)

Description copied from interface: StoreManager

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 StoreManager.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 StoreManager.load(kodo.runtime.KodoStateManager, java.util.Collection, kodo.runtime.FetchConfiguration, java.lang.Object), choosing the fields to load based on the fetch configuration (one easy way to get a collection of fields for an object is via KodoStateManager.getUnloadedFields(kodo.runtime.FetchConfiguration)), or loading all fields if load == FORCE_LOAD_ALL. Any required fields left unloaded will cause a subsequent invocation of StoreManager.load(kodo.runtime.KodoStateManager, java.util.Collection, kodo.runtime.FetchConfiguration, 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 StoreManager.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.

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

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

Returns:

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

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

flush

public Collection flush(Collection states)

Description copied from interface: StoreManager

Flush the given state manager collection to the datastore, returning a collection of optimistic 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 KodoStateManager.setNextVersion(java.lang.Object) method. The current version will roll over to this next version upon successful commit.

Specified by:

flush 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

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

Description copied from interface: StoreManager

Create a new unique datastore identity for the given instance.

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(Class cls,
                            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 KodoQuery newQuery(String language,
                          Object copy)

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

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

getSequenceGenerator

public SequenceGenerator getSequenceGenerator(Class forClass)

Description copied from interface: StoreManager

Returns a SequenceGenerator for the specified class.

Specified by:

getSequenceGenerator in interface StoreManager

close

public void close()

Description copied from interface: StoreManager

Free any resources this store manager is using.

Specified by:

close in interface StoreManager

getJDBCConnection

public Connection getJDBCConnection()

Return a SQL connection to the database. This method is equivalent to StoreManager.getConnection(), but does not require you to cast the returned object to a SQL connection. The close method should always be called on the connection to free any resources it is using. When appropriate, the close method is implemented as a no-op.

load

public Object load(ClassMapping mapping,
                   JDBCFetchConfiguration fetch,
                   Result result)
            throws SQLException

Load the object in the current row of the given result.

load

public Object load(Object oid,
                   JDBCFetchConfiguration fetch)

Load the object with the given oid.

getCount

public int getCount(Select sel)
             throws SQLException

Return the count for the given query.

getResult

public SelectResult getResult(Select sel)
                       throws SQLException

Return the result of executing the given query using a forward- only result set type.

getResult

public SelectResult getResult(Select sel,
                              JDBCFetchConfiguration fetch)
                       throws SQLException

Return the result of executing the given query using a result set type based on the give fetch configuration, or the default if null.

newSelect

public Select newSelect()

Return a new select for queries.

loadSubclasses

public void loadSubclasses(ClassMapping mapping)

Makes sure all subclasses of the given type are loaded in the JVM. This is usually done automatically.