javax.persistence
Interface EntityManager

public interface EntityManager

Interface used to interact with the persistence context.

Since:

EJB 3.0 version.

Author:

Florent Benoit

See Also:

EJB 3.0 specification

Method Summary

void	clear() Clear the persistence context, causing all managed entities to become detached.
void	close() Close an application-managed EntityManager.
boolean	contains(Object entity) Check if the instance belongs to the current persistence context.
Query	createNamedQuery(String name) Create an instance of Query for executing a named query (in the Java Persistence query language or in native SQL).
Query	createNativeQuery(String sqlString) Create an instance of Query for executing a native SQL statement, e.g., for update or delete.
Query	createNativeQuery(String sqlString, Class resultClass) Create an instance of Query for executing a native SQL query.
Query	createNativeQuery(String sqlString, String resultSetMapping) Create an instance of Query for executing a native SQL query.
Query	createQuery(String qlString) Create an instance of Query for executing a Java Persistence query language statement.
<T> T	find(Class<T> entityClass, Object primaryKey) Find by primary key.
void	flush() Synchronize the persistence context to the underlying database.
Object	getDelegate()
FlushModeType	getFlushMode() Get the flush mode that applies to all objects contained in the persistence context.
<T> T	getReference(Class<T> entityClass, Object primaryKey) Get an instance, whose state may be lazily fetched.
EntityTransaction	getTransaction() Return 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(Object entity, LockModeType lockMode) 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(Object entity) Make an instance managed and persistent.
void	refresh(Object entity) Refresh the state of the instance from the database, overwriting changes made to the entity, if any.
void	remove(Object entity) Remove the entity instance.
void	setFlushMode(FlushModeType flushMode) Set the flush mode that applies to all objects contained in the persistence context.

Method Detail

persist

void persist(Object entity)

Make an instance managed and persistent.

Parameters:

entity - the given 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.)

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.

Type Parameters:

T - The class of the entity.

Parameters:

entity - the given entity.

Returns:

the instance that the state was merged to

Throws:

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

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

remove

void remove(Object entity)

Remove the entity instance.

Parameters:

entity - the given entity.

Throws:

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(Class<T> entityClass,
           Object primaryKey)

Find by primary key.

Type Parameters:

T - The class of the entity.

Parameters:

entityClass - the entity class.

primaryKey - the primary key.

Returns:

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

Throws:

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

getReference

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

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

Type Parameters:

T - The class of the entity.

Parameters:

entityClass - the entity class.

primaryKey - the primary key.

Returns:

the found entity instance throws IllegalArgumentException if the first argument does not denote an entity type or the second argument is not a valid type for that entity's primary key throws EntityNotFoundException if the entity state cannot be accessed

flush

void flush()

Synchronize the persistence context to the underlying database.

Throws:

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 - the given flush mode.

getFlushMode

FlushModeType getFlushMode()

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

Returns:

flushMode

lock

void lock(Object entity,
          LockModeType lockMode)

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

Parameters:

entity - the given entity.

lockMode - the lock mode.

Throws:

PersistenceException - if an unsupported lock call is made

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

TransactionRequiredException - if there is no transaction

refresh

void refresh(Object entity)

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

Parameters:

entity - the given entity.

Throws:

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

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.

contains

boolean contains(Object entity)

Check if the instance belongs to the current persistence context.

Parameters:

entity - the given entity

Returns:

true if the given instance belongs to the current persistence context.

Throws:

IllegalArgumentException - if not an entity

createQuery

Query createQuery(String qlString)

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

Parameters:

qlString - a Java Persistence query string

Returns:

the new query instance

Throws:

IllegalArgumentException - if query string is not valid

createNamedQuery

Query createNamedQuery(String name)

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

Parameters:

name - the name of a query defined in metadata

Returns:

the new query instance

Throws:

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

createNativeQuery

Query createNativeQuery(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

createNativeQuery

Query createNativeQuery(String sqlString,
                        Class resultClass)

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

Parameters:

sqlString - a native SQL query string

resultClass - the class of the resulting instance(s)

Returns:

the new query instance

createNativeQuery

Query createNativeQuery(String sqlString,
                        String resultSetMapping)

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

Parameters:

sqlString - a native SQL query string

resultSetMapping - the name of the result set mapping

Returns:

the new query instance

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:

TransactionRequiredException - if there is no transaction.

getDelegate

Object getDelegate()

Returns:

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

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:

IllegalStateException - if the EntityManager is container-managed.

isOpen

boolean isOpen()

Determine whether the EntityManager is open.

Returns:

true until the EntityManager has been closed.

getTransaction

EntityTransaction getTransaction()

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

Returns:

EntityTransaction instance

Throws:

IllegalStateException - if invoked on a JTA EntityManager.