javax.persistence

Interface EntityManager

public interface EntityManager

Interface used to interact with the persistence context and to create executable query objects.

Method Summary

Methods

Modifier and Type	Method and Description
void	clear() Clear the persistence context, causing all managed entities to become detached.
void	close() Close an application-managed entity manager.
boolean	contains(Object entity) Check if the instance is a managed entity instance belonging to the current persistence context.
Query	createNamedQuery(String name) Create an instance of Query for executing a named query (in the Java Persistence query language or in native SQL).
<T> TypedQuery<T>	createNamedQuery(String name, Class<T> resultClass) Create an instance of TypedQuery for executing a Java Persistence query language named query.
Query	createNativeQuery(String sqlString) Create an instance of Query for executing a native SQL statement, e.g., for update or delete.
Query	createNativeQuery(String sqlString, Class<?> resultClass) Create an instance of Query for executing a native SQL query.
Query	createNativeQuery(String sqlString, String resultSetMapping) Create an instance of Query for executing a native SQL query.
<T> TypedQuery<T>	createQuery(CriteriaQuery<T> criteriaQuery) Create an instance of TypedQuery for executing a criteria query.
Query	createQuery(String qlString) Create an instance of Query for executing a Java Persistence query language statement.
<T> TypedQuery<T>	createQuery(String qlString, Class<T> resultClass) Create an instance of TypedQuery for executing a Java Persistence query language statement.
void	detach(Object entity) Remove the given entity from the persistence context, causing a managed entity to become detached.
<T> T	find(Class<T> entityClass, Object primaryKey) Find by primary key.
<T> T	find(Class<T> entityClass, Object primaryKey, LockModeType lockMode) Find by primary key and lock.
<T> T	find(Class<T> entityClass, Object primaryKey, LockModeType lockMode, Map<String,Object> properties) Find by primary key and lock, using the specified properties.
<T> T	find(Class<T> entityClass, Object primaryKey, Map<String,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.
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(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.
Map<String,Object>	getProperties() Get the properties and hints and associated values that are in effect for the entity manager.
<T> T	getReference(Class<T> entityClass, Object primaryKey) Get an instance, whose state may be lazily fetched.
EntityTransaction	getTransaction() Return the resource-level EntityTransaction object.
boolean	isJoinedToTransaction() Determine whether the entity manager is joined to the current transaction.
boolean	isOpen() Determine whether the entity manager is open.
void	joinTransaction() Indicate to the entity manager that a JTA transaction is active.
void	lock(Object entity, LockModeType lockMode) Lock an entity instance that is contained in the persistence context with the specified lock mode type.
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.
<T> T	merge(T entity) Merge the state of the given entity into the current persistence context.
void	persist(Object entity) Make an instance managed and persistent.
void	refresh(Object entity) Refresh the state of the instance from the database, overwriting changes made to the entity, if any.
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.
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.
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.
void	remove(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(String propertyName, Object value) Set an entity manager property or hint.
<T> T	unwrap(Class<T> cls) Return an object of the specified type to allow access to the provider-specific API.

Method Detail

clear

void clear()

Clear the persistence context, causing all managed entities to become detached. Changes made to entities that have not been flushed to the database will not be persisted.

close

void close()

Close an application-managed entity manager. After the close method has been invoked, all methods on the 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 joined to an active transaction, the persistence context remains managed until the transaction completes.

Throws:

IllegalStateException - if the entity manager is container-managed

contains

boolean contains(Object entity)

Check if the instance is a managed entity instance belonging to the current persistence context.

Parameters:

entity - the entity instance

Returns:

boolean indicating if entity is in persistence context

Throws:

IllegalArgumentException - if not an entity

createNamedQuery

Query createNamedQuery(String name)

Create an instance of 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

createNamedQuery

<T> TypedQuery<T> createNamedQuery(String name,
                                 Class<T> resultClass)

Create an instance of 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.[27]

Type Parameters:

T - query result type

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

createNativeQuery

Query createNativeQuery(String sqlString)

Create an instance of Query for executing a native SQL statement, e.g., for update or delete. If the query is not an update or delete query, query execution will result in each row of the SQL result being returned as a result of type Object[] (or a result of type Object if there is only one column in the select list.) Column values are returned in the order of their appearance in the select list and default JDBC type mappings are applied.

Parameters:

sqlString - a native SQL query string

Returns:

the new query instance

createNativeQuery

Query createNativeQuery(String sqlString,
                      Class<?> resultClass)

Create an instance of 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

createNativeQuery

Query createNativeQuery(String sqlString,
                      String resultSetMapping)

Create an instance of 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

createQuery

<T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery)

Create an instance of TypedQuery for executing a criteria query.

Type Parameters:

T - query result type

Parameters:

criteriaQuery - a criteria query object

Returns:

the new query instance

Throws:

IllegalArgumentException - if the criteria query is found to be invalid

createQuery

Query createQuery(String qlString)

Create an instance of 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

createQuery

<T> TypedQuery<T> createQuery(String qlString,
                            Class<T> resultClass)

Create an instance of 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.[26]

Type Parameters:

T - query result type

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

detach

void detach(Object entity)

Remove the given entity from the persistence context, causing a managed entity to become detached. Unflushed changes made to the entity if any (including removal of the entity), will not be synchronized to the database. Entities which previously referenced the detached entity will continue to reference it.

Parameters:

entity - the entity instance

Throws:

IllegalArgumentException - if the instance is not an entity

find

<T> T find(Class<T> entityClass,
         Object primaryKey)

Find by primary key. Search for an entity of the specified class and primary key. If the entity instance is contained in the persistence context it is returned from there.

Type Parameters:

T - the object type of the entity

Parameters:

entityClass - the class of the entity

primaryKey - the 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

find

<T> T find(Class<T> entityClass,
         Object primaryKey,
         LockModeType lockMode)

Find by primary key and lock. 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, and the effect of this method is the same as if the lock method had been called on the entity. 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

Type Parameters:

T - the object type of the entity

Parameters:

entityClass - the class of the entity

primaryKey - the primary key

lockMode - the 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 or if invoked on an entity manager which has not been joined to the current 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

find

<T> T find(Class<T> entityClass,
         Object primaryKey,
         LockModeType lockMode,
         Map<String,Object> 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.

Type Parameters:

T - the object type of the entity

Parameters:

entityClass - the class of the entity

primaryKey - the primary key

lockMode - the 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 than NONE is specified or if invoked on an entity manager which has not been joined to the current 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

find

<T> T find(Class<T> entityClass,
         Object primaryKey,
         Map<String,Object> properties)

Find by primary key, using the specified properties. Search for an entity of the specified class and primary key. If the entity instance is contained in the persistence context it is returned from there. If a vendor-specific property or hint is not recognized, it is silently ignored.

Type Parameters:

T - the object type of the entity

Parameters:

entityClass - the class of the entity

primaryKey - the 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

flush

void flush()

Synchronize the persistence context to the underlying database.

Throws:

TransactionRequiredException - if there is no transaction or if the entity manager has not been joined to the current transaction

PersistenceException - if the flush fails

getCriteriaBuilder

CriteriaBuilder getCriteriaBuilder()

Return an instance of CriteriaBuilder for the creation of CriteriaQuery objects.

Returns:

CriteriaBuilder instance

Throws:

IllegalStateException - if the entity manager has been closed

getDelegate

Object getDelegate()

Return the underlying provider object for the 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

getEntityManagerFactory

EntityManagerFactory getEntityManagerFactory()

Return the entity manager factory for the entity manager.

Returns:

EntityManagerFactory instance

Throws:

IllegalStateException - if the entity manager has been closed

getFlushMode

FlushModeType getFlushMode()

Get the flush mode that applies to all objects contained in the persistence context.

Returns:

flushMode

getLockMode

LockModeType getLockMode(Object entity)

Get the current lock mode for the entity instance.

Parameters:

entity - the entity instance

Returns:

lock mode

Throws:

TransactionRequiredException - if there is no transaction or if the entity manager has not been joined to the current transaction

IllegalArgumentException - if the instance is not a managed entity and a transaction is active

getMetamodel

Metamodel getMetamodel()

Return an instance of Metamodel interface for access to the metamodel of the persistence unit.

Returns:

Metamodel instance

Throws:

IllegalStateException - if the entity manager has been closed

getProperties

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

getReference

<T> 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.

Type Parameters:

T - the object type of the entity

Parameters:

entityClass - the class of the entity

primaryKey - the 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

getTransaction

EntityTransaction getTransaction()

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

isJoinedToTransaction

boolean isJoinedToTransaction()

Determine whether the entity manager is joined to the current transaction. Returns false if the entity manager is not joined to the current transaction or if no transaction is active

Returns:

boolean

isOpen

boolean isOpen()

Determine whether the entity manager is open.

Returns:

true until the entity manager has been closed

joinTransaction

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 or on an entity manager of type SynchronizationType.UNSYNCHRONIZED to associate it with the current JTA transaction.

Throws:

TransactionRequiredException - if there is no transaction

lock

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 - the entity instance

lockMode - the lock mode

Throws:

IllegalArgumentException - if the instance is not an entity or is a detached entity

TransactionRequiredException - if there is no transaction or if invoked on an entity manager which has not been joined to the current 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

lock

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 - the entity instance

lockMode - the 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 or if invoked on an entity manager which has not been joined to the current 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

merge

<T> T merge(T entity)

Merge the state of the given entity into the current persistence context.

Type Parameters:

T - the object type of the entity

Parameters:

entity - the 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 there is no transaction when invoked on a container-managed entity manager that is of type PersistenceContextType.TRANSACTION.

persist

void persist(Object entity)

Make an instance managed and persistent.

Parameters:

entity - the 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 entity

TransactionRequiredException - if there is no transaction when invoked on a container-managed entity manager that is of type PersistenceContextType.TRANSACTION.

refresh

void refresh(Object entity)

Refresh the state of the instance from the database, overwriting changes made to the entity, if any.

Parameters:

entity - the entity instance

Throws:

IllegalArgumentException - if the instance is not an entity or the entity is not managed

TransactionRequiredException - if there is no transaction when invoked on a container-managed entity manager that is of type PersistenceContextType.TRANSACTION.

EntityNotFoundException - if the entity no longer exists in the database

refresh

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 - the entity instance

lockMode - the lock mode

Throws:

IllegalArgumentException - if the instance is not an entity or the entity is not managed

TransactionRequiredException - if invoked on an entity manager of type PersistenceContextType.TRANSACTION when there is no transaction; if invoked on an extended entity manager when there is no transaction and a lock mode other than NONE has been specified; or if invoked on an extended entity manager that has not been joined to the current transaction and a lock mode other than NONE has been specified

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

refresh

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 - the entity instance

lockMode - the 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 invoked on an entity manager of type PersistenceContextType.TRANSACTION when there is no transaction; if invoked on an extended entity manager when there is no transaction and a lock mode other than NONE has been specified; or if invoked on an extended entity manager that has not been joined to the current transaction and a lock mode other than NONE has been specified

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

refresh

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 - the 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 there is no transaction when invoked on a container-managed entity manager that is of type PersistenceContextType.TRANSACTION.

EntityNotFoundException - if the entity no longer exists in the database

remove

void remove(Object entity)

Remove the entity instance.

Parameters:

entity - the entity instance

Throws:

IllegalArgumentException - if the instance is not an entity or is a detached entity

TransactionRequiredException - if there is no transaction when invoked on a container-managed entity manager that is of type PersistenceContextType.TRANSACTION.

setFlushMode

void setFlushMode(FlushModeType flushMode)

Set the flush mode that applies to all objects contained in the persistence context.

Parameters:

flushMode - the flush mode

setProperty

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 hint

value - the value of the property or hint

Throws:

IllegalArgumentException - if the second argument is not valid for the implementation

unwrap

<T> 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.

Type Parameters:

T - type of the class

Parameters:

cls - the class of the object to be returned. This is normally either the underlying EntityManager 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