javax.persistence
Interface EntityManager

All Known Subinterfaces:

JpaEntityManager

public interface EntityManager

Interface used to interact with the persistence context.

An EntityManager instance is associated with a persistence context. A persistence context is a set of entity instances in which for any persistent entity identity there is a unique entity instance. Within the persistence context, the entity instances and their life-cycle are managed. This interface defines the methods that are used to interact with the persistence context. The EntityManager API is used to create and remove persistent entity instances, to find entities by their primary key, and to query over entities.

The set of entities that can be managed by a given EntityManager instance is defined by a persistence unit. A persistence unit defines the set of all classes that are related or grouped by the application, and which must be co-located in their mapping to a single database.

Since:

Java Persistence API 1.0

Method Summary

void	clear() Clear the persistence context, causing all managed entities to become detached.
void	clear(java.lang.Object entity) Remove the given entity from the persistence context, causing a managed entity to become detached.
void	close() Close an application-managed EntityManager.
boolean	contains(java.lang.Object entity) Check if the instance belongs to the current persistence context.
Query	createNamedQuery(java.lang.String name) Create an instance of Query for executing a named query (in the Java Persistence query language or in native SQL).
Query	createNativeQuery(java.lang.String sqlString) Create an instance of Query for executing a native SQL statement, e.g., for update or delete.
Query	createNativeQuery(java.lang.String sqlString, java.lang.Class resultClass) Create an instance of Query for executing a native SQL query.
Query	createNativeQuery(java.lang.String sqlString, java.lang.String resultSetMapping) Create an instance of Query for executing a native SQL query.
Query	createQuery(QueryDefinition qdef) Create an instance of Query for executing a criteria query.
Query	createQuery(java.lang.String qlString) Create an instance of Query for executing a Java Persistence query language statement.
<T> T	find(java.lang.Class<T> entityClass, java.lang.Object primaryKey) Find by primary key.
<T> T	find(java.lang.Class<T> entityClass, java.lang.Object primaryKey, LockModeType lockMode) Find by primary key and lock.
<T> T	find(java.lang.Class<T> entityClass, java.lang.Object primaryKey, LockModeType lockMode, java.util.Map properties) Find by primary key and lock.
void	flush() Synchronize the persistence context to the underlying database.
java.lang.Object	getDelegate() Return the underlying provider object for the EntityManager, if available.
EntityManagerFactory	getEntityManagerFactory() Return the entity manager factory for the entity manager.
FlushModeType	getFlushMode() Get the flush mode that applies to all objects contained in the persistence context.
LockModeType	getLockMode(java.lang.Object entity) Get the current lock mode for the entity instance.
java.util.Map<java.lang.String,java.lang.Object>	getProperties() Get the properties and associated values that are in effect for the entity manager.
QueryBuilder	getQueryBuilder() Return an instance of QueryBuilder for the creation of Criteria API QueryDefinition objects.
<T> T	getReference(java.lang.Class<T> entityClass, java.lang.Object primaryKey) Get an instance, whose state may be lazily fetched.
java.util.Set<java.lang.String>	getSupportedProperties() Get the names of the properties that are supported for use with the entity manager.
EntityTransaction	getTransaction() Returns the resource-level transaction object.
boolean	isOpen() Determine whether the EntityManager is open.
void	joinTransaction() Indicate to the EntityManager that a JTA transaction is active.
void	lock(java.lang.Object entity, LockModeType lockMode) Set the lock mode for an entity object contained in the persistence context.
void	lock(java.lang.Object entity, LockModeType lockMode, java.util.Map properties) Set the lock mode for an entity object contained in the persistence context.
<T> T	merge(T entity) Merge the state of the given entity into the current persistence context.
void	persist(java.lang.Object entity) Make an entity instance managed and persistent.
void	refresh(java.lang.Object entity) Refresh the state of the instance from the database, overwriting changes made to the entity, if any.
void	refresh(java.lang.Object entity, LockModeType lockMode) Refresh the state of the instance from the database, overwriting changes made to the entity, if any, and lock it with respect to given lock mode type.
void	refresh(java.lang.Object entity, LockModeType lockMode, java.util.Map properties) Refresh the state of the instance from the database, overwriting changes made to the entity, if any, and lock it with respect to given lock mode type.
void	remove(java.lang.Object entity) Remove the entity instance.
void	setFlushMode(FlushModeType flushMode) Set the flush mode that applies to all objects contained in the persistence context.
<T> T	unwrap(java.lang.Class<T> cls) Return an object of the specified type to allow access to the provider-specific API.

Method Detail

persist

void persist(java.lang.Object entity)

Make an entity instance managed and persistent.

Parameters:

entity -

Throws:

EntityExistsException - if the entity already exists. (The EntityExistsException may be thrown when the persist operation is invoked, or the EntityExistsException or another PersistenceException may be thrown at flush or commit time.)

java.lang.IllegalStateException - if this EntityManager has been closed.

java.lang.IllegalArgumentException - if not an entity

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

merge

<T> T merge(T entity)

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

Parameters:

entity -

Returns:

the instance that the state was merged to

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

java.lang.IllegalArgumentException - if instance is not an entity or is a removed entity

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

remove

void remove(java.lang.Object entity)

Remove the entity instance.

Parameters:

entity -

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

java.lang.IllegalArgumentException - if not an entity or if 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(java.lang.Class<T> entityClass,
           java.lang.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 -

primaryKey -

Returns:

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

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

java.lang.IllegalArgumentException - if the first argument does not denote an entity type or the second argument is not a valid type for that entity's primary key

find

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

Find by primary key and lock. Search for an entity of the specified class and primary key and lock it with respect to the specified lock type. If the entity instance is contained in the persistence context it is returned from there. If the entity is found within the persistence context and the lock mode type is pessimistic and the entity has a version attribute, the persistence provider must perform optimistic version checks when obtaining the database lock. If these checks fail, the OptimisticLockException will be thrown. If the lock mode type is pessimistic and the entity instance is found but cannot be locked: - the PessimisticLockException will be thrown if the database locking failure causes transaction-level rollback. - the LockTimeoutException will be thrown if the database locking failure causes only statement-level rollback

Parameters:

entityClass -

primaryKey -

lockMode -

Returns:

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

Throws:

java.lang.IllegalArgumentException - if the first argument does not denote an entity type or the second argument is not a valid type for that entity's primary key or is null

TransactionRequiredException - if there is no transaction and a lock mode other than NONE is set

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:

Java Persistence API 2.0

find

<T> T find(java.lang.Class<T> entityClass,
           java.lang.Object primaryKey,
           LockModeType lockMode,
           java.util.Map properties)

Find by primary key and lock. Search for an entity of the specified class and primary key and lock it with respect to the specified lock type. If the entity instance is contained in the persistence context it is returned from there. If the entity is found within the persistence context and the lock mode type is pessimistic and the entity has a version attribute, the persistence provider must perform optimistic version checks when obtaining the database lock. If these checks fail, the OptimisticLockException will be thrown. If the lock mode type is pessimistic and the entity instance is found but cannot be locked: - the PessimisticLockException will be thrown if the database locking failure causes transaction-level rollback. - the LockTimeoutException will be thrown if the database locking failure causes only statement-level rollback If a vendor-specific property or hint is not recognized, it is silently ignored. Portable applications should not rely on the standard timeout hint. Depending on the database in use and the locking mechanisms used by the provider, the hint may or may not be observed.

Parameters:

entityClass -

primaryKey -

lockMode -

properties - standard and vendor-specific properties and hints

Returns:

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

Throws:

java.lang.IllegalArgumentException - if the first argument does not denote an entity type or the second argument is not a valid type for that entity's primary key or is null

TransactionRequiredException - if there is no transaction and a lock mode other than NONE is set

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:

Java Persistence API 2.0

getReference

<T> T getReference(java.lang.Class<T> entityClass,
                   java.lang.Object primaryKey)

Get an instance, whose state may be lazily fetched. If the requested instance does not exist in the database, throws EntityNotFoundException when the instance state is first accessed. (The persistence provider runtime is permitted to throw EntityNotFoundException when getReference(java.lang.Class, java.lang.Object) is called.) The application should not expect that the instance state will be available upon detachment, unless it was accessed by the application while the entity manager was open.

Parameters:

entityClass -

primaryKey -

Returns:

the found entity instance

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

java.lang.IllegalArgumentException - if the first argument does not denote an entity type or the second argument is not a valid type for that entity's primary key

EntityNotFoundException - if the entity state cannot be accessed

flush

void flush()

Synchronize the persistence context to the underlying database.

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

TransactionRequiredException - if there is no 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 -

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

getFlushMode

FlushModeType getFlushMode()

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

Returns:

flush mode

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

lock

void lock(java.lang.Object entity,
          LockModeType lockMode)

Set the lock mode for an entity object contained in the persistence context.

Parameters:

entity -

lockMode -

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

PersistenceException - if an unsupported lock call is made

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

TransactionRequiredException - if there is no transaction

lock

void lock(java.lang.Object entity,
          LockModeType lockMode,
          java.util.Map properties)

Set the lock mode for an entity object contained in the persistence context.

Parameters:

entity -

lockMode -

Throws:

PersistenceException - if an unsupported lock call is made

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

TransactionRequiredException - if there is no transaction

Since:

Java Persistence API 2.0

refresh

void refresh(java.lang.Object entity)

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

Parameters:

entity -

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

java.lang.IllegalArgumentException - if not an entity or entity is not managed

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

EntityNotFoundException - if the entity no longer exists in the database.

refresh

void refresh(java.lang.Object entity,
             LockModeType lockMode)

Refresh the state of the instance from the database, overwriting changes made to the entity, if any, and lock it with respect to given lock mode type. If the lock mode type is pessimistic and the entity instance is found but cannot be locked:

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

Parameters:

entity -

lockMode -

Throws:

java.lang.IllegalArgumentException - if the instance is not an entity or the entity is not managed

TransactionRequiredException - if there is no transaction

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:

Java Persistence API 2.0

refresh

void refresh(java.lang.Object entity,
             LockModeType lockMode,
             java.util.Map properties)

Refresh the state of the instance from the database, overwriting changes made to the entity, if any, and lock it with respect to given lock mode type. If the lock mode type is pessimistic and the entity instance is found but cannot be locked:

• the PessimisticLockException will be thrown if the database locking failure causes transaction-level rollback.
• the LockTimeoutException will be thrown if the database locking failure causes only statement-level rollback If a vendor-specific property or hint is not recognized, it is silently ignored.

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

Parameters:

entity -

lockMode -

properties - standard and vendor-specific properties and hints

Throws:

java.lang.IllegalArgumentException - if the instance is not an entity or the entity is not managed

TransactionRequiredException - if there is no transaction

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:

Java Persistence API 2.0

clear

void clear()

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

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

clear

void clear(java.lang.Object entity)

Remove the given entity from the persistence context, causing a managed entity to become detached. Changes made to the entity that have not been flushed, if any (including removal of the entity), will not be synchronized to the database.

Parameters:

entity -

Throws:

java.lang.IllegalArgumentException - if the instance is not an entity

Since:

Java Persistence API 2.0

contains

boolean contains(java.lang.Object entity)

Check if the instance belongs to the current persistence context.

Parameters:

entity -

Returns:

true if the instance belongs to the current persistence context.

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

java.lang.IllegalArgumentException - if not an entity

getLockMode

LockModeType getLockMode(java.lang.Object entity)

Get the current lock mode for the entity instance.

Parameters:

entity -

Returns:

lock mode

Throws:

TransactionRequiredException - if there is no transaction

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

Since:

Java Persistence API 2.0

getProperties

java.util.Map<java.lang.String,java.lang.Object> getProperties()

Get the properties and associated values that are in effect for the entity manager. Changing the contents of the map does not change the configuration in effect.

Since:

Java Persistence API 2.0

getSupportedProperties

java.util.Set<java.lang.String> getSupportedProperties()

Get the names of the properties that are supported for use with the entity manager. These correspond to properties and hints that may be passed to the methods of the EntityManager interface that take a properties argument or used with the PersistenceContext annotation. These properties include all standard entity manager hints and properties as well as vendor-specific ones supported by the provider. These properties may or may not currently be in effect.

Returns:

property names

Since:

Java Persistence API 2.0

createQuery

Query createQuery(java.lang.String qlString)

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

Parameters:

qlString - a Java Persistence query language query string

Returns:

the new query instance

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

java.lang.IllegalArgumentException - if query string is not valid

createQuery

Query createQuery(QueryDefinition qdef)

Create an instance of Query for executing a criteria query.

Parameters:

qdef - a Criteria API query definition object

Returns:

the new query instance

Throws:

java.lang.IllegalArgumentException - if the query definition is found to be invalid

Since:

Java Persistence API 2.0

createNamedQuery

Query createNamedQuery(java.lang.String name)

Create an instance of Query for executing a named query (in the Java Persistence query language or in native SQL).

Parameters:

name - the name of a query defined in metadata

Returns:

the new query instance

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

java.lang.IllegalArgumentException - if a query has not been defined with the given name

createNativeQuery

Query createNativeQuery(java.lang.String sqlString)

Create an instance of Query for executing a native SQL statement, e.g., for update or delete.

Parameters:

sqlString - a native SQL query string

Returns:

the new query instance

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

createNativeQuery

Query createNativeQuery(java.lang.String sqlString,
                        java.lang.Class resultClass)

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

Parameters:

sqlString - a native SQL query string

resultClass - the class of the resulting instance(s)

Returns:

the new query instance

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

createNativeQuery

Query createNativeQuery(java.lang.String sqlString,
                        java.lang.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

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

joinTransaction

void joinTransaction()

Indicate to the EntityManager that a JTA transaction is active. This method should be called on a JTA application managed EntityManager that was created outside the scope of the active transaction to associate it with the current JTA transaction.

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

TransactionRequiredException - if there is no transaction.

unwrap

<T> T unwrap(java.lang.Class<T> cls)

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

Parameters:

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

Returns:

an instance of the specified class

Throws:

PersistenceException - if the provider does not support the call.

Since:

Java Persistence API 2.0

getDelegate

java.lang.Object getDelegate()

Return the underlying provider object for the EntityManager, if available. The result of this method is implementation specific.

Throws:

java.lang.IllegalStateException - if this EntityManager has been closed.

close

void close()

Close an application-managed EntityManager. After the close method has been invoked, all methods on the EntityManager instance and any Query objects obtained from it will throw the IllegalStateException except for getTransaction and isOpen (which will return false). If this method is called when the EntityManager is associated with an active transaction, the persistence context remains managed until the transaction completes.

Throws:

java.lang.IllegalStateException - if the EntityManager is container-managed or has been already closed..

isOpen

boolean isOpen()

Determine whether the EntityManager is open.

Returns:

true until the EntityManager has been closed.

getTransaction

EntityTransaction getTransaction()

Returns the resource-level transaction object. The EntityTransaction instance may be used serially to begin and commit multiple transactions.

Returns:

EntityTransaction instance

Throws:

java.lang.IllegalStateException - if invoked on a JTA EntityManager.

getEntityManagerFactory

EntityManagerFactory getEntityManagerFactory()

Return the entity manager factory for the entity manager.

Returns:

EntityManagerFactory instance

Throws:

java.lang.IllegalStateException - if the entity manager has been closed.

Since:

Java Persistence API 2.0

getQueryBuilder

QueryBuilder getQueryBuilder()

Return an instance of QueryBuilder for the creation of Criteria API QueryDefinition objects.

Returns:

QueryBuilder instance

Throws:

java.lang.IllegalStateException - if the entity manager has been closed.

Since:

Java Persistence API 2.0