Interface EntityManager

All Superinterfaces:

AutoCloseable, EntityHandler

public interface EntityManager
extends EntityHandler

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. In the Jakarta EE environment, an entity manager with a lifecycle managed by the container may be obtained by dependency injection.

• An EntityManager obtained directly from an EntityManagerFactory is never thread safe, and it is always wrong to share a reference to such an entity manager between multiple concurrently executing threads.
• On the other hand, in the Jakarta EE container environment, a reference to a container-managed, transaction-scoped entity manager obtained by injection is safe to invoke concurrently from distinct threads. The container redirects invocations to distinct instances of EntityManager based on transaction affinity. Even in this scenario, the underlying persistence context must never be shared between threads.

An application-managed EntityManager may be created via a call to EntityManagerFactory.createEntityManager(). The EntityManager must be explicitly closed via a call to EntityHandler.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(Consumer) and EntityManagerFactory.callInTransaction(Function).

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 EntityHandler.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(Object) and remove(Object) instances, find entities by their primary key, and execute queries which range over entity types. A given entity may be disassociated from the persistence context by calling detach(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, RefreshOption...), and EntityHandler.find(Class, Object, FindOption...), 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 EntityHandler.setCacheRetrieveMode(CacheRetrieveMode) and EntityHandler.setCacheStoreMode(CacheStoreMode).

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

• EntityHandler.find(Class, Object, FindOption...) and EntityHandler.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
void	clear()	Clear the persistence context, causing all managed entities to become detached.
boolean	contains(Object entity)	Determine if the given object is a managed entity instance belonging to the current persistence context.
EntityGraph<?>	createEntityGraph(String graphName)	Deprecated, for removal: This API element is subject to removal in a future version. Use EntityHandler.getEntityGraph(String) instead.
Statement	createQuery(CriteriaStatement<?> statement)	Deprecated, for removal: This API element is subject to removal in a future version. Use EntityHandler.createStatement(CriteriaStatement).
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(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.
Object	getDelegate()	Deprecated. Use EntityHandler.unwrap(Class) instead.
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.
<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.
boolean	isJoinedToTransaction()	Determine whether the EntityManager is joined to the current transaction.
void	joinTransaction()	Join the current active JTA transaction.
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, 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.
void	setFlushMode(FlushModeType flushMode)	Set the flush mode that applies to all objects contained in the persistence context.

Methods inherited from interface EntityHandler

callWithConnection, close, createEntityGraph, createNamedQuery, createNamedQuery, createNamedStatement, createNamedStoredProcedureQuery, createNativeQuery, createNativeQuery, createNativeQuery, createNativeQuery, createNativeStatement, createQuery, createQuery, createQuery, createQuery, createQuery, createQuery, createStatement, createStatement, createStatement, createStoredProcedureQuery, createStoredProcedureQuery, createStoredProcedureQuery, find, find, find, findMultiple, findMultiple, get, get, get, getCacheRetrieveMode, getCacheStoreMode, getCriteriaBuilder, getEntityGraph, getEntityGraph, getEntityGraphs, getEntityManagerFactory, getMetamodel, getMultiple, getMultiple, getProperties, getTransaction, isOpen, runWithConnection, setCacheRetrieveMode, setCacheStoreMode, setProperty, unwrap

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

PersistenceException - if the entity class has a generated identifier and an identifier could not be generated

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 type PersistenceContextType.TRANSACTION

OptimisticLockException - if an optimistic locking conflict is detected (note that optimistic version checking might be deferred until changes are flushed to the database)

PersistenceException - if a record could not be read from the database

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

OptimisticLockException - if an optimistic locking conflict is detected (note that optimistic version checking might be deferred until changes are flushed to the database)

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

PersistenceException - if the record could not be read from the database

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 the given lock mode type is not supported for the given entity class or if the record could not be read from the database

Since:

2.0

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

Since:

3.2

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

OptimisticLockException - if an optimistic locking conflict is detected

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 the given lock mode type is not supported for the given entity class

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 the given lock mode type is not supported for the given entity class

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 the given options include a PessimisticLockScope, the specified scope determines whether a pessimistic lock is applied to associated collections and relationships.

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 the given lock mode type is not supported for the given entity class

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

PersistenceException - if the record could not be read from 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

PersistenceException - if the record could not be read from the database

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 the given lock mode type is not supported for the given entity class or if the record could not be read from the database

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 a given lock mode type is not supported for the given entity class or if the record could not be read from the database

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

joinTransaction

void joinTransaction()

Join the current active JTA transaction.

This method should be called on a JTA application-managed EntityManager that was created outside the scope of the active transaction or on an EntityManager of type SynchronizationType.UNSYNCHRONIZED to associate it with the current JTA transaction.

Throws:

TransactionRequiredException - if there is no active transaction

Since:

1.0

isJoinedToTransaction

boolean isJoinedToTransaction()

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

Returns:

True if the EntityManager is joined to the current transaction, or false otherwise

Since:

2.1

createQuery

@Deprecated(since="4.0",
            forRemoval=true)
Statement createQuery(CriteriaStatement<?> statement)

Deprecated, for removal: This API element is subject to removal in a future version.

Use EntityHandler.createStatement(CriteriaStatement).

Create an instance of Statement for executing a criteria statement.

Parameters:

statement - A criteria statement object

Returns:

An instance of Statement which may be used to execute the given statement

Throws:

IllegalArgumentException - if the Statement is found to be invalid

Since:

2.1

createEntityGraph

@Deprecated(since="4.0",
            forRemoval=true)
EntityGraph<?> createEntityGraph(String graphName)

Deprecated, for removal: This API element is subject to removal in a future version.

Use EntityHandler.getEntityGraph(String) instead.

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

Parameters:

graphName - The name of an entity graph

Returns:

A mutable copy of the entity graph, or null

Since:

2.1

getDelegate

@Deprecated(since="4.0")
Object getDelegate()

Deprecated.

Use EntityHandler.unwrap(Class) instead.

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