| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| |
| // |
| // This source code implements specifications defined by the Java |
| // Community Process. In order to remain compliant with the specification |
| // DO NOT add / change / or delete method signatures! |
| // |
| package javax.persistence; |
| |
| import java.util.Map; |
| import java.util.Set; |
| |
| /** |
| * Interface used to interact with the persistence context. |
| * |
| * @version $Rev$ $Date$ |
| */ |
| public interface EntityManager { |
| |
| /** |
| * Make an 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 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 entitys primary key or |
| * is null |
| */ |
| 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, 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 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 entitys 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, |
| * 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. |
| * |
| * @param entity |
| * @throws IllegalArgumentException if the instance is not an |
| * entity |
| */ |
| public void clear(Object entity); |
| |
| // Open Issue: Alternative names for this method and the corresponding cascade option. |
| /** |
| * 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); |
| |
| /** |
| * 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 qdef 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(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 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 QueryDefinition objects. |
| * |
| * @return QueryBuilder instance |
| * @throws IllegalStateException if the entity manager has |
| * been closed. |
| */ |
| public QueryBuilder getQueryBuilder(); |
| } |
