com.solarmetric.kodo.impl.jdbc.runtime
Class JDBCStoreManager

java.lang.Object
  |
  +--com.solarmetric.kodo.impl.jdbc.runtime.JDBCStoreManager

All Implemented Interfaces:

StoreManager

public class JDBCStoreManager

extends Object

implements StoreManager

StoreManager plugin for the common JDO runtime environent that uses JDBC to store persistent data in a relational data store.

Field Summary

static String	CONN_RETAIN_LEGACY Deprecated. Use CONN_RETAIN_ON_DEMAND instead.
static String	CONN_RETAIN_ON_DEMAND The connection retain mode for designating that a connection should be held only as needed.
static String	CONN_RETAIN_PM The connection retain mode for designating that a connection should be held for the duration of the associated PM's life cycle.
static String	CONN_RETAIN_TRANSACTION The connection retain mode for designating that a connection should be held for the duration of a transaction (optimistic or pessimistic).

Constructor Summary

JDBCStoreManager()

Method Summary

boolean	addSQLExecutionListener(SQLExecutionListener listener) Add a listener for all SQLExecution events.
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.
Object	createFromResultSet(ClassMapping cm, SQLExecutionManager sqlem, ResultSet rs, FieldMetaData[] fmds, int index) Create an instance from the given result set; if the instance is already cached it will be returned.
ResultList	executeQuery(ObjectSelect sel, Class type, boolean subs) Load all matching objects for the given query.
ResultList	executeQuery(QuerySelect sel, Class type, boolean subs) Load all matching objects for the given query.
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.
ClassMapping	getClassMapping(Class forClass)
(package private) ClassMapping	getClassMapping(ClassMetaData meta) Return the ClassMapping for the given metadata.
JDBCConfiguration	getConfiguration() Return the configuration for this store.
Connection	getConnection() Returns a Connection to the data store.
String	getConnectionRetainMode() Returns the connection retain mode for the current store manager.
Connector	getConnector() Returns a Connector, which can be used to obtain a Connection instance.
Connector	getConnector2() Returns a Connector, which can be used to obtain a Connection instance for the ConnectionFactory2.
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.
DBDictionary	getDictionary() Obtain a DBDictionary that used this PersistenceManagerImpl's Connector.
(package private) ClassMetaData	getMetaData(Class type) Return the ClassMetaData for the given type.
PersistenceManagerImpl	getPersistenceManager() Return the PersistenceManager this StoreManager is owned by.
JDBCPersistenceManagerFactory	getPersistenceManagerFactory()
SQLExecutionManager	getSQLExecutionManager() Return a SQLExecutionManager for interaction with the database; if there is a transaction in progress the connection will be transactionally consistent.
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) Returns a new KodoExtent for the specified Class.
KodoExtent	newExtent(ClassMetaData meta, boolean subclasses) Deprecated. use newExtent(java.lang.Class,boolean) instead
com.solarmetric.kodo.query.KodoQuery	newQuery(String language, Object copy) Return a query implementation suitable for this runtime.
void	release(SQLExecutionManager manager) Release the SQLExecutionManager if appropriate (i.e., if we do not have an active datastore transaction).
protected void	release(SQLExecutionManager manager, boolean force) Release manager if appropriate, or if force is set to true.
void	releaseConnection(Connection c) Releases the obtained Connection.
void	releaseDatastoreConnection(Object o) Releases a connection obtained through an invocation of getDatastoreConnection().
boolean	removeSQLExecutionListener(SQLExecutionListener listener) Remove a listener for all SQLExecution events.
void	rollback() Rollback the current data store transaction.
void	setConnectionRetainMode(String mode) Sets the connection retain mode for the current store manager.
void	setPersistenceManager(PersistenceManagerImpl pm) Set the PersistenceManager this StoreManager is owned by.

Methods inherited from class java.lang.Object

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

Field Detail

CONN_RETAIN_PM

public static final String CONN_RETAIN_PM

The connection retain mode for designating that a connection should be held for the duration of the associated PM's life cycle. Value: persistence-manager.

CONN_RETAIN_TRANSACTION

public static final String CONN_RETAIN_TRANSACTION

The connection retain mode for designating that a connection should be held for the duration of a transaction (optimistic or pessimistic). Value: transaction.

CONN_RETAIN_ON_DEMAND

public static final String CONN_RETAIN_ON_DEMAND

The connection retain mode for designating that a connection should be held only as needed. This is equivalent to CONN_RETAIN_TRANSACTION for pessimistic transactions. For optimistic transactions, this means that connections will be kept out of the pool for the duration of actual database communications only. If a connection is needed while a connection has already been requested, the same connection will be returned. Value: on-demand.

CONN_RETAIN_LEGACY

public static final String CONN_RETAIN_LEGACY

Deprecated. Use CONN_RETAIN_ON_DEMAND instead.

The connection retain mode for designating that a connection should be held only as needed, and that the old (pre-2.5.3) on-demand semantics are needed. This is equivalent to CONN_RETAIN_TRANSACTION for pessimistic transactions. For optimistic transactions, this means that connections will be kept out of the pool for the duration of actual database communications only. This differs from CONN_RETAIN_ON_DEMAND in that if a conneciton is requested while a connection has already been requested, a new connection will be returned. In general, CONN_RETAIN_ON_DEMAND is preferable. Value: legacy-on-demand.

Constructor Detail

JDBCStoreManager

public JDBCStoreManager()

Method Detail

getPersistenceManager

public PersistenceManagerImpl getPersistenceManager()

Return the PersistenceManager this StoreManager is owned by.

setPersistenceManager

public void setPersistenceManager(PersistenceManagerImpl pm)

Set the PersistenceManager this StoreManager is owned by.

Specified by:

setPersistenceManager in interface StoreManager

getPersistenceManagerFactory

public JDBCPersistenceManagerFactory getPersistenceManagerFactory()

getConfiguration

public JDBCConfiguration getConfiguration()

Return the configuration for this store.

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 connection,
                          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 connection,
                 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

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)

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

Returns a new KodoExtent for the specified ClassMetaData.

Specified by:

newExtent in interface StoreManager

newExtent

public KodoExtent newExtent(Class candidate,
                            boolean subclasses)

Returns a new KodoExtent for the specified Class.

Specified by:

newExtent in interface StoreManager

Since:

2.5

newQuery

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

getConnection

public Connection getConnection()
                         throws SQLException

Returns a Connection to the data store. If a transaction is not currently in progress, then the Connection will not be associated with this store manager's transaction, otherwise it will be the same transaction that is currently being used by the transaction.

releaseConnection

public void releaseConnection(Connection c)
                       throws SQLException

Releases the obtained Connection. 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.

getSQLExecutionManager

public SQLExecutionManager getSQLExecutionManager()

Return a SQLExecutionManager for interaction with the database; if there is a transaction in progress the connection will be transactionally consistent.

getConnector

public Connector getConnector()

Returns a Connector, which can be used to obtain a Connection instance.

getConnector2

public Connector getConnector2()

Returns a Connector, which can be used to obtain a Connection instance for the ConnectionFactory2.

getDictionary

public DBDictionary getDictionary()

Obtain a DBDictionary that used this PersistenceManagerImpl's Connector.

setConnectionRetainMode

public void setConnectionRetainMode(String mode)

Sets the connection retain mode for the current store manager. This can be one of CONN_RETAIN_PM, CONN_RETAIN_TRANSACTION, CONN_RETAIN_ON_DEMAND, or CONN_RETAIN_LEGACY. If it is a different value, an IllegalArgumentException will be thrown.

getConnectionRetainMode

public String getConnectionRetainMode()

Returns the connection retain mode for the current store manager. This is one of CONN_RETAIN_PM, CONN_RETAIN_TRANSACTION, CONN_RETAIN_ON_DEMAND, or CONN_RETAIN_LEGACY.

release

public void release(SQLExecutionManager manager)

Release the SQLExecutionManager if appropriate (i.e., if we do not have an active datastore transaction).

SQLExceptions will be consummed and logged to the runtime log.

release

protected void release(SQLExecutionManager manager,
                       boolean force)

Release manager if appropriate, or if force is set to true.

executeQuery

public ResultList executeQuery(ObjectSelect sel,
                               Class type,
                               boolean subs)

Load all matching objects for the given query. This is only used by ClassMapping.getExtentResultList(javax.jdo.Extent, com.solarmetric.kodo.impl.jdbc.runtime.JDBCStoreManager)

Parameters:

subs - if true, matching subclasses will also be returned

createFromResultSet

public Object createFromResultSet(ClassMapping cm,
                                  SQLExecutionManager sqlem,
                                  ResultSet rs,
                                  FieldMetaData[] fmds,
                                  int index)

Create an instance from the given result set; if the instance is already cached it will be returned.

Parameters:

cm - the mapping for a base type of the instance

sqlem - A SQLExecutionManager that can be used for loading additional data.

rs - the result set to load from

fmds - an array of FieldMetaData objects to load

index - the column index to start at when loading

getClassMapping

ClassMapping getClassMapping(ClassMetaData meta)

Return the ClassMapping for the given metadata.

getClassMapping

public ClassMapping getClassMapping(Class forClass)

getMetaData

ClassMetaData getMetaData(Class type)

Return the ClassMetaData for the given type.

addSQLExecutionListener

public boolean addSQLExecutionListener(SQLExecutionListener listener)

Add a listener for all SQLExecution events.

Returns:

true if we successfully added the listener

Since:

2.4

removeSQLExecutionListener

public boolean removeSQLExecutionListener(SQLExecutionListener listener)

Remove a listener for all SQLExecution events.

Returns:

true if we successfully removed the listener

Since:

2.4

executeQuery

public ResultList executeQuery(QuerySelect sel,
                               Class type,
                               boolean subs)

Load all matching objects for the given query.

Parameters:

subs - if true, matching subclasses will also be returned