javax.jdo.JDOEntityManager - JDO interface
javax.jdo
Interface JDOEntityManager
- Superinterfaces:
EntityManager
,PersistenceManager
- Since:
- JDO 1.0
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.
- Parameters:
listener
- the lifecycle listenerclasses
- the classes of interest to the listener
- Since:
- JDO 2.0
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.
- Since:
- JDO 2.0
- Since:
- JPA 1.0
- Parameters:
entity
- entity instance
- Returns:
- boolean indicating if entity is in persistence context
- Throws:
IllegalArgumentException
- if not an entity
- Since:
- JPA 1.0
Query
for executing a named query (in the Java Persistence query language or in native SQL).- Parameters:
name
- the name of a query defined in metadata
- Returns:
- the new query instance
- Throws:
IllegalArgumentException
- if a query has not been defined with the given name or if the query string is found to be invalid
- Since:
- JPA 1.0
TypedQuery
for executing a Java Persistence query language named query. The select list of the query must contain only a single item, which must be assignable to the type specified by the resultClass
argument.- Parameters:
name
- the name of a query defined in metadataresultClass
- the type of the query result
- Returns:
- the new query instance
- Throws:
IllegalArgumentException
- if a query has not been defined with the given name or if the query string is found to be invalid or if the query result is found to not be assignable to the specified type
- Since:
- JPA 2.0
Query
for executing a native SQL statement, e.g., for update or delete.- Parameters:
sqlString
- a native SQL query string
- Returns:
- the new query instance
- Since:
- JPA 1.0
Query
for executing a native SQL query.- Parameters:
sqlString
- a native SQL query stringresultClass
- the class of the resulting instance(s)
- Returns:
- the new query instance
- Since:
- JPA 1.0
Query
for executing a native SQL query.- Parameters:
sqlString
- a native SQL query stringresultSetMapping
- the name of the result set mapping
- Returns:
- the new query instance
- Since:
- JPA 1.0
Query
for executing a Java Persistence query language statement.- Parameters:
qlString
- a Java Persistence query string
- Returns:
- the new query instance
- Throws:
IllegalArgumentException
- if the query string is found to be invalid
- Since:
- JPA 1.0
TypedQuery
for executing a Java Persistence query language statement. The select list of the query must contain only a single item, which must be assignable to the type specified by the resultClass
argument.- Parameters:
qlString
- a Java Persistence query stringresultClass
- the type of the query result
- Returns:
- the new query instance
- Throws:
IllegalArgumentException
- if the query string is found to be invalid or if the query result is found to not be assignable to the specified type
- Since:
- JPA 2.0
TypedQuery
for executing a criteria query.- Parameters:
criteriaQuery
- a criteria query object
- Returns:
- the new query instance
- Throws:
IllegalArgumentException
- if the criteria query is found to be invalid
- Since:
- JPA 2.0
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.- Returns:
- the
Transaction
associated with thisPersistenceManager
.
- Since:
- JDO 1.0
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
.- Parameters:
pc
- a persistent instance
- Since:
- JDO 1.0
- Parameters:
pcs
- aCollection
of persistent instances
- Since:
- JDO 1.0
- See Also:
deletePersistent(Object pc)
Collection
of instances from the data store.- Parameters:
pcs
- aCollection
of persistent instances
- Since:
- JDO 1.0
- See Also:
deletePersistent(Object pc)
- Parameters:
entity
- entity instance
- Throws:
IllegalArgumentException
- if the instance is not an entity
- Since:
- JPA 2.0
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.- Parameters:
pc
- the instance to detach
- Returns:
- the detached instance
- Since:
- JDO 2.0
- See Also:
detachCopyAll(Object[])
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
.- Parameters:
pcs
- the instances to detach
- Returns:
- the detached instances
- Throws:
JDOUserException
- if any of the instances to be detached do not implement the javax.jdo.spi.Detachable interface.
- Since:
- JDO 2.0
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.- Parameters:
pcs
- the instances to detach
- Returns:
- the detached instances
- Since:
- JDO 2.0
- See Also:
detachCopyAll(Object[])
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.- Parameters:
pc
- the instance to evict from the cache.
- Since:
- JDO 1.0
- Since:
- JDO 1.0
- See Also:
evict(Object pc)
- Parameters:
pcs
- the array of instances to evict from the cache.
- Since:
- JDO 1.0
- See Also:
evict(Object pc)
Collection
of instances as no longer needed in the cache.- Parameters:
pcs
- theCollection
of instances to evict from the cache.
- Since:
- JDO 1.0
- See Also:
evict(Object pc)
- Parameters:
subclasses
- if true, mark instances of subclasses alsopcClass
- the class of instances to evict
- Since:
- JDO 2.1
- Parameters:
entityClass
- entity classprimaryKey
- primary key
- Returns:
- the found entity instance or null if the entity does not exist
- Throws:
IllegalArgumentException
- if the first argument does not denote an entity type or the second argument is is not a valid type for that entity’s primary key or is null
- Since:
- JPA 1.0
If the entity is found within the persistence context and the lock mode type is pessimistic and the entity has a version attribute, the persistence provider must perform optimistic version checks when obtaining the database lock. If these checks fail, the OptimisticLockException
will be thrown.
If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
- the
PessimisticLockException
will be thrown if the database locking failure causes transaction-level rollback - the
LockTimeoutException
will be thrown if the database locking failure causes only statement-level rollback
- Parameters:
entityClass
- entity classprimaryKey
- primary keylockMode
- lock mode
- Returns:
- the found entity instance or null if the entity does not exist
- Throws:
IllegalArgumentException
- if the first argument does not denote an entity type or the second argument is not a valid type for that entity's primary key or is nullTransactionRequiredException
- if there is no transaction and a lock mode other than NONE is specifiedOptimisticLockException
- if the optimistic version check failsPessimisticLockException
- if pessimistic locking fails and the transaction is rolled backLockTimeoutException
- if pessimistic locking fails and only the statement is rolled backPersistenceException
- if an unsupported lock call is made
- Since:
- JPA 2.0
- Returns:
- the copyOnAttach setting.
- Since:
- JDO 2.1
- See Also:
setCopyOnAttach(boolean)
CriteriaBuilder
for the creation of CriteriaQuery
objects.- Returns:
- CriteriaBuilder instance
- Throws:
IllegalStateException
- if the entity manager has been closed
- Since:
- JPA 2.0
- Returns:
- the JDOConnection instance
- Since:
- JDO 2.0
EntityManager
, if available. The result of this method is implementation specific. The unwrap
method is to be preferred for new applications.- Returns:
- underlying provider object for EntityManager
- Since:
- JPA 1.0
- Returns:
- the detachAllOnCommit setting.
- Since:
- JDO 2.0
- See Also:
setDetachAllOnCommit(boolean)
- Returns:
- EntityManagerFactory instance
- Throws:
IllegalStateException
- if the entity manager has been closed
- Since:
- JPA 2.0
getExtent (persistenceCapableClass, true)
.- Parameters:
persistenceCapableClass
-
- Since:
- JDO 2.0
- See Also:
getExtent(Class,boolean)
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.
- Parameters:
persistenceCapableClass
-Class
of instancessubclasses
- whether to include instances of subclasses
- Returns:
- an
Extent
of the specifiedClass
- Since:
- JDO 1.0
- See Also:
Query
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.- Parameters:
cls
- the class or interface for theFetchGroup
name
- the name of the fetch group
- Returns:
- the FetchGroup
- Throws:
JDOUserException
- if the class is not a persistence-capable class or interface
- Since:
- JDO 2.2
FetchPlan
used by this PersistenceManager
.- Returns:
- the FetchPlan
- Since:
- JDO 2.0
- Returns:
- flushMode
- Since:
- JPA 1.0
IgnoreCache set to true
specifies that for all Query
instances created by this PersistenceManager
, the default is the cache should be ignored for queries.
- Returns:
- the ignoreCache setting.
- Since:
- JDO 1.0
- Parameters:
entity
- entity instance
- Returns:
- lock mode
- Throws:
TransactionRequiredException
- if there is no transactionIllegalArgumentException
- if the instance is not a managed entity and a transaction is active
- Since:
- JPA 2.0
- Returns:
- the objects
- Since:
- JDO 2.1
- Parameters:
classes
- The classes of objects that we are interested in
- Returns:
- the objects
- Since:
- JDO 2.1
- Parameters:
states
- The states of objects that we are interested in
- Returns:
- the objects
- Since:
- JDO 2.1
- Parameters:
states
- The states of objects that we are interested inclasses
- The classes of objects that we are interested in
- Returns:
- the objects
- Since:
- JDO 2.1
Metamodel
interface for access to the metamodel of the persistence unit.- Returns:
- Metamodel instance
- Throws:
IllegalStateException
- if the entity manager has been closed
- Since:
- JPA 2.0
PersistenceManager
.- Returns:
- the Multithreaded setting.
- Since:
- JDO 1.0
- See Also:
setMultithreaded
getObjectById(oid, true);
Parameters:
oid
- The object id of the object to load
- Returns:
- the corresponding persistent instance
- Since:
- JDO 1.0
T getObjectById(Class<T> cls, Object key)
Looks up the instance of the given type with the given key.
Parameters:
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
- Returns:
- the corresponding persistent instance
- Since:
- JDO 2.0
Object getObjectById(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 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.
Parameters:
oid
- an ObjectIdvalidate
- if the existence of the instance is to be validated
- Returns:
- the
PersistenceCapable
instance with the specified ObjectId
- Since:
- JDO 1.0
Object getObjectId(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.
Parameters:
pc
- thePersistenceCapable
instance
- Returns:
- the ObjectId of the instance
- Since:
- JDO 1.0
Class getObjectIdClass(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.
Parameters:
cls
- thePersistenceCapable Class
- Returns:
- the
Class
of the ObjectId of the parameter
- Since:
- JDO 1.0
- See Also:
getObjectById
Object[] getObjectsById(Object... oids)
Return the objects with the given oids. This method is equivalent to calling getObjectsById(boolean,Object...)
with the validate flag true.
Parameters:
oids
- the oids of the objects to return
- Returns:
- the objects that were looked up, in the same order as the oids parameter.
- Since:
- JDO 2.0
- See Also:
getObjectsById(boolean,Object...)
Collection getObjectsById(Collection oids)
Return the objects with the given oids. This method is equivalent to calling getObjectsById(Collection, boolean)
with the validate flag true.
Parameters:
oids
- the oids of the objects to return
- Returns:
- the objects that were looked up, in the same order as the oids parameter.
- Since:
- JDO 2.0
- See Also:
getObjectsById(Collection,boolean)
Object[] getObjectsById(boolean validate, Object... oids)
Return the objects with the given oids.
Parameters:
validate
- if true, the existance of the objects in the datastore will be validated.oids
- the oids of the objects to return
- Returns:
- the objects that were looked up, in the same order as the oids parameter.
- Since:
- JDO 2.1
- See Also:
getObjectById(Object,boolean)
Object[] getObjectsById(Object[] oids, boolean validate)
Return the objects with the given oids.
Parameters:
oids
- the oids of the objects to returnvalidate
- if true, the existance of the objects in the datastore will be validated.
- Returns:
- the objects that were looked up, in the same order as the oids parameter.
- Since:
- JDO 2.0
Collection getObjectsById(Collection oids, boolean validate)
Return the objects with the given oids.
Parameters:
oids
- the oids of the objects to returnvalidate
- if true, the existance of the objects in the datastore will be validated.
- Returns:
- the objects that were looked up, in the same order as the oids parameter.
- Since:
- JDO 2.0
- See Also:
getObjectById(Object,boolean)
This method returns the PersistenceManagerFactory
used to create this PersistenceManager
.
Returns:
the
PersistenceManagerFactory
that created thisPersistenceManager
- Since:
- JDO 1.0
Map<String,Object> getProperties()
Get the properties and hints and associated values that are in effect for the entity manager. Changing the contents of the map does not change the configuration in effect.
Returns:
map of properties and hints in effect for entity manager
- Since:
- JPA 2.0
T getReference(Class<T> entityClass, Object primaryKey)
Get an instance, whose state may be lazily fetched. If the requested instance does not exist in the database, the EntityNotFoundException
is thrown when the instance state is first accessed. (The persistence provider runtime is permitted to throw the EntityNotFoundException
when getReference
is called.) The application should not expect that the instance state will be available upon detachment, unless it was accessed by the application while the entity manager was open.
Parameters:
entityClass
- entity classprimaryKey
- primary key
- Returns:
- the found entity instance
- Throws:
IllegalArgumentException
- if the first argument does not denote an entity type or the second argument is not a valid type for that entity’s primary key or is nullEntityNotFoundException
- if the entity state cannot be accessed
- Since:
- JPA 1.0
Sequence getSequence(String name)
Returns the sequence identified by name
.
Parameters:
name
- the name of the Sequence
- Returns:
- the Sequence
- Since:
- JDO 2.0
Date getServerDate()
Get the Date as seen by the server. Clients using this method can order their operations according to a single time source. Implementations use the setting of the server time zone to prepare a Date instance that represents UTC time on the server.
Returns:
a Date instance corresponding to the UTC Date as seen by the server
- Since:
- JDO 2.1
Return the resource-level EntityTransaction
object. The EntityTransaction
instance may be used serially to begin and commit multiple transactions.
Returns:
EntityTransaction instance
- Throws:
IllegalStateException
- if invoked on a JTA entity manager
- Since:
- JPA 1.0
Object getTransactionalObjectId(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
.
Parameters:
pc
- aPersistenceCapable
instance
- Returns:
- the ObjectId of the instance
- Since:
- JDO 1.0
Object getUserObject()
The application can manage the PersistenceManager
instances more easily by having an application object associated with each PersistenceManager
instance.
Returns:
the user object associated with this
PersistenceManager
- Since:
- JDO 1.0
- See Also:
setUserObject
Object getUserObject(Object key)
Get the value for the specified key from the map of user objects.
Parameters:
key
- the key of the object to be returned
- Returns:
- the object
- Since:
- JDO 2.0
boolean isClosed()
A PersistenceManager
instance can be used until it is closed.
Returns:
true
if thisPersistenceManager
has been closed.
- Since:
- JDO 1.0
- See Also:
close()
boolean isOpen()
Determine whether the entity manager is open.
Returns:
true until the entity manager has been closed
- Since:
- JPA 1.0
void joinTransaction()
Indicate to the entity manager that a JTA transaction is active. This method should be called on a JTA application managed entity manager that was created outside the scope of the active transaction to associate it with the current JTA transaction.
Throws:
TransactionRequiredException
- if there is no transaction
- Since:
- JPA 1.0
void lock(Object entity, LockModeType lockMode)
Lock an entity instance that is contained in the persistence context with the specified lock mode type. If a pessimistic lock mode type is specified and the entity contains a version attribute, the persistence provider must also perform optimistic version checks when obtaining the database lock. If these checks fail, the OptimisticLockException
will be thrown.
If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
- the
PessimisticLockException
will be thrown if the database locking failure causes transaction-level rollback - the
LockTimeoutException
will be thrown if the database locking failure causes only statement-level rollback
Parameters:
entity
- entity instancelockMode
- lock mode
- Throws:
IllegalArgumentException
- if the instance is not an entity or is a detached entityTransactionRequiredException
- if there is no transactionEntityNotFoundException
- if the entity does not exist in the database when pessimistic locking is performedOptimisticLockException
- if the optimistic version check failsPessimisticLockException
- if pessimistic locking fails and the transaction is rolled backLockTimeoutException
- if pessimistic locking fails and only the statement is rolled backPersistenceException
- if an unsupported lock call is made
- Since:
- JPA 1.0
void lock(Object entity, LockModeType lockMode, Map<String,Object> properties)
Lock an entity instance that is contained in the persistence context with the specified lock mode type and with specified properties. If a pessimistic lock mode type is specified and the entity contains a version attribute, the persistence provider must also perform optimistic version checks when obtaining the database lock. If these checks fail, the OptimisticLockException
will be thrown.
If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
- the
PessimisticLockException
will be thrown if the database locking failure causes transaction-level rollback - the
LockTimeoutException
will be thrown if the database locking failure causes only statement-level rollback
If a vendor-specific property or hint is not recognized, it is silently ignored.
Portable applications should not rely on the standard timeout hint. Depending on the database in use and the locking mechanisms used by the provider, the hint may or may not be observed.
Parameters:
entity
- entity instancelockMode
- lock modeproperties
- standard and vendor-specific properties and hints
- Throws:
IllegalArgumentException
- if the instance is not an entity or is a detached entityTransactionRequiredException
- if there is no transactionEntityNotFoundException
- if the entity does not exist in the database when pessimistic locking is performedOptimisticLockException
- if the optimistic version check failsPessimisticLockException
- if pessimistic locking fails and the transaction is rolled backLockTimeoutException
- if pessimistic locking fails and only the statement is rolled backPersistenceException
- if an unsupported lock call is made
- Since:
- JPA 2.0
void makeNontransactional(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.
Parameters:
pc
- the instance to make nontransactional.
- Since:
- JDO 1.0
void makeNontransactionalAll(Object... pcs)
Make an array of instances non-transactional after commit.
Parameters:
pcs
- the array of instances to make nontransactional.
- Since:
- JDO 1.0
- See Also:
makeNontransactional(Object pc)
void makeNontransactionalAll(Collection pcs)
Make a Collection
of instances non-transactional after commit.
Parameters:
pcs
- theCollection
of instances to make nontransactional.
- Since:
- JDO 1.0
- See Also:
makeNontransactional(Object pc)
T makePersistent(T pc)
Make the parameter instance persistent in this 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.
Parameters:
pc
- an instance of aClass
that is persistent capable.
- Returns:
- the parameter instance for parameters in the transient or persistent state, or the corresponding persistent instance for detached parameter instances
- Since:
- JDO 1.0
T[] makePersistentAll(T... pcs)
Make an array of instances persistent.
Parameters:
pcs
- an array of instances
- Returns:
- the parameter instances for parameters in the transient or persistent state, or the corresponding persistent instance for detached parameter instances, in the same order as in the parameter array
- Since:
- JDO 1.0
- See Also:
makePersistent(Object pc)
Collection<T> makePersistentAll(Collection<T> pcs)
Make a Collection
of instances persistent.
Parameters:
pcs
- aCollection
of instances
- Returns:
- the parameter instance for parameters in the transient or persistent state, or the corresponding persistent instance for detached parameter instances, with an iteration in the same order as in the parameter Collection
- Since:
- JDO 1.0
- See Also:
makePersistent(Object pc)
void makeTransactional(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.
Parameters:
pc
- the instance to make transactional.
- Since:
- JDO 1.0
void makeTransactionalAll(Object... pcs)
Make an array of instances subject to transactional boundaries.
Parameters:
pcs
- the array of instances to make transactional.
- Since:
- JDO 1.0
- See Also:
makeTransactional(Object pc)
void makeTransactionalAll(Collection pcs)
Make a Collection
of instances subject to transactional boundaries.
Parameters:
pcs
- theCollection
of instances to make transactional.
- Since:
- JDO 1.0
- See Also:
makeTransactional(Object pc)
void makeTransient(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.
Parameters:
pc
- the instance to make transient.
- Since:
- JDO 1.0
void makeTransient(Object pc, boolean useFetchPlan)
Make an instance transient, removing it from management by this 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.
Parameters:
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 transient
- Since:
- JDO 2.0
void makeTransientAll(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.
Parameters:
pcs
- the instances to make transient.
- Since:
- JDO 1.0
void makeTransientAll(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.
Parameters:
pcs
- the instances to make transient.
- Since:
- JDO 1.0
void makeTransientAll(boolean useFetchPlan, Object... pcs)
Make instances transient, removing them from management by this 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.
Parameters:
useFetchPlan
- whether to use the current fetch plan to determine which fields to load and which instances to make transientpcs
- the root instances to make transient.
- Since:
- JDO 2.1
void makeTransientAll(Object[] pcs, boolean useFetchPlan)
Make instances transient, removing them from management by this 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.
Parameters:
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 transient
- Since:
- JDO 2.0
- See Also:
makeTransientAll(boolean,Object...)
void makeTransientAll(Collection pcs, boolean useFetchPlan)
Make instances transient, removing them from management by this 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.
Parameters:
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 transient
- Since:
- JDO 2.0
T merge(T entity)
Merge the state of the given entity into the current persistence context.
Parameters:
entity
- entity instance
- Returns:
- the managed instance that the state was merged to
- Throws:
IllegalArgumentException
- if instance is not an entity or is a removed entityTransactionRequiredException
- if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION
and there is no transaction
- Since:
- JPA 1.0
T newInstance(Class<T> pcClass)
Creates an instance of a persistence-capable interface, or of a concrete or abstract class. The returned instance is transient.
Parameters:
pcClass
- Must be a persistence-capable interface, or a concrete or abstract class that is declared in the metadata.
- Returns:
- the created instance
- Since:
- JDO 2.0
Query newNamedQuery(Class cls, String queryName)
Create a new Query
with the given candidate class from a named query. The query name given must be the name of a query defined in metadata.
Parameters:
cls
- theClass
of candidate instancesqueryName
- the name of the query to look up in metadata
- Returns:
- the new
Query
- Since:
- JDO 1.0
Object newObjectIdInstance(Class pcClass, Object key)
This method returns an object id instance corresponding to the pcClass and key arguments.
Parameters:
pcClass
- theClass
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.
- Returns:
- an instance of the object identity class
- Since:
- JDO 1.0
Create a new Query
specifying the Class
of the candidate instances.
Parameters:
cls
- theClass
of the candidate instances
- Returns:
- the new
Query
- Since:
- JDO 1.0
Create a new Query
with the Class
of the candidate instances and candidate Extent
.
Parameters:
cln
- theExtent
of candidate instances
- Returns:
- the new
Query
- Since:
- JDO 1.0
Create a Construct a new query instance using the specified String as the single-string representation of the query.
Parameters:
query
- the single-string query
- Returns:
- the new
Query
- Since:
- JDO 2.0
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
.
Parameters:
compiled
- anotherQuery
from the same JDO implementation
- Returns:
- the new
Query
- Since:
- JDO 1.0
Create a new Query
with the Class
of the candidate instances and filter.
Parameters:
cls
- theClass
of resultsfilter
- the filter for candidate instances
- Returns:
- the new
Query
- Since:
- JDO 1.0
Create a new Query
using the specified language.
Parameters:
language
- the language of the query parameterquery
- the query, which is of a form determined by the language
- Returns:
- the new
Query
- Since:
- JDO 1.0
Create a new Query
with the candidate Extent
and filter; the class is taken from the Extent
.
Parameters:
cln
- theExtent
of candidate instancesfilter
- the filter for candidate instances
- Returns:
- the new
Query
- Since:
- JDO 1.0
Create a new Query
with the candidate Class
and Collection
.
Parameters:
cls
- theClass
of resultscln
- theCollection
of candidate instances
- Returns:
- the new
Query
- Since:
- JDO 1.0
Create a new Query
with the Class
of the candidate instances, candidate Collection
, and filter.
Parameters:
cls
- theClass
of candidate instancescln
- theCollection
of candidate instancesfilter
- the filter for candidate instances
- Returns:
- the new
Query
- Since:
- JDO 1.0
void persist(Object entity)
Make an instance managed and persistent.
Parameters:
entity
- entity instance
- Throws:
EntityExistsException
- if the entity already exists. (If the entity already exists, the EntityExistsException
may be thrown when the persist operation is invoked, or the EntityExistsException
or another PersistenceException
may be thrown at flush or commit time.)IllegalArgumentException
- if the instance is not an entityTransactionRequiredException
- if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION
and there is no transaction
- Since:
- JPA 1.0
Object putUserObject(Object key, Object val)
Put the specified key-value pair into the map of user objects.
Parameters:
key
-val
-
- Since:
- JDO 2.0
void refresh(Object entity, Map<String,Object> properties)
Refresh the state of the instance from the database, using the specified properties, and overwriting changes made to the entity, if any. If a vendor-specific property or hint is not recognized, it is silently ignored.
Parameters:
entity
- entity instanceproperties
- standard and vendor-specific properties and hints
- Throws:
IllegalArgumentException
- if the instance is not an entity or the entity is not managedTransactionRequiredException
- if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION
and there is no transactionEntityNotFoundException
- if the entity no longer exists in the database
- Since:
- JPA 2.0
void refresh(Object entity, LockModeType lockMode)
Refresh the state of the instance from the database, overwriting changes made to the entity, if any, and lock it with respect to given lock mode type. If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
- the
PessimisticLockException
will be thrown if the database locking failure causes transaction-level rollback - the
LockTimeoutException
will be thrown if the database locking failure causes only statement-level rollback.
Parameters:
entity
- entity instancelockMode
- lock mode
- Throws:
IllegalArgumentException
- if the instance is not an entity or the entity is not managedTransactionRequiredException
- if there is no transaction and if invoked on a container-managed EntityManager
instance with PersistenceContextType.TRANSACTION
or with a lock mode other than NONE
EntityNotFoundException
- if the entity no longer exists in the databasePessimisticLockException
- if pessimistic locking fails and the transaction is rolled backLockTimeoutException
- if pessimistic locking fails and only the statement is rolled backPersistenceException
- if an unsupported lock call is made
- Since:
- JPA 2.0
void refresh(Object entity, LockModeType lockMode, Map<String,Object> properties)
Refresh the state of the instance from the database, overwriting changes made to the entity, if any, and lock it with respect to given lock mode type and with specified properties. If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
- the
PessimisticLockException
will be thrown if the database locking failure causes transaction-level rollback - the
LockTimeoutException
will be thrown if the database locking failure causes only statement-level rollback
If a vendor-specific property or hint is not recognized, it is silently ignored.
Portable applications should not rely on the standard timeout hint. Depending on the database in use and the locking mechanisms used by the provider, the hint may or may not be observed.
Parameters:
entity
- entity instancelockMode
- lock modeproperties
- standard and vendor-specific properties and hints
- Throws:
IllegalArgumentException
- if the instance is not an entity or the entity is not managedTransactionRequiredException
- if there is no transaction and if invoked on a container-managed EntityManager
instance with PersistenceContextType.TRANSACTION
or with a lock mode other than NONE
EntityNotFoundException
- if the entity no longer exists in the databasePessimisticLockException
- if pessimistic locking fails and the transaction is rolled backLockTimeoutException
- if pessimistic locking fails and only the statement is rolled backPersistenceException
- if an unsupported lock call is made
- Since:
- JPA 2.0
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.
Since:
JDO 1.0
- See Also:
refresh(Object pc)
void refreshAll(Object... pcs)
Refresh the state of an array of instances from the data store.
Parameters:
pcs
- the array of instances to refresh.
- Since:
- JDO 1.0
- See Also:
refresh(Object pc)
void refreshAll(Collection pcs)
Refresh the state of a Collection
of instances from the data store.
Parameters:
pcs
- theCollection
of instances to refresh.
- Since:
- JDO 1.0
- See Also:
refresh(Object pc)
void refreshAll(JDOException jdoe)
Refreshes all instances in the exception that failed verification.
Parameters:
jdoe
-
- Since:
- JDO 2.0
void remove(Object entity)
Remove the entity instance.
Parameters:
entity
- entity instance
- Throws:
IllegalArgumentException
- if the instance is not an entity or is a detached entityTransactionRequiredException
- if invoked on a container-managed entity manager of type PersistenceContextType.TRANSACTION
and there is no transaction
- Since:
- JPA 1.0
void removeInstanceLifecycleListener(InstanceLifecycleListener listener)
Removes the listener instance from the list of lifecycle event listeners.
Parameters:
listener
- the listener instance to be removed
- Since:
- JDO 2.0
Object removeUserObject(Object key)
Remove the specified key and its value from the map of user objects.
Parameters:
key
- the key of the object to be removed
- Since:
- JDO 2.0
void retrieve(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.
Parameters:
pc
- the instance
- Since:
- JDO 1.0
void retrieve(Object pc, boolean useFetchPlan)
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. 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.
Parameters:
pc
- the instanceuseFetchPlan
- whether to use the current fetch plan to determine which fields to load and which instances to retrieve.
- Since:
- JDO 2.0
void retrieveAll(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.
Parameters:
pcs
- the instances
- Since:
- JDO 1.0
void retrieveAll(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.
Parameters:
pcs
- the instances
- Since:
- JDO 1.0
void retrieveAll(boolean useFetchPlan, Object... pcs)
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. 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.
Parameters:
useFetchPlan
- whether to use the current fetch plan to determine which fields to load and which instances to retrieve.pcs
- the instances
- Since:
- JDO 2.1
void retrieveAll(Object[] pcs, boolean useFetchPlan)
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. 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.
Parameters:
pcs
- the instancesuseFetchPlan
- whether to use the current fetch plan to determine which fields to load and which instances to retrieve.
- Since:
- JDO 1.0.1
- See Also:
retrieveAll(boolean,Object...)
void retrieveAll(Collection pcs, boolean useFetchPlan)
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. 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.
Parameters:
pcs
- the instancesuseFetchPlan
- whether to use the current fetch plan to determine which fields to load and which instances to retrieve.
- Since:
- JDO 1.0.1
void setCopyOnAttach(boolean flag)
Sets the copyOnAttach setting. 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.
Parameters:
flag
-
- Since:
- JDO 2.1
- See Also:
getCopyOnAttach()
void setDetachAllOnCommit(boolean flag)
Sets the detachAllOnCommit setting. 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.
Parameters:
flag
-
- Since:
- JDO 2.0
- See Also:
getDetachAllOnCommit()
void setFlushMode(FlushModeType flushMode)
Set the flush mode that applies to all objects contained in the persistence context.
Parameters:
flushMode
- flush mode
- Since:
- JPA 1.0
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.
Parameters:
flag
- the ignoreCache setting.
- Since:
- JDO 1.0
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
.
Parameters:
flag
- the Multithreaded setting.
- Since:
- JDO 1.0
void setProperty(String propertyName, Object value)
Set an entity manager property or hint. If a vendor-specific property or hint is not recognized, it is silently ignored.
Parameters:
propertyName
- name of property or hintvalue
- value for property or hint
- Throws:
IllegalArgumentException
- if the second argument is not valid for the implementation
- Since:
- JPA 2.0
void setUserObject(Object o)
The application can manage the PersistenceManager
instances more easily by having an application object associated with each PersistenceManager
instance.
Parameters:
o
- the user instance to be remembered by thePersistenceManager
- Since:
- JDO 1.0
- See Also:
getUserObject
T unwrap(Class<T> cls)
Return an object of the specified type to allow access to the provider-specific API. If the provider's EntityManager
implementation does not support the specified class, the PersistenceException
is thrown.
Parameters:
cls
- the class of the object to be returned. This is normally either the underlyingEntityManager
implementation class or an interface that it implements.
- Returns:
- an instance of the specified class
- Throws:
PersistenceException
- if the provider does not support the call
- Since:
- JPA 2.0
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 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
.
Since:
JDO 1.0
T find(Class<T> entityClass, Object primaryKey, LockModeType lockMode, Map<K,V> properties)
Find by primary key and lock, using the specified properties. Search for an entity of the specified class and primary key and lock it with respect to the specified lock type. If the entity instance is contained in the persistence context, it is returned from there. If the entity is found within the persistence context and the lock mode type is pessimistic and the entity has a version attribute, the persistence provider must perform optimistic version checks when obtaining the database lock. If these checks fail, the OptimisticLockException
will be thrown.
If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
- the
PessimisticLockException
will be thrown if the database locking failure causes transaction-level rollback - the
LockTimeoutException
will be thrown if the database locking failure causes only statement-level rollback
If a vendor-specific property or hint is not recognized, it is silently ignored.
Portable applications should not rely on the standard timeout hint. Depending on the database in use and the locking mechanisms used by the provider, the hint may or may not be observed.
Parameters:
entityClass
- entity classprimaryKey
- primary keylockMode
- lock modeproperties
- standard and vendor-specific properties and hints
- Returns:
- the found entity instance or null if the entity does not exist
- Throws:
IllegalArgumentException
- if the first argument does not denote an entity type or the second argument is not a valid type for that entity's primary key or is nullTransactionRequiredException
- if there is no transaction and a lock mode other than NONE
is specifiedOptimisticLockException
- if the optimistic version check failsPessimisticLockException
- if pessimistic locking fails and the transaction is rolled backLockTimeoutException
- if pessimistic locking fails and only the statement is rolled backPersistenceException
- if an unsupported lock call is made
- Since:
- JPA 2.0
void flush()
Flushes all dirty, new, and deleted instances to the data store. 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, 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
).
Since:
JDO 2.0
void refresh(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.
Parameters:
pc
- the instance to refresh.
- Since:
- JDO 1.0