Author: epbernard Date: 2009-08-14 14:29:45 -0400 (Fri, 14 Aug 2009) New Revision: 17305 Added: core/trunk/entitymanager/src/main/java/org/hibernate/ejb/util/PersistenceUtilHelper.java jpa-api/trunk/src/main/java/javax/persistence/CacheRetrieveMode.java jpa-api/trunk/src/main/java/javax/persistence/CacheStoreMode.java jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnitUtil.java jpa-api/trunk/src/main/java/javax/persistence/PessimisticLockScope.java jpa-api/trunk/src/main/java/javax/persistence/TypedQuery.java Modified: core/trunk/entitymanager/src/main/java/org/hibernate/ejb/AbstractEntityManagerImpl.java core/trunk/entitymanager/src/main/java/org/hibernate/ejb/CurrentEntityManagerImpl.java core/trunk/entitymanager/src/main/java/org/hibernate/ejb/EntityManagerFactoryImpl.java core/trunk/entitymanager/src/main/java/org/hibernate/ejb/HibernatePersistence.java core/trunk/entitymanager/src/main/java/org/hibernate/ejb/QueryImpl.java jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java jpa-api/trunk/src/main/java/javax/persistence/EntityManagerFactory.java jpa-api/trunk/src/main/java/javax/persistence/Parameter.java jpa-api/trunk/src/main/java/javax/persistence/Query.java Log: Add support for the new JPA 2 API from July 23 2009 (only the top level package. Subpackages have not been updated. Also partially implement PersistenceUnitUtil Modified: core/trunk/entitymanager/src/main/java/org/hibernate/ejb/AbstractEntityManagerImpl.java =================================================================== --- core/trunk/entitymanager/src/main/java/org/hibernate/ejb/AbstractEntityManagerImpl.java 2009-08-14 17:26:52 UTC (rev 17304) +++ core/trunk/entitymanager/src/main/java/org/hibernate/ejb/AbstractEntityManagerImpl.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -38,6 +38,7 @@ import javax.persistence.PersistenceException; import javax.persistence.Query; import javax.persistence.TransactionRequiredException; +import javax.persistence.TypedQuery; import javax.persistence.criteria.CriteriaQuery; import javax.persistence.criteria.QueryBuilder; import javax.persistence.metamodel.Metamodel; @@ -125,7 +126,11 @@ } } - public Query createQuery(CriteriaQuery criteriaQuery) { + public <T> TypedQuery<T> createQuery(String qlString, Class<T> resultClass) { + throw new UnsupportedOperationException( "Not yet implemented" ); + } + + public <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery) { // TODO-STEVE : here is the interpretation/compilation portion. // One option is to build on top of the existing // org.hibernate.loader.custom.CustomQuery infastructure @@ -142,6 +147,23 @@ throw new UnsupportedOperationException( "Not yet implemented!" ); } + public <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery, Class<T> resultClass) { + // TODO-STEVE : here is the interpretation/compilation portion. + // One option is to build on top of the existing + // org.hibernate.loader.custom.CustomQuery infastructure + // (which is how native sql queries are implemented e.g.). + // If so, then here we could interpret the criteria into + // a CustomQuery instance which is passed into the + // Query instance returned here. We would then call into + // the various SessionImplementor methods for execution + // such as #listCustomQuery and #scrollCustomQuery. + // + // The drawback to this (^^) approach is that CustomQuery + + // SessionImplementor combo does not support #executeUpdate + // processing... + throw new UnsupportedOperationException( "Not yet implemented!" ); + } + public Query createNamedQuery(String name) { //adjustFlushMode(); org.hibernate.Query namedQuery; @@ -160,6 +182,11 @@ } } + public <T> TypedQuery<T> createNamedQuery(String name, Class<T> resultClass) { + throw new UnsupportedOperationException( "Not yet implemented" ); + } + + public Query createNativeQuery(String sqlString) { //adjustFlushMode(); try { Modified: core/trunk/entitymanager/src/main/java/org/hibernate/ejb/CurrentEntityManagerImpl.java =================================================================== --- core/trunk/entitymanager/src/main/java/org/hibernate/ejb/CurrentEntityManagerImpl.java 2009-08-14 17:26:52 UTC (rev 17304) +++ core/trunk/entitymanager/src/main/java/org/hibernate/ejb/CurrentEntityManagerImpl.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -23,6 +23,7 @@ import java.util.Map; import javax.persistence.PersistenceContextType; +import javax.persistence.TypedQuery; import javax.persistence.spi.PersistenceUnitTransactionType; import org.hibernate.Session; Modified: core/trunk/entitymanager/src/main/java/org/hibernate/ejb/EntityManagerFactoryImpl.java =================================================================== --- core/trunk/entitymanager/src/main/java/org/hibernate/ejb/EntityManagerFactoryImpl.java 2009-08-14 17:26:52 UTC (rev 17304) +++ core/trunk/entitymanager/src/main/java/org/hibernate/ejb/EntityManagerFactoryImpl.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -28,15 +28,19 @@ import javax.persistence.EntityManager; import javax.persistence.PersistenceContextType; import javax.persistence.Cache; +import javax.persistence.PersistenceUnitUtil; import javax.persistence.metamodel.Metamodel; import javax.persistence.criteria.QueryBuilder; import javax.persistence.spi.PersistenceUnitTransactionType; +import javax.persistence.spi.LoadState; import org.hibernate.SessionFactory; +import org.hibernate.Hibernate; import org.hibernate.mapping.PersistentClass; import org.hibernate.cfg.Configuration; import org.hibernate.ejb.criteria.QueryBuilderImpl; import org.hibernate.ejb.metamodel.MetamodelImpl; +import org.hibernate.ejb.util.PersistenceUtilHelper; /** * Actual Hiberate implementation of {@link javax.persistence.EntityManagerFactory}. @@ -52,6 +56,7 @@ private final Class sessionInterceptorClass; private final QueryBuilderImpl criteriaQueryBuilder; private final Metamodel metamodel; + private final HibernatePersistenceUnitUtil util; public EntityManagerFactoryImpl( SessionFactory sessionFactory, @@ -73,6 +78,7 @@ this.metamodel = null; } this.criteriaQueryBuilder = new QueryBuilderImpl( this ); + this.util = new HibernatePersistenceUnitUtil( this ); } public EntityManager createEntityManager() { @@ -114,6 +120,10 @@ return new JPACache( sessionFactory ); } + public PersistenceUnitUtil getPersistenceUnitUtil() { + return null; //To change body of implemented methods use File | Settings | File Templates. + } + public boolean isOpen() { return ! sessionFactory.isClosed(); } @@ -148,4 +158,35 @@ // sessionFactory.getCache().evictQueryRegions(); } } + + private static class HibernatePersistenceUnitUtil implements PersistenceUnitUtil, Serializable { + private final EntityManagerFactoryImpl emf; + + private HibernatePersistenceUnitUtil(EntityManagerFactoryImpl emf) { + this.emf = emf; + } + + public boolean isLoaded(Object entity, String attributeName) { + LoadState state = PersistenceUtilHelper.isLoadedWithoutReference( entity, attributeName ); + if (state == LoadState.LOADED) { + return true; + } + else if (state == LoadState.NOT_LOADED ) { + return false; + } + else { + return PersistenceUtilHelper.isLoadedWithReference( entity, attributeName ) != LoadState.NOT_LOADED; + } + + + } + + public boolean isLoaded(Object entity) { + return PersistenceUtilHelper.isLoaded( entity ) != LoadState.NOT_LOADED; + } + + public Object getIdentifier(Object entity) { + throw new UnsupportedOperationException( "Not yet implemented" ); + } + } } Modified: core/trunk/entitymanager/src/main/java/org/hibernate/ejb/HibernatePersistence.java =================================================================== --- core/trunk/entitymanager/src/main/java/org/hibernate/ejb/HibernatePersistence.java 2009-08-14 17:26:52 UTC (rev 17304) +++ core/trunk/entitymanager/src/main/java/org/hibernate/ejb/HibernatePersistence.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -36,6 +36,7 @@ import javax.persistence.spi.LoadState; import org.hibernate.Hibernate; +import org.hibernate.ejb.util.PersistenceUtilHelper; import org.hibernate.intercept.FieldInterceptionHelper; import org.hibernate.intercept.FieldInterceptor; import org.hibernate.collection.PersistentCollection; @@ -170,140 +171,15 @@ } public LoadState isLoadedWithoutReference(Object proxy, String property) { - Object entity; - boolean sureFromUs = false; - if ( proxy instanceof HibernateProxy ) { - LazyInitializer li = ( ( HibernateProxy ) proxy ).getHibernateLazyInitializer(); - if ( li.isUninitialized() ) { - return LoadState.NOT_LOADED; - } - else { - entity = li.getImplementation(); - } - sureFromUs = true; - } - else { - entity = proxy; - } - - //we are instrumenting but we can't assume we are the only ones - if ( FieldInterceptionHelper.isInstrumented( entity ) ) { - FieldInterceptor interceptor = FieldInterceptionHelper.extractFieldInterceptor( entity ); - final boolean isInitialized = interceptor == null || interceptor.isInitialized( property ); - LoadState state; - if (isInitialized && interceptor != null) { - //property is loaded according to bytecode enhancement, but is it loaded as far as association? - //it's ours, we can read - state = isLoaded( get( entity, property ) ); - //it's ours so we know it's loaded - if (state == LoadState.UNKNOWN) state = LoadState.LOADED; - } - else if ( interceptor != null && (! isInitialized)) { - state = LoadState.NOT_LOADED; - } - else if ( sureFromUs ) { //interceptor == null - //property is loaded according to bytecode enhancement, but is it loaded as far as association? - //it's ours, we can read - state = isLoaded( get( entity, property ) ); - //it's ours so we know it's loaded - if (state == LoadState.UNKNOWN) state = LoadState.LOADED; - } - else { - state = LoadState.UNKNOWN; - } - - return state; - } - else { - //can't do sureFromUs ? LoadState.LOADED : LoadState.UNKNOWN; - //is that an association? - return LoadState.UNKNOWN; - } + return PersistenceUtilHelper.isLoadedWithoutReference( proxy, property ); } public LoadState isLoadedWithReference(Object proxy, String property) { - //for sure we don't instrument and for sure it's not a lazy proxy - Object object = get(proxy, property); - return isLoaded( object ); + return PersistenceUtilHelper.isLoadedWithReference( proxy, property ); } - private Object get(Object proxy, String property) { - final Class<?> clazz = proxy.getClass(); - try { - try { - final Field field = clazz.getField( property ); - setAccessibility( field ); - return field.get( proxy ); - } - catch ( NoSuchFieldException e ) { - final Method method = getMethod( clazz, property ); - if (method != null) { - setAccessibility( method ); - return method.invoke( proxy ); - } - else { - throw new PersistenceException( "Unable to find field or method: " - + clazz + "#" - + property); - } - } - } - catch ( IllegalAccessException e ) { - throw new PersistenceException( "Unable to access field or method: " - + clazz + "#" - + property, e); - } - catch ( InvocationTargetException e ) { - throw new PersistenceException( "Unable to access field or method: " - + clazz + "#" - + property, e); - } - } - - /** - * Returns the method with the specified name or <code>null</code> if it does not exist. - * - * @param clazz The class to check. - * @param methodName The method name. - * - * @return Returns the method with the specified name or <code>null</code> if it does not exist. - */ - public static Method getMethod(Class<?> clazz, String methodName) { - try { - char string[] = methodName.toCharArray(); - string[0] = Character.toUpperCase( string[0] ); - methodName = new String( string ); - try { - return clazz.getMethod( "get" + methodName ); - } - catch ( NoSuchMethodException e ) { - return clazz.getMethod( "is" + methodName ); - } - } - catch ( NoSuchMethodException e ) { - return null; - } - } - - public static void setAccessibility(Member member) { - if ( !Modifier.isPublic( member.getModifiers() ) ) { - //Sun's ease of use, sigh... - ( ( AccessibleObject ) member ).setAccessible( true ); - } - } - public LoadState isLoaded(Object o) { - if ( o instanceof HibernateProxy ) { - final boolean isInitialized = !( ( HibernateProxy ) o ).getHibernateLazyInitializer().isUninitialized(); - return isInitialized ? LoadState.LOADED : LoadState.NOT_LOADED; - } - else if ( o instanceof PersistentCollection ) { - final boolean isInitialized = ( ( PersistentCollection ) o ).wasInitialized(); - return isInitialized ? LoadState.LOADED : LoadState.NOT_LOADED; - } - else { - return LoadState.UNKNOWN; - } + return PersistenceUtilHelper.isLoaded(o); } /** Modified: core/trunk/entitymanager/src/main/java/org/hibernate/ejb/QueryImpl.java =================================================================== --- core/trunk/entitymanager/src/main/java/org/hibernate/ejb/QueryImpl.java 2009-08-14 17:26:52 UTC (rev 17304) +++ core/trunk/entitymanager/src/main/java/org/hibernate/ejb/QueryImpl.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -38,6 +38,7 @@ import static javax.persistence.TemporalType.*; import javax.persistence.TransactionRequiredException; import javax.persistence.LockModeType; +import javax.persistence.Parameter; import org.hibernate.FlushMode; import org.hibernate.HibernateException; @@ -395,16 +396,51 @@ } } - public Map<String, Object> getNamedParameters() { - //FIXME + //FIXME + public Set<Parameter<?>> getParameters() { return null; //To change body of implemented methods use File | Settings | File Templates. } - public List getPositionalParameters() { - //FIXME + //FIXME + public Parameter<?> getParameter(String name) { return null; //To change body of implemented methods use File | Settings | File Templates. } + //FIXME + public Parameter<?> getParameter(int position) { + return null; //To change body of implemented methods use File | Settings | File Templates. + } + + //FIXME + public <T> Parameter<T> getParameter(String name, Class<T> type) { + return null; //To change body of implemented methods use File | Settings | File Templates. + } + + //FIXME + public <T> Parameter<T> getParameter(int position, Class<T> type) { + return null; //To change body of implemented methods use File | Settings | File Templates. + } + + //FIXME + public boolean isBound(Parameter<?> param) { + return false; //To change body of implemented methods use File | Settings | File Templates. + } + + //FIXME + public <T> T getParameterValue(Parameter<T> param) { + return null; //To change body of implemented methods use File | Settings | File Templates. + } + + //FIXME + public Object getParameterValue(String name) { + return null; //To change body of implemented methods use File | Settings | File Templates. + } + + //FIXME + public Object getParameterValue(int position) { + return null; //To change body of implemented methods use File | Settings | File Templates. + } + public Query setFlushMode(FlushModeType flushMode) { if ( flushMode == FlushModeType.AUTO ) { query.setFlushMode( FlushMode.AUTO ); Added: core/trunk/entitymanager/src/main/java/org/hibernate/ejb/util/PersistenceUtilHelper.java =================================================================== --- core/trunk/entitymanager/src/main/java/org/hibernate/ejb/util/PersistenceUtilHelper.java (rev 0) +++ core/trunk/entitymanager/src/main/java/org/hibernate/ejb/util/PersistenceUtilHelper.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -0,0 +1,159 @@ +package org.hibernate.ejb.util; + +import java.lang.reflect.Field; +import java.lang.reflect.Method; +import java.lang.reflect.InvocationTargetException; +import java.lang.reflect.Member; +import java.lang.reflect.Modifier; +import java.lang.reflect.AccessibleObject; +import javax.persistence.spi.LoadState; +import javax.persistence.PersistenceException; + +import org.hibernate.proxy.HibernateProxy; +import org.hibernate.proxy.LazyInitializer; +import org.hibernate.intercept.FieldInterceptionHelper; +import org.hibernate.intercept.FieldInterceptor; +import org.hibernate.collection.PersistentCollection; + +/** + * @author Emmanuel Bernard + */ +public class PersistenceUtilHelper { + public static LoadState isLoadedWithoutReference(Object proxy, String property) { + Object entity; + boolean sureFromUs = false; + if ( proxy instanceof HibernateProxy ) { + LazyInitializer li = ( ( HibernateProxy ) proxy ).getHibernateLazyInitializer(); + if ( li.isUninitialized() ) { + return LoadState.NOT_LOADED; + } + else { + entity = li.getImplementation(); + } + sureFromUs = true; + } + else { + entity = proxy; + } + + //we are instrumenting but we can't assume we are the only ones + if ( FieldInterceptionHelper.isInstrumented( entity ) ) { + FieldInterceptor interceptor = FieldInterceptionHelper.extractFieldInterceptor( entity ); + final boolean isInitialized = interceptor == null || interceptor.isInitialized( property ); + LoadState state; + if (isInitialized && interceptor != null) { + //property is loaded according to bytecode enhancement, but is it loaded as far as association? + //it's ours, we can read + state = isLoaded( get( entity, property ) ); + //it's ours so we know it's loaded + if (state == LoadState.UNKNOWN) state = LoadState.LOADED; + } + else if ( interceptor != null && (! isInitialized)) { + state = LoadState.NOT_LOADED; + } + else if ( sureFromUs ) { //interceptor == null + //property is loaded according to bytecode enhancement, but is it loaded as far as association? + //it's ours, we can read + state = isLoaded( get( entity, property ) ); + //it's ours so we know it's loaded + if (state == LoadState.UNKNOWN) state = LoadState.LOADED; + } + else { + state = LoadState.UNKNOWN; + } + + return state; + } + else { + //can't do sureFromUs ? LoadState.LOADED : LoadState.UNKNOWN; + //is that an association? + return LoadState.UNKNOWN; + } + } + + public static LoadState isLoadedWithReference(Object proxy, String property) { + //for sure we don't instrument and for sure it's not a lazy proxy + Object object = get(proxy, property); + return isLoaded( object ); + } + + private static Object get(Object proxy, String property) { + final Class<?> clazz = proxy.getClass(); + try { + try { + final Field field = clazz.getField( property ); + setAccessibility( field ); + return field.get( proxy ); + } + catch ( NoSuchFieldException e ) { + final Method method = getMethod( clazz, property ); + if (method != null) { + setAccessibility( method ); + return method.invoke( proxy ); + } + else { + throw new PersistenceException( "Unable to find field or method: " + + clazz + "#" + + property); + } + } + } + catch ( IllegalAccessException e ) { + throw new PersistenceException( "Unable to access field or method: " + + clazz + "#" + + property, e); + } + catch ( InvocationTargetException e ) { + throw new PersistenceException( "Unable to access field or method: " + + clazz + "#" + + property, e); + } + } + + /** + * Returns the method with the specified name or <code>null</code> if it does not exist. + * + * @param clazz The class to check. + * @param methodName The method name. + * + * @return Returns the method with the specified name or <code>null</code> if it does not exist. + */ + private static Method getMethod(Class<?> clazz, String methodName) { + try { + char string[] = methodName.toCharArray(); + string[0] = Character.toUpperCase( string[0] ); + methodName = new String( string ); + try { + return clazz.getMethod( "get" + methodName ); + } + catch ( NoSuchMethodException e ) { + return clazz.getMethod( "is" + methodName ); + } + } + catch ( NoSuchMethodException e ) { + return null; + } + } + + private static void setAccessibility(Member member) { + if ( !Modifier.isPublic( member.getModifiers() ) ) { + //Sun's ease of use, sigh... + ( ( AccessibleObject ) member ).setAccessible( true ); + } + } + + public static LoadState isLoaded(Object o) { + if ( o instanceof HibernateProxy ) { + final boolean isInitialized = !( ( HibernateProxy ) o ).getHibernateLazyInitializer().isUninitialized(); + return isInitialized ? LoadState.LOADED : LoadState.NOT_LOADED; + } + else if ( o instanceof PersistentCollection ) { + final boolean isInitialized = ( ( PersistentCollection ) o ).wasInitialized(); + return isInitialized ? LoadState.LOADED : LoadState.NOT_LOADED; + } + else { + return LoadState.UNKNOWN; + } + } + +} Added: jpa-api/trunk/src/main/java/javax/persistence/CacheRetrieveMode.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/CacheRetrieveMode.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/CacheRetrieveMode.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -0,0 +1,18 @@ +// $Id: Cache.java 16130 2009-03-10 14:28:07Z hardy.ferentschik $ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +package javax.persistence; + +public enum CacheRetrieveMode { + + /** + * Read entity data from the cache: this is + * the default behavior. + */ + USE, + + /** + * Bypass the cache: get data directly from + * the database. + */ + BYPASS +} Added: jpa-api/trunk/src/main/java/javax/persistence/CacheStoreMode.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/CacheStoreMode.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/CacheStoreMode.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -0,0 +1,26 @@ +// $Id: Cache.java 16130 2009-03-10 14:28:07Z hardy.ferentschik $ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +package javax.persistence; + +public enum CacheStoreMode { + + /** + * Insert/update entity data into cache when read + * from database and when committed into database: + * this is the default behavior. Does not force refresh + * of already cached items when reading from database. + */ + USE, + + /** + * Don't insert into cache. + */ + BYPASS, + + /** + * Insert/update entity data into cache when read + * from database and when committed into database. + * Forces refresh of cache for items read from database. + */ + REFRESH +} Modified: jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java 2009-08-14 17:26:52 UTC (rev 17304) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityManager.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -540,19 +540,31 @@ public Query createQuery(String qlString); /** - * Create an instance of Query for executing a + * Create an instance of TypedQuery for executing a * criteria query. - * - * @param criteriaQuery a Criteria API query definition object - * + * @param criteriaQuery a criteria query object * @return the new query instance - * * @throws IllegalArgumentException if the query definition is - * found to be invalid + * found to be invalid */ - public Query createQuery(CriteriaQuery criteriaQuery); + public <T> TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery); /** + * Create an instance of TypedQuery for executing a + * Java Persistence query language statement. + * The select list of the query must contain only a single + * item, which must be assignable to the type specified by + * the resultClass argument. + * @param qlString a Java Persistence query string + * @param resultClass the type of the query result + * @return the new query instance + * @throws IllegalArgumentException if the query string is found + * to be invalid or if the query result is found to + * not be assignable to the specified type. + */ + public <T> TypedQuery<T> createQuery(String qlString, Class<T> resultClass); + + /** * Create an instance of Query for executing a * named query (in the Java Persistence query language * or in native SQL). @@ -568,6 +580,23 @@ public Query createNamedQuery(String name); /** + * Create an instance of TypedQuery for executing a + * named query (in the Java Persistence query language + * or in native SQL). + * The select list of the query must contain only a single + * item, which must be assignable to the type specified by + * the resultClass argument. + * @param name the name of a query defined in metadata + * @param resultClass the type of the query result + * @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 or if the query result is found to + * not be assignable to the specified type. + */ + public <T> TypedQuery<T> createNamedQuery(String name, Class<T> resultClass); + + /** * Create an instance of Query for executing * a native SQL statement, e.g., for update or delete. * Modified: jpa-api/trunk/src/main/java/javax/persistence/EntityManagerFactory.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/EntityManagerFactory.java 2009-08-14 17:26:52 UTC (rev 17304) +++ jpa-api/trunk/src/main/java/javax/persistence/EntityManagerFactory.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -1,110 +1,119 @@ // $Id$ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. -package javax.persistence; - -import java.util.Map; -import java.util.Set; -import javax.persistence.criteria.QueryBuilder; -import javax.persistence.metamodel.Metamodel; - -/** - * Interface used to interact with the entity manager factory * for the persistence unit. - */ -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. - */ - 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. - */ - public EntityManager createEntityManager(Map map); - - /** - * Return an instance of QueryBuilder for the creation of - * Criteria API objects. - * - * @return QueryBuilder instance - * - * @throws IllegalStateException if the entity manager factory - * 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(); - - /** - * Indicates whether the factory is open. Returns true - * until the factory has been closed. - */ - public boolean isOpen(); - - /** - * 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(); - - /** - * 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<String, Object> 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 - */ - 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. - */ - public Cache getCache(); +package javax.persistence; + +import java.util.Map; +import java.util.Set; +import javax.persistence.criteria.QueryBuilder; +import javax.persistence.metamodel.Metamodel; + +/** + * Interface used to interact with the entity manager factory * for the persistence unit. + */ +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. + */ + 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. + */ + public EntityManager createEntityManager(Map map); + + /** + * Return an instance of QueryBuilder for the creation of + * Criteria API objects. + * + * @return QueryBuilder instance + * + * @throws IllegalStateException if the entity manager factory + * 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(); + + /** + * Indicates whether the factory is open. Returns true + * until the factory has been closed. + */ + public boolean isOpen(); + + /** + * 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(); + + /** + * 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<String, Object> 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 + */ + 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. + */ + public Cache getCache(); + + /** + * Return interface providing access to utility methods + * for the persistence unit. + * @return PersistenceUnitUtil interface + * @throws IllegalStateException if the entity manager factory + * has been closed. + */ + public PersistenceUnitUtil getPersistenceUnitUtil(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/Parameter.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Parameter.java 2009-08-14 17:26:52 UTC (rev 17304) +++ jpa-api/trunk/src/main/java/javax/persistence/Parameter.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -21,5 +21,19 @@ * @return position of parameter */ Integer getPosition(); + + /** + * Return the Java type of the parameter. Values bound to the + * parameter must be assignable to this type. + * This method is required to be supported for criteria queries + * only. Applications that use this method for Java Persistence + * query language queries and native queries will not be portable. + * @return the Java type of the parameter + * @throws IllegalStateException if invoked on a parameter + * obtained from a Java persistence query language query or + * native query when the implementation does not support this + * use. + */ + Class<T> getJavaType(); } Added: jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnitUtil.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnitUtil.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PersistenceUnitUtil.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -0,0 +1,52 @@ +// $Id: PersistenceUtil.java 17036 2009-07-08 09:09:38Z epbernard $ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +package javax.persistence; + +/** + * Utility interface between the application and the persistence + * provider managing the persistence unit. + * + * The methods of this interface should only be invoked on entity + * instances obtained from or managed by entity managers for this + * persistence unit or on new entity instances. + */ +public interface PersistenceUnitUtil extends PersistenceUtil { + + /** + * Determine the load state of a given persistent attribute + * of an entity belonging to the persistence unit. + * @param entity containing the attribute + * @param attributeName name of attribute whose load state is + * to be determined + * @return false if entity's state has not been loaded or + * if the attribute state has not been loaded, otherwise true + */ + public boolean isLoaded(Object entity, String attributeName); + + /** + * Determine the load state of an entity belonging to the + * persistence unit. + * This method can be used to determine the load state + * of an entity passed as a reference. An entity is + * considered loaded if all attributes for which FetchType + * EAGER has been specified have been loaded. + * The isLoaded(Object, String) method should be used to + * determine the load state of an attribute. + * Not doing so might lead to unintended loading of state. + * @param entity whose load state is to be determined + * @return false if the entity has not been loaded, else true. + */ + public boolean isLoaded(Object entity); + + /** + * Returns the id of the entity. + * A generated id is not guaranteed to be available until after + * the database insert has occurred. + * Returns null if the entity does not yet have an id + * @param entity + * @return id of the entity + * @throws IllegalStateException if the entity is found not to be + * an entity. + */ + public Object getIdentifier(Object entity); +} Added: jpa-api/trunk/src/main/java/javax/persistence/PessimisticLockScope.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/PessimisticLockScope.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/PessimisticLockScope.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -0,0 +1,8 @@ +// $Id:$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +package javax.persistence; + +public enum PessimisticLockScope { + NORMAL, + EXTENDED +} Modified: jpa-api/trunk/src/main/java/javax/persistence/Query.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/Query.java 2009-08-14 17:26:52 UTC (rev 17304) +++ jpa-api/trunk/src/main/java/javax/persistence/Query.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -1,5 +1,5 @@ -// $Id$ -// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +// $Id$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence; import java.util.Calendar; @@ -237,26 +237,119 @@ TemporalType temporalType); /** - * Get the parameters names and associated values of the - * parameters that are bound for the query instance. - * Returns empty map if no parameters have been bound - * or if the query does not use named parameters. - * - * @return named parameters - */ - public Map<String, Object> getNamedParameters(); + * Get the parameter objects corresponding to the declared + * parameters of the query. + * Returns empty set if the query has no parameters. + * This method is not required to be supported for native + * queries. + * @return set of the parameter objects + * @throws IllegalStateException if invoked on a native + * query when the implementation does not support + * this use + */ + Set<Parameter<?>> getParameters(); - /** - * Get the values of the positional parameters - * that are bound for the query instance. - * Positional parameters are listed in order of position. - * Returns empty list if no parameters have been bound - * or if the query does not use positional parameters. - * - * @return positional parameters - */ - public List getPositionalParameters(); + /** + * Get the parameter object corresponding to the declared + * parameter of the given name. + * This method is not required to be supported for native + * queries. + * @param name + * @return parameter object + * @throws IllegalArgumentException if the parameter of the + * specified name does not exist + * @throws IllegalStateException if invoked on a native + * query when the implementation does not support + * this use + */ + Parameter<?> getParameter(String name); + /** + * Get the parameter object corresponding to the declared + * positional parameter with the given position. + * This method is not required to be supported for native + * queries. + * @param position + * @return parameter object + * @throws IllegalArgumentException if the parameter with the + * specified position does not exist + * @throws IllegalStateException if invoked on a native + * query when the implementation does not support + * this use + */ + Parameter<?> getParameter(int position); + + /** + * Get the parameter of the given name and type. + * This method is required to be supported for criteria queries + * only. + * @param name + * @param type + * @return parameter object + * @throws IllegalArgumentException if the parameter of the + * specified name does not exist or is not assignable + * to the type + * @throws IllegalStateException if invoked on a native + * query or Java Persistence query language query when + * the implementation does not support this use + */ + <T> Parameter<T> getParameter(String name, Class<T> type); + + /** + * Get the positional parameter with the given position and type. + * This method is required to be supported for criteria queries + * only. + * @param position + * @param type + * @return parameter object + * @throws IllegalArgumentException if the parameter with the + * specified position does not exist or is not assignable + * to the type + * @throws IllegalStateException if invoked on a native + * query or Java Persistence query language query when + * the implementation does not support this use + */ + <T> Parameter<T> getParameter(int position, Class<T> type); + + /** + * Return a boolean indicating whether a value has been bound + * to the parameter. + * @param param parameter object + * @return boolean indicating whether parameter has been bound + */ + boolean isBound(Parameter<?> param); + + /** + * Return the value bound to the parameter. + * @param param parameter object + * @return parameter value + * @throws IllegalStateException if the parameter has not been + * been bound + */ + <T> T getParameterValue(Parameter<T> param); + + /** + * Return the value bound to the named parameter. + * @param name + * @return parameter value + * @throws IllegalStateException if the parameter has not been + * been bound + * @throws IllegalArgumentException if the parameter of the + * specified name does not exist + */ + Object getParameterValue(String name); + + /** + * Return the value bound to the positional parameter. + * @param position + * @return parameter value + * @throws IllegalStateException if the parameter has not been + * been bound + * @throws IllegalArgumentException if the parameter with the + * specified position does not exist + */ + Object getParameterValue(int position); + /** * Set the flush mode type to be used for the query execution. * The flush mode type applies to the query regardless of the Added: jpa-api/trunk/src/main/java/javax/persistence/TypedQuery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/TypedQuery.java (rev 0) +++ jpa-api/trunk/src/main/java/javax/persistence/TypedQuery.java 2009-08-14 18:29:45 UTC (rev 17305) @@ -0,0 +1,203 @@ +// $Id:$ +// EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. +package javax.persistence; + +import java.util.List; +import java.util.Date; +import java.util.Calendar; + +/** + * Interface used to control the execution of typed queries. + * @param <X> query result type + */ +public interface TypedQuery<X> extends Query { + + /** + * Execute a SELECT query and return the query results + * as a typed List. + * @return a list of the results + * @throws IllegalStateException if called for a Java + * Persistence query language UPDATE or DELETE statement + * @throws QueryTimeoutException if the query execution exceeds + * the query timeout value set + * @throws TransactionRequiredException if a lock mode has + * been set and there is no transaction + * @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 + */ + List<X> getResultList(); + + /** + * Execute a SELECT query that returns a single result. + * @return the result + * @throws NoResultException if there is no result + * @throws NonUniqueResultException if more than one result + * @throws IllegalStateException if called for a Java + * Persistence query language UPDATE or DELETE statement + * @throws QueryTimeoutException if the query execution exceeds + * the query timeout value set + * @throws TransactionRequiredException if a lock mode has + * been set and there is no transaction + * @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 + */ + X getSingleResult(); + + /** + * Set the maximum number of results to retrieve. + * @param maxResult + * @return the same query instance + * @throws IllegalArgumentException if argument is negative + */ + TypedQuery<X> setMaxResults(int maxResult); + + /** + * Set the position of the first result to retrieve. + * @param startPosition position of the first result, + * numbered from 0 + * @return the same query instance + * @throws IllegalArgumentException if argument is negative + */ + TypedQuery<X> setFirstResult(int startPosition); + + /** + * Set a query hint. + * If a vendor-specific 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 hintName + * @param value + * @return the same query instance + * @throws IllegalArgumentException if the second argument is not + * valid for the implementation + */ + TypedQuery<X> setHint(String hintName, Object value); + + /** + * Bind the value of a Parameter object. + * @param param parameter object + * @param value parameter value + * @return the same query instance + * @throws IllegalArgumentException if parameter + * does not correspond to a parameter of the + * query + */ + <T> TypedQuery<X> setParameter(Parameter<T> param, T value); + + /** + * Bind an instance of java.util.Date to a Parameter object. + * @param parameter object + * @param value + * @param temporalType + * @return the same query instance + * @throws IllegalArgumentException if position does not + * correspond to a parameter of the query + */ + TypedQuery<X> setParameter(Parameter<Date> param, Date value, TemporalType temporalType); + + + /** + * Bind an instance of java.util.Calendar to a Parameter object. + * @param parameter + * @param value + * @param temporalType + * @return the same query instance + * @throws IllegalArgumentException if position does not + * correspond to a parameter of the query + */ + TypedQuery<X> setParameter(Parameter<Calendar> param, Calendar value, TemporalType temporalType); + + /** + * Bind an argument to a named parameter. + * @param name the parameter name + * @param value + * @return the same query instance + * @throws IllegalArgumentException if parameter name does not + * correspond to a parameter of the query or if + * the argument is of incorrect type + */ + TypedQuery<X> setParameter(String name, Object value); + + /** + * Bind an instance of java.util.Date to a named parameter. + * @param name + * @param value + * @param temporalType + * @return the same query instance + * @throws IllegalArgumentException if parameter name does not + * correspond to a parameter of the query + */ + TypedQuery<X> setParameter(String name, Date value, TemporalType temporalType); + + /** + * Bind an instance of java.util.Calendar to a named parameter. + * @param name + * @param value + * @param temporalType + * @return the same query instance + * @throws IllegalArgumentException if parameter name does not + * correspond to a parameter of the query + */ + TypedQuery<X> setParameter(String name, Calendar value, TemporalType temporalType); + + /** + * Bind an argument to a positional parameter. + * @param position + * @param value + * @return the same query instance + * @throws IllegalArgumentException if position does not + * correspond to a positional parameter of the + * query or if the argument is of incorrect type + */ + TypedQuery<X> setParameter(int position, Object value); + + /** + * Bind an instance of java.util.Date to a positional parameter. + * @param position + * @param value + * @param temporalType + * @return the same query instance + * @throws IllegalArgumentException if position does not + * correspond to a positional parameter of the query + */ + TypedQuery<X> setParameter(int position, Date value, TemporalType temporalType); + + /** + * Bind an instance of java.util.Calendar to a positional + * parameter. + * @param position + * @param value + * @param temporalType + * @return the same query instance + * @throws IllegalArgumentException if position does not + * correspond to a positional parameter of the query + */ + TypedQuery<X> setParameter(int position, Calendar value, TemporalType temporalType); + + /** + * Set the flush mode type to be used for the query execution. + * The flush mode type applies to the query regardless of the + * flush mode type in use for the entity manager. + * @return the same query instance + * @param flushMode + */ + TypedQuery<X> setFlushMode(FlushModeType flushMode); + + /** + * Set the lock mode type to be used for the query execution. + * @param lockMode + * @return the same query instance + * @throws IllegalStateException if the query is found not to + * be a Java Persistence query language SELECT query + * or a Criteria API query + */ + TypedQuery<X> setLockMode(LockModeType lockMode); + +}