geronimo-scm mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From djen...@apache.org
Subject svn commit: r721048 [2/5] - in /geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence: ./ spi/
Date Thu, 27 Nov 2008 00:23:46 GMT
Modified: geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityManager.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityManager.java?rev=721048&r1=721047&r2=721048&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityManager.java (original)
+++ geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityManager.java Wed Nov 26 16:23:43 2008
@@ -27,529 +27,596 @@
 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.
-    */
+     * 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.
-    */
+     * 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.
-    */
+     * 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
-    */
+     * 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 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
-    */
+     * 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);
+                      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
-    */
+     * 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);
+                      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
-    */
+     * 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
-    */
+     * 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
-    */
+     * 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
-    */
+     * 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
-    */
+     * 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
-    */
+     * 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);
+                     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
-    */
+     * 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
-    */
+     * 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
-    */
+     * 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);
+                        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.
-    */
+     * 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
-    */
+     * 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.
+
+    //    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
-    */
+     * 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
-    */
+     * 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.
-    */
+     * 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
-    */
+     * 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
-    */
+     * 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
-    */
+     * 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
-    */
+     * 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
-    */
+     * 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
-    */
+     * 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);
+                                   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
-    */
+     * 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);
+                                   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.
-    */
+     * 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.
-    */
+     * 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.
-    */
+     * 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.
-    */
+     * 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.
-    */
+     * 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.
-    */
+     * 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.
-    */
+     * 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.
-    */
+     * 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();
 }

Modified: geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityManagerFactory.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityManagerFactory.java?rev=721048&r1=721047&r2=721048&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityManagerFactory.java (original)
+++ geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityManagerFactory.java Wed Nov 26 16:23:43 2008
@@ -29,78 +29,93 @@
 
 /**
  * Interface used to interact with the entity manager factory
- * for the persistence unit. 
+ * for the persistence unit.
+ *
  * @version $Rev$ $Date$
  */
 public interface EntityManagerFactory {
 
     /**
-    * Create a new EntityManager.
-    * This method returns a new EntityManager instance each time
-    * it is invoked.
-    * The isOpen method will return true on the returned instance.
-    * @throws IllegalStateException if the entity manager factory
-    * has been closed.
-    */
+     * Create a new EntityManager.
+     * This method returns a new EntityManager instance each time
+     * it is invoked.
+     * The isOpen method will return true on the returned instance.
+     *
+     * @throws IllegalStateException if the entity manager factory
+     *                               has been closed.
+     */
     public EntityManager createEntityManager();
+
     /**
-    * Create a new EntityManager with the specified Map of
-    * properties.
-    * This method returns a new EntityManager instance each time
-    * it is invoked.
-    * The isOpen method will return true on the returned instance.
-    * @throws IllegalStateException if the entity manager factory
-    * has been closed.
-    */
+     * Create a new EntityManager with the specified Map of
+     * properties.
+     * This method returns a new EntityManager instance each time
+     * it is invoked.
+     * The isOpen method will return true on the returned instance.
+     *
+     * @throws IllegalStateException if the entity manager factory
+     *                               has been closed.
+     */
     public EntityManager createEntityManager(Map map);
+
     /**
-    * Return an instance of QueryBuilder for the creation of
-    * Criteria API QueryDefinition objects.
-    * @return QueryBuilder instance
-    * @throws IllegalStateException if the entity manager factory
-    * has been closed.
-    */
+     * Return an instance of QueryBuilder for the creation of
+     * Criteria API QueryDefinition objects.
+     *
+     * @return QueryBuilder instance
+     * @throws IllegalStateException if the entity manager factory
+     *                               has been closed.
+     */
     public QueryBuilder getQueryBuilder();
+
     /**
-    * Close the factory, releasing any resources that it holds.
-    * After a factory instance is closed, all methods invoked on
-    * it will throw an IllegalStateException, except for isOpen,
-    * which will return false. Once an EntityManagerFactory has
-    * been closed, all its entity managers are considered to be
-    * in the closed state.
-    * @throws IllegalStateException if the entity manager factory
-    * has been closed.
-    */
+     * Close the factory, releasing any resources that it holds.
+     * After a factory instance is closed, all methods invoked on
+     * it will throw an IllegalStateException, except for isOpen,
+     * which will return false. Once an EntityManagerFactory has
+     * been closed, all its entity managers are considered to be
+     * in the closed state.
+     *
+     * @throws IllegalStateException if the entity manager factory
+     *                               has been closed.
+     */
     public void close();
+
     /**
-    * Indicates whether the factory is open. Returns true
-    * until the factory has been closed.
-    */
+     * Indicates whether the factory is open. Returns true
+     * until the factory has been closed.
+     */
     public boolean isOpen();
+
     /**
-    * Get the properties and associated values that are in effect
-    * for the entity manager factory. Changing the contents of the
-    * map does not change the configuration in effect.
-    * @return properties
-    */
+     * Get the properties and associated values that are in effect
+     * for the entity manager factory. Changing the contents of the
+     * map does not change the configuration in effect.
+     *
+     * @return properties
+     */
     public Map getProperties();
+
     /**
-    * Get the names of the properties that are supported for use
-    * with the entity manager factory. These correspond to
-    * properties that may be passed to the methods of the
-    * EntityManagerFactory interface that take a properties
-    * argument. These include all standard properties as well as
-    * vendor-specific properties supported by the provider. These
-    * properties may or may not currently be in effect.
-    * @return properties and hints
-    */
+     * Get the names of the properties that are supported for use
+     * with the entity manager factory. These correspond to
+     * properties that may be passed to the methods of the
+     * EntityManagerFactory interface that take a properties
+     * argument. These include all standard properties as well as
+     * vendor-specific properties supported by the provider. These
+     * properties may or may not currently be in effect.
+     *
+     * @return properties and hints
+     */
     public Set<String> getSupportedProperties();
+
     /**
-    * Access the cache that is associated with the entity manager
-    * factory (the "second level cache").
-    * @return instance of the Cache interface
-    * @throws IllegalStateException if the entity manager factory
-    * has been closed.
-    */
+     * Access the cache that is associated with the entity manager
+     * factory (the "second level cache").
+     *
+     * @return instance of the Cache interface
+     * @throws IllegalStateException if the entity manager factory
+     *                               has been closed.
+     */
     public Cache getCache();
 }

Modified: geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityResult.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityResult.java?rev=721048&r1=721047&r2=721048&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityResult.java (original)
+++ geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityResult.java Wed Nov 26 16:23:43 2008
@@ -24,9 +24,9 @@
 //
 package javax.persistence;
 
-import java.lang.annotation.Target;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
  * @version $Rev$ $Date$

Modified: geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityTransaction.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityTransaction.java?rev=721048&r1=721047&r2=721048&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityTransaction.java (original)
+++ geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/EntityTransaction.java Wed Nov 26 16:23:43 2008
@@ -28,16 +28,16 @@
  * @version $Rev$ $Date$
  */
 public interface EntityTransaction {
-	public void begin();
+    public void begin();
 
-	public void commit();
+    public void commit();
 
-	public void rollback();
+    public void rollback();
 
-	public boolean isActive();
+    public boolean isActive();
 
-	public void setRollbackOnly();
+    public void setRollbackOnly();
 
-	public boolean getRollbackOnly();
+    public boolean getRollbackOnly();
 
 }

Modified: geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/Enumerated.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/Enumerated.java?rev=721048&r1=721047&r2=721048&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/Enumerated.java (original)
+++ geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/Enumerated.java Wed Nov 26 16:23:43 2008
@@ -24,10 +24,10 @@
 //
 package javax.persistence;
 
-import java.lang.annotation.Retention;
-import java.lang.annotation.Target;
 import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
  * @version $Rev$ $Date$

Modified: geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/ExcludeDefaultListeners.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/ExcludeDefaultListeners.java?rev=721048&r1=721047&r2=721048&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/ExcludeDefaultListeners.java (original)
+++ geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/ExcludeDefaultListeners.java Wed Nov 26 16:23:43 2008
@@ -24,15 +24,15 @@
 //
 package javax.persistence;
 
-import java.lang.annotation.Target;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
  * @version $Rev$ $Date$
  */
-@Target( { ElementType.TYPE })
+@Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ExcludeDefaultListeners {
 } 

Modified: geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/ExcludeSuperclassListeners.java
URL: http://svn.apache.org/viewvc/geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/ExcludeSuperclassListeners.java?rev=721048&r1=721047&r2=721048&view=diff
==============================================================================
--- geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/ExcludeSuperclassListeners.java (original)
+++ geronimo/specs/trunk/geronimo-jpa_2.0_spec/src/main/java/javax/persistence/ExcludeSuperclassListeners.java Wed Nov 26 16:23:43 2008
@@ -24,15 +24,15 @@
 //
 package javax.persistence;
 
-import java.lang.annotation.Target;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
 
 /**
  * @version $Rev$ $Date$
  */
-@Target( { ElementType.TYPE })
+@Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ExcludeSuperclassListeners {
 }



Mime
View raw message