com.sptci.jdo
Class PersistenceManager2

java.lang.Object
  com.sptci.jdo.PersistenceManager2

All Implemented Interfaces:

javax.jdo.PersistenceManager

public class PersistenceManager2
extends java.lang.Object
implements javax.jdo.PersistenceManager

A proxy around a javax.jdo.PersistenceManager used to ensure a singleton PersistenceManager instance for the entire application.

Version:

$Id: PersistenceManager2.java,v 1.2 2006/02/15 00:48:39 rakesh Exp $

Author:

Rakesh Vidyadharan 05^th February, 2006

Copyright 2006, Sans Pareil Technologies, Inc.

See Also:

PersistenceManagerFactory.getPersistenceManager()

Field Summary

private javax.jdo.PersistenceManager

persistenceManager The PersistenceManager instance that is decorated.

Constructor Summary

protected

PersistenceManager2(javax.jdo.PersistenceManager pm) Create a new instance of the decorator using the specified PersistenceManager

Method Summary

void	addInstanceLifecycleListener(javax.jdo.listener.InstanceLifecycleListener listener, java.lang.Class[] classes) Method to register a lifecycle listener as per JDO 2.0 spec 12.15.
void	checkConsistency() This method validates the cache with the datastore.
void	close() Close this PersistenceManager so that no further requests may be made on it.
javax.jdo.Transaction	currentTransaction() Return the Transaction instance associated with a PersistenceManager.
void	deletePersistent(java.lang.Object pc) Delete the persistent instance from the data store.
void	deletePersistentAll(java.util.Collection pcs) Delete a Collection of instances from the data store.
void	deletePersistentAll(java.lang.Object[] pcs) Delete an array of instances from the data store.
java.lang.Object	detachCopy(java.lang.Object pc) JDO method to detach a persistent object.
java.util.Collection	detachCopyAll(java.util.Collection pcs) Detach the specified objects from the PersistenceManager.
java.lang.Object[]	detachCopyAll(java.lang.Object[] pcs) Detach the specified objects from the PersistenceManager .
void	evict(java.lang.Object pc) Mark an instance as no longer needed in the cache.
void	evictAll() Mark all persistent-nontransactional instances as no longer needed in the cache.
void	evictAll(java.util.Collection pcs) Mark a Collection of instances as no longer needed in the cache.
void	evictAll(java.lang.Object[] pcs) Mark an array of instances as no longer needed in the cache.
void	flush() This method flushes all dirty, new, and deleted instances to the datastore.
javax.jdo.datastore.JDOConnection	getDataStoreConnection() Accessor for a connection on the datastore.
boolean	getDetachAllOnCommit() Accessor for whether to detach all objects on commit of the transaction.
javax.jdo.Extent	getExtent(java.lang.Class pcClass) Extents are collections of datastore objects managed by the datastore, not by explicit user operations on collections.
javax.jdo.Extent	getExtent(java.lang.Class persistenceCapableClass, boolean subclasses) The PersistenceManager manages a collection of instances in the data store based on the class of the instances.
javax.jdo.FetchPlan	getFetchPlan() Acessor for the current FetchPlan
boolean	getIgnoreCache() Get the ignoreCache setting for queries.
boolean	getMultithreaded() Get the current Multithreaded flag for this PersistenceManager.
java.lang.Object	getObjectById(java.lang.Class cls, java.lang.Object key) Convenience method that exactly matches the behavior of calling pm.getObjectById (pm.newObjectIdInstance (cls, key), true) for SingleFieldIdentity.
java.lang.Object	getObjectById(java.lang.Object id) Accessor for an object given the object id.
java.lang.Object	getObjectById(java.lang.Object oid, boolean validate) This method locates a persistent instance in the cache of instances managed by this PersistenceManager.
java.lang.Object	getObjectId(java.lang.Object pc) The ObjectId returned by this method represents the JDO identity of the instance.
java.lang.Class	getObjectIdClass(java.lang.Class cls) Return the Class that implements the JDO Identity for the specified PersistenceCapable class.
java.util.Collection	getObjectsById(java.util.Collection oids) Accessor for the objects given the object ids, validating the objects.
java.util.Collection	getObjectsById(java.util.Collection oids, boolean validate) Accessor for the objects given the object ids.
java.lang.Object[]	getObjectsById(java.lang.Object[] oids) Accessor for the objects given the object ids, validating the objects.
java.lang.Object[]	getObjectsById(java.lang.Object[] oids, boolean validate) Accessor for the objects given the object ids.
javax.jdo.PersistenceManager	getPersistenceManager() Returns persistenceManager.
javax.jdo.PersistenceManagerFactory	getPersistenceManagerFactory() This method returns the PersistenceManagerFactory used to create this PersistenceManager.
javax.jdo.datastore.Sequence	getSequence(java.lang.String sequenceName) Method to retrieve a sequence by name.
java.lang.Object	getTransactionalObjectId(java.lang.Object pc) The ObjectId returned by this method represents the JDO identity of the instance.
java.lang.Object	getUserObject() The application can manage the PersistenceManager instances more easily by having an application object associated with each PersistenceManager instance.
java.lang.Object	getUserObject(java.lang.Object key) Method to get a user object from the PersistenceManager.
boolean	isClosed() A PersistenceManager instance can be used until it is closed.
void	makeNontransactional(java.lang.Object pc) Make an instance non-transactional after commit.
void	makeNontransactionalAll(java.util.Collection pcs) Make a Collection of instances non-transactional after commit.
void	makeNontransactionalAll(java.lang.Object[] pcs) Make an array of instances non-transactional after commit.
java.lang.Object	makePersistent(java.lang.Object pc) Make the transient instance persistent in this PersistenceManager.
java.util.Collection	makePersistentAll(java.util.Collection pcs) Make a Collection of instances persistent.
java.lang.Object[]	makePersistentAll(java.lang.Object[] pcs) Make an array of instances persistent.
void	makeTransactional(java.lang.Object pc) Make an instance subject to transactional boundaries.
void	makeTransactionalAll(java.util.Collection pcs) Make a Collection of instances subject to transactional boundaries.
void	makeTransactionalAll(java.lang.Object[] pcs) Make an array of instances subject to transactional boundaries.
void	makeTransient(java.lang.Object pc) Make an instance transient, removing it from management by this PersistenceManager.
void	makeTransientAll(java.util.Collection pcs) Make a Collection of instances transient, removing them from management by this PersistenceManager.
void	makeTransientAll(java.lang.Object[] pcs) Make an array of instances transient, removing them from management by this PersistenceManager.
java.lang.Object	newInstance(java.lang.Class interfaceClass) Method to generate an instance of an interface or abstract class.
javax.jdo.Query	newNamedQuery(java.lang.Class cls, java.lang.String queryName) Construct a query instance with the candidate class and the query name.
java.lang.Object	newObjectIdInstance(java.lang.Class pcClass, java.lang.Object key) This method returns an object id instance corresponding to the pcClass and key arguments.
java.lang.Object	newObjectIdInstance(java.lang.Class pcClass, java.lang.String str) This method returns an object id instance corresponding to the Class and String arguments.
javax.jdo.Query	newQuery() Create a new Query with no elements.
javax.jdo.Query	newQuery(java.lang.Class cls) Create a new Query specifying the Class of the candidate instances.
javax.jdo.Query	newQuery(java.lang.Class cls, java.util.Collection cln) Create a new Query with the candidate Class and Collection.
javax.jdo.Query	newQuery(java.lang.Class cls, java.util.Collection cln, java.lang.String filter) Create a new Query with the Class of the candidate instances, candidate Collection, and filter.
javax.jdo.Query	newQuery(java.lang.Class cls, java.lang.String filter) Create a new Query with the Class of the candidate instances and filter.
javax.jdo.Query	newQuery(javax.jdo.Extent cln) Create a new Query with the Class of the candidate instances and candidate Extent.
javax.jdo.Query	newQuery(javax.jdo.Extent cln, java.lang.String filter) Create a new Query with the candidate Extent and filter; the class is taken from the Extent.
javax.jdo.Query	newQuery(java.lang.Object compiled) Create a new Query using elements from another Query.
javax.jdo.Query	newQuery(java.lang.String query) Construct a query instance using the specified Single-String query.
javax.jdo.Query	newQuery(java.lang.String language, java.lang.Object query) Create a new Query using the specified language.
java.lang.Object	putUserObject(java.lang.Object key, java.lang.Object value) Method to put a user object into the PersistenceManager.
void	refresh(java.lang.Object pc) Refresh the state of the instance from the data store.
void	refreshAll() Refresh the state of all applicable instances from the data store.
void	refreshAll(java.util.Collection pcs) Refresh the state of a Collection of instances from the data store.
void	refreshAll(javax.jdo.JDOException exc) Method to do a refresh of objects that failed verification in the exception.
void	refreshAll(java.lang.Object[] pcs) Refresh the state of an array of instances from the data store.
void	removeInstanceLifecycleListener(javax.jdo.listener.InstanceLifecycleListener listener) Method to remove a currently registered lifecycle listener, as per JDO 2.0 spec 12.15.
java.lang.Object	removeUserObject(java.lang.Object key) Method to remove a user object from the PersistenceManager.
void	retrieve(java.lang.Object pc) Retrieve field values of an instance from the store.
void	retrieve(java.lang.Object pc, boolean fgOnly) Method to retrieve the fields of an object.
void	retrieveAll(java.util.Collection pcs) Retrieve field values of instances from the store.
void	retrieveAll(java.util.Collection pcs, boolean fgOnly) Retrieve field values of instances from the store.
void	retrieveAll(java.lang.Object[] pcs) Retrieve field values of instances from the store.
void	retrieveAll(java.lang.Object[] pcs, boolean fgOnly) Retrieve field values of instances from the store.
void	setDetachAllOnCommit(boolean flag) Mutator for whether to detach all objects on commit of the transaction.
void	setIgnoreCache(boolean flag) Set the ignoreCache parameter for queries.
void	setMultithreaded(boolean flag) Set the Multithreaded flag for this PersistenceManager.
void	setUserObject(java.lang.Object o) The application can manage the PersistenceManager instances more easily by having an application object associated with each PersistenceManager instance.

Methods inherited from class java.lang.Object

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

Field Detail

persistenceManager

private javax.jdo.PersistenceManager persistenceManager

The PersistenceManager instance that is decorated.

Constructor Detail

PersistenceManager2

protected PersistenceManager2(javax.jdo.PersistenceManager pm)

Create a new instance of the decorator using the specified PersistenceManager

Parameters:

pm - The object to decorate.

Method Detail

isClosed

public boolean isClosed()

A PersistenceManager instance can be used until it is closed.

Specified by:

isClosed in interface javax.jdo.PersistenceManager

Returns:

true if this PersistenceManager has been closed.

See Also:

close()

close

public void close()

Close this PersistenceManager so that no further requests may be made on it. A PersistenceManager instance can be used only until it is closed.

Closing a PersistenceManager might release it to the pool of available PersistenceManagers, or might be garbage collected, at the option of the JDO implementation. Before being used again to satisfy a getPersistenceManager() request, the default values for options will be restored to their values as specified in the PersistenceManagerFactory.

This method closes the PersistenceManager.

Note: Over-ridden to never close the decorated PersistenceManager. To close the persistence manager execute getPersistenceManager().close()

Specified by:

close in interface javax.jdo.PersistenceManager

currentTransaction

public javax.jdo.Transaction currentTransaction()

Return the Transaction instance associated with a PersistenceManager. There is one Transaction instance associated with each PersistenceManager instance. The Transaction instance supports options as well as transaction completion requests.

Specified by:

currentTransaction in interface javax.jdo.PersistenceManager

Returns:

the Transaction associated with this PersistenceManager.

evict

public void evict(java.lang.Object pc)

Mark an instance as no longer needed in the cache. Eviction is normally done automatically by the PersistenceManager at transaction completion. This method allows the application to explicitly provide a hint to the PersistenceManager that the instance is no longer needed in the cache.

Specified by:

evict in interface javax.jdo.PersistenceManager

Parameters:

pc - the instance to evict from the cache.

evictAll

public void evictAll(java.lang.Object[] pcs)

Mark an array of instances as no longer needed in the cache.

Specified by:

evictAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the array of instances to evict from the cache.

See Also:

evict(Object)

evictAll

public void evictAll(java.util.Collection pcs)

Mark a Collection of instances as no longer needed in the cache.

Specified by:

evictAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the Collection of instances to evict from the cache.

See Also:

evict(Object)

evictAll

public void evictAll()

Mark all persistent-nontransactional instances as no longer needed in the cache. It transitions all persistent-nontransactional instances to hollow. Transactional instances are subject to eviction based on the RetainValues setting.

Specified by:

evictAll in interface javax.jdo.PersistenceManager

See Also:

evict(Object)

refresh

public void refresh(java.lang.Object pc)

Refresh the state of the instance from the data store.

In an optimistic transaction, the state of instances in the cache might not match the state in the data store. This method is used to reload the state of the instance from the data store so that a subsequent commit is more likely to succeed.

Outside a transaction, this method will refresh nontransactional state.

Specified by:

refresh in interface javax.jdo.PersistenceManager

Parameters:

pc - the instance to refresh.

refreshAll

public void refreshAll(java.lang.Object[] pcs)

Refresh the state of an array of instances from the data store.

Specified by:

refreshAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the array of instances to refresh.

See Also:

refresh(Object)

refreshAll

public void refreshAll(java.util.Collection pcs)

Refresh the state of a Collection of instances from the data store.

Specified by:

refreshAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the Collection of instances to refresh.

See Also:

refresh(Object)

refreshAll

public void refreshAll()

Refresh the state of all applicable instances from the data store.

If called with an active transaction, all transactional instances will be refreshed. If called outside an active transaction, all nontransactional instances will be refreshed.

Specified by:

refreshAll in interface javax.jdo.PersistenceManager

See Also:

refresh(Object)

newQuery

public javax.jdo.Query newQuery()

Create a new Query with no elements.

Specified by:

newQuery in interface javax.jdo.PersistenceManager

Returns:

the new Query.

newQuery

public javax.jdo.Query newQuery(java.lang.Object compiled)

Create a new Query using elements from another Query. The other Query must have been created by the same JDO implementation. It might be active in a different PersistenceManager or might have been serialized and restored.

All of the settings of the other Query are copied to this Query, except for the candidate Collection or Extent.

Specified by:

newQuery in interface javax.jdo.PersistenceManager

Parameters:

compiled - Another Query from the same JDO implementation

Returns:

the new Query

newQuery

public javax.jdo.Query newQuery(java.lang.String language,
                                java.lang.Object query)

Create a new Query using the specified language.

Specified by:

newQuery in interface javax.jdo.PersistenceManager

Parameters:

language - the language of the query parameter

query - the query, which is of a form determined by the language

Returns:

the new Query

newQuery

public javax.jdo.Query newQuery(java.lang.Class cls)

Create a new Query specifying the Class of the candidate instances.

Specified by:

newQuery in interface javax.jdo.PersistenceManager

Parameters:

cls - the Class of the candidate instances

Returns:

the new Query

newQuery

public javax.jdo.Query newQuery(javax.jdo.Extent cln)

Create a new Query with the Class of the candidate instances and candidate Extent.

Specified by:

newQuery in interface javax.jdo.PersistenceManager

Parameters:

cln - the Extent of candidate instances

Returns:

the new Query

newQuery

public javax.jdo.Query newQuery(java.lang.Class cls,
                                java.util.Collection cln)

Create a new Query with the candidate Class and Collection.

Specified by:

newQuery in interface javax.jdo.PersistenceManager

Parameters:

cls - the Class of results

cln - the Collection of candidate instances

Returns:

the new Query

newQuery

public javax.jdo.Query newQuery(java.lang.Class cls,
                                java.lang.String filter)

Create a new Query with the Class of the candidate instances and filter.

Specified by:

newQuery in interface javax.jdo.PersistenceManager

Parameters:

cls - the Class of results

filter - the filter for candidate instances

Returns:

the new Query

newQuery

public javax.jdo.Query newQuery(java.lang.Class cls,
                                java.util.Collection cln,
                                java.lang.String filter)

Create a new Query with the Class of the candidate instances, candidate Collection, and filter.

Specified by:

newQuery in interface javax.jdo.PersistenceManager

Parameters:

cls - the Class of candidate instances

cln - the Collection of candidate instances

filter - the filter for candidate instances

Returns:

the new Query

newQuery

public javax.jdo.Query newQuery(javax.jdo.Extent cln,
                                java.lang.String filter)

Create a new Query with the candidate Extent and filter; the class is taken from the Extent.

Specified by:

newQuery in interface javax.jdo.PersistenceManager

Parameters:

cln - the Extent of candidate instances

filter - the filter for candidate instances

Returns:

the new Query

getExtent

public javax.jdo.Extent getExtent(java.lang.Class persistenceCapableClass,
                                  boolean subclasses)

The PersistenceManager manages a collection of instances in the data store based on the class of the instances. This method returns an Extent of instances in the data store that might be iterated or given to a Query. The Extent itself might not reference any instances, but only hold the class name and an indicator as to whether subclasses are included in the Extent.

Note that the Extent might be very large.

Specified by:

getExtent in interface javax.jdo.PersistenceManager

Parameters:

persistenceCapableClass - Class of instances

subclasses - whether to include instances of subclasses

Returns:

an Extent of the specified Class

getObjectById

public java.lang.Object getObjectById(java.lang.Object oid,
                                      boolean validate)

This method locates a persistent instance in the cache of instances managed by this PersistenceManager. The getObjectById method attempts to find an instance in the cache with the specified JDO identity. The oid parameter object might have been returned by an earlier call to getObjectId or getTransactionalObjectId, or might have been constructed by the application.

If the PersistenceManager is unable to resolve the oid parameter to an ObjectId instance, then it throws a JDOUserException.

If the validate flag is false, and there is already an instance in the cache with the same JDO identity as the oid parameter, then this method returns it. There is no change made to the state of the returned instance.

If there is not an instance already in the cache with the same JDO identity as the oid parameter, then this method creates an instance with the specified JDO identity and returns it. If there is no transaction in progress, the returned instance will be hollow or persistent-nontransactional, at the choice of the implementation.

If there is a transaction in progress, the returned instance will be hollow, persistent-nontransactional, or persistent-clean, at the choice of the implementation.

It is an implementation decision whether to access the data store, if required to determine the exact class. This will be the case of inheritance, where multiple PersistenceCapable classes share the same ObjectId class.

If the validate flag is false, and the instance does not exist in the data store, then this method might not fail. It is an implementation choice whether to fail immediately with a JDODataStoreException. But a subsequent access of the fields of the instance will throw a JDODataStoreException if the instance does not exist at that time. Further, if a relationship is established to this instance, then the transaction in which the association was made will fail.

If the validate flag is true, and there is already a transactional instance in the cache with the same JDO identity as the oid parameter, then this method returns it. There is no change made to the state of the returned instance.

If there is an instance already in the cache with the same JDO identity as the oid parameter, but the instance is not transactional, then it must be verified in the data store. If the instance does not exist in the datastore, then a JDODataStoreException is thrown.

If there is not an instance already in the cache with the same JDO identity as the oid parameter, then this method creates an instance with the specified JDO identity, verifies that it exists in the data store, and returns it. If there is no transaction in progress, the returned instance will be hollow or persistent-nontransactional, at the choice of the implementation.

If there is a data store transaction in progress, the returned instance will be persistent-clean. If there is an optimistic transaction in progress, the returned instance will be persistent-nontransactional.

Specified by:

getObjectById in interface javax.jdo.PersistenceManager

Parameters:

oid - an ObjectId

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

Returns:

the PersistenceCapable instance with the specified ObjectId

See Also:

getObjectId(Object pc), getTransactionalObjectId(Object pc)

getObjectId

public java.lang.Object getObjectId(java.lang.Object pc)

The ObjectId returned by this method represents the JDO identity of the instance. The ObjectId is a copy (clone) of the internal state of the instance, and changing it does not affect the JDO identity of the instance.

The getObjectId method returns an ObjectId instance that represents the object identity of the specified JDO instance. The identity is guaranteed to be unique only in the context of the JDO PersistenceManager that created the identity, and only for two types of JDO Identity: those that are managed by the application, and those that are managed by the data store.

If the object identity is being changed in the transaction, by the application modifying one or more of the application key fields, then this method returns the identity as of the beginning of the transaction. The value returned by getObjectId will be different following afterCompletion processing for successful transactions.

Within a transaction, the ObjectId returned will compare equal to the ObjectId returned by only one among all JDO instances associated with the PersistenceManager regardless of the type of ObjectId.

The ObjectId does not necessarily contain any internal state of the instance, nor is it necessarily an instance of the class used to manage identity internally. Therefore, if the application makes a change to the ObjectId instance returned by this method, there is no effect on the instance from which the ObjectId was obtained.

The getObjectById method can be used between instances of PersistenceManager of different JDO vendors only for instances of persistence capable classes using application-managed (primary key) JDO identity. If it is used for instances of classes using datastore identity, the method might succeed, but there are no guarantees that the parameter and return instances are related in any way.

Specified by:

getObjectId in interface javax.jdo.PersistenceManager

Parameters:

pc - the PersistenceCapable instance

Returns:

the ObjectId of the instance

See Also:

getTransactionalObjectId(Object pc), getObjectById(Object oid, boolean validate)

getTransactionalObjectId

public java.lang.Object getTransactionalObjectId(java.lang.Object pc)

The ObjectId returned by this method represents the JDO identity of the instance. The ObjectId is a copy (clone) of the internal state of the instance, and changing it does not affect the JDO identity of the instance.

If the object identity is being changed in the transaction, by the application modifying one or more of the application key fields, then this method returns the current identity in the transaction.

If there is no transaction in progress, or if none of the key fields is being modified, then this method will return the same value as getObjectId(java.lang.Object).

Specified by:

getTransactionalObjectId in interface javax.jdo.PersistenceManager

Parameters:

pc - a PersistenceCapable instance

Returns:

the ObjectId of the instance

See Also:

getObjectId(Object pc), getObjectById(Object oid, boolean validate)

newObjectIdInstance

public java.lang.Object newObjectIdInstance(java.lang.Class pcClass,
                                            java.lang.String str)

This method returns an object id instance corresponding to the Class and String arguments. The String argument might have been the result of executing toString on an object id instance.

Parameters:

pcClass - the Class of the persistence-capable instance

str - the String form of the object id

Returns:

an instance of the object identity class

makePersistent

public java.lang.Object makePersistent(java.lang.Object pc)

Make the transient instance persistent in this PersistenceManager. This method must be called in an active transaction. The PersistenceManager assigns an ObjectId to the instance and transitions it to persistent-new. The instance will be managed in the Extent associated with its Class. The instance will be put into the data store at commit. The closure of instances of PersistenceCapable classes reachable from persistent fields will be made persistent at commit. [This is known as persistence by reachability.]

Specified by:

makePersistent in interface javax.jdo.PersistenceManager

Parameters:

pc - a transient instance of a Class that implements PersistenceCapable

makePersistentAll

public java.lang.Object[] makePersistentAll(java.lang.Object[] pcs)

Make an array of instances persistent.

Specified by:

makePersistentAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - an array of transient instances

See Also:

makePersistent(Object)

makePersistentAll

public java.util.Collection makePersistentAll(java.util.Collection pcs)

Make a Collection of instances persistent.

Specified by:

makePersistentAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - a Collection of transient instances

See Also:

makePersistent(Object)

deletePersistent

public void deletePersistent(java.lang.Object pc)

Delete the persistent instance from the data store. This method must be called in an active transaction. The data store object will be removed at commit. Unlike makePersistent, which makes the closure of the instance persistent, the closure of the instance is not deleted from the data store. This method has no effect if the instance is already deleted in the current transaction. This method throws JDOUserException if the instance is transient or is managed by another PersistenceManager.

Specified by:

deletePersistent in interface javax.jdo.PersistenceManager

Parameters:

pc - a persistent instance

deletePersistentAll

public void deletePersistentAll(java.lang.Object[] pcs)

Delete an array of instances from the data store.

Specified by:

deletePersistentAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - a Collection of persistent instances

See Also:

deletePersistent(Object)

deletePersistentAll

public void deletePersistentAll(java.util.Collection pcs)

Delete a Collection of instances from the data store.

Specified by:

deletePersistentAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - a Collection of persistent instances

See Also:

deletePersistent(Object)

makeTransient

public void makeTransient(java.lang.Object pc)

Make an instance transient, removing it from management by this PersistenceManager.

The instance loses its JDO identity and it is no longer associated with any PersistenceManager. The state of fields is preserved unchanged.

Specified by:

makeTransient in interface javax.jdo.PersistenceManager

Parameters:

pc - the instance to make transient.

makeTransientAll

public void makeTransientAll(java.lang.Object[] pcs)

Make an array of instances transient, removing them from management by this PersistenceManager.

The instances lose their JDO identity and they are no longer associated with any PersistenceManager. The state of fields is preserved unchanged.

Specified by:

makeTransientAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the instances to make transient.

makeTransientAll

public void makeTransientAll(java.util.Collection pcs)

Make a Collection of instances transient, removing them from management by this PersistenceManager.

The instances lose their JDO identity and they are no longer associated with any PersistenceManager. The state of fields is preserved unchanged.

Specified by:

makeTransientAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the instances to make transient.

makeTransactional

public void makeTransactional(java.lang.Object pc)

Make an instance subject to transactional boundaries.

Transient instances normally do not observe transaction boundaries. This method makes transient instances sensitive to transaction completion. If an instance is modified in a transaction, and the transaction rolls back, the state of the instance is restored to the state before the first change in the transaction.

For persistent instances read in optimistic transactions, this method allows the application to make the state of the instance part of the transactional state. At transaction commit, the state of the instance in the cache is compared to the state of the instance in the data store. If they are not the same, then an exception is thrown.

Specified by:

makeTransactional in interface javax.jdo.PersistenceManager

Parameters:

pc - the instance to make transactional.

makeTransactionalAll

public void makeTransactionalAll(java.lang.Object[] pcs)

Make an array of instances subject to transactional boundaries.

Specified by:

makeTransactionalAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the array of instances to make transactional.

See Also:

makeTransactional(Object)

makeTransactionalAll

public void makeTransactionalAll(java.util.Collection pcs)

Make a Collection of instances subject to transactional boundaries.

Specified by:

makeTransactionalAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the Collection of instances to make transactional.

See Also:

makeTransactional(Object)

makeNontransactional

public void makeNontransactional(java.lang.Object pc)

Make an instance non-transactional after commit.

Normally, at transaction completion, instances are evicted from the cache. This method allows an application to identify an instance as not being evicted from the cache at transaction completion. Instead, the instance remains in the cache with nontransactional state.

Specified by:

makeNontransactional in interface javax.jdo.PersistenceManager

Parameters:

pc - the instance to make nontransactional.

makeNontransactionalAll

public void makeNontransactionalAll(java.lang.Object[] pcs)

Make an array of instances non-transactional after commit.

Specified by:

makeNontransactionalAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the array of instances to make nontransactional.

See Also:

makeNontransactional(Object)

makeNontransactionalAll

public void makeNontransactionalAll(java.util.Collection pcs)

Make a Collection of instances non-transactional after commit.

Specified by:

makeNontransactionalAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the Collection of instances to make nontransactional.

See Also:

makeNontransactional(Object)

retrieve

public void retrieve(java.lang.Object pc)

Retrieve field values of an instance from the store. This tells the PersistenceManager that the application intends to use the instance, and its field values must be retrieved.

The PersistenceManager might use policy information about the class to retrieve associated instances.

Specified by:

retrieve in interface javax.jdo.PersistenceManager

Parameters:

pc - the instance

retrieveAll

public void retrieveAll(java.util.Collection pcs)

Retrieve field values of instances from the store. This tells the PersistenceManager that the application intends to use the instances, and all field values must be retrieved.

The PersistenceManager might use policy information about the class to retrieve associated instances.

Specified by:

retrieveAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the instances

retrieveAll

public void retrieveAll(java.lang.Object[] pcs)

Retrieve field values of instances from the store. This tells the PersistenceManager that the application intends to use the instances, and all field values must be retrieved.

The PersistenceManager might use policy information about the class to retrieve associated instances.

Specified by:

retrieveAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the instances

setUserObject

public void setUserObject(java.lang.Object o)

The application can manage the PersistenceManager instances more easily by having an application object associated with each PersistenceManager instance.

Specified by:

setUserObject in interface javax.jdo.PersistenceManager

Parameters:

o - the user instance to be remembered by the PersistenceManager

See Also:

getUserObject()

getUserObject

public java.lang.Object getUserObject()

The application can manage the PersistenceManager instances more easily by having an application object associated with each PersistenceManager instance.

Specified by:

getUserObject in interface javax.jdo.PersistenceManager

Returns:

the user object associated with this PersistenceManager

See Also:

setUserObject(java.lang.Object)

getPersistenceManagerFactory

public javax.jdo.PersistenceManagerFactory getPersistenceManagerFactory()

This method returns the PersistenceManagerFactory used to create this PersistenceManager.

Specified by:

getPersistenceManagerFactory in interface javax.jdo.PersistenceManager

Returns:

the PersistenceManagerFactory that created this PersistenceManager

getObjectIdClass

public java.lang.Class getObjectIdClass(java.lang.Class cls)

Return the Class that implements the JDO Identity for the specified PersistenceCapable class. The application can use the returned Class to construct a JDO Identity instance for application identity PersistenceCapable classes. This JDO Identity instance can then be used to get an instance of the PersistenceCapable class for use in the application.

In order for the application to construct an instance of the ObjectId class it needs to know the class being used by the JDO implementation.

Specified by:

getObjectIdClass in interface javax.jdo.PersistenceManager

Parameters:

cls - the PersistenceCapable Class

Returns:

the Class of the ObjectId of the parameter

See Also:

getObjectById(java.lang.Object, boolean)

setMultithreaded

public void setMultithreaded(boolean flag)

Set the Multithreaded flag for this PersistenceManager. Applications that use multiple threads to invoke methods or access fields from instances managed by this PersistenceManager must set this flag to true. Instances managed by this PersistenceManager include persistent or transactional instances of PersistenceCapable classes, as well as helper instances such as Query, Transaction, or Extent.

Specified by:

setMultithreaded in interface javax.jdo.PersistenceManager

Parameters:

flag - the Multithreaded setting.

getMultithreaded

public boolean getMultithreaded()

Get the current Multithreaded flag for this PersistenceManager.

Specified by:

getMultithreaded in interface javax.jdo.PersistenceManager

Returns:

the Multithreaded setting.

See Also:

setMultithreaded(boolean)

setIgnoreCache

public void setIgnoreCache(boolean flag)

Set the ignoreCache parameter for queries.

IgnoreCache set to true specifies that for all Query instances created by this PersistenceManager, the default is the cache should be ignored for queries.

Specified by:

setIgnoreCache in interface javax.jdo.PersistenceManager

Parameters:

flag - the ignoreCache setting.

getIgnoreCache

public boolean getIgnoreCache()

Get the ignoreCache setting for queries.

IgnoreCache set to true specifies that for all Query instances created by this PersistenceManager, the default is the cache should be ignored for queries.

Specified by:

getIgnoreCache in interface javax.jdo.PersistenceManager

Returns:

the ignoreCache setting.

getPersistenceManager

public final javax.jdo.PersistenceManager getPersistenceManager()

Returns persistenceManager. This may be used to force close the PersistenceManager instance this class decorates.

Returns:

PersistenceManager The value/reference of/to persistenceManager.

addInstanceLifecycleListener

public void addInstanceLifecycleListener(javax.jdo.listener.InstanceLifecycleListener listener,
                                         java.lang.Class[] classes)

Method to register a lifecycle listener as per JDO 2.0 spec 12.15.

Specified by:

addInstanceLifecycleListener in interface javax.jdo.PersistenceManager

Parameters:

listener - The instance lifecycle listener to sends events to

classes - The classes that it is interested in

removeInstanceLifecycleListener

public void removeInstanceLifecycleListener(javax.jdo.listener.InstanceLifecycleListener listener)

Method to remove a currently registered lifecycle listener, as per JDO 2.0 spec 12.15.

Specified by:

removeInstanceLifecycleListener in interface javax.jdo.PersistenceManager

Parameters:

listener - The instance lifecycle listener to remove.

getDataStoreConnection

public javax.jdo.datastore.JDOConnection getDataStoreConnection()

Accessor for a connection on the datastore. See JDO 2.0 spec section 12.16

Specified by:

getDataStoreConnection in interface javax.jdo.PersistenceManager

Returns:

The JDO connection to the datastore

getSequence

public javax.jdo.datastore.Sequence getSequence(java.lang.String sequenceName)

Method to retrieve a sequence by name. As per JDO2 spec section 12.14 If the named sequence is not known, throws a JDOUserException.

Specified by:

getSequence in interface javax.jdo.PersistenceManager

Parameters:

sequenceName - Fully qualified name of the sequence

Returns:

The sequence

newInstance

public java.lang.Object newInstance(java.lang.Class interfaceClass)

Method to generate an instance of an interface or abstract class.

Specified by:

newInstance in interface javax.jdo.PersistenceManager

Parameters:

interfaceClass - The class of the interface or abstract class defined in MetaData

Returns:

The instance

getFetchPlan

public javax.jdo.FetchPlan getFetchPlan()

Acessor for the current FetchPlan

Specified by:

getFetchPlan in interface javax.jdo.PersistenceManager

Returns:

FetchPlan

checkConsistency

public void checkConsistency()

This method validates the cache with the datastore. It has no effect if a transaction is not active. If a datastore transaction is active, this method verifies the consistency of instances in the cache against the datastore. An implementation might flush instances as if flush() were called, but it is not required to do so. If an optimistic transaction is active, this method obtains a datastore connection and verifies the consistency of the instances in the cache against the datastore. If any inconsistencies are detected, a JDOOptimisticVerificationException is thrown. This exception contains a nested JDOOptimisticVerificationException for each object that failed the consistency check. No datastore resources acquired during the execution of this method are held beyond the scope of this method.

Specified by:

checkConsistency in interface javax.jdo.PersistenceManager

flush

public void flush()

This method flushes all dirty, new, and deleted instances to the datastore. It has no effect if a transaction is not active. If a datastore transaction is active, this method synchronizes the cache with the datastore and reports any exceptions. If an optimistic transaction is active, this method obtains a datastore connection and synchronizes the cache with the datastore using this connection. The connection obtained by this method is held until the end of the transaction.

Specified by:

flush in interface javax.jdo.PersistenceManager

getUserObject

public java.lang.Object getUserObject(java.lang.Object key)

Method to get a user object from the PersistenceManager. This is for user objects which are stored under a key. The parameter is not inspected or used in any way by the JDO implementation.

Specified by:

getUserObject in interface javax.jdo.PersistenceManager

Parameters:

key - The key to store the user object under

Returns:

The user object for that key

putUserObject

public java.lang.Object putUserObject(java.lang.Object key,
                                      java.lang.Object value)

Method to put a user object into the PersistenceManager. This is so that multiple users can each have a user object for example. The parameter is not inspected or used in any way by the JDO implementation.

Specified by:

putUserObject in interface javax.jdo.PersistenceManager

Parameters:

key - The key to store the user object under

value - The object to store

Returns:

The previous value for this key

removeUserObject

public java.lang.Object removeUserObject(java.lang.Object key)

Method to remove a user object from the PersistenceManager. This is for user objects which are stored under a key. The parameter is not inspected or used in any way by the JDO implementation.

Specified by:

removeUserObject in interface javax.jdo.PersistenceManager

Parameters:

key - The key whose uder object is to be removed.

Returns:

The user object that was removed

detachCopy

public java.lang.Object detachCopy(java.lang.Object pc)

JDO method to detach a persistent object. If the object is of class that is not detachable a ClassNotDetachableException will be thrown. If the object is not persistent a JDOUserException is thrown.

Specified by:

detachCopy in interface javax.jdo.PersistenceManager

Parameters:

pc - The object

Returns:

The detached object

detachCopyAll

public java.lang.Object[] detachCopyAll(java.lang.Object[] pcs)

Detach the specified objects from the PersistenceManager . The objects returned can be manipulated and re-attached with makePersistentAll( Object[] ). The detached instances will be unmanaged copies of the specified parameters, and are suitable for serialization and manipulation outside of a JDO environment. When detaching instances, only fields in the current FetchPlan 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 FetchPlan.

Specified by:

detachCopyAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the instances to detach

Returns:

the detached instances

Throws:

JDOUserException - if any of the instances do not

ClassNotDetachableException - If any of the objects are of a class that is not detachable

detachCopyAll

public java.util.Collection detachCopyAll(java.util.Collection pcs)

Detach the specified objects from the PersistenceManager.

Specified by:

detachCopyAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the instances to detach

Returns:

the detached instances

See Also:

detachCopyAll( Object[] )

getDetachAllOnCommit

public boolean getDetachAllOnCommit()

Accessor for whether to detach all objects on commit of the transaction.

Specified by:

getDetachAllOnCommit in interface javax.jdo.PersistenceManager

Returns:

Whether to detach all on commit.

setDetachAllOnCommit

public void setDetachAllOnCommit(boolean flag)

Mutator for whether to detach all objects on commit of the transaction.

Specified by:

setDetachAllOnCommit in interface javax.jdo.PersistenceManager

Parameters:

flag - Whether to detach all on commit.

retrieve

public void retrieve(java.lang.Object pc,
                     boolean fgOnly)

Method to retrieve the fields of an object.

Specified by:

retrieve in interface javax.jdo.PersistenceManager

Parameters:

pc - The object

fgOnly - Whether to retrieve the current fetch group fields only

retrieveAll

public void retrieveAll(java.lang.Object[] pcs,
                        boolean fgOnly)

Retrieve field values of instances from the store. This tells the PersistenceManager that the application intends to use the instances, and their field values should be retrieved. The fields in the current fetch group must be retrieved, and the implementation might retrieve more fields than the current fetch group.

The PersistenceManager might use policy information about the class to retrieve associated instances.

Specified by:

retrieveAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the instances

fgOnly - whether to retrieve only the current fetch group fields

retrieveAll

public void retrieveAll(java.util.Collection pcs,
                        boolean fgOnly)

Retrieve field values of instances from the store. This tells the PersistenceManager that the application intends to use the instances, and their field values should be retrieved. The fields in the current fetch group must be retrieved, and the implementation might retrieve more fields than the current fetch group.

The PersistenceManager might use policy information about the class to retrieve associated instances.

Specified by:

retrieveAll in interface javax.jdo.PersistenceManager

Parameters:

pcs - the instances

fgOnly - whether to retrieve only the current fetch-group fields

getObjectsById

public java.util.Collection getObjectsById(java.util.Collection oids)

Accessor for the objects given the object ids, validating the objects.

Specified by:

getObjectsById in interface javax.jdo.PersistenceManager

Parameters:

oids - Ids of the objects.

Returns:

The Objects with these ids (in the same order)

getObjectsById

public java.lang.Object[] getObjectsById(java.lang.Object[] oids)

Accessor for the objects given the object ids, validating the objects.

Specified by:

getObjectsById in interface javax.jdo.PersistenceManager

Parameters:

oids - Ids of the objects.

Returns:

The Objects with these ids (in the same order)

getObjectsById

public java.util.Collection getObjectsById(java.util.Collection oids,
                                           boolean validate)

Accessor for the objects given the object ids.

Specified by:

getObjectsById in interface javax.jdo.PersistenceManager

Parameters:

oids - Ids of the objects.

validate - Whether to validate the object state

Returns:

The Objects with these ids (in the same order)

getObjectsById

public java.lang.Object[] getObjectsById(java.lang.Object[] oids,
                                         boolean validate)

Accessor for the objects given the object ids.

Specified by:

getObjectsById in interface javax.jdo.PersistenceManager

Parameters:

oids - Ids of the objects.

validate - Whether to validate the object state

Returns:

The Objects with these ids (in the same order)

newObjectIdInstance

public java.lang.Object newObjectIdInstance(java.lang.Class pcClass,
                                            java.lang.Object key)

This method returns an object id instance corresponding to the pcClass and key arguments. A String argument might have been the result of executing toString on an object id instance. The key argument is the value of the key field for single field identity. This method is portable for datastore identity and application identity.

Specified by:

newObjectIdInstance in interface javax.jdo.PersistenceManager

Parameters:

pcClass - Class of the PersistenceCapable to create the OID for.

key - Value of the key for SingleFieldIdentity

Returns:

The new object-id instance

getObjectById

public java.lang.Object getObjectById(java.lang.Object id)

Accessor for an object given the object id.

Specified by:

getObjectById in interface javax.jdo.PersistenceManager

Parameters:

id - Id of the object.

Returns:

The Object

getObjectById

public java.lang.Object getObjectById(java.lang.Class cls,
                                      java.lang.Object key)

Convenience method that exactly matches the behavior of calling pm.getObjectById (pm.newObjectIdInstance (cls, key), true) for SingleFieldIdentity.

Specified by:

getObjectById in interface javax.jdo.PersistenceManager

Parameters:

cls - Class of the PersistenceCapable

key - Value of the key field for SingleFieldIdentity

Returns:

The object for this id.

getExtent

public javax.jdo.Extent getExtent(java.lang.Class pcClass)

Extents are collections of datastore objects managed by the datastore, not by explicit user operations on collections. Extent capability is a boolean property of classes that are persistence capable. If an instance of a class that has a managed extent is made persistent via reachability, the instance is put into the extent implicitly.

Specified by:

getExtent in interface javax.jdo.PersistenceManager

Parameters:

pcClass - The class to query

Returns:

returns an Extent that contains all of the instances in the parameter class, and all of the instances of the parameter class and its subclasses.

newNamedQuery

public javax.jdo.Query newNamedQuery(java.lang.Class cls,
                                     java.lang.String queryName)

Construct a query instance with the candidate class and the query name.

Specified by:

newNamedQuery in interface javax.jdo.PersistenceManager

Parameters:

cls - The class to query

queryName - Name of the query.

Returns:

The query

newQuery

public javax.jdo.Query newQuery(java.lang.String query)

Construct a query instance using the specified Single-String query.

Specified by:

newQuery in interface javax.jdo.PersistenceManager

Parameters:

query - The single-string query

Returns:

The Query

refreshAll

public void refreshAll(javax.jdo.JDOException exc)

Method to do a refresh of objects that failed verification in the exception.

Specified by:

refreshAll in interface javax.jdo.PersistenceManager

Parameters:

exc - The JDO exception containing the objects that failed