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	DETACH_ALL Mode to detach all fields.
static int	DETACH_FGS Mode to detach all fields in the current fetch groups.
static int	DETACH_LOADED Mode to detach all currently-loaded fields.
static int	LOCK_NONE No lock.
static int	LOCK_READ Generic read lock level.
static int	LOCK_WRITE Generic write lock level.
static int	LOOKUP_CHECK Mode to check that oids with no corresponding cached instance represent records in the database for calls to PersistenceManager.getObjectById(java.lang.Object, boolean) when the validate parameter is false.
static int	LOOKUP_HOLLOW Mode to return hollow objects from PersistenceManager.getObjectById(java.lang.Object, boolean) when the validate parameter is false.

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	checkConsistency() JDO 2.0 Preview.
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() JDO 2.0 Preview.
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.
int	getDetachFields() Detach mode constant to determine which fields are part of the detached graph.
boolean	getDetachOnClose() Whether to detach all persistent managed objects when the persistence manager closes.
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.
int	getObjectLookupMode() Whether to return hollow objects from PersistenceManager.getObjectById(java.lang.Object, boolean) when the validate parameter is false.
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. replaced by KodoPersistenceManagerSPI.getStateManager(java.lang.Object)
KodoStateManager	getStateManager(Object pc) Deprecated. replaced by KodoPersistenceManagerSPI.getStateManager(java.lang.Object)
StoreManager	getStoreManager(boolean unwrap) Deprecated. replaced by KodoPersistenceManagerSPI.getStoreManager(boolean)
Collection	getTransactionalObjects() Return a list of current transaction instances.
Object	getUserObject(Object key) JDO 2.0 Preview.
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.
Query	newNamedQuery(Class cls, String name) JDO 2.0 Preview.
Object	putUserObject(Object key, Object val) JDO 2.0 Preview.
void	registerListener(TransactionListener tl) Register a listener for transaction-related events.
boolean	removeListener(TransactionListener tl) Remove a listener for transaction-related events.
Object	removeUserObject(Object key) JDO 2.0 Preview.
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	setDetachFields(int mode) Detach mode constant to determine which fields are part of the detached graph.
void	setDetachOnClose(boolean detach) Whether to detach all persistent managed objects when the persistence manager closes.
void	setObjectLookupMode(int mode) Whether to return hollow objects from PersistenceManager.getObjectById(java.lang.Object, boolean) when the validate parameter is false.
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

LOOKUP_CHECK

public static final int LOOKUP_CHECK

Mode to check that oids with no corresponding cached instance represent records in the database for calls to PersistenceManager.getObjectById(java.lang.Object, boolean) when the validate parameter is false.

LOOKUP_HOLLOW

public static final int LOOKUP_HOLLOW

Mode to return hollow objects from PersistenceManager.getObjectById(java.lang.Object, boolean) when the validate parameter is false.

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.

DETACH_FGS

public static final int DETACH_FGS

Mode to detach all fields in the current fetch groups.

DETACH_LOADED

public static final int DETACH_LOADED

Mode to detach all currently-loaded fields.

DETACH_ALL

public static final int DETACH_ALL

Mode to detach all fields.

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.

getObjectLookupMode

public int getObjectLookupMode()

Whether to return hollow objects from PersistenceManager.getObjectById(java.lang.Object, boolean) when the validate parameter is false.

setObjectLookupMode

public void setObjectLookupMode(int mode)

Whether to return hollow objects from PersistenceManager.getObjectById(java.lang.Object, boolean) when the validate parameter is false.

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. In the JDO 2 specification, this is part of Transaction.

getRollbackOnly

public boolean getRollbackOnly()

JDO 2.0 Preview. Return whether the current transaction has been marked for rollback. In the JDO 2 specification, this is part of Transaction.

flush

public void flush()

JDO 2.0 Preview. 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

checkConsistency

public void checkConsistency()

JDO 2.0 Preview. Check the consistency of the persistence manager cache, reporting any optimistic violations, constraint violations, etc. In a datastore transaction or a flushed optimistic transaction, this method will act just like flush(). In an optimistic transaction that has not yet begun a datastore-level transaction, however, it will only report exceptions that would occur on flush, without retaining any datastore resources.

newNamedQuery

public Query newNamedQuery(Class cls,
                           String name)

JDO 2.0 Preview. Return the named query defined in the metadata.

Parameters:

cls - if not null, the candidate class to query

name - the name of the query to lookup

Returns:

a Query instance based on the information defined in the metadata

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.

getDetachOnClose

public boolean getDetachOnClose()

Whether to detach all persistent managed objects when the persistence manager closes.

setDetachOnClose

public void setDetachOnClose(boolean detach)

Whether to detach all persistent managed objects when the persistence manager closes.

getDetachFields

public int getDetachFields()

Detach mode constant to determine which fields are part of the detached graph. Defaults to DETACH_FGS.

setDetachFields

public void setDetachFields(int mode)

Detach mode constant to determine which fields are part of the detached graph. Defaults to DETACH_FGS.

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. replaced by KodoPersistenceManagerSPI.getStoreManager(boolean)

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. replaced by KodoPersistenceManagerSPI.getStateManager(java.lang.Object)

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)

Deprecated. replaced by KodoPersistenceManagerSPI.getStateManager(java.lang.Object)

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

putUserObject

public Object putUserObject(Object key,
                            Object val)

JDO 2.0 Preview. Put the specified key-value pair into the map of user objects.

Since:

3.2

getUserObject

public Object getUserObject(Object key)

JDO 2.0 Preview. Get the value for the specified key from the map of user objects.

Since:

3.2

removeUserObject

public Object removeUserObject(Object key)

JDO 2.0 Preview. Remove the specified key and its value from the map of user objects.

Since:

3.2