javax.persistence
Interface EntityManager


public interface EntityManager

Interface used to interact with the persistence context.


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 EJB QL or 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 ejbqlString)
          Create an instance of Query for executing an EJB QL 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()
          Return the underlying provider object for the EntityManager, if available.
 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 -
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 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.

Parameters:
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 -
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.

Parameters:
entityClass -
primaryKey -
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.

Parameters:
entityClass -
primaryKey -
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
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 -

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 -
lockMode -
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 -
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 -
Returns:
Throws:
IllegalArgumentException - if not an entity

createQuery

Query createQuery(String ejbqlString)
Create an instance of Query for executing an EJB QL statement.

Parameters:
ejbqlString - an EJB QL 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 EJB QL or 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()
Return the underlying provider object for the EntityManager, if available. The result of this method is implementation specific

Returns:

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.