|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface PersistenceManager
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 |
addInstanceLifecycleListener(InstanceLifecycleListener listener,
java.lang.Class... classes)
Adds the listener instance to the list of lifecycle event listeners. |
|
void |
checkConsistency()
Validates the PersistenceManager cache with the
datastore. |
|
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. |
|
|
detachCopy(T pc)
Detach the specified instance from the PersistenceManager . |
|
|
detachCopyAll(java.util.Collection<T> pcs)
Detach the specified instances from the PersistenceManager . |
|
|
detachCopyAll(T... pcs)
Detach the specified instances 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(boolean subclasses,
java.lang.Class pcClass)
Mark the parameter 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()
Flushes all dirty, new, and deleted instances to the data store. |
|
boolean |
getCopyOnAttach()
Gets the copyOnAttach setting. |
|
JDOConnection |
getDataStoreConnection()
If this method is called while a datastore transaction is active, the object returned will be enlisted in the current transaction. |
|
java.lang.Integer |
getDatastoreReadTimeoutMillis()
Get the effective timeout setting for datastore read operations associated with this persistence manager. |
|
java.lang.Integer |
getDatastoreWriteTimeoutMillis()
Get the effective timeout setting for write operations. |
|
boolean |
getDetachAllOnCommit()
Gets the detachAllOnCommit setting. |
|
|
getExtent(java.lang.Class<T> persistenceCapableClass)
Equivalent to getExtent (persistenceCapableClass,
true) . |
|
|
getExtent(java.lang.Class<T> persistenceCapableClass,
boolean subclasses)
The PersistenceManager manages a collection of instances in
the data store based on the class of the instances. |
|
FetchGroup |
getFetchGroup(java.lang.Class cls,
java.lang.String name)
Get a modifiable FetchGroup for the Class and name. |
|
FetchPlan |
getFetchPlan()
Returns the FetchPlan used by this
PersistenceManager . |
|
boolean |
getIgnoreCache()
Get the ignoreCache setting for queries. |
|
java.util.Set |
getManagedObjects()
Get the objects managed by this persistence manager. |
|
java.util.Set |
getManagedObjects(java.lang.Class... classes)
Get the objects managed by this persistence manager being instances of the specified classes. |
|
java.util.Set |
getManagedObjects(java.util.EnumSet<ObjectState> states)
Get the objects managed by this persistence manager having the specified object states. |
|
java.util.Set |
getManagedObjects(java.util.EnumSet<ObjectState> states,
java.lang.Class... classes)
Get the objects managed by this persistence manager having the specified object states and being instances of the specified classes. |
|
boolean |
getMultithreaded()
Get the current Multithreaded flag for this PersistenceManager . |
|
|
getObjectById(java.lang.Class<T> cls,
java.lang.Object key)
Looks up the instance of the given type with the given key. |
|
java.lang.Object |
getObjectById(java.lang.Object oid)
Looks up the instance corresponding to the specified oid. |
|
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.lang.Object[] |
getObjectsById(boolean validate,
java.lang.Object... oids)
Return the objects with the given oids. |
|
java.util.Collection |
getObjectsById(java.util.Collection oids)
Return the objects with the given oids. |
|
java.util.Collection |
getObjectsById(java.util.Collection oids,
boolean validate)
Return the objects with the given oids. |
|
java.lang.Object[] |
getObjectsById(java.lang.Object... oids)
Return the objects with the given oids. |
|
java.lang.Object[] |
getObjectsById(java.lang.Object[] oids,
boolean validate)
Deprecated. |
|
PersistenceManagerFactory |
getPersistenceManagerFactory()
This method returns the PersistenceManagerFactory used to
create this PersistenceManager . |
|
Sequence |
getSequence(java.lang.String name)
Returns the sequence identified by name . |
|
java.util.Date |
getServerDate()
Get the Date as seen by the server. |
|
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)
Get the value for the specified key from the map of user objects. |
|
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. |
|
|
makePersistent(T pc)
Make the parameter instance persistent in this PersistenceManager . |
|
|
makePersistentAll(java.util.Collection<T> pcs)
Make a Collection of instances persistent. |
|
|
makePersistentAll(T... 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 |
makeTransient(java.lang.Object pc,
boolean useFetchPlan)
Make an instance transient, removing it from management by this PersistenceManager . |
|
void |
makeTransientAll(boolean useFetchPlan,
java.lang.Object... pcs)
Make instances transient, removing them 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.util.Collection pcs,
boolean useFetchPlan)
Make 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 . |
|
void |
makeTransientAll(java.lang.Object[] pcs,
boolean useFetchPlan)
Deprecated. |
|
|
newInstance(java.lang.Class<T> pcClass)
Creates an instance of a persistence-capable interface, or of a concrete or abstract class. |
|
Query |
newNamedQuery(java.lang.Class cls,
java.lang.String queryName)
Create a new Query with the given candidate class
from a named query. |
|
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. |
|
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 query)
Create a Construct a new query instance using the specified String as the single-string representation of the query. |
|
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 val)
Put the specified key-value pair into the map of user objects. |
|
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(JDOException jdoe)
Refreshes all instances in the exception that failed verification. |
|
void |
refreshAll(java.lang.Object... pcs)
Refresh the state of an array of instances from the data store. |
|
void |
removeInstanceLifecycleListener(InstanceLifecycleListener listener)
Removes the listener instance from the list of lifecycle event listeners. |
|
java.lang.Object |
removeUserObject(java.lang.Object key)
Remove the specified key and its value from the map of user objects. |
|
void |
retrieve(java.lang.Object pc)
Retrieve field values of an instance from the store. |
|
void |
retrieve(java.lang.Object pc,
boolean useFetchPlan)
Retrieve field values of an instance from the store. |
|
void |
retrieveAll(boolean useFetchPlan,
java.lang.Object... pcs)
Retrieve field values of instances from the store. |
|
void |
retrieveAll(java.util.Collection pcs)
Retrieve field values of instances from the store. |
|
void |
retrieveAll(java.util.Collection pcs,
boolean useFetchPlan)
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 useFetchPlan)
Deprecated. |
|
void |
setCopyOnAttach(boolean flag)
Sets the copyOnAttach setting. |
|
void |
setDatastoreReadTimeoutMillis(java.lang.Integer interval)
Specify a timeout interval (milliseconds) for any datastore read operations associated with this persistence manager. |
|
void |
setDatastoreWriteTimeoutMillis(java.lang.Integer interval)
Specify a timeout interval (milliseconds) for any write operations associated with this persistence manager. |
|
void |
setDetachAllOnCommit(boolean flag)
Sets the detachAllOnCommit setting. |
|
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 |
---|
boolean isClosed()
PersistenceManager
instance can be used until it is
closed.
true
if this PersistenceManager
has
been closed.close()
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
.
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
.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.void evictAll(java.lang.Object... pcs)
pcs
- the array of instances to evict from the cache.evict(Object pc)
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)
void evictAll(boolean subclasses, java.lang.Class pcClass)
pcClass
- the class of instances to evictsubclasses
- if true, mark instances of subclasses alsovoid evictAll()
evict(Object pc)
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.void refreshAll(java.lang.Object... pcs)
pcs
- the array of instances to refresh.refresh(Object pc)
void refreshAll(java.util.Collection pcs)
Collection
of instances from the
data store.
pcs
- the Collection
of instances to refresh.refresh(Object pc)
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)
void refreshAll(JDOException jdoe)
Query newQuery()
Query
with no elements.
Query
.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
implementation
Query
Query newQuery(java.lang.String query)
query
- the single-string query
Query
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 language
Query
Query newQuery(java.lang.Class cls)
Query
specifying the Class
of the
candidate instances.
cls
- the Class
of the candidate instances
Query
Query newQuery(Extent cln)
Query
with the Class
of the
candidate instances and candidate Extent
.
cln
- the Extent
of candidate instances
Query
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 instances
Query
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 instances
Query
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 instances
Query
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 instances
Query
Query newNamedQuery(java.lang.Class cls, java.lang.String queryName)
Query
with the given candidate class
from a named query. The query name given must be the name of a
query defined in metadata.
cls
- the Class
of candidate instancesqueryName
- the name of the query to look up in metadata
Query
<T> Extent<T> getExtent(java.lang.Class<T> 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 subclasses
Extent
of the specified Class
Query
<T> Extent<T> getExtent(java.lang.Class<T> persistenceCapableClass)
getExtent (persistenceCapableClass,
true)
.
getExtent(Class,boolean)
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
JDOObjectNotFoundException
. But a subsequent access
of the fields of the
instance will throw a JDOObjectNotFoundException
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
JDOObjectNotFoundException
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 validated
PersistenceCapable
instance with the specified
ObjectIdgetObjectId(Object pc)
,
getTransactionalObjectId(Object pc)
<T> T getObjectById(java.lang.Class<T> cls, java.lang.Object key)
cls
- The type of object to loadkey
- either the string representation of the object id, or
an object representation of a single field identity key
java.lang.Object getObjectById(java.lang.Object oid)
getObjectById(oid, true);
- Parameters:
oid
- The object id of the object to load
- Returns:
- the corresponding persistent instance
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
instance
getTransactionalObjectId(Object pc)
,
getObjectById(Object oid, boolean validate)
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
instance
getObjectId(Object pc)
,
getObjectById(Object oid, boolean validate)
java.lang.Object newObjectIdInstance(java.lang.Class pcClass, java.lang.Object key)
pcClass
- the Class
of the persistence-capable instancekey
- for single-field identity, the parameter for the
constructor; for non-single-field application identity, the result
of toString() on the object id instance.
java.util.Collection getObjectsById(java.util.Collection oids, boolean validate)
oids
- the oids of the objects to returnvalidate
- if true, the existance of the objects in
the datastore will be validated.
getObjectById(Object,boolean)
java.util.Collection getObjectsById(java.util.Collection oids)
getObjectsById(Collection, boolean)
with the validate flag true.
oids
- the oids of the objects to return
getObjectsById(Collection,boolean)
java.lang.Object[] getObjectsById(java.lang.Object[] oids, boolean validate)
oids
- the oids of the objects to returnvalidate
- if true, the existance of the objects in
the datastore will be validated.
getObjectById(Object,boolean)
,
getObjectsById(boolean,Object...)
java.lang.Object[] getObjectsById(boolean validate, java.lang.Object... oids)
oids
- the oids of the objects to returnvalidate
- if true, the existance of the objects in
the datastore will be validated.
getObjectById(Object,boolean)
java.lang.Object[] getObjectsById(java.lang.Object... oids)
getObjectsById(boolean,Object...)
with the validate flag true.
oids
- the oids of the objects to return
getObjectsById(boolean,Object...)
<T> T makePersistent(T pc)
PersistenceManager
.
This method makes transient instances persistent and applies detached
instance changes to the cache. It must be called in the context of
an active transaction, or a JDOUserException is thrown. For a transient
instance, it assigns an object identity to the instance and transitions
it to persistent-new. Any transient instances reachable from this
instance via persistent fields of this instance become provisionally
persistent, transitively. That is, they behave as persistent-new
instances (return true to isPersistent, isNew, and isDirty).
But at commit time, the reachability algorithm is run again,
and instances made provisionally persistent that are not then
reachable from persistent instances will revert to transient.
During makePersistent of transient instances, the create life cycle listener is called.
For detached instances, it locates or instantiates a persistent instance with the same JDO identity as the detached instance, and merges the persistent state of the detached instance into the persistent instance. Only the state of persistent fields is merged. If non-persistent state needs to be copied, the application should use the jdoPostAttach callback or the postAttach lifecycle event listener. Any references to the detached instances from instances in the closure of the parameter instances are modified to refer to the corresponding persistent instance instead of to the detached instance.
During attachment of detached instances, the attach callbacks and attach life cycle listeners are called.
During application of changes of the detached state, if the JDO implementation can determine that there were no changes made during detachment, then the implementation is not required to mark the corresponding instance dirty. If it cannot determine if changes were made, then it must mark the instance dirty. No consistency checking is done during makePersistent of detached instances. If consistency checking is required by the application, then flush or checkConsistency should be called after attaching the instances.
These methods have no effect on parameter persistent instances already managed by this PersistenceManager. They will throw a JDOUserException if the parameter instance is managed by a different PersistenceManager. If an instance is of a class whose identity type (application, datastore, or none) is not supported by the JDO implementation, then a JDOUserException will be thrown for that instance. The return value for parameter instances in the transient or persistent states is the same as the parameter value. The return value for parameter instances in the detached state is the persistent instance corresponding to the detached instance. The return values for makePersistentAll methods correspond by position to the parameter instances.
pc
- an instance of a Class
that is persistent
capable.
<T> T[] makePersistentAll(T... pcs)
pcs
- an array of instances
makePersistent(Object pc)
<T> java.util.Collection<T> makePersistentAll(java.util.Collection<T> pcs)
Collection
of instances persistent.
pcs
- a Collection
of instances
makePersistent(Object pc)
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 instancevoid deletePersistentAll(java.lang.Object... pcs)
pcs
- a Collection
of persistent instancesdeletePersistent(Object pc)
void deletePersistentAll(java.util.Collection pcs)
Collection
of instances from the data store.
pcs
- a Collection
of persistent instancesdeletePersistent(Object pc)
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.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.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.void makeTransient(java.lang.Object pc, boolean useFetchPlan)
PersistenceManager
. If the useFetchPlan parameter is
false, this method behaves exactly as makeTransient(Object pc).
The affected instance(s) lose their JDO identity and are no longer
associated with any PersistenceManager
. The state
of fields is unchanged.
If the useFetchPlan parameter is true, then the current FetchPlan is applied to the pc parameter, as if detachCopy(Object) had been called. After the graph of instances is loaded, the instances reachable via loaded fields is made transient. The state of fields in the affected instances is as specified by the FetchPlan.
Unlike detachCopy, the instances are not detached; there is no detachment information in the instances.
The instances to be made transient do not need to implement the javax.jdo.spi.Detachable interface.
pc
- the root instance to make transient.useFetchPlan
- whether to use the current fetch plan to determine
which fields to load and which instances to make transientvoid makeTransientAll(java.lang.Object[] pcs, boolean useFetchPlan)
PersistenceManager
. If the useFetchPlan parameter
is false, this method behaves exactly as makeTransientAll(Object[] pcs).
The affected instance(s) lose their JDO identity and are no longer
associated with any PersistenceManager
. The state
of fields is unchanged.
If the useFetchPlan parameter is true, then the current FetchPlan is applied to the pcs parameters and the entire graph of instances reachable via loaded fields is made transient. The state of fields in the affected instances is as specified by the FetchPlan.
Unlike detachCopy, the instances are not detached; there is no detachment information in the instances.
The instances to be made transient do not need to implement the javax.jdo.spi.Detachable interface.
pcs
- the root instances to make transient.useFetchPlan
- whether to use the current fetch plan to determine
which fields to load and which instances to make transientmakeTransientAll(boolean,Object...)
void makeTransientAll(boolean useFetchPlan, java.lang.Object... pcs)
PersistenceManager
. If the useFetchPlan parameter
is false, this method behaves exactly as makeTransientAll(Object[] pcs).
The affected instance(s) lose their JDO identity and are no longer
associated with any PersistenceManager
. The state
of fields is unchanged.
If the useFetchPlan parameter is true, then the current FetchPlan is applied to the pcs parameters and the entire graph of instances reachable via loaded fields is made transient. The state of fields in the affected instances is as specified by the FetchPlan.
Unlike detachCopy, the instances are not detached; there is no detachment information in the instances.
The instances to be made transient do not need to implement the javax.jdo.spi.Detachable interface.
pcs
- the root instances to make transient.useFetchPlan
- whether to use the current fetch plan to determine
which fields to load and which instances to make transientvoid makeTransientAll(java.util.Collection pcs, boolean useFetchPlan)
PersistenceManager
. If the useFetchPlan parameter
is false, this method behaves exactly as
makeTransientAll(Collection pcs).
The affected instance(s) lose their JDO identity and are no longer
associated with any PersistenceManager
. The state
of fields is unchanged.
If the useFetchPlan parameter is true, then the current FetchPlan is applied to the pcs parameters and the entire graph of instances reachable via loaded fields is made transient. The state of fields in the affected instances is as specified by the FetchPlan.
Unlike detachCopy, the instances are not detached; there is no detachment information in the instances.
The instances to be made transient do not need to implement the javax.jdo.spi.Detachable interface.
pcs
- the root instances to make transient.useFetchPlan
- whether to use the current fetch plan to determine
which fields to load and which instances to make transientvoid 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.void makeTransactionalAll(java.lang.Object... pcs)
pcs
- the array of instances to make transactional.makeTransactional(Object pc)
void makeTransactionalAll(java.util.Collection pcs)
Collection
of instances subject to transactional
boundaries.
pcs
- the Collection
of instances to make
transactional.makeTransactional(Object pc)
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.void makeNontransactionalAll(java.lang.Object... pcs)
pcs
- the array of instances to make nontransactional.makeNontransactional(Object pc)
void makeNontransactionalAll(java.util.Collection pcs)
Collection
of instances non-transactional after
commit.
pcs
- the Collection
of instances to make
nontransactional.makeNontransactional(Object pc)
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 instancevoid retrieve(java.lang.Object pc, boolean useFetchPlan)
PersistenceManager
that the application intends to use
the instance, and its field values must be retrieved.
If the useFetchPlan parameter is false, this method behaves exactly as the corresponding method without the useFetchPlan parameter. If the useFetchPlan parameter is true, and the fetch plan has not been modified from its default setting, all fields in the current fetch plan are fetched, and other fields might be fetched lazily by the implementation. If the useFetchPlan parameter is true, and the fetch plan has been changed from its default setting, then the fields specified by the fetch plan are loaded, along with related instances specified by the fetch plan.
pc
- the instanceuseFetchPlan
- whether to use the current fetch plan to determine
which fields to load and which instances to retrieve.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 instancesvoid retrieveAll(java.util.Collection pcs, boolean useFetchPlan)
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.
If the useFetchPlan parameter is false, this method behaves exactly as the corresponding method without the useFetchPlan parameter. If the useFetchPlan parameter is true, and the fetch plan has not been modified from its default setting, all fields in the current fetch plan are fetched, and other fields might be fetched lazily by the implementation. If the useFetchPlan parameter is true, and the fetch plan has been changed from its default setting, then the fields specified by the fetch plan are loaded, along with related instances specified by the fetch plan.
pcs
- the instancesuseFetchPlan
- whether to use the current fetch plan to determine
which fields to load and which instances to retrieve.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 instancesvoid retrieveAll(java.lang.Object[] pcs, boolean useFetchPlan)
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.
If the useFetchPlan parameter is false, this method behaves exactly as the corresponding method without the useFetchPlan parameter. If the useFetchPlan parameter is true, and the fetch plan has not been modified from its default setting, all fields in the current fetch plan are fetched, and other fields might be fetched lazily by the implementation. If the useFetchPlan parameter is true, and the fetch plan has been changed from its default setting, then the fields specified by the fetch plan are loaded, along with related instances specified by the fetch plan.
pcs
- the instancesuseFetchPlan
- whether to use the current fetch plan to determine
which fields to load and which instances to retrieve.retrieveAll(boolean,Object...)
void retrieveAll(boolean useFetchPlan, java.lang.Object... pcs)
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.
If the useFetchPlan parameter is false, this method behaves exactly as the corresponding method without the useFetchPlan parameter. If the useFetchPlan parameter is true, and the fetch plan has not been modified from its default setting, all fields in the current fetch plan are fetched, and other fields might be fetched lazily by the implementation. If the useFetchPlan parameter is true, and the fetch plan has been changed from its default setting, then the fields specified by the fetch plan are loaded, along with related instances specified by the fetch plan.
pcs
- the instancesuseFetchPlan
- whether to use the current fetch plan to determine
which fields to load and which instances to retrieve.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()
java.lang.Object getUserObject()
PersistenceManager
instances
more easily by having an application object associated with each
PersistenceManager
instance.
PersistenceManager
setUserObject(java.lang.Object)
PersistenceManagerFactory getPersistenceManagerFactory()
PersistenceManagerFactory
used to
create this PersistenceManager
.
PersistenceManagerFactory
that created
this PersistenceManager
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)
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.boolean getMultithreaded()
PersistenceManager
.
setMultithreaded(boolean)
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.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.
void setDatastoreReadTimeoutMillis(java.lang.Integer interval)
interval
- the timeout interval (milliseconds)java.lang.Integer getDatastoreReadTimeoutMillis()
setDatastoreReadTimeoutMillis(Integer)
,
PersistenceManagerFactory.setDatastoreReadTimeoutMillis(Integer)
void setDatastoreWriteTimeoutMillis(java.lang.Integer interval)
interval
- the timeout interval (milliseconds)java.lang.Integer getDatastoreWriteTimeoutMillis()
setDatastoreWriteTimeoutMillis(Integer)
,
PersistenceManagerFactory.setDatastoreWriteTimeoutMillis(Integer)
boolean getDetachAllOnCommit()
setDetachAllOnCommit(boolean)
void setDetachAllOnCommit(boolean flag)
DetachAllOnCommit set to false
specifies that the
state of persistent instances in the cache after commit is defined
by the retainValues
flag. With this flag set to true,
during beforeCompletion all cached instances are prepared for
detachment according to the fetch plan in effect at commit. Loading
fields and unloading fields required by the fetch plan is done after
calling the user's beforeCompletion
callback. During
afterCompletion
, before calling the user's
afterCompletion
callback, all detachable persistent
instances in the cache transition to detached; non-detachable
persistent instances transition to transient; and detachable
instances can be serialized as detached instances. Transient
transactional instances are unaffected by this flag.
getDetachAllOnCommit()
boolean getCopyOnAttach()
setCopyOnAttach(boolean)
void setCopyOnAttach(boolean flag)
CopyOnAttach set to true
specifies that during
makePersistent, copies are made of detached parameter instances.
With this flag set to false
, detached parameter
instances are attached directly and change their state from
detached-clean to persistent-clean or from detached-dirty to
persistent-dirty.
getCopyOnAttach()
<T> T detachCopy(T pc)
PersistenceManager
.
The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
and the active fetch groups determine the scope of fetching for the
graph of instances reachable from the pc parameter. The state of fields
in the affected instances is as specified by the FetchPlan.
pc
- the instance to detach
detachCopyAll(Object[])
<T> java.util.Collection<T> detachCopyAll(java.util.Collection<T> pcs)
PersistenceManager
.
The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
and the active fetch groups determine the scope of fetching for the
graph of instances reachable from the pcs parameter. The state of fields
in the affected instances is as specified by the FetchPlan.
pcs
- the instances to detach
detachCopyAll(Object[])
<T> T[] detachCopyAll(T... pcs)
PersistenceManager
.
The flags for detachment (DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS)
and the active fetch groups determine the scope of fetching for the
graph of instances reachable from the pcs parameter. The state of fields
in the affected instances is as specified by the FetchPlan.
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
.
pcs
- the instances to detach
JDOUserException
- if any of the instances to be detached do not
implement the javax.jdo.spi.Detachable interface.makePersistentAll(Object[])
,
getFetchPlan()
java.lang.Object putUserObject(java.lang.Object key, java.lang.Object val)
java.lang.Object getUserObject(java.lang.Object key)
key
- the key of the object to be returned
java.lang.Object removeUserObject(java.lang.Object key)
key
- the key of the object to be removedvoid flush()
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, synchronizes the cache with the datastore using this connection and reports any exceptions. The connection obtained by this method is held until the end of the transaction.
If exceptions occur during flush, the implementation will
set the current transaction's RollbackOnly
flag
(see Transaction.setRollbackOnly()
).
void checkConsistency()
PersistenceManager
cache with the
datastore. This method 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.
FetchPlan getFetchPlan()
FetchPlan
used by this
PersistenceManager
.
<T> T newInstance(java.lang.Class<T> pcClass)
pcClass
- Must be a persistence-capable interface,
or a concrete or abstract class that is declared in the metadata.
Sequence getSequence(java.lang.String name)
name
.
name
- the name of the Sequence
JDOConnection getDataStoreConnection()
void addInstanceLifecycleListener(InstanceLifecycleListener listener, java.lang.Class... classes)
classes
parameter identifies all
of the classes of interest. If the classes
parameter is specified as null
, events for all
persistent classes and interfaces will be sent to
listenerInstance
.
The listenerInstance will be called for each event for which it implements the corresponding listenerInstance interface.
listener
- the lifecycle listenerclasses
- the classes of interest to the listenervoid removeInstanceLifecycleListener(InstanceLifecycleListener listener)
listener
- the listener instance to be removedjava.util.Date getServerDate()
java.util.Set getManagedObjects()
java.util.Set getManagedObjects(java.util.EnumSet<ObjectState> states)
states
- The states of objects that we are interested in
java.util.Set getManagedObjects(java.lang.Class... classes)
classes
- The classes of objects that we are interested in
java.util.Set getManagedObjects(java.util.EnumSet<ObjectState> states, java.lang.Class... classes)
states
- The states of objects that we are interested inclasses
- The classes of objects that we are interested in
FetchGroup getFetchGroup(java.lang.Class cls, java.lang.String name)
FetchGroup
for the Class and name.
If a modifiable FetchGroup
already exists in the
PersistenceManager
scope, return it.
If not, create and populate a new FetchGroup
from the
existing definition in the PersistenceManager
or
PersistenceManagerFactory
. If the definition for the
FetchGroup
is not in scope in either the
PersistenceManager
or
PersistenceManagerFactory
, create it with no members.
The FetchGroup
immediately
becomes active and in scope of the PersistenceManager, and hides
the corresponding fetch group in the PersistenceManagerFactory.
cls
- the class or interface for the FetchGroup
name
- the name of the fetch group
JDOUserException
- if the class is not a persistence-capable
class or interface
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |