javax.persistence.EntityManager - JPA interface
javax.persistence
Interface EntityManager
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.
- Since:
- JPA 1.0
- See Also:
-
Query
-
TypedQuery
-
CriteriaQuery
-
PersistenceContext
- Since:
- JPA 1.0
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. - Throws:
-
IllegalStateException
- if the entity manager is container-managed
- 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 metadata -
resultClass
- 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 string -
resultClass
- 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 string -
resultSetMapping
- 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 string -
resultClass
- 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
- Parameters:
-
entity
- entity instance
- Throws:
-
IllegalArgumentException
- if the instance is not an entity
- Since:
- JPA 2.0
- Parameters:
-
entityClass
- entity class -
primaryKey
- 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
- Parameters:
-
entityClass
- entity class -
primaryKey
- primary key -
properties
- 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 is not a valid type for that entity’s primary key or is null
- Since:
- JPA 2.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 class -
primaryKey
- primary key -
lockMode
- 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 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
- Since:
- JPA 2.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
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 class -
primaryKey
- primary key -
lockMode
- lock mode -
properties
- 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 null -
TransactionRequiredException
- if there is no transaction and a lock mode other thanNONE
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
- Since:
- JPA 2.0
- Throws:
-
TransactionRequiredException
- if there is no transaction -
PersistenceException
- if the flush fails
- Since:
- JPA 1.0
CriteriaBuilder
for the creation of CriteriaQuery
objects. - Returns:
- CriteriaBuilder instance
- Throws:
-
IllegalStateException
- if the entity manager has been closed
- Since:
- JPA 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:
- EntityManagerFactory instance
- Throws:
-
IllegalStateException
- if the entity manager has been closed
- Since:
- JPA 2.0
- Returns:
- flushMode
- Since:
- JPA 1.0
- Parameters:
-
entity
- entity instance
- Returns:
- lock mode
- Throws:
-
TransactionRequiredException
- if there is no transaction -
IllegalArgumentException
- if the instance is not a managed entity and a transaction is active
- Since:
- JPA 2.0
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
- Returns:
- map of properties and hints in effect for entity manager
- Since:
- JPA 2.0
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 class -
primaryKey
- 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 null -
EntityNotFoundException
- if the entity state cannot be accessed
- Since:
- JPA 1.0
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
- Returns:
- true until the entity manager has been closed
- Since:
- JPA 1.0
- Throws:
-
TransactionRequiredException
- if there is no transaction
- Since:
- JPA 1.0
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 instance -
lockMode
- lock mode
- Throws:
-
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 made
- Since:
- JPA 1.0
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 instance -
lockMode
- lock mode -
properties
- standard and vendor-specific properties and hints
- Throws:
-
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 made
- Since:
- JPA 2.0
- 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 entity -
TransactionRequiredException
- if invoked on a container-managed entity manager of typePersistenceContextType.TRANSACTION
and there is no transaction
- Since:
- JPA 1.0
- Parameters:
-
entity
- entity instance
- Throws:
-
EntityExistsException
- if the entity already exists. (If the entity already exists, theEntityExistsException
may be thrown when the persist operation is invoked, or theEntityExistsException
or anotherPersistenceException
may be thrown at flush or commit time.) -
IllegalArgumentException
- if the instance is not an entity -
TransactionRequiredException
- if invoked on a container-managed entity manager of typePersistenceContextType.TRANSACTION
and there is no transaction
- Since:
- JPA 1.0
- Parameters:
-
entity
- entity instance
- Throws:
-
IllegalArgumentException
- if the instance is not an entity or the entity is not managed -
TransactionRequiredException
- if invoked on a container-managed entity manager of typePersistenceContextType.TRANSACTION
and there is no transaction -
EntityNotFoundException
- if the entity no longer exists in the database
- Since:
- JPA 1.0
If a vendor-specific property or hint is not recognized, it is silently ignored.
- Parameters:
-
entity
- entity instance -
properties
- standard and vendor-specific properties and hints
- Throws:
-
IllegalArgumentException
- if the instance is not an entity or the entity is not managed -
TransactionRequiredException
- if invoked on a container-managed entity manager of typePersistenceContextType.TRANSACTION
and there is no transaction -
EntityNotFoundException
- if the entity no longer exists in the database
- Since:
- JPA 2.0
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 instance -
lockMode
- lock mode
- Throws:
-
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-managedEntityManager
instance withPersistenceContextType.TRANSACTION
or with a lock mode other thanNONE
-
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 made
- Since:
- JPA 2.0
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 instance -
lockMode
- lock mode -
properties
- standard and vendor-specific properties and hints
- Throws:
-
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-managedEntityManager
instance withPersistenceContextType.TRANSACTION
or with a lock mode other thanNONE
-
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 made
- Since:
- JPA 2.0
- Parameters:
-
entity
- entity instance
- Throws:
-
IllegalArgumentException
- if the instance is not an entity or is a detached entity -
TransactionRequiredException
- if invoked on a container-managed entity manager of typePersistenceContextType.TRANSACTION
and there is no transaction
- Since:
- JPA 1.0
- Parameters:
-
flushMode
- flush mode
- Since:
- JPA 1.0
- Parameters:
-
propertyName
- name of property or hint -
value
- value for property or hint
- Throws:
-
IllegalArgumentException
- if the second argument is not valid for the implementation
- Since:
- JPA 2.0
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