kodo.runtime
Interface KodoPersistenceManager

All Superinterfaces:

com.solarmetric.util.Closeable, Connection, LocalTransaction, LocalTransaction, PersistenceManager, Synchronization, Transaction

All Known Subinterfaces:

KodoPersistenceManagerSPI

public interface KodoPersistenceManager

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

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.

Method Summary

void	assertActiveTransaction() Throw an exception if there is no active transaction.
void	assertNontransactionalRead() Throw an exception if there is no transaction active and nontransactional reading is not enabled.
void	assertOpen() Throw an exception if this persistence manager has been closed.
Object	attach(Object pc) JDO 2.0 Preview.
Collection	attachAll(Collection pcs) JDO 2.0 Preview.
Object[]	attachAll(Object[] pcs) 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() 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	getObjectById(Object oid, FetchConfiguration conf, Object connection) Return the object with the given oid.
Object[]	getObjectsById(Object[] oids, boolean validate) JDO 2.0 Preview.
Object[]	getObjectsById(Object[] oids, FetchConfiguration conf, Object connection) Return the objects with the given oids.
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) Return the store manager in use.
Collection	getTransactionalObjects() Return a list of current transaction instances.
boolean	isManaged() Whether this persistence manager is using managed transactions.
void	lock() Deprecated.
void	makeClassDirty(Class cls) Mark the given class as dirty within the current transaction.
KodoStateManager	makeEmbedded(Object pc, KodoStateManager owner, int ownerField) Deprecated.
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	setRollbackOnly() JDO 2.0 Preview.
void	unlock() Deprecated.

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

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.

Method Detail

getConfiguration

public JDOConfiguration getConfiguration()

Return the configuration associated with this persistence manager.

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

getObjectById

public Object getObjectById(Object oid,
                            FetchConfiguration conf,
                            Object connection)

Return the object with the given oid. If present, the cached instance will be returned. Otherwise, the instance will be initialized through the store as usual; however, in this case the store will be passed the given connection information, and the system will load the object according to the given fetch configuratiion (or the persistence manager's configuration, if the given one is null). This method is provided as an optimization opportunity to concrete jdo implementations built on this common runtime. It is not for use by client code.

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

boolean - 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)

getObjectsById

public Object[] getObjectsById(Object[] oids,
                               FetchConfiguration conf,
                               Object connection)

Return the objects with the given oids. If present, the cached instance will be returned. Otherwise, the instance will be initialized through the store as usual; however, in this case the store will be passed the given connection information, and the system will load the object according to the given fetch configuratiion (or the persistence manager's configuration, if the given one is null). This method is provided as an optimization opportunity to concrete jdo implementations built on this common runtime. It is not for use by client code.

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

makeEmbedded

public KodoStateManager makeEmbedded(Object pc,
                                     KodoStateManager owner,
                                     int ownerField)

Deprecated.

For implementation use only. Make the given instance embedded.

Parameters:

pc - the instance to embed, or null to embed a newly-created instance that will be loaded with datastore data

owner - the owning state manager

ownerField - the field number of the owning object

Returns:

the state manager for the embedded instance

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:

pc - 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:

pc - 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)

getStoreManager

public StoreManager getStoreManager(boolean unwrap)

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

assertOpen

public void assertOpen()

Throw an exception if this persistence manager has been closed.

assertActiveTransaction

public void assertActiveTransaction()

Throw an exception if there is no active transaction.

assertNontransactionalRead

public void assertNontransactionalRead()

Throw an exception if there is no transaction active and nontransactional reading is not enabled.

lock

public void lock()

Deprecated.

Synchronizes on an internal lock if the Multithreaded flag is set to true. Make sure to call unlock() in a finally clause of the same method.

unlock

public void unlock()

Deprecated.

Releases the internal lock.