com.triactive.jdo
Interface PersistenceManager

All Superinterfaces:

javax.jdo.PersistenceManager

All Known Implementing Classes:

PersistenceManagerImpl

public interface PersistenceManager

extends javax.jdo.PersistenceManager

An extension to the standard persistence manager interface including methods specific to TriActive JDO.

Applications should not use these methods.

Author:

Mike Martin

Method Summary

int	dataStoreModifyCount() Returns the number of data store modifications made under this persistence manager.
void	dump(java.lang.Object obj, java.io.PrintWriter out) Prints debugging info on an object to the specified output.
void	enlistInTransaction(StateManager sm) Called by state managers to enlist in the transaction cache.
void	evictFromTransaction(StateManager sm) Called by state managers to evict themselves from the transaction cache.
StateManager	findStateManager(java.lang.Object obj) Finds the StateManager for a given object.
java.util.List	findStateManagers(java.util.Collection objs) Finds the StateManagers for a collection of objects.
void	flushDirty() Causes any dirty state manager to be updated in storage.
java.sql.Connection	getConnection(boolean forWriting) Obtains a JDBC connection to the data store.
java.lang.Object	getObjectById(java.lang.Object id, java.lang.Class contextClass, boolean validate) Locates a persistent instance in the cache of instances managed by this PersistenceManager.
java.lang.Object	getObjectById(java.lang.Object id, java.lang.Class contextClass, int[] fieldNumbers, FieldManager fieldManager) Locates a persistent instance in the cache of instances managed by this PersistenceManager.
StoreManager	getStoreManager() Returns the store manager used for storage by this persistence manager.
void	hereIsStateManager(StateManager sm, java.lang.Object obj) Called by state managers when their getPersistenceManager() method is called.
void	markDirty(StateManager sm) Marks the specified state manager as dirty.
void	releaseConnection(java.sql.Connection conn) Release a previously-obtained data store connection.
void	removeStateManager(StateManager sm) Called by state managers when disconnecting from the managed object.

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

Method Detail

getStoreManager

public StoreManager getStoreManager()

Returns the store manager used for storage by this persistence manager.

getConnection

public java.sql.Connection getConnection(boolean forWriting)
                                  throws java.sql.SQLException

Obtains a JDBC connection to the data store. If a JDO transaction is active, this is the connection on which the corresponding JDBC transaction is active. Otherwise a new connection is obtained from the underlying data source.

Parameters:

forWriting - true if the connection will be used for updates.

Returns:

A JDBC connection.

Throws:

java.sql.SQLException

releaseConnection

public void releaseConnection(java.sql.Connection conn)
                       throws java.sql.SQLException

Release a previously-obtained data store connection. Must be called once for every connection obtained with getConnection(boolean) (use try/finally).

Throws:

java.sql.SQLException

enlistInTransaction

public void enlistInTransaction(StateManager sm)

Called by state managers to enlist in the transaction cache.

evictFromTransaction

public void evictFromTransaction(StateManager sm)

Called by state managers to evict themselves from the transaction cache.

removeStateManager

public void removeStateManager(StateManager sm)

Called by state managers when disconnecting from the managed object. Also evicts from the transaction cache.

getObjectById

public java.lang.Object getObjectById(java.lang.Object id,
                                      java.lang.Class contextClass,
                                      boolean validate)

Locates a persistent instance in the cache of instances managed by this PersistenceManager. This is a variation of getObjectById(Object, boolean) that allows a context class to be specified for class loading purposes.

Parameters:

id - An object ID.

contextClass - A class to use as a class-loading context, if necessary, or null to use just the default class loader(s).

validate - true if the existence of the instance is to be validated.

Returns:

The PersistenceCapable instance having the specified object ID.

getObjectById

public java.lang.Object getObjectById(java.lang.Object id,
                                      java.lang.Class contextClass,
                                      int[] fieldNumbers,
                                      FieldManager fieldManager)

Locates a persistent instance in the cache of instances managed by this PersistenceManager. This is a variation of getObjectById(Object,Class,boolean) that allows specific initial field values to be offered to the state manager. Classes in the store package use this method to proactively offer field values in cases where they are readily available. If the instance is in a state that can benefit from newly available field values, the fields are replaced in the instance and a state change occurs as though the instance itself had read a field.

Parameters:

id - An object ID.

contextClass - A class to use as a class-loading context, if necessary, or null to use just the default class loader(s).

fieldNumbers - The field numbers being offered.

fieldManager - A field manager from which to get the offered fields.

Returns:

The PersistenceCapable instance having the specified object ID.

findStateManager

public StateManager findStateManager(java.lang.Object obj)

Finds the StateManager for a given object.

Returns:

The object's state manager, or null if obj is null or has no state manager.

Throws:

javax.jdo.JDOUserException - If obj is not PersistenceCapable or is managed by a different PersistenceManager.

findStateManagers

public java.util.List findStateManagers(java.util.Collection objs)

Finds the StateManagers for a collection of objects.

Returns:

A list of state managers, one for each object in objs. Each entry in the list is null if the corresponding object reference is null or the object has no state manager.

Throws:

javax.jdo.JDOUserException - If any object in objs is not PersistenceCapable or is managed by a different PersistenceManager.

hereIsStateManager

public void hereIsStateManager(StateManager sm,
                               java.lang.Object obj)

Called by state managers when their getPersistenceManager() method is called. This is used by findStateManager(java.lang.Object) to quickly locate an object's state manager.

markDirty

public void markDirty(StateManager sm)

Marks the specified state manager as dirty.

In this case, "dirty" means having one or more fields modified that have not been updated in storage via the StoreManager. The persistence manager allows at most one state manager at a time to be considered dirty. The sole purpose of this delayed update is to coalesce multiple field changes on the same object into one SQL UPDATE.

flushDirty

public void flushDirty()

Causes any dirty state manager to be updated in storage.

dataStoreModifyCount

public int dataStoreModifyCount()

Returns the number of data store modifications made under this persistence manager. Can be used as a version stamp on the data store. Note that it only reflects modifications made to objects from this persistence manager.

dump

public void dump(java.lang.Object obj,
                 java.io.PrintWriter out)

Prints debugging info on an object to the specified output.