Module jakarta.persistence

Package jakarta.persistence

Interface EntityManager

All Superinterfaces:

AutoCloseable

public interface EntityManager
extends AutoCloseable

Interface used to interact with the persistence context.

An instance of EntityManager must be obtained from an EntityManagerFactory, and is only able to manage persistence of entities belonging to the associated persistence unit.

An application-managed EntityManager may be created via a call to EntityManagerFactory.createEntityManager(). The EntityManager must be explicitly closed via a call to close(), to allow resources to be cleaned up by the persistence provider. This approach places almost complete responsibility for cleanup and exception management on the client, and is thus considered quite error-prone. It is much safer to use the methods EntityManagerFactory.runInTransaction(java.util.function.Consumer<jakarta.persistence.EntityManager>) and EntityManagerFactory.callInTransaction(java.util.function.Function<jakarta.persistence.EntityManager, R>).

entityManagerFactory.runInTransaction(entityManager -> {
    // do work in a persistence context
    ...
});

In the Jakarta EE environment, a container-managed EntityManager may be obtained by dependency injection, using PersistenceContext.

// inject the container-managed entity manager
@PersistenceContext(unitName="orderMgt")
EntityManager entityManager;

If the persistence unit has resource local transaction management, transactions must be managed using the EntityTransaction obtained by calling getTransaction().

A complete idiom for custom application management of the EntityManager and its associated resource-local EntityTransaction is as follows:

EntityManager entityManager = entityManagerFactory.createEntityManager();
EntityTransaction transaction = entityManager.getTransaction();
try {
    transaction.begin();
    // do work
    ...
    transaction.commit();
}
catch (Exception e) {
    if (transaction.isActive()) transaction.rollback();
    throw e;
}
finally {
    entityManager.close();
}

Each EntityManager instance is associated with a distinct persistence context. A persistence context is a set of entity instances in which for any given persistent entity identity (defined by an entity type and primary key) there is at most one entity instance. The entity instances associated with a persistence context are considered managed objects, with a well-defined lifecycle under the control of the persistence provider.

Any entity instance can be characterized as being in one of the following lifecycle states:

• A new entity has no persistent identity, and is not yet associated with any persistence context.
• A managed entity is an instance with a persistent identity that is currently associated with a persistence context.
• A detached entity is an instance with a persistent identity that is not (or no longer) associated with any active persistence context.
• A removed entity is an instance with a persistent identity, and associated with a persistence context, that is scheduled for removal from the database upon transaction commit.

The EntityManager API is used to perform operations that affect the state of the persistence context, or that modify the lifecycle state of individual entity instances. The client may persist(java.lang.Object) and remove(java.lang.Object) instances, find entities by their primary key, and execute queries which range over entity types. An entity may be disassociated from the persistence context by calling detach(java.lang.Object), and a persistence context may be completely cleared, detaching all its entities, by calling clear().

The client may also make changes to the state of an entity instance by mutating the entity directly, or it may request that the state of a detached instance be merged, replacing the state of a managed instance with the same persistent identity. Note that there is no explicit "update" operation; since an entity is a managed object, modifications to its persistent fields and properties are automatically detected, as long as it is associated with an active persistence context.

Modifications to the state of entities associated with a persistence context are not immediately synchronized with the database. Synchronization happens during a process called flush. The timing of the flush process depends on the flush mode, which may be set explicitly by calling setFlushMode(FlushModeType).

• For FlushModeType.COMMIT, the persistence context is flushed before the transaction commits.
• For FlushModeType.AUTO, which is the default, the persistence context must also be flushed before execution of any query whose result set would be affected by unflushed modifications to entities associated with the persistence context.

The client may force an immediate flush to occur by calling flush().

At any given moment, a persistence context might hold an optimistic or pessimistic lock on an entity instance. The full range of possible lock types is enumerated by LockModeType. Some operations of this interface, including the methods lock(Object, LockModeType), refresh(Object, LockModeType), and find(Class, Object, LockModeType), accept an explicit LockModeType, allowing the client to request a specific type of lock.

Interaction of the persistence context (or first-level cache) with the second-level cache, if any, may be controlled by calling setCacheRetrieveMode(CacheRetrieveMode) and setCacheStoreMode(CacheStoreMode).

Some operations accept one or more built-in and vendor-specific options:

• find(Class, Object, FindOption...) and find(EntityGraph, Object, FindOption...) accept FindOptions,
• refresh(Object, RefreshOption...) accepts RefreshOptions, and
• lock(Object, LockModeType, LockOption...) accepts LockOptions.

Since:

1.0

See Also:

• Query
• TypedQuery
• CriteriaQuery
• PersistenceContext
• StoredProcedureQuery
• EntityManagerFactory

Method Summary

Modifier and Type	Method	Description
<C, T> T	callWithConnection(ConnectionFunction<C,T> function)	Call the given function and return its result using the database connection underlying this EntityManager.
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)	Determine if the given object is a managed entity instance belonging to the current persistence context.
<T> EntityGraph<T>	createEntityGraph(Class<T> rootType)	Create a new mutable EntityGraph, allowing dynamic definition of an entity graph.
EntityGraph<?>	createEntityGraph(String graphName)	Obtain a mutable copy of a named EntityGraph, or return null if there is no entity graph with the given name.
Query	createNamedQuery(String name)	Create an instance of Query for executing a named query written in the Jakarta Persistence query language or in native SQL.
<T> TypedQuery<T>	createNamedQuery(String name, Class<T> resultClass)	Create an instance of TypedQuery for executing a Jakarta Persistence query language named query.
StoredProcedureQuery	createNamedStoredProcedureQuery(String name)	Create an instance of StoredProcedureQuery for executing a stored procedure in the database.
Query	createNativeQuery(String sqlString)	Create an instance of Query for executing a native SQL statement, e.g., for update or delete.
<T> Query	createNativeQuery(String sqlString, Class<T> 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.
Query	createQuery(CriteriaDelete<?> deleteQuery)	Create an instance of Query for executing a criteria delete query.
<T> TypedQuery<T>	createQuery(CriteriaQuery<T> criteriaQuery)	Create an instance of TypedQuery for executing a criteria query.
<T> TypedQuery<T>	createQuery(CriteriaSelect<T> selectQuery)	Create an instance of TypedQuery for executing a criteria query, which may be a union or intersection of top-level queries.
Query	createQuery(CriteriaUpdate<?> updateQuery)	Create an instance of Query for executing a criteria update query.
<T> TypedQuery<T>	createQuery(TypedQueryReference<T> reference)	Create an instance of TypedQuery for executing a named query written in the Jakarta Persistence query language or in native SQL.
Query	createQuery(String qlString)	Create an instance of Query for executing a Jakarta Persistence query language statement.
<T> TypedQuery<T>	createQuery(String qlString, Class<T> resultClass)	Create an instance of TypedQuery for executing a Jakarta Persistence query language statement.
StoredProcedureQuery	createStoredProcedureQuery(String procedureName)	Create an instance of StoredProcedureQuery for executing a stored procedure in the database.
StoredProcedureQuery	createStoredProcedureQuery(String procedureName, Class<?>... resultClasses)	Create an instance of StoredProcedureQuery for executing a stored procedure in the database.
StoredProcedureQuery	createStoredProcedureQuery(String procedureName, String... resultSetMappings)	Create an instance of StoredProcedureQuery for executing a stored procedure in the database.
void	detach(Object entity)	Evict the given managed or removed entity from the persistence context, causing the entity to become immediately detached.
<T> T	find(EntityGraph<T> entityGraph, Object primaryKey, FindOption... options)	Find an instance of the root entity of the given EntityGraph by primary key, using the specified options, and interpreting the EntityGraph as a load graph.
<T> T	find(Class<T> entityClass, Object primaryKey)	Find by primary key.
<T> T	find(Class<T> entityClass, Object primaryKey, FindOption... options)	Find an instance of the given entity class by primary key, using the specified options.
<T> T	find(Class<T> entityClass, Object primaryKey, LockModeType lockMode)	Find by primary key and obtain the given lock type for the resulting entity.
<T> T	find(Class<T> entityClass, Object primaryKey, LockModeType lockMode, Map<String,Object> properties)	Find by primary key and lock the entity, 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 changes held in the persistence context to the underlying database.
CacheRetrieveMode	getCacheRetrieveMode()	The cache retrieval mode for this persistence context.
CacheStoreMode	getCacheStoreMode()	The cache storage mode for this persistence context.
CriteriaBuilder	getCriteriaBuilder()	Obtain an instance of CriteriaBuilder which may be used to construct CriteriaQuery objects.
Object	getDelegate()	Return the underlying provider object for the EntityManager, if available.
EntityGraph<?>	getEntityGraph(String graphName)	Obtain a named EntityGraph.
<T> List<EntityGraph<? super T>>	getEntityGraphs(Class<T> entityClass)	Return all named EntityGraphs that are defined for the given entity class type.
EntityManagerFactory	getEntityManagerFactory()	The entity manager factory which created this 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 held by this persistence context on the given managed entity instance.
Metamodel	getMetamodel()	Obtain an instance of the Metamodel interface which provides access to metamodel objects describing the managed types belonging to the persistence unit.
Map<String,Object>	getProperties()	The properties and hints and their associated values which are in effect for this entity manager.
<T> T	getReference(Class<T> entityClass, Object primaryKey)	Obtain a reference to an instance of the given entity class with the given primary key, whose state may be lazily fetched.
<T> T	getReference(T entity)	Obtain a reference to an instance of the entity class of the given object, with the same primary key as the given object, 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 and join the persistence context to it.
void	lock(Object entity, LockModeType lockMode)	Lock an entity instance belonging to the persistence context, obtaining the specified lock mode.
void	lock(Object entity, LockModeType lockMode, LockOption... options)	Lock an entity instance belonging to the persistence context, obtaining the specified lock mode, using the specified options.
void	lock(Object entity, LockModeType lockMode, Map<String,Object> properties)	Lock an entity instance belonging to the persistence context, obtaining the specified lock mode, using the specified properties.
<T> T	merge(T entity)	Merge the state of the given new or detached entity instance into the current persistence context, resulting in, respectively, an insert or possible update when the persistence context is synchronized with the database.
void	persist(Object entity)	Make a new entity instance managed and persistent, resulting in its insertion in the database when the persistence context is synchronized with the database, or make a removed entity managed, undoing the effect of a previous call to remove(Object).
void	refresh(Object entity)	Refresh the state of the given managed entity instance from the database, overwriting unflushed changes made to the entity, if any.
void	refresh(Object entity, LockModeType lockMode)	Refresh the state of the given managed entity instance from the database, overwriting unflushed changes made to the entity, if any, and obtain the given lock mode.
void	refresh(Object entity, LockModeType lockMode, Map<String,Object> properties)	Refresh the state of the given managed entity instance from the database, overwriting unflushed changes made to the entity, if any, and obtain the given lock mode, using the specified properties.
void	refresh(Object entity, RefreshOption... options)	Refresh the state of the given managed entity instance from the database, using the specified options, overwriting changes made to the entity, if any.
void	refresh(Object entity, Map<String,Object> properties)	Refresh the state of the given managed entity instance from the database, using the specified properties, and overwriting unflushed changes made to the entity, if any.
void	remove(Object entity)	Mark a managed entity instance as removed, resulting in its deletion from the database when the persistence context is synchronized with the database.
<C> void	runWithConnection(ConnectionConsumer<C> action)	Execute the given action using the database connection underlying this EntityManager.
void	setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode)	Set the default cache retrieval mode for this persistence context.
void	setCacheStoreMode(CacheStoreMode cacheStoreMode)	Set the default cache storage mode for this persistence context.
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 a provider-specific API.

Method Details

persist

void persist(Object entity)

Make a new entity instance managed and persistent, resulting in its insertion in the database when the persistence context is synchronized with the database, or make a removed entity managed, undoing the effect of a previous call to remove(Object). This operation cascades to every entity related by an association marked cascade=PERSIST. If the given entity instance is already managed, that is, if it already belongs to this persistence context, and has not been marked for removal, it is itself ignored, but the operation still cascades.

Parameters:

entity - a new, managed, or removed entity instance

Throws:

EntityExistsException - if the given entity is detached (if the entity is detached, 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 given 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

merge

<T> T merge(T entity)

Merge the state of the given new or detached entity instance into the current persistence context, resulting in, respectively, an insert or possible update when the persistence context is synchronized with the database. Return a managed instance with the same persistent state as the given entity instance, but a distinct Java object identity. If the given entity is detached, the returned entity has the same persistent identity. This operation cascades to every entity related by an association marked cascade=MERGE. If the given entity instance is managed, that is, if it belongs to this persistence context, and has not been marked for removal, it is itself ignored, but the operation still cascades, and it is returned directly.

Parameters:

entity - a new, managed, or detached entity instance

Returns:

the managed instance that the state was merged to

Throws:

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

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

remove

void remove(Object entity)

Mark a managed entity instance as removed, resulting in its deletion from the database when the persistence context is synchronized with the database. This operation cascades to every entity related by an association marked cascade=REMOVE. If the given entity instance is already removed, it is ignored. If the given entity is new, it is itself ignored, but the operation still cascades.

Parameters:

entity - a managed, new, or removed 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 type PersistenceContextType.TRANSACTION and there is no transaction

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.

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 if the second argument is not a valid type for that entity's primary key or is null

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.

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 if the second argument is not a valid type for that entity's primary key or is null

Since:

2.0

find

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

Find by primary key and obtain the given lock type for the resulting entity. 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(java.lang.Object, jakarta.persistence.LockModeType) 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 is thrown.

If the lock mode type is pessimistic and the entity instance is found but cannot be locked:

• the PessimisticLockException is thrown if the database locking failure causes transaction-level rollback
• the LockTimeoutException is 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 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

Since:

2.0

find

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

Find by primary key and lock the entity, 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 is thrown.

If the lock mode type is pessimistic and the entity instance is found but cannot be locked:

• the PessimisticLockException is thrown if the database locking failure causes transaction-level rollback
• the LockTimeoutException is 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 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

Since:

2.0

find

<T> T find(Class<T> entityClass,
 Object primaryKey,
 FindOption... options)

Find an instance of the given entity class by primary key, using the specified options. Search for an entity with the specified class and primary key. If the given options include a LockModeType, 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 is thrown.

If the lock mode type is pessimistic and the entity instance is found but cannot be locked:

• the PessimisticLockException is thrown if the database locking failure causes transaction-level rollback
• the LockTimeoutException is thrown if the database locking failure causes only statement-level rollback

If a vendor-specific option is not recognized, it is silently ignored.

Portable applications should not rely on the standard timeout option. Depending on the database in use and the locking mechanisms used by the provider, this option may or may not be observed.

Parameters:

entityClass - entity class

primaryKey - primary key

options - standard and vendor-specific options

Returns:

the found entity instance or null if the entity does not exist

Throws:

IllegalArgumentException - if there are contradictory options, if the first argument does not denote an entity type belonging to the persistence unit, or if the second argument is not a valid non-null instance of the entity primary key type

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

Since:

3.2

find

<T> T find(EntityGraph<T> entityGraph,
 Object primaryKey,
 FindOption... options)

Find an instance of the root entity of the given EntityGraph by primary key, using the specified options, and interpreting the EntityGraph as a load graph. Search for an entity with the specified type and primary key. If the given options include a LockModeType, 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 is thrown.

If the lock mode type is pessimistic and the entity instance is found but cannot be locked:

• the PessimisticLockException is thrown if the database locking failure causes transaction-level rollback
• the LockTimeoutException is thrown if the database locking failure causes only statement-level rollback

If a vendor-specific option is not recognized, it is silently ignored.

Portable applications should not rely on the standard timeout option. Depending on the database in use and the locking mechanisms used by the provider, this option may or may not be observed.

Parameters:

entityGraph - entity graph interpreted as a load graph

primaryKey - primary key

options - standard and vendor-specific options

Returns:

the found entity instance or null if the entity does not exist

Throws:

IllegalArgumentException - if there are contradictory options, if the first argument does not denote an entity type belonging to the persistence unit, or if the second argument is not a valid non-null instance of the entity primary key type

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

Since:

3.2

getReference

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

Obtain a reference to an instance of the given entity class with the given primary key, 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 but not required to throw the EntityNotFoundException when getReference() is called.)

This operation allows the application to create an association to an entity without loading its state from the database.

The application should not expect the instance state to 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:

a reference to the 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

getReference

<T> T getReference(T entity)

Obtain a reference to an instance of the entity class of the given object, with the same primary key as the given object, whose state may be lazily fetched. The given object may be persistent or detached, but may be neither new nor removed.

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 but not required to throw the EntityNotFoundException when getReference() is called.)

This operation allows the application to create an association to an entity without loading its state from the database.

The application should not expect the instance state to be available upon detachment, unless it was accessed by the application while the entity manager was open.

Parameters:

entity - a persistent or detached entity instance

Returns:

a reference to the entity instance

Throws:

IllegalArgumentException - if the given object is not an entity, or if it is neither persistent nor detached

EntityNotFoundException - if the entity state cannot be accessed

flush

void flush()

Synchronize changes held in 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

setFlushMode

void setFlushMode(FlushModeType flushMode)

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

Parameters:

flushMode - flush mode

getFlushMode

FlushModeType getFlushMode()

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

Returns:

the current FlushModeType

lock

void lock(Object entity,
 LockModeType lockMode)

Lock an entity instance belonging to the persistence context, obtaining the specified lock mode.

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 is thrown.

If the lock mode type is pessimistic and the entity instance is found but cannot be locked:

• the PessimisticLockException is thrown if the database locking failure causes transaction-level rollback
• the LockTimeoutException is thrown if the database locking failure causes only statement-level rollback

Parameters:

entity - a managed 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 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 belonging to the persistence context, obtaining the specified lock mode, using the 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 is thrown.

If the lock mode type is pessimistic and the entity instance is found but cannot be locked:

• the PessimisticLockException is thrown if the database locking failure causes transaction-level rollback
• the LockTimeoutException ia 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 - a managed 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 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

Since:

2.0

lock

void lock(Object entity,
 LockModeType lockMode,
 LockOption... options)

Lock an entity instance belonging to the persistence context, obtaining the specified lock mode, using the specified options.

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 is thrown.

If the lock mode type is pessimistic and the entity instance is found but cannot be locked:

• the PessimisticLockException is thrown if the database locking failure causes transaction-level rollback
• the LockTimeoutException is thrown if the database locking failure causes only statement-level rollback

If a vendor-specific LockOption is not recognized, it is silently ignored.

Portable applications should not rely on the standard timeout option. Depending on the database in use and the locking mechanisms used by the provider, the option may or may not be observed.

Parameters:

entity - a managed entity instance

lockMode - lock mode

options - standard and vendor-specific options

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

Since:

3.2

refresh

void refresh(Object entity)

Refresh the state of the given managed entity instance from the database, overwriting unflushed changes made to the entity, if any. This operation cascades to every entity related by an association marked cascade=REFRESH.

Parameters:

entity - a managed 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 of type PersistenceContextType.TRANSACTION

EntityNotFoundException - if the entity no longer exists in the database

refresh

void refresh(Object entity,
 Map<String,Object> properties)

Refresh the state of the given managed entity instance from the database, using the specified properties, and overwriting unflushed changes made to the entity, if any. This operation cascades to every entity related by an association marked cascade=REFRESH.

If a vendor-specific property or hint is not recognized, it is silently ignored.

Parameters:

entity - a managed 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 of type PersistenceContextType.TRANSACTION

EntityNotFoundException - if the entity no longer exists in the database

Since:

2.0

refresh

void refresh(Object entity,
 LockModeType lockMode)

Refresh the state of the given managed entity instance from the database, overwriting unflushed changes made to the entity, if any, and obtain the given lock mode. This operation cascades to every entity related by an association marked cascade=REFRESH.

If the lock mode type is pessimistic and the entity instance is found but cannot be locked:

• the PessimisticLockException is thrown if the database locking failure causes transaction-level rollback
• the LockTimeoutException is thrown if the database locking failure causes only statement-level rollback.

Parameters:

entity - a managed entity instance

lockMode - lock mode

Throws:

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

TransactionRequiredException - if invoked on a container-managed 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 LockModeType.NONE was specified; or if invoked on an extended entity manager that has not been joined to the current transaction and any lock mode other than NONE was 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

Since:

2.0

refresh

void refresh(Object entity,
 LockModeType lockMode,
 Map<String,Object> properties)

Refresh the state of the given managed entity instance from the database, overwriting unflushed changes made to the entity, if any, and obtain the given lock mode, using the specified properties. This operation cascades to every entity related by an association marked cascade=REFRESH.

If the lock mode type is pessimistic and the entity instance is found but cannot be locked:

• the PessimisticLockException is thrown if the database locking failure causes transaction-level rollback
• the LockTimeoutException is 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 - a managed entity instance

lockMode - lock mode

properties - standard and vendor-specific properties and hints

Throws:

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

TransactionRequiredException - if invoked on a container-managed 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 LockModeType.NONE was specified; or if invoked on an extended entity manager that has not been joined to the current transaction and any lock mode other than NONE was 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

Since:

2.0

refresh

void refresh(Object entity,
 RefreshOption... options)

Refresh the state of the given managed entity instance from the database, using the specified options, overwriting changes made to the entity, if any. If the supplied options include a LockModeType, lock the given entity, obtaining the given lock mode. This operation cascades to every entity related by an association marked cascade=REFRESH.

If the lock mode type is pessimistic and the entity instance is found but cannot be locked:

• the PessimisticLockException is thrown if the database locking failure causes transaction-level rollback
• the LockTimeoutException is thrown if the database locking failure causes only statement-level rollback.

If a vendor-specific RefreshOption is not recognized, it is silently ignored.

Portable applications should not rely on the standard timeout option. Depending on the database in use and the locking mechanisms used by the provider, the hint may or may not be observed.

Parameters:

entity - a managed entity instance

options - standard and vendor-specific options

Throws:

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

TransactionRequiredException - if invoked on a container-managed 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 LockModeType.NONE was specified; or if invoked on an extended entity manager that has not been joined to the current transaction and any lock mode other than NONE was 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

Since:

3.2

clear

void clear()

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

detach

void detach(Object entity)

Evict the given managed or removed entity from the persistence context, causing the entity to become immediately detached. Unflushed changes made to the entity, if any, including deletion of the entity, will never be synchronized to the database. Managed entities which reference the given entity continue to reference it. This operation cascades to every entity related by an association marked cascade=DETACH. If the given entity instance is new or detached, that is, if it is not associated with this persistence context, it is ignored.

Parameters:

entity - a managed or removed entity instance

Throws:

IllegalArgumentException - if the instance is not an entity

Since:

2.0

contains

boolean contains(Object entity)

Determine if the given object is a managed entity instance belonging to the current persistence context.

Parameters:

entity - entity instance

Returns:

boolean value indicating if entity belongs to the persistence context

Throws:

IllegalArgumentException - if not an entity

getLockMode

LockModeType getLockMode(Object entity)

Get the current lock mode held by this persistence context on the given managed entity instance.

Parameters:

entity - a managed entity instance

Returns:

the lock mode currently held

Throws:

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

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

Since:

2.0

setCacheRetrieveMode

void setCacheRetrieveMode(CacheRetrieveMode cacheRetrieveMode)

Set the default cache retrieval mode for this persistence context.

Parameters:

cacheRetrieveMode - cache retrieval mode

Since:

3.2

setCacheStoreMode

void setCacheStoreMode(CacheStoreMode cacheStoreMode)

Set the default cache storage mode for this persistence context.

Parameters:

cacheStoreMode - cache storage mode

Since:

3.2

getCacheRetrieveMode

CacheRetrieveMode getCacheRetrieveMode()

The cache retrieval mode for this persistence context.

Since:

3.2

getCacheStoreMode

CacheStoreMode getCacheStoreMode()

The cache storage mode for this persistence context.

Since:

3.2

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 the property or hint

value - value for the property or hint

Throws:

IllegalArgumentException - if the property or hint name is recognized by the implementation, but the second argument is not valid value

Since:

2.0

getProperties

Map<String,Object> getProperties()

The properties and hints and their associated values which are in effect for this entity manager. Modifying the contents of the returned map does not change the configuration in effect.

Returns:

a map of properties and hints currently in effect

Since:

2.0

createQuery

Query createQuery(String qlString)

Create an instance of Query for executing a Jakarta Persistence query language statement.

Parameters:

qlString - a Jakarta Persistence query string

Returns:

the new query instance

Throws:

IllegalArgumentException - if the query string is found to be invalid

createQuery

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

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

2.0

createQuery

<T> TypedQuery<T> createQuery(CriteriaSelect<T> selectQuery)

Create an instance of TypedQuery for executing a criteria query, which may be a union or intersection of top-level queries.

Parameters:

selectQuery - a criteria query object

Returns:

the new query instance

Throws:

IllegalArgumentException - if the criteria query is found to be invalid

Since:

3.2

createQuery

Query createQuery(CriteriaUpdate<?> updateQuery)

Create an instance of Query for executing a criteria update query.

Parameters:

updateQuery - a criteria update query object

Returns:

the new query instance

Throws:

IllegalArgumentException - if the update query is found to be invalid

Since:

2.1

createQuery

Query createQuery(CriteriaDelete<?> deleteQuery)

Create an instance of Query for executing a criteria delete query.

Parameters:

deleteQuery - a criteria delete query object

Returns:

the new query instance

Throws:

IllegalArgumentException - if the delete query is found to be invalid

Since:

2.1

createQuery

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

Create an instance of TypedQuery for executing a Jakarta 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 Jakarta 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:

2.0

createNamedQuery

Query createNamedQuery(String name)

Create an instance of Query for executing a named query written in the Jakarta 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

See Also:

• NamedQuery
• NamedNativeQuery

createNamedQuery

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

Create an instance of TypedQuery for executing a Jakarta 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:

2.0

createQuery

<T> TypedQuery<T> createQuery(TypedQueryReference<T> reference)

Create an instance of TypedQuery for executing a named query written in the Jakarta Persistence query language or in native SQL.

Parameters:

reference - a reference to the query defined in metadata

Returns:

the new query instance

Throws:

IllegalArgumentException - if a query has not been defined, 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

See Also:

• EntityManagerFactory.getNamedQueries(Class)
• NamedQuery
• NamedNativeQuery

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 occurrence in the select list and default JDBC type mappings are applied.

Parameters:

sqlString - a native SQL query string

Returns:

the new query instance

createNativeQuery

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

Create an instance of Query for executing a native SQL query.

In the next release of this API, the return type of this method will change to TypedQuery<T>.

Parameters:

sqlString - a native SQL query string

resultClass - the type of the query result

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

createNamedStoredProcedureQuery

StoredProcedureQuery createNamedStoredProcedureQuery(String name)

Create an instance of StoredProcedureQuery for executing a stored procedure in the database.

Parameters must be registered before the stored procedure can be executed.

If the stored procedure returns one or more result sets, any result set is returned as a list of type Object[].

Parameters:

name - name assigned to the stored procedure query in metadata

Returns:

the new stored procedure query instance

Throws:

IllegalArgumentException - if no query has been defined with the given name

Since:

2.1

createStoredProcedureQuery

StoredProcedureQuery createStoredProcedureQuery(String procedureName)

Create an instance of StoredProcedureQuery for executing a stored procedure in the database.

Parameters must be registered before the stored procedure can be executed.

If the stored procedure returns one or more result sets, any result set is returned as a list of type Object[].

Parameters:

procedureName - name of the stored procedure in the database

Returns:

the new stored procedure query instance

Throws:

IllegalArgumentException - if a stored procedure of the given name does not exist (or if query execution will fail)

Since:

2.1

createStoredProcedureQuery

StoredProcedureQuery createStoredProcedureQuery(String procedureName,
 Class<?>... resultClasses)

Create an instance of StoredProcedureQuery for executing a stored procedure in the database.

Parameters must be registered before the stored procedure can be executed.

The resultClass arguments must be specified in the order in which the result sets is returned by the stored procedure invocation.

Parameters:

procedureName - name of the stored procedure in the database

resultClasses - classes to which the result sets produced by the stored procedure are to be mapped

Returns:

the new stored procedure query instance

Throws:

IllegalArgumentException - if a stored procedure of the given name does not exist (or if query execution will fail)

Since:

2.1

createStoredProcedureQuery

StoredProcedureQuery createStoredProcedureQuery(String procedureName,
 String... resultSetMappings)

Create an instance of StoredProcedureQuery for executing a stored procedure in the database.

Parameters must be registered before the stored procedure can be executed.

The resultSetMapping arguments must be specified in the order in which the result sets is returned by the stored procedure invocation.

Parameters:

procedureName - name of the stored procedure in the database

resultSetMappings - the names of the result set mappings to be used in mapping result sets returned by the stored procedure

Returns:

the new stored procedure query instance

Throws:

IllegalArgumentException - if a stored procedure or result set mapping of the given name does not exist (or the query execution will fail)

joinTransaction

void joinTransaction()

Indicate to the entity manager that a JTA transaction is active and join the persistence context to it.

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 active transaction

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

Since:

2.1

unwrap

<T> T unwrap(Class<T> cls)

Return an object of the specified type to allow access to a provider-specific API. If the provider implementation of EntityManager does not support the given type, the PersistenceException is thrown.

Parameters:

cls - the class of the object to be returned. This is usually either the underlying class implementing EntityManager or an interface it implements.

Returns:

an instance of the specified class

Throws:

PersistenceException - if the provider does not support the given type

Since:

2.0

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:

the underlying provider object

close

void close()

Close an application-managed entity manager.

After invocation of close(), every method of the EntityManager instance and of any instance of Query, TypedQuery, or StoredProcedureQuery obtained from it throws the IllegalStateException, except for getProperties(), getTransaction(), and isOpen() (which returns 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.

Specified by:

close in interface AutoCloseable

Throws:

IllegalStateException - if the entity manager is container-managed

isOpen

boolean isOpen()

Determine whether the entity manager is open.

Returns:

true until the entity manager has been closed

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

getEntityManagerFactory

EntityManagerFactory getEntityManagerFactory()

The entity manager factory which created this entity manager.

Returns:

the EntityManagerFactory

Throws:

IllegalStateException - if the entity manager has been closed

Since:

2.0

getCriteriaBuilder

CriteriaBuilder getCriteriaBuilder()

Obtain an instance of CriteriaBuilder which may be used to construct CriteriaQuery objects.

Returns:

an instance of CriteriaBuilder

Throws:

IllegalStateException - if the entity manager has been closed

Since:

2.0

See Also:

• EntityManagerFactory.getCriteriaBuilder()

getMetamodel

Metamodel getMetamodel()

Obtain an instance of the Metamodel interface which provides access to metamodel objects describing the managed types belonging to the persistence unit.

Returns:

an instance of Metamodel

Throws:

IllegalStateException - if the entity manager has been closed

Since:

2.0

createEntityGraph

<T> EntityGraph<T> createEntityGraph(Class<T> rootType)

Create a new mutable EntityGraph, allowing dynamic definition of an entity graph.

Parameters:

rootType - class of entity graph

Returns:

entity graph

Since:

2.1

createEntityGraph

EntityGraph<?> createEntityGraph(String graphName)

Obtain a mutable copy of a named EntityGraph, or return null if there is no entity graph with the given name.

Parameters:

graphName - name of an entity graph

Returns:

entity graph

Since:

2.1

getEntityGraph

EntityGraph<?> getEntityGraph(String graphName)

Obtain a named EntityGraph. The returned instance of EntityGraph should be considered immutable.

Parameters:

graphName - name of an existing entity graph

Returns:

named entity graph

Throws:

IllegalArgumentException - if there is no entity of graph with the given name

Since:

2.1

getEntityGraphs

<T> List<EntityGraph<? super T>> getEntityGraphs(Class<T> entityClass)

Return all named EntityGraphs that are defined for the given entity class type.

Parameters:

entityClass - entity class

Returns:

list of all entity graphs defined for the entity

Throws:

IllegalArgumentException - if the class is not an entity

Since:

2.1

runWithConnection

<C> void runWithConnection(ConnectionConsumer<C> action)

Execute the given action using the database connection underlying this EntityManager. Usually, the connection is a JDBC connection, but a provider might support some other native connection type, and is not required to support java.sql.Connection. If this EntityManager is associated with a transaction, the action is executed in the context of the transaction. The given action should close any resources it creates, but should not close the connection itself, nor commit or roll back the transaction. If the given action throws an exception, the persistence provider must mark the transaction for rollback.

Type Parameters:

C - the connection type, usually java.sql.Connection

Parameters:

action - the action

Throws:

PersistenceException - wrapping the checked Exception thrown by ConnectionConsumer.accept(C), if any

Since:

3.2

callWithConnection

<C,
T> T callWithConnection(ConnectionFunction<C,T> function)

Call the given function and return its result using the database connection underlying this EntityManager. Usually, the connection is a JDBC connection, but a provider might support some other native connection type, and is not required to support java.sql.Connection. If this EntityManager is associated with a transaction, the function is executed in the context of the transaction. The given function should close any resources it creates, but should not close the connection itself, nor commit or roll back the transaction. If the given action throws an exception, the persistence provider must mark the transaction for rollback.

Type Parameters:

C - the connection type, usually java.sql.Connection

T - the type of result returned by the function

Parameters:

function - the function

Returns:

the value returned by ConnectionFunction.apply(C).

Throws:

PersistenceException - wrapping the checked Exception thrown by ConnectionFunction.apply(C), if any

Since:

3.2