Author: hardy.ferentschik Date: 2009-05-12 07:22:11 -0400 (Tue, 12 May 2009) New Revision: 16542 Modified: jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java Log: ANN-831 Readded getDelegate() Modified: jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java 2009-05-12 09:11:50 UTC (rev 16541) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java 2009-05-12 11:22:11 UTC (rev 16542) @@ -1,706 +1,714 @@ // $Id$ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence; - -import java.util.Map; -import java.util.Set; -import javax.persistence.criteria.CriteriaQuery; -import javax.persistence.criteria.QueryBuilder; -import javax.persistence.metamodel.Metamodel; - -/** - * Interface used to interact with the persistence context. - */ -public interface EntityManager { - /** - * Make an instance managed and persistent. - * - * @param entity - * - * @throws EntityExistsException if the entity already exists. - * (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.) - * @throws IllegalArgumentException if the instance is not an - * entity - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - */ - public void persist(Object entity); - - /** - * Merge the state of the given entity into the - * current persistence context. - * - * @param entity - * - * @return the managed instance that the state was merged to - * - * @throws IllegalArgumentException if instance is not an - * entity or is a removed entity - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - */ - public <T> T merge(T entity); - - /** - * Remove the entity instance. - * - * @param entity - * - * @throws IllegalArgumentException if the instance is not an - * entity or is a detached entity - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - */ - public void remove(Object entity); - - /** - * 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. - * - * @param entityClass - * @param primaryKey - * - * @return 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 - * is not a valid type for that entity�s primary key or - * is null - */ - public <T> T find(Class<T> entityClass, Object primaryKey); - - /** - * Find by primary key, using the specified properties. - * 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. - * If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * - * @param entityClass - * @param primaryKey - * @param properties standard and vendor-specific properties - * - * @return 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 - * is not a valid type for that entity�s primary key or - * is null - */ - public <T> T find(Class<T> entityClass, Object primaryKey, - Map<String, Object> 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, and the effect of this method is - * the same as if the lock method had been called on the entity. - * 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 - * - * @param entityClass - * @param primaryKey - * @param lockMode - * - * @return 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 or - * is null - * @throws TransactionRequiredException if there is no - * transaction and a lock mode other than NONE is set - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public <T> T find(Class<T> entityClass, Object primaryKey, - LockModeType lockMode); - - /** - * Find by primary key and lock, using the specified properties. - * 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. - * - * @param entityClass - * @param primaryKey - * @param lockMode - * @param properties standard and vendor-specific properties - * and hints - * - * @return 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 or - * is null - * @throws TransactionRequiredException if there is no - * transaction and a lock mode other than NONE is set - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public <T> T find(Class<T> entityClass, Object primaryKey, - LockModeType lockMode, - Map<String, Object> properties); - - /** - * 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. - * - * @param entityClass - * @param primaryKey - * - * @return 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 or - * is null - * @throws EntityNotFoundException if the entity state - * cannot be accessed - */ - public <T> T getReference(Class<T> entityClass, - Object primaryKey); - - /** - * Synchronize the persistence context to the - * underlying database. - * - * @throws TransactionRequiredException if there is - * no transaction - * @throws PersistenceException if the flush fails - */ - public void flush(); - - /** - * Set the flush mode that applies to all objects contained - * in the persistence context. - * - * @param flushMode - */ - public void setFlushMode(FlushModeType flushMode); - - /** - * Get the flush mode that applies to all objects contained - * in the persistence context. - * - * @return flushMode - */ - public FlushModeType getFlushMode(); - - /** - * Lock an entity instance that is contained in the persistence - * context with the specified lock mode type. - * If a pessimistic lock mode type is specified and the entity - * contains a version attribute, the persistence provider must - * also 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 - * - * @param entity - * @param lockMode - * - * @throws IllegalArgumentException if the instance is not an - * entity or is a detached entity - * @throws TransactionRequiredException if there is no - * transaction - * @throws EntityNotFoundException if the entity does not exist - * in the database when pessimistic locking is - * performed - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public void lock(Object entity, LockModeType lockMode); - - /** - * Lock an entity instance that is contained in the persistence - * context with the specified lock mode type and with specified - * properties. - * If a pessimistic lock mode type is specified and the entity - * contains a version attribute, the persistence provider must - * also 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. - * - * @param entity - * @param lockMode - * @param properties standard and vendor-specific properties - * and hints - * - * @throws IllegalArgumentException if the instance is not an - * entity or is a detached entity - * @throws TransactionRequiredException if there is no - * transaction - * @throws EntityNotFoundException if the entity does not exist - * in the database when pessimistic locking is - * performed - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public void lock(Object entity, LockModeType lockMode, - Map<String, Object> properties); - - /** - * Refresh the state of the instance from the database, - * overwriting changes made to the entity, if any. - * - * @param entity - * - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - * @throws EntityNotFoundException if the entity no longer - * exists in the database - */ - public void refresh(Object entity); - - /** - * Refresh the state of the instance from the database, using - * the specified properties, and overwriting changes made to - * the entity, if any. - * If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * - * @param entity - * @param properties standard and vendor-specific properties - * - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - * @throws EntityNotFoundException if the entity no longer - * exists in the database - */ - public void refresh(Object entity, - Map<String, Object> 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. - * - * @param entity - * @param lockMode - * - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if there is no - * transaction - * @throws EntityNotFoundException if the entity no longer exists - * in the database - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public void refresh(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 and with - * specified properties. - * 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. - * - * @param entity - * @param lockMode - * @param properties standard and vendor-specific properties - * and hints - * - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if there is no - * transaction - * @throws EntityNotFoundException if the entity no longer exists - * in the database - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public void refresh(Object entity, LockModeType lockMode, - Map<String, Object> properties); - - /** - * 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. - */ - public void clear(); - - /** - * Remove the given entity from the persistence context, causing - * a managed entity to become detached. Unflushed changes made - * to the entity if any (including removal of the entity), - * will not be synchronized to the database. Entities which - * previously referenced the detached entity will continue to - * reference it. - * - * @param entity - * - * @throws IllegalArgumentException if the instance is not an - * entity - */ - public void detach(Object entity); - - /** - * Check if the instance is a managed entity instance belonging - * to the current persistence context. - * - * @param entity - * - * @return - * - * @throws IllegalArgumentException if not an entity - */ - public boolean contains(Object entity); - - /** - * Get the current lock mode for the entity instance. - * - * @param entity - * - * @return lock mode - * - * @throws TransactionRequiredException if there is no - * transaction - * @throws IllegalArgumentException if the instance is not a - * managed entity and a transaction is active - */ - public LockModeType getLockMode(Object entity); - - /** - * Set an entity manager property. - * If a vendor-specific property is not recognized, it is - * silently ignored. - * - * @param propertyName - * @param value - * - * @throws IllegalArgumentException if the second argument is not - * valid for the implementation - */ - public void setProperty(String propertyName, Object value); - - /** - * 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. - */ - public Map<String, Object> getProperties(); - - /** - * 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. - * - * @return property names - */ - public Set<String> getSupportedProperties(); - - /** - * Create an instance of Query for executing a - * Java Persistence query language statement. - * - * @param qlString a Java Persistence query string - * - * @return the new query instance - * - * @throws IllegalArgumentException if the query string is found - * to be invalid - */ - public Query createQuery(String qlString); - - /** - * Create an instance of Query for executing a - * criteria query. - * - * @param criteriaQuery a Criteria API query definition object - * - * @return the new query instance - * - * @throws IllegalArgumentException if the query definition is - * found to be invalid - */ - public Query createQuery(CriteriaQuery criteriaQuery); - - /** - * Create an instance of Query for executing a - * named query (in the Java Persistence query language - * or in native SQL). - * - * @param name the name of a query defined in metadata - * - * @return the new query instance - * - * @throws IllegalArgumentException if a query has not been - * defined with the given name or if the query string is - * found to be invalid - */ - public Query createNamedQuery(String name); - - /** - * Create an instance of Query for executing - * a native SQL statement, e.g., for update or delete. - * - * @param sqlString a native SQL query string - * - * @return the new query instance - */ - public Query createNativeQuery(String sqlString); - - /** - * Create an instance of Query for executing - * a native SQL query. - * - * @param sqlString a native SQL query string - * @param resultClass the class of the resulting instance(s) - * - * @return the new query instance - */ - public Query createNativeQuery(String sqlString, - Class resultClass); - - /** - * Create an instance of Query for executing - * a native SQL query. - * - * @param sqlString a native SQL query string - * @param resultSetMapping the name of the result set mapping - * - * @return the new query instance - */ - public Query createNativeQuery(String sqlString, - String resultSetMapping); - - /** - * 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. - */ - public void joinTransaction(); - - /** - * 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. - * - * @param cls the class of the object to be returned. This is - * normally either the underlying EntityManager implementation - * class or an interface that it implements. - * - * @return an instance of the specified class - * - * @throws PersistenceException if the provider does not - * support the call. - */ - public <T> T unwrap(Class<T> cls); - - /** - * Return the underlying provider object for the EntityManager, - * if available. The result of this method is implementation - * specific. The unwrap method is to be preferred for new - * applications. - * / - * public Object getDelegate(); - * /** - * 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 getProperties, getSupportedProperties, 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. - */ - public void close(); - - /** - * Determine whether the EntityManager is open. - * - * @return true until the EntityManager has been closed. - */ - public boolean isOpen(); - - /** - * Return the resource-level transaction object. - * The EntityTransaction instance may be used serially to - * begin and commit multiple transactions. - * - * @return EntityTransaction instance - * - * @throws IllegalStateException if invoked on a JTA - * EntityManager. - */ - public EntityTransaction getTransaction(); - - /** - * Return the entity manager factory for the entity manager. - * - * @return EntityManagerFactory instance - * - * @throws IllegalStateException if the entity manager has - * been closed. - */ - public EntityManagerFactory getEntityManagerFactory(); - - /** - * Return an instance of QueryBuilder for the creation of - * Criteria API Query objects. - * - * @return QueryBuilder instance - * - * @throws IllegalStateException if the entity manager has - * been closed. - */ - public QueryBuilder getQueryBuilder(); - - /** - * Return an instance of Metamodel interface for access to the - * metamodel of the persistence unit. - * - * @return Metamodel instance - * - * @throws IllegalStateException if the entity manager has - * been closed. - */ - public Metamodel getMetamodel(); +package javax.persistence; + +import java.util.Map; +import java.util.Set; +import javax.persistence.criteria.CriteriaQuery; +import javax.persistence.criteria.QueryBuilder; +import javax.persistence.metamodel.Metamodel; + +/** + * Interface used to interact with the persistence context. + */ +public interface EntityManager { + /** + * Make an instance managed and persistent. + * + * @param entity + * + * @throws EntityExistsException if the entity already exists. + * (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.) + * @throws IllegalArgumentException if the instance is not an + * entity + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * PersistenceContextType.TRANSACTION and there is + * no transaction. + */ + public void persist(Object entity); + + /** + * Merge the state of the given entity into the + * current persistence context. + * + * @param entity + * + * @return the managed instance that the state was merged to + * + * @throws IllegalArgumentException if instance is not an + * entity or is a removed entity + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * PersistenceContextType.TRANSACTION and there is + * no transaction. + */ + public <T> T merge(T entity); + + /** + * Remove the entity instance. + * + * @param entity + * + * @throws IllegalArgumentException if the instance is not an + * entity or is a detached entity + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * PersistenceContextType.TRANSACTION and there is + * no transaction. + */ + public void remove(Object entity); + + /** + * 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. + * + * @param entityClass + * @param primaryKey + * + * @return 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 + * is not a valid type for that entity�s primary key or + * is null + */ + public <T> T find(Class<T> entityClass, Object primaryKey); + + /** + * Find by primary key, using the specified properties. + * 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. + * If a vendor-specific property or hint is not recognized, + * it is silently ignored. + * + * @param entityClass + * @param primaryKey + * @param properties standard and vendor-specific properties + * + * @return 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 + * is not a valid type for that entity�s primary key or + * is null + */ + public <T> T find(Class<T> entityClass, Object primaryKey, + Map<String, Object> 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, and the effect of this method is + * the same as if the lock method had been called on the entity. + * 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 + * + * @param entityClass + * @param primaryKey + * @param lockMode + * + * @return 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 or + * is null + * @throws TransactionRequiredException if there is no + * transaction and a lock mode other than NONE is set + * @throws OptimisticLockException if the optimistic version + * check fails + * @throws PessimisticLockException if pessimistic locking + * fails and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + */ + public <T> T find(Class<T> entityClass, Object primaryKey, + LockModeType lockMode); + + /** + * Find by primary key and lock, using the specified properties. + * 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. + * + * @param entityClass + * @param primaryKey + * @param lockMode + * @param properties standard and vendor-specific properties + * and hints + * + * @return 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 or + * is null + * @throws TransactionRequiredException if there is no + * transaction and a lock mode other than NONE is set + * @throws OptimisticLockException if the optimistic version + * check fails + * @throws PessimisticLockException if pessimistic locking + * fails and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + */ + public <T> T find(Class<T> entityClass, Object primaryKey, + LockModeType lockMode, + Map<String, Object> properties); + + /** + * 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. + * + * @param entityClass + * @param primaryKey + * + * @return 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 or + * is null + * @throws EntityNotFoundException if the entity state + * cannot be accessed + */ + public <T> T getReference(Class<T> entityClass, + Object primaryKey); + + /** + * Synchronize the persistence context to the + * underlying database. + * + * @throws TransactionRequiredException if there is + * no transaction + * @throws PersistenceException if the flush fails + */ + public void flush(); + + /** + * Set the flush mode that applies to all objects contained + * in the persistence context. + * + * @param flushMode + */ + public void setFlushMode(FlushModeType flushMode); + + /** + * Get the flush mode that applies to all objects contained + * in the persistence context. + * + * @return flushMode + */ + public FlushModeType getFlushMode(); + + /** + * Lock an entity instance that is contained in the persistence + * context with the specified lock mode type. + * If a pessimistic lock mode type is specified and the entity + * contains a version attribute, the persistence provider must + * also 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 + * + * @param entity + * @param lockMode + * + * @throws IllegalArgumentException if the instance is not an + * entity or is a detached entity + * @throws TransactionRequiredException if there is no + * transaction + * @throws EntityNotFoundException if the entity does not exist + * in the database when pessimistic locking is + * performed + * @throws OptimisticLockException if the optimistic version + * check fails + * @throws PessimisticLockException if pessimistic locking fails + * and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + */ + public void lock(Object entity, LockModeType lockMode); + + /** + * Lock an entity instance that is contained in the persistence + * context with the specified lock mode type and with specified + * properties. + * If a pessimistic lock mode type is specified and the entity + * contains a version attribute, the persistence provider must + * also 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. + * + * @param entity + * @param lockMode + * @param properties standard and vendor-specific properties + * and hints + * + * @throws IllegalArgumentException if the instance is not an + * entity or is a detached entity + * @throws TransactionRequiredException if there is no + * transaction + * @throws EntityNotFoundException if the entity does not exist + * in the database when pessimistic locking is + * performed + * @throws OptimisticLockException if the optimistic version + * check fails + * @throws PessimisticLockException if pessimistic locking fails + * and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + */ + public void lock(Object entity, LockModeType lockMode, + Map<String, Object> properties); + + /** + * Refresh the state of the instance from the database, + * overwriting changes made to the entity, if any. + * + * @param entity + * + * @throws IllegalArgumentException if the instance is not + * an entity or the entity is not managed + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * PersistenceContextType.TRANSACTION and there is + * no transaction. + * @throws EntityNotFoundException if the entity no longer + * exists in the database + */ + public void refresh(Object entity); + + /** + * Refresh the state of the instance from the database, using + * the specified properties, and overwriting changes made to + * the entity, if any. + * If a vendor-specific property or hint is not recognized, + * it is silently ignored. + * + * @param entity + * @param properties standard and vendor-specific properties + * + * @throws IllegalArgumentException if the instance is not + * an entity or the entity is not managed + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * PersistenceContextType.TRANSACTION and there is + * no transaction. + * @throws EntityNotFoundException if the entity no longer + * exists in the database + */ + public void refresh(Object entity, + Map<String, Object> 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. + * + * @param entity + * @param lockMode + * + * @throws IllegalArgumentException if the instance is not + * an entity or the entity is not managed + * @throws TransactionRequiredException if there is no + * transaction + * @throws EntityNotFoundException if the entity no longer exists + * in the database + * @throws PessimisticLockException if pessimistic locking fails + * and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + */ + public void refresh(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 and with + * specified properties. + * 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. + * + * @param entity + * @param lockMode + * @param properties standard and vendor-specific properties + * and hints + * + * @throws IllegalArgumentException if the instance is not + * an entity or the entity is not managed + * @throws TransactionRequiredException if there is no + * transaction + * @throws EntityNotFoundException if the entity no longer exists + * in the database + * @throws PessimisticLockException if pessimistic locking fails + * and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + */ + public void refresh(Object entity, LockModeType lockMode, + Map<String, Object> properties); + + /** + * 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. + */ + public void clear(); + + /** + * Remove the given entity from the persistence context, causing + * a managed entity to become detached. Unflushed changes made + * to the entity if any (including removal of the entity), + * will not be synchronized to the database. Entities which + * previously referenced the detached entity will continue to + * reference it. + * + * @param entity + * + * @throws IllegalArgumentException if the instance is not an + * entity + */ + public void detach(Object entity); + + /** + * Check if the instance is a managed entity instance belonging + * to the current persistence context. + * + * @param entity + * + * @return + * + * @throws IllegalArgumentException if not an entity + */ + public boolean contains(Object entity); + + /** + * Get the current lock mode for the entity instance. + * + * @param entity + * + * @return lock mode + * + * @throws TransactionRequiredException if there is no + * transaction + * @throws IllegalArgumentException if the instance is not a + * managed entity and a transaction is active + */ + public LockModeType getLockMode(Object entity); + + /** + * Set an entity manager property. + * If a vendor-specific property is not recognized, it is + * silently ignored. + * + * @param propertyName + * @param value + * + * @throws IllegalArgumentException if the second argument is not + * valid for the implementation + */ + public void setProperty(String propertyName, Object value); + + /** + * 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. + */ + public Map<String, Object> getProperties(); + + /** + * 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. + * + * @return property names + */ + public Set<String> getSupportedProperties(); + + /** + * Create an instance of Query for executing a + * Java Persistence query language statement. + * + * @param qlString a Java Persistence query string + * + * @return the new query instance + * + * @throws IllegalArgumentException if the query string is found + * to be invalid + */ + public Query createQuery(String qlString); + + /** + * Create an instance of Query for executing a + * criteria query. + * + * @param criteriaQuery a Criteria API query definition object + * + * @return the new query instance + * + * @throws IllegalArgumentException if the query definition is + * found to be invalid + */ + public Query createQuery(CriteriaQuery criteriaQuery); + + /** + * Create an instance of Query for executing a + * named query (in the Java Persistence query language + * or in native SQL). + * + * @param name the name of a query defined in metadata + * + * @return the new query instance + * + * @throws IllegalArgumentException if a query has not been + * defined with the given name or if the query string is + * found to be invalid + */ + public Query createNamedQuery(String name); + + /** + * Create an instance of Query for executing + * a native SQL statement, e.g., for update or delete. + * + * @param sqlString a native SQL query string + * + * @return the new query instance + */ + public Query createNativeQuery(String sqlString); + + /** + * Create an instance of Query for executing + * a native SQL query. + * + * @param sqlString a native SQL query string + * @param resultClass the class of the resulting instance(s) + * + * @return the new query instance + */ + public Query createNativeQuery(String sqlString, + Class resultClass); + + /** + * Create an instance of Query for executing + * a native SQL query. + * + * @param sqlString a native SQL query string + * @param resultSetMapping the name of the result set mapping + * + * @return the new query instance + */ + public Query createNativeQuery(String sqlString, + String resultSetMapping); + + /** + * 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. + */ + public void joinTransaction(); + + /** + * 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. + * + * @param cls the class of the object to be returned. This is + * normally either the underlying EntityManager implementation + * class or an interface that it implements. + * + * @return an instance of the specified class + * + * @throws PersistenceException if the provider does not + * support the call. + */ + public <T> T unwrap(Class<T> cls); + + /** + * Return the underlying provider object for the EntityManager, + * if available. The result of this method is implementation + * specific. The unwrap method is to be preferred for new + * applications. + */ + public Object getDelegate(); + + /** + * Return the underlying provider object for the EntityManager, + * if available. The result of this method is implementation + * specific. The unwrap method is to be preferred for new + * applications. + * / + * public Object getDelegate(); + * /** + * 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 getProperties, getSupportedProperties, 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. + */ + public void close(); + + /** + * Determine whether the EntityManager is open. + * + * @return true until the EntityManager has been closed. + */ + public boolean isOpen(); + + /** + * Return the resource-level transaction object. + * The EntityTransaction instance may be used serially to + * begin and commit multiple transactions. + * + * @return EntityTransaction instance + * + * @throws IllegalStateException if invoked on a JTA + * EntityManager. + */ + public EntityTransaction getTransaction(); + + /** + * Return the entity manager factory for the entity manager. + * + * @return EntityManagerFactory instance + * + * @throws IllegalStateException if the entity manager has + * been closed. + */ + public EntityManagerFactory getEntityManagerFactory(); + + /** + * Return an instance of QueryBuilder for the creation of + * Criteria API Query objects. + * + * @return QueryBuilder instance + * + * @throws IllegalStateException if the entity manager has + * been closed. + */ + public QueryBuilder getQueryBuilder(); + + /** + * Return an instance of Metamodel interface for access to the + * metamodel of the persistence unit. + * + * @return Metamodel instance + * + * @throws IllegalStateException if the entity manager has + * been closed. + */ + public Metamodel getMetamodel(); }