/*******************************************************************************
 * Copyright (c) 1998, 2009 Oracle. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0
 * which accompanies this distribution.
 * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * The API for this class and its comments are derived from the JPA 2.0 specification
 * which is developed under the Java Community Process (JSR 317) and is copyright
 * Sun Microsystems, Inc.
 *
 * Contributors:
 *     dclarke - Java Persistence API 2.0 Public Draft
 *     			 Specification and licensing terms available from
 *     		   	 http://jcp.org/en/jsr/detail?id=317
 *
 * EARLY ACCESS - PUBLIC DRAFT
 * This is an implementation of an early-draft specification developed under the
 * Java Community Process (JCP) and is made available for testing and evaluation
 * purposes only. The code is not compatible with any specification of the JCP.
 ******************************************************************************/

package javax.persistence;

import java.util.Map;
import java.util.Set;

/**
 * Interface used to interact with the persistence context.
 *
 * <p>
 * An <code>EntityManager</code> instance is associated with a persistence
 * context. A persistence context is a set of entity instances in which for any
 * persistent entity identity there is a unique entity instance. Within the
 * persistence context, the entity instances and their life-cycle are managed.
 * This interface defines the methods that are used to interact with the
 * persistence context. The <code>EntityManager</code> API is used to create and
 * remove persistent entity instances, to find entities by their primary key,
 * and to query over entities.
 *
 * <p>
 * The set of entities that can be managed by a given <code>EntityManager</code>
 * instance is defined by a persistence unit. A persistence unit defines the set
 * of all classes that are related or grouped by the application, and which must
 * be co-located in their mapping to a single database.
 *
 * @since Java Persistence API 1.0
 */
public interface EntityManager {

	/**
	 * Make an entity instance managed and persistent.
	 *
	 * @param 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.)
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 * @throws IllegalArgumentException
	 *             if 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 instance that the state was merged to
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 * @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 IllegalStateException
	 *             if this EntityManager has been closed.
	 * @throws IllegalArgumentException
	 *             if not an entity or if 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 IllegalStateException
	 *             if this EntityManager has been closed.
	 * @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
	 */
	public <T> T find(Class<T> entityClass, Object primaryKey);

	/**
	 * 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. 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
	 * @since Java Persistence API 2.0
	 */
	public <T> T find(Class<T> entityClass, Object primaryKey, LockModeType lockMode);

	/**
	 * 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. 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
	 * @since Java Persistence API 2.0
	 */
	public <T> T find(Class<T> entityClass, Object primaryKey, LockModeType lockMode, Map properties);

	/**
	 * Get an instance, whose state may be lazily fetched. If the requested
	 * instance does not exist in the database, throws
	 * {@link EntityNotFoundException} when the instance state is first
	 * accessed. (The persistence provider runtime is permitted to throw
	 * {@link EntityNotFoundException} when {@link #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 IllegalStateException
	 *             if this EntityManager has been closed.
	 * @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
	 */
	public <T> T getReference(Class<T> entityClass, Object primaryKey);

	/**
	 * Synchronize the persistence context to the underlying database.
	 *
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 * @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
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 */
	public void setFlushMode(FlushModeType flushMode);

	/**
	 * Get the flush mode that applies to all objects contained in the
	 * persistence context.
	 *
	 * @return flush mode
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 */
	public FlushModeType getFlushMode();

	/**
	 * Set the lock mode for an entity object contained in the persistence
	 * context.
	 *
	 * @param entity
	 * @param lockMode
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 * @throws PersistenceException
	 *             if an unsupported lock call is made
	 * @throws IllegalArgumentException
	 *             if the instance is not an entity or is a detached entity
	 * @throws TransactionRequiredException
	 *             if there is no transaction
	 */
	public void lock(Object entity, LockModeType lockMode);

	/**
	 * Set the lock mode for an entity object contained in the persistence
	 * context.
	 *
	 * @param entity
	 * @param lockMode
	 * @throws PersistenceException
	 *             if an unsupported lock call is made
	 * @throws IllegalArgumentException
	 *             if the instance is not an entity or is a detached entity
	 * @throws javax.persistence.TransactionRequiredException
	 *             if there is no transaction
	 * @since Java Persistence API 2.0
	 */
	public void lock(Object entity, LockModeType lockMode, Map properties);

	/**
	 * Refresh the state of the instance from the database, overwriting changes
	 * made to the entity, if any.
	 *
	 * @param entity
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 * @throws IllegalArgumentException
	 *             if not an entity or 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, 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:
	 * <ul>
	 * <li> the PessimisticLockException will be thrown if the database locking
	 * failure causes transaction-level rollback. <li> the LockTimeoutException
	 * will be thrown if the database locking failure causes only
	 * statement-level rollback.
	 * </ul>
	 *
	 * @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
	 * @since Java Persistence API 2.0
	 */
	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. If the lock mode type is pessimistic and the entity instance is
	 * found but cannot be locked:
	 * <ul>
	 * <li> the PessimisticLockException will be thrown if the database locking
	 * failure causes transaction-level rollback. <li> 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.
	 * </ul>
	 * <p>
	 * 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
	 * @since Java Persistence API 2.0
	 */
	public void refresh(Object entity, LockModeType lockMode, Map 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.
	 *
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 */
	public void clear();

	/**
	 * Remove the given entity from the persistence context, causing a managed
	 * entity to become detached. Changes made to the entity that have not been
	 * flushed, if any (including removal of the entity), will not be
	 * synchronized to the database.
	 *
	 * @param entity
	 * @throws IllegalArgumentException
	 *             if the instance is not an entity
	 * @since Java Persistence API 2.0
	 */
	public void clear(Object entity);

	/**
	 * Check if the instance belongs to the current persistence context.
	 *
	 * @param entity
	 * @return <code>true</code> if the instance belongs to the current
	 *         persistence context.
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 * @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
	 * @since Java Persistence API 2.0
	 */
	public LockModeType getLockMode(Object entity);

	/**
	 * 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.
	 *
	 * @since Java Persistence API 2.0
	 */
	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
	 * @since Java Persistence API 2.0
	 */
	public Set<String> getSupportedProperties();

	/**
	 * Create an instance of Query for executing a Java Persistence query
	 * language statement.
	 *
	 * @param qlString
	 *            a Java Persistence query language query string
	 * @return the new query instance
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 * @throws IllegalArgumentException
	 *             if query string is not valid
	 */
	public Query createQuery(String qlString);

	/**
	 * Create an instance of Query for executing a criteria query.
	 *
	 * @param qdef
	 *            a Criteria API query definition object
	 * @return the new query instance
	 * @throws IllegalArgumentException
	 *             if the query definition is found to be invalid
	 * @since Java Persistence API 2.0
	 */
	public Query createQuery(QueryDefinition qdef);

	/**
	 * 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 IllegalStateException
	 *             if this EntityManager has been closed.
	 * @throws IllegalArgumentException
	 *             if a query has not been defined with the given name
	 */
	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
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 */
	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
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 */
	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
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 */
	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 IllegalStateException
	 *             if this EntityManager has been closed.
	 * @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.
	 * @since Java Persistence API 2.0
	 */
	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.
	 *
	 * @throws IllegalStateException
	 *             if this EntityManager has been closed.
	 */
	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
	 * 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 or has been already
	 *             closed..
	 */
	public void close();

	/**
	 * Determine whether the EntityManager is open.
	 *
	 * @return true until the EntityManager has been closed.
	 */
	public boolean isOpen();

	/**
	 * Returns 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.
	 * @since Java Persistence API 2.0
	 */
	public EntityManagerFactory getEntityManagerFactory();

	/**
	 * Return an instance of QueryBuilder for the creation of Criteria API
	 * QueryDefinition objects.
	 *
	 * @return QueryBuilder instance
	 * @throws IllegalStateException
	 *             if the entity manager has been closed.
	 * @since Java Persistence API 2.0
	 */
	public QueryBuilder getQueryBuilder();
}