8.10.1 javax.persistence.EntityManager interface

(1) Definition of the 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() ;
 
}

To Page Top

(2) Notes

• When the transaction scope persistence context is used, the persist, merge, remove, and refresh methods must be invoked in the transaction context. If the transaction context does not exist, javax.persistence.TransactionRequiredException is thrown.

• The find and getReference methods can also be invoked outside the transaction context. When the transaction scope persistence context is used, the resulting entity has a detached status. When the extended persistence context is used, the resulting entity has a managed status.

• The Query and EntityTransaction objects obtained from EntityManager can be used while EntityManager is open.

• If the argument of the createQuery method is not a valid JPQL (Java Persistence Query Language), IllegalArgumentException is thrown or the execution of the query fails. If the native query is incorrect and if the definition of the result set is not compatible with the query result, PersistenceException is thrown when the query is executed and the execution of the query fails. When possible, PersistenceException wraps the database exceptions.

• If a runtime exception is thrown in the method of the EntityManager interface, the transaction is rolled back.

• The close, isOpen, joinTransaction, and getTransaction methods are used for managing the application-managed EntityManager.

• With the EJB specifications, the following methods can invoke the EntityManager methods in the Stateless Session Bean:

  • Business method of the business interface or component interface

  • Business method

  • Interceptor method

  • Timeout callback method

  The EntityManager methods cannot be invoked with the constructor, the setter method (including setSessionContext method) of the DI, and the life cycle callback method (PostConstruct and PreDestroy). If the EntityManager methods are invoked in the unpermitted locations, the KDJE56538-E message is displayed and java.lang.IllegalStateException is thrown.

• With the EJB specifications, the following methods can invoke the EntityManager methods in the Stateful Session Bean:

  • Life cycle callback method (PostConstruct and PreDestroy)

  • Business method of the business interface or component interface

  • Business method

  • Interceptor method

  • afterBegin and beforeCompletion methods of SessionSynchronization

  The EntityManager methods cannot be invoked with the constructor, the setter method of the DI, and afterCompletion method of SessionSynchronization. If the EntityManager methods are invoked in unpermitted locations, the KDJE56538-E message is displayed and java.lang.IllegalStateException is thrown.

Note the following points as well when you use the JPA with Application Server:

• EntityManager that the application obtains by using inject, JNDI lookup, and EntityManagerFactory becomes the proxy class of EntityManager provided by Application Server and not the EntityManager object provided by the JPA provider. If you use the getDelegate() method of this proxy class, you can obtain the EntityManager object provided by the JPA provider. However, when the container-managed EntityManager is used, the container manages the EntityManager life cycle, so do not invoke the close() method of the EntityManager object obtained by using the getDelegate() method, from the application.

• If the getDelegate() method of EntityManager is invoked when the transaction scope persistence context is used and when transaction does not exist, the container cannot close the returned EntityManager. In this case, you must invoke EntityManager.close() with the application.

To Page Top