Author: hardy.ferentschik Date: 2009-05-12 08:01:51 -0400 (Tue, 12 May 2009) New Revision: 16548 Added: jpa-api/tags/v2_0_Beta2/ jpa-api/tags/v2_0_Beta2/pom.xml jpa-api/tags/v2_0_Beta2/src/main/java/javax/persistence/EntityManager.java Removed: jpa-api/tags/v2_0_Beta2/pom.xml jpa-api/tags/v2_0_Beta2/src/main/java/javax/persistence/EntityManager.java Log: Created tag v2_0_Beta2. Copied: jpa-api/tags/v2_0_Beta2 (from rev 16193, jpa-api/trunk) Deleted: jpa-api/tags/v2_0_Beta2/pom.xml =================================================================== --- jpa-api/trunk/pom.xml 2009-03-20 11:39:26 UTC (rev 16193) +++ jpa-api/tags/v2_0_Beta2/pom.xml 2009-05-12 12:01:51 UTC (rev 16548) @@ -1,130 +0,0 @@ -<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> - <modelVersion>4.0.0</modelVersion> - - <groupId>org.hibernate.java-persistence</groupId> - <artifactId>jpa-api</artifactId> - <version>2.0.Beta1</version> - <packaging>jar</packaging> - <name>JPA API</name> - - <description>JSR 317: Java Persistence API 2.0</description> - - <inceptionYear>2007</inceptionYear> - - <licenses> - <license> - <url>license.txt</url> - </license> - </licenses> - - <scm> - <connection>scm:svn:https://svn.jboss.org/repos/hibernate/jpa-api/tags/... - <url>http://fisheye.jboss.org/browse/Hibernate/jpa-api/tags/v2_0_Beta1&... - </scm> - - <developers> - <developer> - <id>epbernard</id> - <name>Emmanuel Bernard</name> - <email&gt;emmanuel(a)hibernate.org&lt;/email&gt; - <organization>JBoss, a division of Red Hat</organization> - <url>http://in.relation.to/Bloggers/Emmanuel</url> - </developer> - <developer> - <id>hardy.ferentschik</id> - <name>Hardy Ferentschik</name> - <email&gt;hferents(a)redhat.com&lt;/email&gt; - <organization>JBoss, a division of Red Hat</organization> - <url>http://in.relation.to/Bloggers/Hardy</url> - </developer> - </developers> - - <build> - <extensions> - <extension> - <groupId>org.apache.maven.wagon</groupId> - <artifactId>wagon-webdav</artifactId> - <version>1.0-beta-2</version> - </extension> - </extensions> - <pluginManagement> - <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-compiler-plugin</artifactId> - <version>2.0.2</version> - <configuration> - <source>1.5</source> - <target>1.5</target> - </configuration> - </plugin> - <plugin> - <artifactId>maven-source-plugin</artifactId> - <executions> - <execution> - <id>attach-sources</id> - <goals> - <goal>jar</goal> - </goals> - </execution> - </executions> - </plugin> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-jar-plugin</artifactId> - <version>2.2</version> - <configuration> - <archive> - <manifestEntries> - <Built-By>hibernate.org</Built-By> - <Specification-Title>Java Persistence API, Version 2.0</Specification-Title> - <Specification-Version>${pom.version}</Specification-Version> - <Specification-Vendor>Sun Microsystems, Inc.</Specification-Vendor> - <Implementation-Version>${pom.version}</Implementation-Version> - <Implementation-Vendor>hibernate.org</Implementation-Vendor> - <Implementation-Title>JAP API</Implementation-Title> - </manifestEntries> - </archive> - </configuration> - </plugin> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-javadoc-plugin</artifactId> - <version>2.5</version> - <configuration> - <use>true</use> - <version>true</version> - <overview>${basedir}/src/main/javadoc/package.html</overview> - <windowtitle>EJB 3.0 Persistence API Documentation</windowtitle> - <doctitle>EJB 3.0 Persistence API Documentation</doctitle> - <links> - <link>http://java.sun.com/j2se/1.5/docs/api</link> - </links> - <stylesheetfile>${basedir}/src/main/javadoc/jdstyle.css</stylesheetfile> - </configuration> - </plugin> - <plugin> - <artifactId>maven-release-plugin</artifactId> - <configuration> - <goals>package</goals> - </configuration> - </plugin> - </plugins> - </pluginManagement> - </build> - - <distributionManagement> - <repository> - <!-- Copy the dist to the local checkout of the JBoss maven2 repo ${maven.repository.root} --> - <!-- It is anticipated that ${maven.repository.root} be set in user's settings.xml --> - <!-- todo : replace this with direct svn access once the svnkit providers are available --> - <id>repository.jboss.org</id> - <url>file://${maven.repository.root}</url> - </repository> - <snapshotRepository> - <id>snapshots.jboss.org</id> - <name>JBoss Snapshot Repository</name> - <url>dav:https://snapshots.jboss.org/maven2</url> - </snapshotRepository> - </distributionManagement> -</project> \ No newline at end of file Copied: jpa-api/tags/v2_0_Beta2/pom.xml (from rev 16547, jpa-api/trunk/pom.xml) =================================================================== --- jpa-api/tags/v2_0_Beta2/pom.xml (rev 0) +++ jpa-api/tags/v2_0_Beta2/pom.xml 2009-05-12 12:01:51 UTC (rev 16548) @@ -0,0 +1,127 @@ +<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> + <modelVersion>4.0.0</modelVersion> + + <groupId>org.hibernate.java-persistence</groupId> + <artifactId>jpa-api</artifactId> + <version>2.0.Beta2</version> + <packaging>jar</packaging> + <name>JPA API</name> + + <description>JSR 317: Java Persistence API 2.0</description> + + <inceptionYear>2007</inceptionYear> + + <licenses> + <license> + <url>license.txt</url> + </license> + </licenses> + + <scm> + <connection>scm:svn:https://svn.jboss.org/repos/hibernate/jpa-api/tags/... + <url>http://fisheye.jboss.org/browse/Hibernate/jpa-api/tags/v2_0_Beta2&... + </scm> + + <developers> + <developer> + <id>epbernard</id> + <name>Emmanuel Bernard</name> + <email&gt;emmanuel(a)hibernate.org&lt;/email&gt; + <organization>JBoss, a division of Red Hat</organization> + <url>http://in.relation.to/Bloggers/Emmanuel</url> + </developer> + <developer> + <id>hardy.ferentschik</id> + <name>Hardy Ferentschik</name> + <email&gt;hferents(a)redhat.com&lt;/email&gt; + <organization>JBoss, a division of Red Hat</organization> + <url>http://in.relation.to/Bloggers/Hardy</url> + </developer> + </developers> + + <build> + <extensions> + <extension> + <groupId>org.apache.maven.wagon</groupId> + <artifactId>wagon-webdav</artifactId> + <version>1.0-beta-2</version> + </extension> + </extensions> + <pluginManagement> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-compiler-plugin</artifactId> + <version>2.0.2</version> + <configuration> + <source>1.5</source> + <target>1.5</target> + </configuration> + </plugin> + <plugin> + <artifactId>maven-source-plugin</artifactId> + <executions> + <execution> + <id>attach-sources</id> + <goals> + <goal>jar</goal> + </goals> + </execution> + </executions> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-jar-plugin</artifactId> + <version>2.2</version> + <configuration> + <archive> + <manifestEntries> + <Built-By>hibernate.org</Built-By> + <Specification-Title>Java Persistence API, Version 2.0</Specification-Title> + <Specification-Version>${pom.version}</Specification-Version> + <Specification-Vendor>Sun Microsystems, Inc.</Specification-Vendor> + <Implementation-Version>${pom.version}</Implementation-Version> + <Implementation-Vendor>hibernate.org</Implementation-Vendor> + <Implementation-Title>JAP API</Implementation-Title> + </manifestEntries> + </archive> + </configuration> + </plugin> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <version>2.5</version> + <configuration> + <use>true</use> + <version>true</version> + <overview>${basedir}/src/main/javadoc/package.html</overview> + <windowtitle>EJB 3.0 Persistence API Documentation</windowtitle> + <doctitle>EJB 3.0 Persistence API Documentation</doctitle> + <links> + <link>http://java.sun.com/j2se/1.5/docs/api</link> + </links> + <stylesheetfile>${basedir}/src/main/javadoc/jdstyle.css</stylesheetfile> + </configuration> + </plugin> + <plugin> + <artifactId>maven-release-plugin</artifactId> + <configuration> + <goals>package</goals> + </configuration> + </plugin> + </plugins> + </pluginManagement> + </build> + + <distributionManagement> + <repository> + <id>repository.jboss.org</id> + <url>file://${maven.repository.root}</url> + </repository> + <snapshotRepository> + <id>snapshots.jboss.org</id> + <name>JBoss Snapshot Repository</name> + <url>dav:https://snapshots.jboss.org/maven2</url> + </snapshotRepository> + </distributionManagement> +</project> Deleted: jpa-api/tags/v2_0_Beta2/src/main/java/javax/persistence/EntityManager.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java 2009-03-20 11:39:26 UTC (rev 16193) +++ jpa-api/tags/v2_0_Beta2/src/main/java/javax/persistence/EntityManager.java 2009-05-12 12:01:51 UTC (rev 16548) @@ -1,706 +0,0 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence; - -import java.util.Map; -import java.util.Set; -import javax.persistence.criteria.CriteriaQuery; -import javax.persistence.criteria.QueryBuilder; -import javax.persistence.metamodel.Metamodel; - -/** - * Interface used to interact with the persistence context. - */ -public interface EntityManager { - /** - * Make an instance managed and persistent. - * - * @param entity - * - * @throws EntityExistsException if the entity already exists. - * (If the entity already exists, the EntityExistsException may - * be thrown when the persist operation is invoked, or the - * EntityExistsException or another PersistenceException may be - * thrown at flush or commit time.) - * @throws IllegalArgumentException if the instance is not an - * entity - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - */ - public void persist(Object entity); - - /** - * Merge the state of the given entity into the - * current persistence context. - * - * @param entity - * - * @return the managed instance that the state was merged to - * - * @throws IllegalArgumentException if instance is not an - * entity or is a removed entity - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - */ - public <T> T merge(T entity); - - /** - * Remove the entity instance. - * - * @param entity - * - * @throws IllegalArgumentException if the instance is not an - * entity or is a detached entity - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - */ - public void remove(Object entity); - - /** - * Find by primary key. - * Search for an entity of the specified class and primary key. - * If the entity instance is contained in the persistence context - * it is returned from there. - * - * @param entityClass - * @param primaryKey - * - * @return the found entity instance or null - * if the entity does not exist - * - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * is not a valid type for that entity�s primary key or - * is null - */ - public <T> T find(Class<T> entityClass, Object primaryKey); - - /** - * Find by primary key, using the specified properties. - * Search for an entity of the specified class and primary key. - * If the entity instance is contained in the persistence context - * it is returned from there. - * If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * - * @param entityClass - * @param primaryKey - * @param properties standard and vendor-specific properties - * - * @return the found entity instance or null - * if the entity does not exist - * - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * is not a valid type for that entity�s primary key or - * is null - */ - public <T> T find(Class<T> entityClass, Object primaryKey, - Map<String, Object> properties); - - /** - * Find by primary key and lock. - * Search for an entity of the specified class and primary key - * and lock it with respect to the specified lock type. - * If the entity instance is contained in the persistence context - * it is returned from there, and the effect of this method is - * the same as if the lock method had been called on the entity. - * If the entity is found within the persistence context and the - * lock mode type is pessimistic and the entity has a version - * attribute, the persistence provider must perform optimistic - * version checks when obtaining the database lock. If these - * checks fail, the OptimisticLockException will be thrown. - * If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - * - the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback. - * - the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - * - * @param entityClass - * @param primaryKey - * @param lockMode - * - * @return the found entity instance or null if the entity does - * not exist - * - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * not a valid type for that entity's primary key or - * is null - * @throws TransactionRequiredException if there is no - * transaction and a lock mode other than NONE is set - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public <T> T find(Class<T> entityClass, Object primaryKey, - LockModeType lockMode); - - /** - * Find by primary key and lock, using the specified properties. - * Search for an entity of the specified class and primary key - * and lock it with respect to the specified lock type. - * If the entity instance is contained in the persistence context - * it is returned from there. If the entity is found - * within the persistence context and the lock mode type - * is pessimistic and the entity has a version attribute, the - * persistence provider must perform optimistic version checks - * when obtaining the database lock. If these checks fail, - * the OptimisticLockException will be thrown. - * If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - * - the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback. - * - the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - * If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * Portable applications should not rely on the standard timeout - * hint. Depending on the database in use and the locking - * mechanisms used by the provider, the hint may or may not - * be observed. - * - * @param entityClass - * @param primaryKey - * @param lockMode - * @param properties standard and vendor-specific properties - * and hints - * - * @return the found entity instance or null if the entity does - * not exist - * - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * not a valid type for that entity's primary key or - * is null - * @throws TransactionRequiredException if there is no - * transaction and a lock mode other than NONE is set - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking - * fails and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public <T> T find(Class<T> entityClass, Object primaryKey, - LockModeType lockMode, - Map<String, Object> properties); - - /** - * Get an instance, whose state may be lazily fetched. - * If the requested instance does not exist in the database, - * the EntityNotFoundException is thrown when the instance - * state is first accessed. (The persistence provider runtime is - * permitted to throw the EntityNotFoundException when - * getReference is called.) - * The application should not expect that the instance state will - * be available upon detachment, unless it was accessed by the - * application while the entity manager was open. - * - * @param entityClass - * @param primaryKey - * - * @return the found entity instance - * - * @throws IllegalArgumentException if the first argument does - * not denote an entity type or the second argument is - * not a valid type for that entity�s primary key or - * is null - * @throws EntityNotFoundException if the entity state - * cannot be accessed - */ - public <T> T getReference(Class<T> entityClass, - Object primaryKey); - - /** - * Synchronize the persistence context to the - * underlying database. - * - * @throws TransactionRequiredException if there is - * no transaction - * @throws PersistenceException if the flush fails - */ - public void flush(); - - /** - * Set the flush mode that applies to all objects contained - * in the persistence context. - * - * @param flushMode - */ - public void setFlushMode(FlushModeType flushMode); - - /** - * Get the flush mode that applies to all objects contained - * in the persistence context. - * - * @return flushMode - */ - public FlushModeType getFlushMode(); - - /** - * Lock an entity instance that is contained in the persistence - * context with the specified lock mode type. - * If a pessimistic lock mode type is specified and the entity - * contains a version attribute, the persistence provider must - * also perform optimistic version checks when obtaining the - * database lock. If these checks fail, the - * OptimisticLockException will be thrown. - * If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - * - the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback. - * - the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - * - * @param entity - * @param lockMode - * - * @throws IllegalArgumentException if the instance is not an - * entity or is a detached entity - * @throws TransactionRequiredException if there is no - * transaction - * @throws EntityNotFoundException if the entity does not exist - * in the database when pessimistic locking is - * performed - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public void lock(Object entity, LockModeType lockMode); - - /** - * Lock an entity instance that is contained in the persistence - * context with the specified lock mode type and with specified - * properties. - * If a pessimistic lock mode type is specified and the entity - * contains a version attribute, the persistence provider must - * also perform optimistic version checks when obtaining the - * database lock. If these checks fail, the - * OptimisticLockException will be thrown. - * If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - * - the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback. - * - the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - * If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * Portable applications should not rely on the standard timeout - * hint. Depending on the database in use and the locking - * mechanisms used by the provider, the hint may or may not - * be observed. - * - * @param entity - * @param lockMode - * @param properties standard and vendor-specific properties - * and hints - * - * @throws IllegalArgumentException if the instance is not an - * entity or is a detached entity - * @throws TransactionRequiredException if there is no - * transaction - * @throws EntityNotFoundException if the entity does not exist - * in the database when pessimistic locking is - * performed - * @throws OptimisticLockException if the optimistic version - * check fails - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public void lock(Object entity, LockModeType lockMode, - Map<String, Object> properties); - - /** - * Refresh the state of the instance from the database, - * overwriting changes made to the entity, if any. - * - * @param entity - * - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - * @throws EntityNotFoundException if the entity no longer - * exists in the database - */ - public void refresh(Object entity); - - /** - * Refresh the state of the instance from the database, using - * the specified properties, and overwriting changes made to - * the entity, if any. - * If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * - * @param entity - * @param properties standard and vendor-specific properties - * - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if invoked on a - * container-managed entity manager of type - * PersistenceContextType.TRANSACTION and there is - * no transaction. - * @throws EntityNotFoundException if the entity no longer - * exists in the database - */ - public void refresh(Object entity, - Map<String, Object> properties); - - /** - * Refresh the state of the instance from the database, - * overwriting changes made to the entity, if any, and - * lock it with respect to given lock mode type. - * If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - * - the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback. - * - the LockTimeoutException will be thrown if the - * database locking failure causes only statement-level - * rollback. - * - * @param entity - * @param lockMode - * - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if there is no - * transaction - * @throws EntityNotFoundException if the entity no longer exists - * in the database - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public void refresh(Object entity, LockModeType lockMode); - - /** - * Refresh the state of the instance from the database, - * overwriting changes made to the entity, if any, and - * lock it with respect to given lock mode type and with - * specified properties. - * If the lock mode type is pessimistic and the entity instance - * is found but cannot be locked: - * - the PessimisticLockException will be thrown if the database - * locking failure causes transaction-level rollback. - * - the LockTimeoutException will be thrown if the database - * locking failure causes only statement-level rollback - * If a vendor-specific property or hint is not recognized, - * it is silently ignored. - * Portable applications should not rely on the standard timeout - * hint. Depending on the database in use and the locking - * mechanisms used by the provider, the hint may or may not - * be observed. - * - * @param entity - * @param lockMode - * @param properties standard and vendor-specific properties - * and hints - * - * @throws IllegalArgumentException if the instance is not - * an entity or the entity is not managed - * @throws TransactionRequiredException if there is no - * transaction - * @throws EntityNotFoundException if the entity no longer exists - * in the database - * @throws PessimisticLockException if pessimistic locking fails - * and the transaction is rolled back - * @throws LockTimeoutException if pessimistic locking fails and - * only the statement is rolled back - * @throws PersistenceException if an unsupported lock call - * is made - */ - public void refresh(Object entity, LockModeType lockMode, - Map<String, Object> properties); - - /** - * Clear the persistence context, causing all managed - * entities to become detached. Changes made to entities that - * have not been flushed to the database will not be - * persisted. - */ - public void clear(); - - /** - * Remove the given entity from the persistence context, causing - * a managed entity to become detached. Unflushed changes made - * to the entity if any (including removal of the entity), - * will not be synchronized to the database. Entities which - * previously referenced the detached entity will continue to - * reference it. - * - * @param entity - * - * @throws IllegalArgumentException if the instance is not an - * entity - */ - public void detach(Object entity); - - /** - * Check if the instance is a managed entity instance belonging - * to the current persistence context. - * - * @param entity - * - * @return - * - * @throws IllegalArgumentException if not an entity - */ - public boolean contains(Object entity); - - /** - * Get the current lock mode for the entity instance. - * - * @param entity - * - * @return lock mode - * - * @throws TransactionRequiredException if there is no - * transaction - * @throws IllegalArgumentException if the instance is not a - * managed entity and a transaction is active - */ - public LockModeType getLockMode(Object entity); - - /** - * Set an entity manager property. - * If a vendor-specific property is not recognized, it is - * silently ignored. - * - * @param propertyName - * @param value - * - * @throws IllegalArgumentException if the second argument is not - * valid for the implementation - */ - public void setProperty(String propertyName, Object value); - - /** - * Get the properties and associated values that are in effect - * for the entity manager. Changing the contents of the map does - * not change the configuration in effect. - */ - public Map<String, Object> getProperties(); - - /** - * Get the names of the properties that are supported for use - * with the entity manager. - * These correspond to properties and hints that may be passed - * to the methods of the EntityManager interface that take a - * properties argument or used with the PersistenceContext - * annotation. These properties include all standard entity - * manager hints and properties as well as vendor-specific ones - * supported by the provider. These properties may or may not - * currently be in effect. - * - * @return property names - */ - public Set<String> getSupportedProperties(); - - /** - * Create an instance of Query for executing a - * Java Persistence query language statement. - * - * @param qlString a Java Persistence query string - * - * @return the new query instance - * - * @throws IllegalArgumentException if the query string is found - * to be invalid - */ - public Query createQuery(String qlString); - - /** - * Create an instance of Query for executing a - * criteria query. - * - * @param criteriaQuery a Criteria API query definition object - * - * @return the new query instance - * - * @throws IllegalArgumentException if the query definition is - * found to be invalid - */ - public Query createQuery(CriteriaQuery criteriaQuery); - - /** - * Create an instance of Query for executing a - * named query (in the Java Persistence query language - * or in native SQL). - * - * @param name the name of a query defined in metadata - * - * @return the new query instance - * - * @throws IllegalArgumentException if a query has not been - * defined with the given name or if the query string is - * found to be invalid - */ - public Query createNamedQuery(String name); - - /** - * Create an instance of Query for executing - * a native SQL statement, e.g., for update or delete. - * - * @param sqlString a native SQL query string - * - * @return the new query instance - */ - public Query createNativeQuery(String sqlString); - - /** - * Create an instance of Query for executing - * a native SQL query. - * - * @param sqlString a native SQL query string - * @param resultClass the class of the resulting instance(s) - * - * @return the new query instance - */ - public Query createNativeQuery(String sqlString, - Class resultClass); - - /** - * Create an instance of Query for executing - * a native SQL query. - * - * @param sqlString a native SQL query string - * @param resultSetMapping the name of the result set mapping - * - * @return the new query instance - */ - public Query createNativeQuery(String sqlString, - String resultSetMapping); - - /** - * Indicate to the EntityManager that a JTA transaction is - * active. This method should be called on a JTA application - * managed EntityManager that was created outside the scope - * of the active transaction to associate it with the current - * JTA transaction. - * - * @throws TransactionRequiredException if there is - * no transaction. - */ - public void joinTransaction(); - - /** - * Return an object of the specified type to allow access to the - * provider-specific API. If the provider's EntityManager - * implementation does not support the specified class, the - * PersistenceException is thrown. - * - * @param cls the class of the object to be returned. This is - * normally either the underlying EntityManager implementation - * class or an interface that it implements. - * - * @return an instance of the specified class - * - * @throws PersistenceException if the provider does not - * support the call. - */ - public <T> T unwrap(Class<T> cls); - - /** - * Return the underlying provider object for the EntityManager, - * if available. The result of this method is implementation - * specific. The unwrap method is to be preferred for new - * applications. - * / - * public Object getDelegate(); - * /** - * Close an application-managed EntityManager. - * After the close method has been invoked, all methods - * on the EntityManager instance and any Query objects obtained - * from it will throw the IllegalStateException except - * for getProperties, getSupportedProperties, getTransaction, - * and isOpen (which will return false). - * If this method is called when the EntityManager is - * associated with an active transaction, the persistence - * context remains managed until the transaction completes. - * - * @throws IllegalStateException if the EntityManager - * is container-managed. - */ - public void close(); - - /** - * Determine whether the EntityManager is open. - * - * @return true until the EntityManager has been closed. - */ - public boolean isOpen(); - - /** - * Return the resource-level transaction object. - * The EntityTransaction instance may be used serially to - * begin and commit multiple transactions. - * - * @return EntityTransaction instance - * - * @throws IllegalStateException if invoked on a JTA - * EntityManager. - */ - public EntityTransaction getTransaction(); - - /** - * Return the entity manager factory for the entity manager. - * - * @return EntityManagerFactory instance - * - * @throws IllegalStateException if the entity manager has - * been closed. - */ - public EntityManagerFactory getEntityManagerFactory(); - - /** - * Return an instance of QueryBuilder for the creation of - * Criteria API Query objects. - * - * @return QueryBuilder instance - * - * @throws IllegalStateException if the entity manager has - * been closed. - */ - public QueryBuilder getQueryBuilder(); - - /** - * Return an instance of Metamodel interface for access to the - * metamodel of the persistence unit. - * - * @return Metamodel instance - * - * @throws IllegalStateException if the entity manager has - * been closed. - */ - public Metamodel getMetamodel(); -} Copied: jpa-api/tags/v2_0_Beta2/src/main/java/javax/persistence/EntityManager.java (from rev 16542, jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java) =================================================================== --- jpa-api/tags/v2_0_Beta2/src/main/java/javax/persistence/EntityManager.java (rev 0) +++ jpa-api/tags/v2_0_Beta2/src/main/java/javax/persistence/EntityManager.java 2009-05-12 12:01:51 UTC (rev 16548) @@ -0,0 +1,714 @@ +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +package javax.persistence; + +import java.util.Map; +import java.util.Set; +import javax.persistence.criteria.CriteriaQuery; +import javax.persistence.criteria.QueryBuilder; +import javax.persistence.metamodel.Metamodel; + +/** + * Interface used to interact with the persistence context. + */ +public interface EntityManager { + /** + * Make an instance managed and persistent. + * + * @param entity + * + * @throws EntityExistsException if the entity already exists. + * (If the entity already exists, the EntityExistsException may + * be thrown when the persist operation is invoked, or the + * EntityExistsException or another PersistenceException may be + * thrown at flush or commit time.) + * @throws IllegalArgumentException if the instance is not an + * entity + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * PersistenceContextType.TRANSACTION and there is + * no transaction. + */ + public void persist(Object entity); + + /** + * Merge the state of the given entity into the + * current persistence context. + * + * @param entity + * + * @return the managed instance that the state was merged to + * + * @throws IllegalArgumentException if instance is not an + * entity or is a removed entity + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * PersistenceContextType.TRANSACTION and there is + * no transaction. + */ + public <T> T merge(T entity); + + /** + * Remove the entity instance. + * + * @param entity + * + * @throws IllegalArgumentException if the instance is not an + * entity or is a detached entity + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * PersistenceContextType.TRANSACTION and there is + * no transaction. + */ + public void remove(Object entity); + + /** + * Find by primary key. + * Search for an entity of the specified class and primary key. + * If the entity instance is contained in the persistence context + * it is returned from there. + * + * @param entityClass + * @param primaryKey + * + * @return the found entity instance or null + * if the entity does not exist + * + * @throws IllegalArgumentException if the first argument does + * not denote an entity type or the second argument is + * is not a valid type for that entity�s primary key or + * is null + */ + public <T> T find(Class<T> entityClass, Object primaryKey); + + /** + * Find by primary key, using the specified properties. + * Search for an entity of the specified class and primary key. + * If the entity instance is contained in the persistence context + * it is returned from there. + * If a vendor-specific property or hint is not recognized, + * it is silently ignored. + * + * @param entityClass + * @param primaryKey + * @param properties standard and vendor-specific properties + * + * @return the found entity instance or null + * if the entity does not exist + * + * @throws IllegalArgumentException if the first argument does + * not denote an entity type or the second argument is + * is not a valid type for that entity�s primary key or + * is null + */ + public <T> T find(Class<T> entityClass, Object primaryKey, + Map<String, Object> properties); + + /** + * Find by primary key and lock. + * Search for an entity of the specified class and primary key + * and lock it with respect to the specified lock type. + * If the entity instance is contained in the persistence context + * it is returned from there, and the effect of this method is + * the same as if the lock method had been called on the entity. + * If the entity is found within the persistence context and the + * lock mode type is pessimistic and the entity has a version + * attribute, the persistence provider must perform optimistic + * version checks when obtaining the database lock. If these + * checks fail, the OptimisticLockException will be thrown. + * If the lock mode type is pessimistic and the entity instance + * is found but cannot be locked: + * - the PessimisticLockException will be thrown if the database + * locking failure causes transaction-level rollback. + * - the LockTimeoutException will be thrown if the database + * locking failure causes only statement-level rollback + * + * @param entityClass + * @param primaryKey + * @param lockMode + * + * @return the found entity instance or null if the entity does + * not exist + * + * @throws IllegalArgumentException if the first argument does + * not denote an entity type or the second argument is + * not a valid type for that entity's primary key or + * is null + * @throws TransactionRequiredException if there is no + * transaction and a lock mode other than NONE is set + * @throws OptimisticLockException if the optimistic version + * check fails + * @throws PessimisticLockException if pessimistic locking + * fails and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + */ + public <T> T find(Class<T> entityClass, Object primaryKey, + LockModeType lockMode); + + /** + * Find by primary key and lock, using the specified properties. + * Search for an entity of the specified class and primary key + * and lock it with respect to the specified lock type. + * If the entity instance is contained in the persistence context + * it is returned from there. If the entity is found + * within the persistence context and the lock mode type + * is pessimistic and the entity has a version attribute, the + * persistence provider must perform optimistic version checks + * when obtaining the database lock. If these checks fail, + * the OptimisticLockException will be thrown. + * If the lock mode type is pessimistic and the entity instance + * is found but cannot be locked: + * - the PessimisticLockException will be thrown if the database + * locking failure causes transaction-level rollback. + * - the LockTimeoutException will be thrown if the database + * locking failure causes only statement-level rollback + * If a vendor-specific property or hint is not recognized, + * it is silently ignored. + * Portable applications should not rely on the standard timeout + * hint. Depending on the database in use and the locking + * mechanisms used by the provider, the hint may or may not + * be observed. + * + * @param entityClass + * @param primaryKey + * @param lockMode + * @param properties standard and vendor-specific properties + * and hints + * + * @return the found entity instance or null if the entity does + * not exist + * + * @throws IllegalArgumentException if the first argument does + * not denote an entity type or the second argument is + * not a valid type for that entity's primary key or + * is null + * @throws TransactionRequiredException if there is no + * transaction and a lock mode other than NONE is set + * @throws OptimisticLockException if the optimistic version + * check fails + * @throws PessimisticLockException if pessimistic locking + * fails and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + */ + public <T> T find(Class<T> entityClass, Object primaryKey, + LockModeType lockMode, + Map<String, Object> properties); + + /** + * Get an instance, whose state may be lazily fetched. + * If the requested instance does not exist in the database, + * the EntityNotFoundException is thrown when the instance + * state is first accessed. (The persistence provider runtime is + * permitted to throw the EntityNotFoundException when + * getReference is called.) + * The application should not expect that the instance state will + * be available upon detachment, unless it was accessed by the + * application while the entity manager was open. + * + * @param entityClass + * @param primaryKey + * + * @return the found entity instance + * + * @throws IllegalArgumentException if the first argument does + * not denote an entity type or the second argument is + * not a valid type for that entity�s primary key or + * is null + * @throws EntityNotFoundException if the entity state + * cannot be accessed + */ + public <T> T getReference(Class<T> entityClass, + Object primaryKey); + + /** + * Synchronize the persistence context to the + * underlying database. + * + * @throws TransactionRequiredException if there is + * no transaction + * @throws PersistenceException if the flush fails + */ + public void flush(); + + /** + * Set the flush mode that applies to all objects contained + * in the persistence context. + * + * @param flushMode + */ + public void setFlushMode(FlushModeType flushMode); + + /** + * Get the flush mode that applies to all objects contained + * in the persistence context. + * + * @return flushMode + */ + public FlushModeType getFlushMode(); + + /** + * Lock an entity instance that is contained in the persistence + * context with the specified lock mode type. + * If a pessimistic lock mode type is specified and the entity + * contains a version attribute, the persistence provider must + * also perform optimistic version checks when obtaining the + * database lock. If these checks fail, the + * OptimisticLockException will be thrown. + * If the lock mode type is pessimistic and the entity instance + * is found but cannot be locked: + * - the PessimisticLockException will be thrown if the database + * locking failure causes transaction-level rollback. + * - the LockTimeoutException will be thrown if the database + * locking failure causes only statement-level rollback + * + * @param entity + * @param lockMode + * + * @throws IllegalArgumentException if the instance is not an + * entity or is a detached entity + * @throws TransactionRequiredException if there is no + * transaction + * @throws EntityNotFoundException if the entity does not exist + * in the database when pessimistic locking is + * performed + * @throws OptimisticLockException if the optimistic version + * check fails + * @throws PessimisticLockException if pessimistic locking fails + * and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + */ + public void lock(Object entity, LockModeType lockMode); + + /** + * Lock an entity instance that is contained in the persistence + * context with the specified lock mode type and with specified + * properties. + * If a pessimistic lock mode type is specified and the entity + * contains a version attribute, the persistence provider must + * also perform optimistic version checks when obtaining the + * database lock. If these checks fail, the + * OptimisticLockException will be thrown. + * If the lock mode type is pessimistic and the entity instance + * is found but cannot be locked: + * - the PessimisticLockException will be thrown if the database + * locking failure causes transaction-level rollback. + * - the LockTimeoutException will be thrown if the database + * locking failure causes only statement-level rollback + * If a vendor-specific property or hint is not recognized, + * it is silently ignored. + * Portable applications should not rely on the standard timeout + * hint. Depending on the database in use and the locking + * mechanisms used by the provider, the hint may or may not + * be observed. + * + * @param entity + * @param lockMode + * @param properties standard and vendor-specific properties + * and hints + * + * @throws IllegalArgumentException if the instance is not an + * entity or is a detached entity + * @throws TransactionRequiredException if there is no + * transaction + * @throws EntityNotFoundException if the entity does not exist + * in the database when pessimistic locking is + * performed + * @throws OptimisticLockException if the optimistic version + * check fails + * @throws PessimisticLockException if pessimistic locking fails + * and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + */ + public void lock(Object entity, LockModeType lockMode, + Map<String, Object> properties); + + /** + * Refresh the state of the instance from the database, + * overwriting changes made to the entity, if any. + * + * @param entity + * + * @throws IllegalArgumentException if the instance is not + * an entity or the entity is not managed + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * PersistenceContextType.TRANSACTION and there is + * no transaction. + * @throws EntityNotFoundException if the entity no longer + * exists in the database + */ + public void refresh(Object entity); + + /** + * Refresh the state of the instance from the database, using + * the specified properties, and overwriting changes made to + * the entity, if any. + * If a vendor-specific property or hint is not recognized, + * it is silently ignored. + * + * @param entity + * @param properties standard and vendor-specific properties + * + * @throws IllegalArgumentException if the instance is not + * an entity or the entity is not managed + * @throws TransactionRequiredException if invoked on a + * container-managed entity manager of type + * PersistenceContextType.TRANSACTION and there is + * no transaction. + * @throws EntityNotFoundException if the entity no longer + * exists in the database + */ + public void refresh(Object entity, + Map<String, Object> properties); + + /** + * Refresh the state of the instance from the database, + * overwriting changes made to the entity, if any, and + * lock it with respect to given lock mode type. + * If the lock mode type is pessimistic and the entity instance + * is found but cannot be locked: + * - the PessimisticLockException will be thrown if the database + * locking failure causes transaction-level rollback. + * - the LockTimeoutException will be thrown if the + * database locking failure causes only statement-level + * rollback. + * + * @param entity + * @param lockMode + * + * @throws IllegalArgumentException if the instance is not + * an entity or the entity is not managed + * @throws TransactionRequiredException if there is no + * transaction + * @throws EntityNotFoundException if the entity no longer exists + * in the database + * @throws PessimisticLockException if pessimistic locking fails + * and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + */ + public void refresh(Object entity, LockModeType lockMode); + + /** + * Refresh the state of the instance from the database, + * overwriting changes made to the entity, if any, and + * lock it with respect to given lock mode type and with + * specified properties. + * If the lock mode type is pessimistic and the entity instance + * is found but cannot be locked: + * - the PessimisticLockException will be thrown if the database + * locking failure causes transaction-level rollback. + * - the LockTimeoutException will be thrown if the database + * locking failure causes only statement-level rollback + * If a vendor-specific property or hint is not recognized, + * it is silently ignored. + * Portable applications should not rely on the standard timeout + * hint. Depending on the database in use and the locking + * mechanisms used by the provider, the hint may or may not + * be observed. + * + * @param entity + * @param lockMode + * @param properties standard and vendor-specific properties + * and hints + * + * @throws IllegalArgumentException if the instance is not + * an entity or the entity is not managed + * @throws TransactionRequiredException if there is no + * transaction + * @throws EntityNotFoundException if the entity no longer exists + * in the database + * @throws PessimisticLockException if pessimistic locking fails + * and the transaction is rolled back + * @throws LockTimeoutException if pessimistic locking fails and + * only the statement is rolled back + * @throws PersistenceException if an unsupported lock call + * is made + */ + public void refresh(Object entity, LockModeType lockMode, + Map<String, Object> properties); + + /** + * Clear the persistence context, causing all managed + * entities to become detached. Changes made to entities that + * have not been flushed to the database will not be + * persisted. + */ + public void clear(); + + /** + * Remove the given entity from the persistence context, causing + * a managed entity to become detached. Unflushed changes made + * to the entity if any (including removal of the entity), + * will not be synchronized to the database. Entities which + * previously referenced the detached entity will continue to + * reference it. + * + * @param entity + * + * @throws IllegalArgumentException if the instance is not an + * entity + */ + public void detach(Object entity); + + /** + * Check if the instance is a managed entity instance belonging + * to the current persistence context. + * + * @param entity + * + * @return + * + * @throws IllegalArgumentException if not an entity + */ + public boolean contains(Object entity); + + /** + * Get the current lock mode for the entity instance. + * + * @param entity + * + * @return lock mode + * + * @throws TransactionRequiredException if there is no + * transaction + * @throws IllegalArgumentException if the instance is not a + * managed entity and a transaction is active + */ + public LockModeType getLockMode(Object entity); + + /** + * Set an entity manager property. + * If a vendor-specific property is not recognized, it is + * silently ignored. + * + * @param propertyName + * @param value + * + * @throws IllegalArgumentException if the second argument is not + * valid for the implementation + */ + public void setProperty(String propertyName, Object value); + + /** + * Get the properties and associated values that are in effect + * for the entity manager. Changing the contents of the map does + * not change the configuration in effect. + */ + public Map<String, Object> getProperties(); + + /** + * Get the names of the properties that are supported for use + * with the entity manager. + * These correspond to properties and hints that may be passed + * to the methods of the EntityManager interface that take a + * properties argument or used with the PersistenceContext + * annotation. These properties include all standard entity + * manager hints and properties as well as vendor-specific ones + * supported by the provider. These properties may or may not + * currently be in effect. + * + * @return property names + */ + public Set<String> getSupportedProperties(); + + /** + * Create an instance of Query for executing a + * Java Persistence query language statement. + * + * @param qlString a Java Persistence query string + * + * @return the new query instance + * + * @throws IllegalArgumentException if the query string is found + * to be invalid + */ + public Query createQuery(String qlString); + + /** + * Create an instance of Query for executing a + * criteria query. + * + * @param criteriaQuery a Criteria API query definition object + * + * @return the new query instance + * + * @throws IllegalArgumentException if the query definition is + * found to be invalid + */ + public Query createQuery(CriteriaQuery criteriaQuery); + + /** + * Create an instance of Query for executing a + * named query (in the Java Persistence query language + * or in native SQL). + * + * @param name the name of a query defined in metadata + * + * @return the new query instance + * + * @throws IllegalArgumentException if a query has not been + * defined with the given name or if the query string is + * found to be invalid + */ + public Query createNamedQuery(String name); + + /** + * Create an instance of Query for executing + * a native SQL statement, e.g., for update or delete. + * + * @param sqlString a native SQL query string + * + * @return the new query instance + */ + public Query createNativeQuery(String sqlString); + + /** + * Create an instance of Query for executing + * a native SQL query. + * + * @param sqlString a native SQL query string + * @param resultClass the class of the resulting instance(s) + * + * @return the new query instance + */ + public Query createNativeQuery(String sqlString, + Class resultClass); + + /** + * Create an instance of Query for executing + * a native SQL query. + * + * @param sqlString a native SQL query string + * @param resultSetMapping the name of the result set mapping + * + * @return the new query instance + */ + public Query createNativeQuery(String sqlString, + String resultSetMapping); + + /** + * Indicate to the EntityManager that a JTA transaction is + * active. This method should be called on a JTA application + * managed EntityManager that was created outside the scope + * of the active transaction to associate it with the current + * JTA transaction. + * + * @throws TransactionRequiredException if there is + * no transaction. + */ + public void joinTransaction(); + + /** + * Return an object of the specified type to allow access to the + * provider-specific API. If the provider's EntityManager + * implementation does not support the specified class, the + * PersistenceException is thrown. + * + * @param cls the class of the object to be returned. This is + * normally either the underlying EntityManager implementation + * class or an interface that it implements. + * + * @return an instance of the specified class + * + * @throws PersistenceException if the provider does not + * support the call. + */ + public <T> T unwrap(Class<T> cls); + + /** + * Return the underlying provider object for the EntityManager, + * if available. The result of this method is implementation + * specific. The unwrap method is to be preferred for new + * applications. + */ + public Object getDelegate(); + + /** + * Return the underlying provider object for the EntityManager, + * if available. The result of this method is implementation + * specific. The unwrap method is to be preferred for new + * applications. + * / + * public Object getDelegate(); + * /** + * Close an application-managed EntityManager. + * After the close method has been invoked, all methods + * on the EntityManager instance and any Query objects obtained + * from it will throw the IllegalStateException except + * for getProperties, getSupportedProperties, getTransaction, + * and isOpen (which will return false). + * If this method is called when the EntityManager is + * associated with an active transaction, the persistence + * context remains managed until the transaction completes. + * + * @throws IllegalStateException if the EntityManager + * is container-managed. + */ + public void close(); + + /** + * Determine whether the EntityManager is open. + * + * @return true until the EntityManager has been closed. + */ + public boolean isOpen(); + + /** + * Return the resource-level transaction object. + * The EntityTransaction instance may be used serially to + * begin and commit multiple transactions. + * + * @return EntityTransaction instance + * + * @throws IllegalStateException if invoked on a JTA + * EntityManager. + */ + public EntityTransaction getTransaction(); + + /** + * Return the entity manager factory for the entity manager. + * + * @return EntityManagerFactory instance + * + * @throws IllegalStateException if the entity manager has + * been closed. + */ + public EntityManagerFactory getEntityManagerFactory(); + + /** + * Return an instance of QueryBuilder for the creation of + * Criteria API Query objects. + * + * @return QueryBuilder instance + * + * @throws IllegalStateException if the entity manager has + * been closed. + */ + public QueryBuilder getQueryBuilder(); + + /** + * Return an instance of Metamodel interface for access to the + * metamodel of the persistence unit. + * + * @return Metamodel instance + * + * @throws IllegalStateException if the entity manager has + * been closed. + */ + public Metamodel getMetamodel(); +}