kodo.runtime
Interface KodoPersistenceManager

All Superinterfaces:

com.solarmetric.util.Closeable, Connection, LocalTransaction, LocalTransaction, PersistenceManager, com.solarmetric.profile.ProfilingAgentProvider, com.solarmetric.profile.ProfilingEnvironment, Synchronization, Transaction

All Known Subinterfaces:

KodoPersistenceManagerSPI

public interface KodoPersistenceManager

extends PersistenceManager, Transaction, Synchronization, Connection, LocalTransaction, LocalTransaction, com.solarmetric.util.Closeable, com.solarmetric.profile.ProfilingEnvironment, com.solarmetric.profile.ProfilingAgentProvider

Interface implemented by Kodo persistence managers.

Since:

3.0

Field Summary

static int	CONN_RETAIN_DEMAND Constant indicating that connections will be obtained as needed.
static int	CONN_RETAIN_PM Constant indicating that each persistence manager will retain a single connection that it will use for its lifespan.
static int	CONN_RETAIN_TRANS Constant indicating that connections will be retained for the life of each transaction.
static int	LOCK_NONE No lock.
static int	LOCK_READ Generic read lock level.
static int	LOCK_WRITE Generic write lock level.

Method Summary

Object	attach(Object pc) JDO 2.0 Preview.
Collection	attachAll(Collection pcs) JDO 2.0 Preview.
Object[]	attachAll(Object[] pcs) JDO 2.0 Preview.
boolean	cancelAll() Cancel all pending data store statements.
void	commitAndResume() Issue a commit and then start a new transaction.
Object	detach(Object pc) JDO 2.0 Preview.
Collection	detachAll(Collection pcs) JDO 2.0 Preview.
Object[]	detachAll(Object[] pcs) JDO 2.0 Preview.
void	evictAll(Class cls) Evict all persistent-clean and persistent-nontransactional instances in the extent of the given class (including subclasses).
void	evictAll(Extent extent) Evict all persistent-clean and persistent-nontransactional instances in the given Extent.
void	flush() Flush all transactional instances to the data store.
Object	getCachedObjectById(Object oid) Return the cached instance for the given oid/object, or null if not cached.
ClassLoader	getClassLoader() Return the current thread's class loader at the time this persistence manager was obtained from the persistence manager factory.
JDOConfiguration	getConfiguration() Return the configuration associated with this persistence manager.
Object	getConnection() Return the connection in use by the persistence manager, or a new connection if none.
String	getConnectionPassword() Return the connection password.
int	getConnectionRetainMode() Return the connection retain mode for this persistence manager.
String	getConnectionUserName() Return the connection user name.
Collection	getDirtyClasses() Return the set of classes that have been made dirty in the current transaction.
FetchConfiguration	getFetchConfiguration() Return the (mutable) fetch configuration for loading objects from this persistence manager.
Collection	getManagedObjects() Return a list of all managed instances.
ManagedRuntime	getManagedRuntime() Return the managed runtime in use.
Object[]	getObjectsById(Object[] oids, boolean validate) JDO 2.0 Preview.
boolean	getRetainValuesInOptimistic() Per-persistence manager configuration of whether to retain values when entering an optimistic transaction.
boolean	getRollbackOnly() JDO 2.0 Preview.
KodoStateManager	getState(Object oid) Deprecated. Use getStateManager(java.lang.Object) instead.
KodoStateManager	getStateManager(Object pc) Return the state manager for the given instance.
StoreManager	getStoreManager(boolean unwrap) Deprecated.
Collection	getTransactionalObjects() Return a list of current transaction instances.
boolean	isManaged() Whether this persistence manager is using managed transactions.
void	lockPersistent(Object pc) Ensure that the given instance is locked at the current lock level, as set in the FetchConfiguration for the persistence manager.
void	lockPersistent(Object pc, int level, int timeout) Ensure that the given instance is locked at the given lock level.
void	lockPersistentAll(Collection pcs) Ensure that the given instances are locked at the current lock level, as set in the FetchConfiguration for the persistence manager.
void	lockPersistentAll(Collection pcs, int level, int timeout) Ensure that the given instances are locked at the given lock level.
void	lockPersistentAll(Object[] pcs) Ensure that the given instances are locked at the current lock level, as set in the FetchConfiguration for the persistence manager.
void	lockPersistentAll(Object[] pcs, int level, int timeout) Ensure that the given instances are locked at the given lock level.
void	makeClassDirty(Class cls) Mark the given class as dirty within the current transaction.
void	registerListener(TransactionListener tl) Register a listener for transaction-related events.
boolean	removeListener(TransactionListener tl) Remove a listener for transaction-related events.
void	retrieve(Object pc, boolean dfgOnly) Immediately load the given object's persistent fields.
void	rollbackAndResume() Issue a rollback and then start a new transaction.
void	setRetainValuesInOptimistic(boolean retain) Per-persistence manager configuration of whether to retain values when entering an optimistic transaction.
void	setRollbackOnly() JDO 2.0 Preview.

Methods inherited from interface javax.jdo.PersistenceManager

close, currentTransaction, deletePersistent, deletePersistentAll, deletePersistentAll, evict, evictAll, evictAll, evictAll, getExtent, getIgnoreCache, getMultithreaded, getObjectById, getObjectId, getObjectIdClass, getPersistenceManagerFactory, getTransactionalObjectId, getUserObject, isClosed, makeNontransactional, makeNontransactionalAll, makeNontransactionalAll, makePersistent, makePersistentAll, makePersistentAll, makeTransactional, makeTransactionalAll, makeTransactionalAll, makeTransient, makeTransientAll, makeTransientAll, newObjectIdInstance, newQuery, newQuery, newQuery, newQuery, newQuery, newQuery, newQuery, newQuery, newQuery, refresh, refreshAll, refreshAll, refreshAll, retrieve, retrieveAll, retrieveAll, retrieveAll, retrieveAll, setIgnoreCache, setMultithreaded, setUserObject

Methods inherited from interface javax.jdo.Transaction

begin, commit, getNontransactionalRead, getNontransactionalWrite, getOptimistic, getPersistenceManager, getRestoreValues, getRetainValues, getSynchronization, isActive, rollback, setNontransactionalRead, setNontransactionalWrite, setOptimistic, setRestoreValues, setRetainValues, setSynchronization

Methods inherited from interface javax.transaction.Synchronization

afterCompletion, beforeCompletion

Methods inherited from interface javax.resource.cci.Connection

close, createInteraction, getLocalTransaction, getMetaData, getResultSetInfo

Methods inherited from interface javax.resource.cci.LocalTransaction

begin, commit, rollback

Methods inherited from interface javax.resource.spi.LocalTransaction

begin, commit, rollback

Methods inherited from interface com.solarmetric.util.Closeable

close

Methods inherited from interface com.solarmetric.profile.ProfilingAgentProvider

getProfilingAgent

Field Detail

CONN_RETAIN_DEMAND

public static final int CONN_RETAIN_DEMAND

Constant indicating that connections will be obtained as needed.

CONN_RETAIN_TRANS

public static final int CONN_RETAIN_TRANS

Constant indicating that connections will be retained for the life of each transaction.

CONN_RETAIN_PM

public static final int CONN_RETAIN_PM

Constant indicating that each persistence manager will retain a single connection that it will use for its lifespan.

LOCK_NONE

public static final int LOCK_NONE

No lock. Value of 0. For convenience, this constant is also defined in FetchConfiguration.

LOCK_READ

public static final int LOCK_READ

Generic read lock level. Value of 10. For convenience, this constant is also defined in FetchConfiguration.

LOCK_WRITE

public static final int LOCK_WRITE

Generic write lock level. Value of 20. For convenience, this constant is also defined in FetchConfiguration.

Method Detail

getConfiguration

public JDOConfiguration getConfiguration()

Return the configuration associated with this persistence manager.

getRetainValuesInOptimistic

public boolean getRetainValuesInOptimistic()

Per-persistence manager configuration of whether to retain values when entering an optimistic transaction.

setRetainValuesInOptimistic

public void setRetainValuesInOptimistic(boolean retain)

Per-persistence manager configuration of whether to retain values when entering an optimistic transaction.

getFetchConfiguration

public FetchConfiguration getFetchConfiguration()

Return the (mutable) fetch configuration for loading objects from this persistence manager.

getConnectionRetainMode

public int getConnectionRetainMode()

Return the connection retain mode for this persistence manager.

getConnection

public Object getConnection()

Return the connection in use by the persistence manager, or a new connection if none.

isManaged

public boolean isManaged()

Whether this persistence manager is using managed transactions.

getManagedRuntime

public ManagedRuntime getManagedRuntime()

Return the managed runtime in use.

getClassLoader

public ClassLoader getClassLoader()

Return the current thread's class loader at the time this persistence manager was obtained from the persistence manager factory.

getConnectionUserName

public String getConnectionUserName()

Return the connection user name.

getConnectionPassword

public String getConnectionPassword()

Return the connection password.

registerListener

public void registerListener(TransactionListener tl)

Register a listener for transaction-related events.

Since:

2.5

removeListener

public boolean removeListener(TransactionListener tl)

Remove a listener for transaction-related events.

Since:

2.5

commitAndResume

public void commitAndResume()

Issue a commit and then start a new transaction. This is identical to:

	pm.currentTransaction ().commit ();
	pm.currentTransaction ().begin ();
	

except that the PersistenceManager's internal atomic lock is utilized, so this method can be safely executed from multiple threads.

Since:

2.4

See Also:

Transaction.commit(), Transaction.begin()

rollbackAndResume

public void rollbackAndResume()

Issue a rollback and then start a new transaction. This is identical to:

	pm.currentTransaction ().rollback ();
	pm.currentTransaction ().begin ();
	

except that the PersistenceManager's internal atomic lock is utilized, so this method can be safely executed from multiple threads.

Since:

2.4

See Also:

Transaction.rollback(), Transaction.begin()

setRollbackOnly

public void setRollbackOnly()

JDO 2.0 Preview. Mark the current transaction for rollback.

getRollbackOnly

public boolean getRollbackOnly()

JDO 2.0 Preview. Return whether the current transaction has been marked for rollback.

flush

public void flush()

Flush all transactional instances to the data store. This method may set the rollback only flag on the current transaction if it encounters an error. In this case it will throw a JDOFatalException.

Since:

2.5

getObjectsById

public Object[] getObjectsById(Object[] oids,
                               boolean validate)

JDO 2.0 Preview. Return the objects with the given oids.

Parameters:

oids - the oids of the objects to return

validate - if true, the existance of the objects in the datastore will be validated.

Returns:

the objects that were looked up, in the same order as the oids parameter.

See Also:

PersistenceManager.getObjectById(Object,boolean)

getCachedObjectById

public Object getCachedObjectById(Object oid)

Return the cached instance for the given oid/object, or null if not cached.

Parameters:

oid - the object's id

Returns:

the cached object, or null if not cached

evictAll

public void evictAll(Class cls)

Evict all persistent-clean and persistent-nontransactional instances in the extent of the given class (including subclasses).

evictAll

public void evictAll(Extent extent)

Evict all persistent-clean and persistent-nontransactional instances in the given Extent.

detach

public Object detach(Object pc)

JDO 2.0 Preview. Detach the specified object from the PersistenceManager.

Parameters:

pc - the instance to detach

Returns:

the detached instance

See Also:

detachAll(Object[])

detachAll

public Collection detachAll(Collection pcs)

JDO 2.0 Preview. Detach the specified objects from the PersistenceManager.

Parameters:

pcs - the instances to detach

Returns:

the detached instances

See Also:

detachAll(Object[])

detachAll

public Object[] detachAll(Object[] pcs)

JDO 2.0 Preview. Detach the specified objects from the PersistenceManager. The objects returned can be manipulated and re-attached with attachAll(Object[]). The detached instances will be unmanaged copies of the specified parameters, and are suitable for serialization and manipulation outside of a Kodo environment. When detaching instances, only fields in the current FetchConfiguration will be traversed. Thus, to detach a graph of objects, relations to other persistent instances must either be in the default-fetch-group, or in the current custom FetchConfiguration.

Parameters:

pcs - the instances to detach

Returns:

the detached instances

Throws:

JDOUserException - if any of the instances do not have the detachable metadata extension.

See Also:

attachAll(Object[]), KodoHelper.getDetachedObjectId(java.lang.Object), KodoHelper.getDetachedState(java.lang.Object), getFetchConfiguration()

attach

public Object attach(Object pc)

JDO 2.0 Preview. Import the specified object into the PersistenceManager.

Parameters:

pc - instance to import

Returns:

the re-attached instance

See Also:

attachAll(Object[])

attachAll

public Collection attachAll(Collection pcs)

JDO 2.0 Preview. Import the specified objects into the PersistenceManager.

Parameters:

pcs - Collection of instances to import

Returns:

the re-attached instances

See Also:

attachAll(Object[])

attachAll

public Object[] attachAll(Object[] pcs)

JDO 2.0 Preview. Import the specified objects into the PersistenceManager. Instances that were previously detached from this or another PersistenceManager will have their changed merged into the persistent instances. Instances that are new will be persisted as new instances.

Parameters:

pcs - array of instances to import

Returns:

the re-attached instances

Throws:

JDOUserException - if any of the instances are not detachable, or if there is not a current active transaction.

JDOOptimisticVerificationException - when attempting to attaching instance that has been deleted in the data store, or when attaching an instance into a PersistenceManager that currently has cached an earlier version of that instance.

See Also:

detachAll(Object[])

retrieve

public void retrieve(Object pc,
                     boolean dfgOnly)

Immediately load the given object's persistent fields. One might use this action to make sure that an instance's fields are loaded before transitioning it to transient. Note that this action is not recursive. Any related objects that are loaded will not necessarily have their fields loaded.

Parameters:

pc - the instance whose fields should be retrieved

dfgOnly - indicator as to whether to retrieve only fields in the current fetch groups, or all fields

See Also:

PersistenceManager.retrieveAll(Collection,boolean)

lockPersistent

public void lockPersistent(Object pc,
                           int level,
                           int timeout)

Ensure that the given instance is locked at the given lock level.

Parameters:

pc - the object to lock

level - the lock level to use

timeout - the number of milliseconds to wait for the lock before giving up, or -1 for no limit

Since:

3.1

lockPersistent

public void lockPersistent(Object pc)

Ensure that the given instance is locked at the current lock level, as set in the FetchConfiguration for the persistence manager.

Since:

3.1

lockPersistentAll

public void lockPersistentAll(Collection pcs,
                              int level,
                              int timeout)

Ensure that the given instances are locked at the given lock level.

Parameters:

pcs - the objects to lock

level - the lock level to use

timeout - the number of milliseconds to wait for the lock before giving up, or -1 for no limit

Since:

3.1

lockPersistentAll

public void lockPersistentAll(Collection pcs)

Ensure that the given instances are locked at the current lock level, as set in the FetchConfiguration for the persistence manager.

Since:

3.1

lockPersistentAll

public void lockPersistentAll(Object[] pcs,
                              int level,
                              int timeout)

Ensure that the given instances are locked at the given lock level.

Parameters:

pcs - the objects to lock

level - the lock level to use

timeout - the number of milliseconds to wait for the lock before giving up, or -1 for no limit

Since:

3.1

lockPersistentAll

public void lockPersistentAll(Object[] pcs)

Ensure that the given instances are locked at the current lock level, as set in the FetchConfiguration for the persistence manager.

Since:

3.1

cancelAll

public boolean cancelAll()

Cancel all pending data store statements. If statements are cancelled while a flush is in progress, the transaction rollback only flag will be set.

Returns:

true if any statements were cancelled, false otherwise

Since:

3.1

getStoreManager

public StoreManager getStoreManager(boolean unwrap)

Deprecated.

Return the store manager in use.

Parameters:

unwrap - if true, the native store manager will be returned; otherwise, the store manager used by this persistence manager, which may be a decorator around the native store manager, will be returned

getState

public KodoStateManager getState(Object oid)

Deprecated. Use getStateManager(java.lang.Object) instead.

Return the state manager for the instance with the given oid. Includes objects made persistent in the current transaction.

getStateManager

public KodoStateManager getStateManager(Object pc)

Return the state manager for the given instance. Includes objects made persistent in the current transaction.

getManagedObjects

public Collection getManagedObjects()

Return a list of all managed instances.

getTransactionalObjects

public Collection getTransactionalObjects()

Return a list of current transaction instances.

makeClassDirty

public void makeClassDirty(Class cls)

Mark the given class as dirty within the current transaction.

Since:

3.0

getDirtyClasses

public Collection getDirtyClasses()

Return the set of classes that have been made dirty in the current transaction. Classes are made dirty automatically when an instance becomes dirty, or through explicit calls to makeClassDirty(java.lang.Class).

Since:

3.0