|
EclipseLink 2.2.0, build 'v20110202-r8913' API Reference | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface EntityManager
Interface used to interact with the persistence context.
An EntityManager
instance is associated with
a persistence context. A persistence context is a set of entity
instances in which for any persistent entity identity there is
a unique entity instance. Within the persistence context, the
entity instances and their lifecycle are managed.
The EntityManager
API is used
to create and remove persistent entity instances, to find entities
by their primary key, and to query over entities.
The set of entities that can be managed by a given
EntityManager
instance is defined by a persistence
unit. A persistence unit defines the set of all classes that are
related or grouped by the application, and which must be
colocated in their mapping to a single database.
Query
,
TypedQuery
,
CriteriaQuery
,
PersistenceContext
Method Summary | ||
---|---|---|
void |
clear()
Clear the persistence context, causing all managed entities to become detached. |
|
void |
close()
Close an application-managed entity manager. |
|
boolean |
contains(java.lang.Object entity)
Check if the instance is a managed entity instance belonging to the current persistence context. |
|
Query |
createNamedQuery(java.lang.String name)
Create an instance of Query for executing a named query
(in the Java Persistence query language or in native SQL). |
|
|
createNamedQuery(java.lang.String name,
java.lang.Class<T> resultClass)
Create an instance of TypedQuery for executing a
Java Persistence query language named query. |
|
Query |
createNativeQuery(java.lang.String sqlString)
Create an instance of Query for executing
a native SQL statement, e.g., for update or delete. |
|
Query |
createNativeQuery(java.lang.String sqlString,
java.lang.Class resultClass)
Create an instance of Query for executing
a native SQL query. |
|
Query |
createNativeQuery(java.lang.String sqlString,
java.lang.String resultSetMapping)
Create an instance of Query for executing
a native SQL query. |
|
|
createQuery(CriteriaQuery<T> criteriaQuery)
Create an instance of TypedQuery for executing a
criteria query. |
|
Query |
createQuery(java.lang.String qlString)
Create an instance of Query for executing a
Java Persistence query language statement. |
|
|
createQuery(java.lang.String qlString,
java.lang.Class<T> resultClass)
Create an instance of TypedQuery for executing a
Java Persistence query language statement. |
|
void |
detach(java.lang.Object entity)
Remove the given entity from the persistence context, causing a managed entity to become detached. |
|
|
find(java.lang.Class<T> entityClass,
java.lang.Object primaryKey)
Find by primary key. |
|
|
find(java.lang.Class<T> entityClass,
java.lang.Object primaryKey,
LockModeType lockMode)
Find by primary key and lock. |
|
|
find(java.lang.Class<T> entityClass,
java.lang.Object primaryKey,
LockModeType lockMode,
java.util.Map<java.lang.String,java.lang.Object> properties)
Find by primary key and lock, using the specified properties. |
|
|
find(java.lang.Class<T> entityClass,
java.lang.Object primaryKey,
java.util.Map<java.lang.String,java.lang.Object> properties)
Find by primary key, using the specified properties. |
|
void |
flush()
Synchronize the persistence context to the underlying database. |
|
CriteriaBuilder |
getCriteriaBuilder()
Return an instance of CriteriaBuilder for the creation of
CriteriaQuery objects. |
|
java.lang.Object |
getDelegate()
Return the underlying provider object for the EntityManager ,
if available. |
|
EntityManagerFactory |
getEntityManagerFactory()
Return the entity manager factory for the entity manager. |
|
FlushModeType |
getFlushMode()
Get the flush mode that applies to all objects contained in the persistence context. |
|
LockModeType |
getLockMode(java.lang.Object entity)
Get the current lock mode for the entity instance. |
|
Metamodel |
getMetamodel()
Return an instance of Metamodel interface for access to the
metamodel of the persistence unit. |
|
java.util.Map<java.lang.String,java.lang.Object> |
getProperties()
Get the properties and hints and associated values that are in effect for the entity manager. |
|
|
getReference(java.lang.Class<T> entityClass,
java.lang.Object primaryKey)
Get an instance, whose state may be lazily fetched. |
|
EntityTransaction |
getTransaction()
Return the resource-level EntityTransaction object. |
|
boolean |
isOpen()
Determine whether the entity manager is open. |
|
void |
joinTransaction()
Indicate to the entity manager that a JTA transaction is active. |
|
void |
lock(java.lang.Object entity,
LockModeType lockMode)
Lock an entity instance that is contained in the persistence context with the specified lock mode type. |
|
void |
lock(java.lang.Object entity,
LockModeType lockMode,
java.util.Map<java.lang.String,java.lang.Object> properties)
Lock an entity instance that is contained in the persistence context with the specified lock mode type and with specified properties. |
|
|
merge(T entity)
Merge the state of the given entity into the current persistence context. |
|
void |
persist(java.lang.Object entity)
Make an instance managed and persistent. |
|
void |
refresh(java.lang.Object entity)
Refresh the state of the instance from the database, overwriting changes made to the entity, if any. |
|
void |
refresh(java.lang.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. |
|
void |
refresh(java.lang.Object entity,
LockModeType lockMode,
java.util.Map<java.lang.String,java.lang.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. |
|
void |
refresh(java.lang.Object entity,
java.util.Map<java.lang.String,java.lang.Object> properties)
Refresh the state of the instance from the database, using the specified properties, and overwriting changes made to the entity, if any. |
|
void |
remove(java.lang.Object entity)
Remove the entity instance. |
|
void |
setFlushMode(FlushModeType flushMode)
Set the flush mode that applies to all objects contained in the persistence context. |
|
void |
setProperty(java.lang.String propertyName,
java.lang.Object value)
Set an entity manager property or hint. |
|
|
unwrap(java.lang.Class<T> cls)
Return an object of the specified type to allow access to the provider-specific API. |
Method Detail |
---|
void persist(java.lang.Object entity)
entity
- entity instance
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.)
java.lang.IllegalArgumentException
- if the instance is not an
entity
TransactionRequiredException
- if invoked on a
container-managed entity manager of type
PersistenceContextType.TRANSACTION
and there is
no transaction<T> T merge(T entity)
entity
- entity instance
java.lang.IllegalArgumentException
- if instance is not an
entity or is a removed entity
TransactionRequiredException
- if invoked on a
container-managed entity manager of type
PersistenceContextType.TRANSACTION
and there is
no transactionvoid remove(java.lang.Object entity)
entity
- entity instance
java.lang.IllegalArgumentException
- if the instance is not an
entity or is a detached entity
TransactionRequiredException
- if invoked on a
container-managed entity manager of type
PersistenceContextType.TRANSACTION
and there is
no transaction<T> T find(java.lang.Class<T> entityClass, java.lang.Object primaryKey)
entityClass
- entity classprimaryKey
- primary key
java.lang.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<T> T find(java.lang.Class<T> entityClass, java.lang.Object primaryKey, java.util.Map<java.lang.String,java.lang.Object> properties)
entityClass
- entity classprimaryKey
- primary keyproperties
- standard and vendor-specific properties
and hints
java.lang.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<T> T find(java.lang.Class<T> entityClass, java.lang.Object primaryKey, LockModeType lockMode)
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:
PessimisticLockException
will be thrown if the database
locking failure causes transaction-level rollback
LockTimeoutException
will be thrown if the database
locking failure causes only statement-level rollback
entityClass
- entity classprimaryKey
- primary keylockMode
- lock mode
java.lang.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 null
TransactionRequiredException
- if there is no
transaction and a lock mode other than NONE is
specified
OptimisticLockException
- if the optimistic version
check fails
PessimisticLockException
- if pessimistic locking
fails and the transaction is rolled back
LockTimeoutException
- if pessimistic locking fails and
only the statement is rolled back
PersistenceException
- if an unsupported lock call
is made<T> T find(java.lang.Class<T> entityClass, java.lang.Object primaryKey, LockModeType lockMode, java.util.Map<java.lang.String,java.lang.Object> properties)
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:
PessimisticLockException
will be thrown if the database
locking failure causes transaction-level rollback
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.
entityClass
- entity classprimaryKey
- primary keylockMode
- lock modeproperties
- standard and vendor-specific properties
and hints
java.lang.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 null
TransactionRequiredException
- if there is no
transaction and a lock mode other than NONE
is
specified
OptimisticLockException
- if the optimistic version
check fails
PessimisticLockException
- if pessimistic locking
fails and the transaction is rolled back
LockTimeoutException
- if pessimistic locking fails and
only the statement is rolled back
PersistenceException
- if an unsupported lock call
is made<T> T getReference(java.lang.Class<T> entityClass, java.lang.Object primaryKey)
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.
entityClass
- entity classprimaryKey
- primary key
java.lang.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 null
EntityNotFoundException
- if the entity state
cannot be accessedvoid flush()
TransactionRequiredException
- if there is
no transaction
PersistenceException
- if the flush failsvoid setFlushMode(FlushModeType flushMode)
flushMode
- flush modeFlushModeType getFlushMode()
void lock(java.lang.Object entity, LockModeType lockMode)
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:
PessimisticLockException
will be thrown if the database
locking failure causes transaction-level rollback
LockTimeoutException
will be thrown if the database
locking failure causes only statement-level rollback
entity
- entity instancelockMode
- lock mode
java.lang.IllegalArgumentException
- if the instance is not an
entity or is a detached entity
TransactionRequiredException
- if there is no
transaction
EntityNotFoundException
- if the entity does not exist
in the database when pessimistic locking is
performed
OptimisticLockException
- if the optimistic version
check fails
PessimisticLockException
- if pessimistic locking fails
and the transaction is rolled back
LockTimeoutException
- if pessimistic locking fails and
only the statement is rolled back
PersistenceException
- if an unsupported lock call
is madevoid lock(java.lang.Object entity, LockModeType lockMode, java.util.Map<java.lang.String,java.lang.Object> 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:
PessimisticLockException
will be thrown if the database
locking failure causes transaction-level rollback
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.
entity
- entity instancelockMode
- lock modeproperties
- standard and vendor-specific properties
and hints
java.lang.IllegalArgumentException
- if the instance is not an
entity or is a detached entity
TransactionRequiredException
- if there is no
transaction
EntityNotFoundException
- if the entity does not exist
in the database when pessimistic locking is
performed
OptimisticLockException
- if the optimistic version
check fails
PessimisticLockException
- if pessimistic locking fails
and the transaction is rolled back
LockTimeoutException
- if pessimistic locking fails and
only the statement is rolled back
PersistenceException
- if an unsupported lock call
is madevoid refresh(java.lang.Object entity)
entity
- entity instance
java.lang.IllegalArgumentException
- if the instance is not
an entity or the entity is not managed
TransactionRequiredException
- if invoked on a
container-managed entity manager of type
PersistenceContextType.TRANSACTION
and there is
no transaction
EntityNotFoundException
- if the entity no longer
exists in the databasevoid refresh(java.lang.Object entity, java.util.Map<java.lang.String,java.lang.Object> properties)
If a vendor-specific property or hint is not recognized, it is silently ignored.
entity
- entity instanceproperties
- standard and vendor-specific properties
and hints
java.lang.IllegalArgumentException
- if the instance is not
an entity or the entity is not managed
TransactionRequiredException
- if invoked on a
container-managed entity manager of type
PersistenceContextType.TRANSACTION
and there is
no transaction
EntityNotFoundException
- if the entity no longer
exists in the databasevoid refresh(java.lang.Object entity, LockModeType lockMode)
If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
PessimisticLockException
will be thrown if the database
locking failure causes transaction-level rollback
LockTimeoutException
will be thrown if the
database locking failure causes only statement-level
rollback.
entity
- entity instancelockMode
- lock mode
java.lang.IllegalArgumentException
- if the instance is not
an entity or the entity is not managed
TransactionRequiredException
- 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 database
PessimisticLockException
- if pessimistic locking fails
and the transaction is rolled back
LockTimeoutException
- if pessimistic locking fails and
only the statement is rolled back
PersistenceException
- if an unsupported lock call
is madevoid refresh(java.lang.Object entity, LockModeType lockMode, java.util.Map<java.lang.String,java.lang.Object> properties)
If the lock mode type is pessimistic and the entity instance is found but cannot be locked:
PessimisticLockException
will be thrown if the database
locking failure causes transaction-level rollback
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.
entity
- entity instancelockMode
- lock modeproperties
- standard and vendor-specific properties
and hints
java.lang.IllegalArgumentException
- if the instance is not
an entity or the entity is not managed
TransactionRequiredException
- 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 database
PessimisticLockException
- if pessimistic locking fails
and the transaction is rolled back
LockTimeoutException
- if pessimistic locking fails and
only the statement is rolled back
PersistenceException
- if an unsupported lock call
is madevoid clear()
void detach(java.lang.Object entity)
entity
- entity instance
java.lang.IllegalArgumentException
- if the instance is not an
entityboolean contains(java.lang.Object entity)
entity
- entity instance
java.lang.IllegalArgumentException
- if not an entityLockModeType getLockMode(java.lang.Object entity)
entity
- entity instance
TransactionRequiredException
- if there is no
transaction
java.lang.IllegalArgumentException
- if the instance is not a
managed entity and a transaction is activevoid setProperty(java.lang.String propertyName, java.lang.Object value)
propertyName
- name of property or hintvalue
- value for property or hint
java.lang.IllegalArgumentException
- if the second argument is
not valid for the implementationjava.util.Map<java.lang.String,java.lang.Object> getProperties()
Query createQuery(java.lang.String qlString)
Query
for executing a
Java Persistence query language statement.
qlString
- a Java Persistence query string
java.lang.IllegalArgumentException
- if the query string is
found to be invalid<T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery)
TypedQuery
for executing a
criteria query.
criteriaQuery
- a criteria query object
java.lang.IllegalArgumentException
- if the criteria query is
found to be invalid<T> TypedQuery<T> createQuery(java.lang.String qlString, java.lang.Class<T> resultClass)
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.
qlString
- a Java Persistence query stringresultClass
- the type of the query result
java.lang.IllegalArgumentException
- if the query string is found
to be invalid or if the query result is found to
not be assignable to the specified typeQuery createNamedQuery(java.lang.String name)
Query
for executing a named query
(in the Java Persistence query language or in native SQL).
name
- the name of a query defined in metadata
java.lang.IllegalArgumentException
- if a query has not been
defined with the given name or if the query string is
found to be invalid<T> TypedQuery<T> createNamedQuery(java.lang.String name, java.lang.Class<T> resultClass)
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.
name
- the name of a query defined in metadataresultClass
- the type of the query result
java.lang.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 typeQuery createNativeQuery(java.lang.String sqlString)
Query
for executing
a native SQL statement, e.g., for update or delete.
sqlString
- a native SQL query string
Query createNativeQuery(java.lang.String sqlString, java.lang.Class resultClass)
Query
for executing
a native SQL query.
sqlString
- a native SQL query stringresultClass
- the class of the resulting instance(s)
Query createNativeQuery(java.lang.String sqlString, java.lang.String resultSetMapping)
Query
for executing
a native SQL query.
sqlString
- a native SQL query stringresultSetMapping
- the name of the result set mapping
void joinTransaction()
TransactionRequiredException
- if there is
no transaction<T> T unwrap(java.lang.Class<T> cls)
EntityManager
implementation does not support the specified class, the
PersistenceException
is thrown.
cls
- the class of the object to be returned. This is
normally either the underlying EntityManager
implementation
class or an interface that it implements.
PersistenceException
- if the provider does not
support the calljava.lang.Object getDelegate()
EntityManager
,
if available. The result of this method is implementation
specific. The unwrap
method is to be preferred for new
applications.
void close()
EntityManager
instance and any
Query
and TypedQuery
objects obtained from it will throw the IllegalStateException
except for getProperties
,
getTransaction
, and isOpen
(which will return false).
If this method is called when the entity manager is
associated with an active transaction, the persistence
context remains managed until the transaction completes.
java.lang.IllegalStateException
- if the entity manager
is container-managedboolean isOpen()
EntityTransaction getTransaction()
EntityTransaction
object.
The EntityTransaction
instance may be used serially to
begin and commit multiple transactions.
java.lang.IllegalStateException
- if invoked on a JTA
entity managerEntityManagerFactory getEntityManagerFactory()
java.lang.IllegalStateException
- if the entity manager has
been closedCriteriaBuilder getCriteriaBuilder()
CriteriaBuilder
for the creation of
CriteriaQuery
objects.
java.lang.IllegalStateException
- if the entity manager has
been closedMetamodel getMetamodel()
Metamodel
interface for access to the
metamodel of the persistence unit.
java.lang.IllegalStateException
- if the entity manager has
been closed
|
EclipseLink 2.2.0, build 'v20110202-r8913' API Reference | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |