This subsection describes the interface definition and the notes on the javax.persistence.EntityManager interface.
package javax.persistence;
/**
* Interface for operating the persistence context.
*
* EntityManager instance is associated with the persistence context.
* The persistence context is a set of entity instances and
* the entity instance is unique for each
* perpetuated entity.
* The entity instances and their life cycles
* are managed in the persistence context.
* The EntityManager interface defines the methods for operating the * persistence context and is used for
* creating or deleting the perpetuated entity instances,
* searching the entity based on the primary key, and for executing
* the entity query.
*
* Define the set of entities that can be managed by EntityManager
* using the persistence unit.
* The persistence unit defines the group of entity classes used
* by the application and also defines the mapping between the entity
* classes and the database.
*/
public interface EntityManager {
/**
* The instance is set to managed and is perpetuated.
* @param entity instance of the persistent entity
* @throws EntityExistsException When the entity already exists
* (When persist method is invoked, EntityExistsException is thrown
* or EntityExistsException or another PersistenceException
* is thrown during flush or commit)
* @throws IllegalArgumentException When the argument is not an entity
* @throws TransactionRequiredException When the container-managed
* EntityManager specifying PersistenceContextType.TRANSACTION
* is invoked when the transaction does not exist
*/
public void persist(Object entity) ;
/**
* The entity status is merged with the current persistence context
* @param entity Entity
* @return instance where the status is merged with the persistence context
* @throws IllegalArgumentException When the instance is not an entity
* or is a removed entity
* @throws TransactionRequiredException When the container-managed
* EntityManager specifying PersistenceContextType.TRANSACTION
* is invoked when the transaction does not exist.
*/
public <T> T merge(T entity) ;
/**
* entity instance is deleted.
* @param entity Entity
* @throws IllegalArgumentException Instance is not an entity
* or is a detached entity
* @throws TransactionRequiredException When the container-managed
* EntityManager specifying PersistenceContextType.TRANSACTION
* is invoked when the transaction does not exist.
*/
public void remove(Object entity) ;
/**
* Searches the primary key.
* @param entityClass Entity class
* @param primaryKey Primary key
* @return Instance of the searched entity
* null when the entity does not exist
* @throws IllegalArgumentException When the entityClass argument
* is not an entity type or if the primaryKey argument is not the
* valid type as the primary key of that entity
*/
public <T> T find(Class<T> entityClass, Object primaryKey) ;
/**
* The status obtains the delayed fetch instance.
* When the requested entity does not exist in the database,
* When the instance status is accessed for the first time
* EntityNotFoundException is thrown.
* (when getReference is invoked, the JPA provider is also allowed
* to throw EntityNotFoundException)
* If the application does not access the instance while
* Entity Manager is open, do not expect that the instance status
* can be accessed during detach
* @param entityClass Entity class
* @param primaryKey Primary key
* @return Instance of the searched entity
* @throws IllegalArgumentException When the entityClass argument
* is not an entity type or the primaryKey argument is not a
* valid type as the primary key of that entity
* @throws EntityNotFoundException When the entity status cannot
* be accessed
*/
public <T> T getReference(Class<T> entityClass, Object primaryKey) ;
/**
* The persistence context status is flushed in the database.
* @throws TransactionRequiredException When the transaction does
* not exist
* @throws PersistenceException When flush fails
*/
public void flush() ;
/**
* Specifies the flush mode applied to all the objects
* included in the persistence context.
* @param flushMode Flush mode
*/
public void setFlushMode(FlushModeType flushMode) ;
/**
* Obtains the flush mode applied to all the objects
* included in the persistence context.
* @return flushMode Flush mode
*/
public FlushModeType getFlushMode() ;
/**
* Sets the lock mode of the entity objects
* included in the persistence context.
* @param entity Entity
* @param lockMode Lock mode
* @throws PersistenceException When an unsupported
* lock invocation is performed
* @throws IllegalArgumentException When the instance is not an entity
* or is a detached entity
* @throws TransactionRequiredException When the transaction
* does not exist
*/
public void lock(Object entity, LockModeType lockMode) ;
/**
* Instance status is refreshed to the database status.
* If the instance status is changed, the status is
* overwritten by the database status.
* @param entity Entity
* @throws IllegalArgumentException When the argument is not an entity
* or does not have the managed status
* @throws TransactionRequiredException When the container-managed
* EntityManager specifying PersistenceContextType.TRANSACTION
* is invoked when the transaction does not exist
* @throws EntityNotFoundException When the entity already
* does not exist in the database
*/
public void refresh(Object entity) ;
/**
* Clears the persistence context and all the managed entities
* are detached.
* If the entity has changes that were not flushed in the database
* the entity is not perpetuated.
*/
public void clear() ;
/**
* Checks if the instance is included in the current
* persistence context.
* @param entity Entity
* @return true if included
* @throws IllegalArgumentException When the argument is not an entity
*/
public boolean contains(Object entity) ;
/**
* Creates a Query instance for executing
* JPQL(Java Persistence Query language) statement
* @param qlString Java Persistence Query statement
* @return New Query instance
* @throws IllegalArgumentException When the query statement is not valid
*/
public Query createQuery(String qlString) ;
/**
* Creates a Query instance for executing the named query
* (JPQL or native SQL).
* @param name Name of the query defined in the Meta data
* @return New Query instance
* @throws IllegalArgumentException If the query with the specified
* name is not defined.
*/
public Query createNamedQuery(String name) ;
/**
* Creates a Query instance for executing the native SQL statement
* (update statement and delete statement)
* @param sqlString Native SQL statement
* @return New Query instance
*/
public Query createNativeQuery(String sqlString) ;
/**
* Creates a Query instance for executing the native SQL query.
* @param sqlString Native SQL statement
* @param resultClass Class of the instance that forms the
* return value
* @return New Query instance
*/
public Query createNativeQuery(String sqlString, Class result-
Class) ;
/**
* Creates a Query instance for executing the native SQL query.
* @param sqlString Native SQL statement
* @param resultSetMapping Result set mapping name
* @return New Query instance
*/
public Query createNativeQuery(String sqlString, String result-
SetMapping) ;
/**
* Reports EntityManager that the JTA transaction is active.
* This method is invoked by the application
* to associate the application-managed JTA entity manager that was
* created outside the transaction scope
* with the current JTA transaction.
* @throws TransactionRequiredException When the transaction
* does not exist
*/
public void joinTransaction() ;
/**
* Returned when the lower provider objects exist.
* The return value of this method depends on the implementation,
* but when the container-managed EntityManager is used in
* Cosminexus Component Container,
* the EntityManager object of the JPA provider is returned.
* @return EntityManager object of the JPA provider
* /
public Object getDelegate() ;
/**
* Closes the application-managed EntityManager.
* After the close method is invoked, all the methods other than
* getTransaction and isOpen (returning false) of the Query object
* obtained from EntityManager instance and EntityManager
* throw IllegalStateException.
* If this method is invoked when EntityManager
* is associated with an active transaction, the persistence context
* continues to exist until the transaction is concluded.
* @throws IllegalStateException For the container-managed
* EntityManager
*/
public void close() ;
/**
* Returns whether EntityManager is open.
* @return Returns true until EntityManager closes.
*/
public boolean isOpen() ;
/**
* Returns the resource level transaction object.
* Used by the EntityTransaction instance to start and commit
* multiple transactions serially.
* @return EntityTransaction instance
* @throws IllegalStateException When this method is invoked with
* the JTA entity manager
*/
public EntityTransaction getTransaction() ;
}
Note the following points as well when you use the JPA with Application Server: