|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
PersistenceManager
is the primary interface for JDO-aware application
components. It is the factory for Query
and Transaction
instances,
and contains methods to manage the life cycle of PersistenceCapable
instances.
A PersistenceManager
is obtained from the
PersistenceManagerFactory
(recommended) or by construction.
Method Summary | |
void |
close()
Close this PersistenceManager so that no further requests may be
made on it. |
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. |
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. |
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. |
boolean |
getIgnoreCache()
Get the ignoreCache setting for queries. |
boolean |
getMultithreaded()
Get the current Multithreaded flag for this PersistenceManager . |
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. |
PersistenceManagerFactory |
getPersistenceManagerFactory()
This method returns the PersistenceManagerFactory used to create
this PersistenceManager . |
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. |
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. |
void |
makePersistent(java.lang.Object pc)
Make the transient instance persistent in this PersistenceManager . |
void |
makePersistentAll(java.util.Collection pcs)
Make a Collection of instances persistent. |
void |
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 |
newObjectIdInstance(java.lang.Class pcClass,
java.lang.String str)
This method returns an object id instance corresponding to the Class
and String arguments. |
Query |
newQuery()
Create a new Query with no elements. |
Query |
newQuery(java.lang.Class cls)
Create a new Query specifying the Class of the candidate instances. |
Query |
newQuery(java.lang.Class cls,
java.util.Collection cln)
Create a new Query with the candidate Class
and Collection . |
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. |
Query |
newQuery(java.lang.Class cls,
java.lang.String filter)
Create a new Query with the Class of the
candidate instances and filter. |
Query |
newQuery(Extent cln)
Create a new Query with the Class of the
candidate instances and candidate Extent . |
Query |
newQuery(Extent cln,
java.lang.String filter)
Create a new Query with the
candidate Extent and filter; the class
is taken from the Extent . |
Query |
newQuery(java.lang.Object compiled)
Create a new Query using elements from another Query . |
Query |
newQuery(java.lang.String language,
java.lang.Object query)
Create a new Query using the specified language. |
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(java.lang.Object[] pcs)
Refresh the state of an array of instances from the data store. |
void |
retrieve(java.lang.Object pc)
Retrieve field values of an instance from the store. |
void |
retrieveAll(java.util.Collection pcs)
Retrieve field values of instances from the store. |
void |
retrieveAll(java.util.Collection pcs,
boolean DFGOnly)
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 DFGOnly)
Retrieve field values of instances from the store. |
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. |
Method Detail |
public boolean isClosed()
PersistenceManager
instance can be used until it is closed.true
if this PersistenceManager
has been closed.close()
public void close()
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
PersistenceManager
s, 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
.
public Transaction currentTransaction()
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.Transaction
associated with this
PersistenceManager
.public void evict(java.lang.Object pc)
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.pc
- the instance to evict from the cache.public void evictAll(java.lang.Object[] pcs)
pcs
- the array of instances to evict from the cache.evict(Object pc)
public void evictAll(java.util.Collection pcs)
Collection
of instances as no longer needed in the cache.pcs
- the Collection
of instances to evict from the cache.evict(Object pc)
public void evictAll()
evict(Object pc)
public void refresh(java.lang.Object pc)
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.
pc
- the instance to refresh.public void refreshAll(java.lang.Object[] pcs)
pcs
- the array of instances to refresh.refresh(Object pc)
public void refreshAll(java.util.Collection pcs)
Collection
of instances from the data store.pcs
- the Collection
of instances to refresh.refresh(Object pc)
public void refreshAll()
If called with an active transaction, all transactional instances will be refreshed. If called outside an active transaction, all nontransactional instances will be refreshed.
refresh(Object pc)
public Query newQuery()
Query
with no elements.Query
.public Query newQuery(java.lang.Object compiled)
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
.
compiled
- another Query
from the same JDO implementationQuery
public Query newQuery(java.lang.String language, java.lang.Object query)
Query
using the specified language.language
- the language of the query parameterquery
- the query, which is of a form determined by the languageQuery
public Query newQuery(java.lang.Class cls)
Query
specifying the Class
of the candidate instances.cls
- the Class
of the candidate instancesQuery
public Query newQuery(Extent cln)
Query
with the Class
of the
candidate instances and candidate Extent
.cln
- the Extent
of candidate instancesQuery
public Query newQuery(java.lang.Class cls, java.util.Collection cln)
Query
with the candidate Class
and Collection
.cls
- the Class
of resultscln
- the Collection
of candidate instancesQuery
public Query newQuery(java.lang.Class cls, java.lang.String filter)
Query
with the Class
of the
candidate instances and filter.cls
- the Class
of resultsfilter
- the filter for candidate instancesQuery
public Query newQuery(java.lang.Class cls, java.util.Collection cln, java.lang.String filter)
Query
with the Class
of the candidate instances,
candidate Collection
, and filter.cls
- the Class
of candidate instancescln
- the Collection
of candidate instancesfilter
- the filter for candidate instancesQuery
public Query newQuery(Extent cln, java.lang.String filter)
Query
with the
candidate Extent
and filter; the class
is taken from the Extent
.cln
- the Extent
of candidate instancesfilter
- the filter for candidate instancesQuery
public Extent getExtent(java.lang.Class persistenceCapableClass, boolean subclasses)
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.
persistenceCapableClass
- Class
of instancessubclasses
- whether to include instances of subclassesExtent
of the specified Class
Query
public java.lang.Object getObjectById(java.lang.Object oid, boolean validate)
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.
oid
- an ObjectIdvalidate
- if the existence of the instance is to be validatedPersistenceCapable
instance with the specified ObjectIdgetObjectId(Object pc)
,
getTransactionalObjectId(Object pc)
public java.lang.Object getObjectId(java.lang.Object pc)
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.
pc
- the PersistenceCapable
instancegetTransactionalObjectId(Object pc)
,
getObjectById(Object oid, boolean validate)
public java.lang.Object getTransactionalObjectId(java.lang.Object pc)
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
.
pc
- a PersistenceCapable
instancegetObjectId(Object pc)
,
getObjectById(Object oid, boolean validate)
public java.lang.Object newObjectIdInstance(java.lang.Class pcClass, java.lang.String str)
Class
and String
arguments. The String
argument might have been the
result of executing toString
on an object id instance.pcClass
- the Class
of the persistence-capable instancestr
- the String
form of the object idpublic void makePersistent(java.lang.Object pc)
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.]pc
- a transient instance of a Class
that implements
PersistenceCapable
public void makePersistentAll(java.lang.Object[] pcs)
pcs
- an array of transient instancesmakePersistent(Object pc)
public void makePersistentAll(java.util.Collection pcs)
Collection
of instances persistent.pcs
- a Collection
of transient instancesmakePersistent(Object pc)
public void deletePersistent(java.lang.Object pc)
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
.pc
- a persistent instancepublic void deletePersistentAll(java.lang.Object[] pcs)
pcs
- a Collection
of persistent instancesdeletePersistent(Object pc)
public void deletePersistentAll(java.util.Collection pcs)
Collection
of instances from the data store.pcs
- a Collection
of persistent instancesdeletePersistent(Object pc)
public void makeTransient(java.lang.Object pc)
PersistenceManager
.
The instance loses its JDO identity and it is no longer associated
with any PersistenceManager
. The state of fields is preserved unchanged.
pc
- the instance to make transient.public void makeTransientAll(java.lang.Object[] pcs)
PersistenceManager
.
The instances lose their JDO identity and they are no longer associated
with any PersistenceManager
. The state of fields is preserved unchanged.
pcs
- the instances to make transient.public void makeTransientAll(java.util.Collection pcs)
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.
pcs
- the instances to make transient.public void makeTransactional(java.lang.Object pc)
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.
pc
- the instance to make transactional.public void makeTransactionalAll(java.lang.Object[] pcs)
pcs
- the array of instances to make transactional.makeTransactional(Object pc)
public void makeTransactionalAll(java.util.Collection pcs)
Collection
of instances subject to transactional boundaries.pcs
- the Collection
of instances to make transactional.makeTransactional(Object pc)
public void makeNontransactional(java.lang.Object pc)
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.
pc
- the instance to make nontransactional.public void makeNontransactionalAll(java.lang.Object[] pcs)
pcs
- the array of instances to make nontransactional.makeNontransactional(Object pc)
public void makeNontransactionalAll(java.util.Collection pcs)
Collection
of instances non-transactional after commit.pcs
- the Collection
of instances to make nontransactional.makeNontransactional(Object pc)
public void retrieve(java.lang.Object pc)
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.
pc
- the instancepublic void retrieveAll(java.util.Collection pcs)
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.
pcs
- the instancespublic void retrieveAll(java.util.Collection pcs, boolean DFGOnly)
PersistenceManager
that the application intends to use the
instances, and their field values should be retrieved. The fields
in the default fetch group must be retrieved, and the implementation
might retrieve more fields than the default fetch group.
The PersistenceManager
might use policy information about the
class to retrieve associated instances.
pcs
- the instancesDFGOnly
- whether to retrieve only the default fetch group fieldspublic void retrieveAll(java.lang.Object[] pcs)
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.
pcs
- the instancespublic void retrieveAll(java.lang.Object[] pcs, boolean DFGOnly)
PersistenceManager
that the application intends to use the
instances, and their field values should be retrieved. The fields
in the default fetch group must be retrieved, and the implementation
might retrieve more fields than the default fetch group.
The PersistenceManager
might use policy information about the
class to retrieve associated instances.
pcs
- the instancesDFGOnly
- whether to retrieve only the default fetch group fieldspublic void setUserObject(java.lang.Object o)
PersistenceManager
instances
more easily by having an application object associated with each
PersistenceManager
instance.o
- the user instance to be remembered by the PersistenceManager
getUserObject()
public java.lang.Object getUserObject()
PersistenceManager
instances
more easily by having an application object associated with each
PersistenceManager
instance.PersistenceManager
setUserObject(java.lang.Object)
public PersistenceManagerFactory getPersistenceManagerFactory()
PersistenceManagerFactory
used to create
this PersistenceManager
.PersistenceManagerFactory
that created
this PersistenceManager
public java.lang.Class getObjectIdClass(java.lang.Class cls)
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.
cls
- the PersistenceCapable Class
Class
of the ObjectId of the parametergetObjectById(java.lang.Object, boolean)
public void setMultithreaded(boolean flag)
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
.flag
- the Multithreaded setting.public boolean getMultithreaded()
PersistenceManager
.setMultithreaded(boolean)
public void setIgnoreCache(boolean flag)
IgnoreCache set to true
specifies that for all Query
instances created by this
PersistenceManager
, the default is the cache should be ignored for queries.
flag
- the ignoreCache setting.public boolean getIgnoreCache()
IgnoreCache set to true
specifies that for all Query
instances created by this
PersistenceManager
, the default is the cache should be ignored for queries.
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |