[hibernate-commits] Hibernate SVN: r17525 - jpa-api/trunk/src/main/java/javax/persistence/criteria.

Author: steve.ebersole(a)jboss.com Date: 2009-09-17 16:22:44 -0400 (Thu, 17 Sep 2009) New Revision: 17525 Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/AbstractQuery.java jpa-api/trunk/src/main/java/javax/persistence/criteria/CollectionJoin.java jpa-api/trunk/src/main/java/javax/persistence/criteria/CriteriaQuery.java jpa-api/trunk/src/main/java/javax/persistence/criteria/Expression.java jpa-api/trunk/src/main/java/javax/persistence/criteria/FetchParent.java jpa-api/trunk/src/main/java/javax/persistence/criteria/From.java jpa-api/trunk/src/main/java/javax/persistence/criteria/ListJoin.java jpa-api/trunk/src/main/java/javax/persistence/criteria/MapJoin.java jpa-api/trunk/src/main/java/javax/persistence/criteria/ParameterExpression.java jpa-api/trunk/src/main/java/javax/persistence/criteria/Path.java jpa-api/trunk/src/main/java/javax/persistence/criteria/Predicate.java jpa-api/trunk/src/main/java/javax/persistence/criteria/QueryBuilder.java jpa-api/trunk/src/main/java/javax/persistence/criteria/Subquery.java Log: validated javax.persistence.criteria package definitions against spec version dated 2009.31.08 (plus accounted for Subquery#getJoins being renamed to getCorrelatedJoins as indicated by Linda in email response) Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/AbstractQuery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/AbstractQuery.java 2009-09-17 17:36:24 UTC (rev 17524) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/AbstractQuery.java 2009-09-17 20:22:44 UTC (rev 17525) @@ -22,27 +22,21 @@ /** * Add a query root corresponding to the given entity, * forming a cartesian product with any existing roots. - * @param entity metamodel entity representing the entity - * of type X + * @param entityClass the entity class * @return query root corresponding to the given entity */ - <X> Root<X> from(EntityType<X> entity); + <X> Root<X> from(Class<X> entityClass); /** * Add a query root corresponding to the given entity, * forming a cartesian product with any existing roots. - * @param entityClass the entity class + * @param entity metamodel entity representing the entity + * of type X * @return query root corresponding to the given entity */ - <X> Root<X> from(Class<X> entityClass); + <X> Root<X> from(EntityType<X> entity); /** - * Return the query roots. - * @return the set of query roots - */ - Set<Root<?>> getRoots(); - - /** * Modify the query to restrict the query results according * to the specified boolean expression. * Replaces the previously added restriction(s), if any. @@ -73,6 +67,17 @@ */ AbstractQuery<T> groupBy(Expression<?>... grouping); + /** + * Specify the expressions that are used to form groups over + * the query results. + * Replaces the previous specified grouping expressions, if any. + * If no grouping expressions are specified, any previously + * added grouping expressions are simply removed. + * @param grouping list of zero or more grouping expressions + * @return the modified query + */ + AbstractQuery<T> groupBy(List<Expression<?>> grouping); + /** * Specify a restriction over the groups of the query. * Replaces the previous having restriction(s), if any. @@ -107,18 +112,25 @@ AbstractQuery<T> distinct(boolean distinct); /** + * Create a subquery of the query. + * @param type the subquery result type + * @return subquery + */ + <U> Subquery<U> subquery(Class<U> type); + + /** + * Return the query roots. + * @return the set of query roots + */ + Set<Root<?>> getRoots(); + + /** * Return the selection of the query * @return selection item */ Selection<T> getSelection(); /** - * Return a list of the grouping expressions - * @return the list of grouping expressions - */ - List<Expression<?>> getGroupList(); - - /** * Return the predicate that corresponds to the where clause * restriction(s). * @return where clause predicate @@ -126,6 +138,12 @@ Predicate getRestriction(); /** + * Return a list of the grouping expressions + * @return the list of grouping expressions + */ + List<Expression<?>> getGroupList(); + + /** * Return the predicate that corresponds to the restriction(s) * over the grouping items. * @return having clause predicate @@ -140,12 +158,15 @@ */ boolean isDistinct(); - /** - * Create a subquery of the query. - * @param type the subquery result type - * @return subquery - */ - <U> Subquery<U> subquery(Class<U> type); - + /** + * Return the result type of the query or subquery. + * If a result type was specified as an argument to the + * createQuery or subquery method, that type will be returned. + * If the query was created using the createTupleQuery + * method, the result type is Tuple. + * Otherwise, the result type is Object. + * @return result type + */ + Class<T> getResultType(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/CollectionJoin.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/CollectionJoin.java 2009-09-17 17:36:24 UTC (rev 17524) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/CollectionJoin.java 2009-09-17 20:22:44 UTC (rev 17525) @@ -13,8 +13,7 @@ * @param <Z> The source type of the join * @param <E> The element type of the target Collection */ -public interface CollectionJoin<Z, E> - extends PluralJoin<Z, Collection<E>, E> { +public interface CollectionJoin<Z, E> extends PluralJoin<Z, Collection<E>, E> { /** * Return the metamodel representation for the collection Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/CriteriaQuery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/CriteriaQuery.java 2009-09-17 17:36:24 UTC (rev 17524) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/CriteriaQuery.java 2009-09-17 20:22:44 UTC (rev 17525) @@ -11,119 +11,145 @@ */ public interface CriteriaQuery<T> extends AbstractQuery<T> { - /** - * Specify the item that is to be returned in the query result. - * Replaces the previously specified selection(s), if any. - * @param selection selection specifying the item that - * is to be returned in the query result - * @return the modified query - */ - CriteriaQuery<T> select(Selection<? extends T> selection); + /** + * Specify the item that is to be returned in the query result. + * Replaces the previously specified selection(s), if any. + * + * Note: Applications using the string-based API may need to + * specify the type of the select item when it results from + * a get or join operation and the query result type is + * specified. For example: + * + * CriteriaQuery<String> q = qb.createQuery(String.class); + * Root<Order> order = q.from(Order.class); + * q.select(order.get("shippingAddress").<String>get("state")); + * + * CriteriaQuery<Product> q2 = qb.createQuery(Product.class); + * q2.select(q2.from(Order.class) + * .join("items") + * .<Item,Product>join("product")); + * + * @param selection selection specifying the item that + * is to be returned in the query result + * @return the modified query + * @throws IllegalArgumentException if the selection is + * a compound selection and more than one selection + * item has the same assigned alias + */ + CriteriaQuery<T> select(Selection<? extends T> selection); - /** - * Specify the selection items that are to be returned in the - * query result. - * Replaces the previously specified selection(s), if any. - * - * The type of the result of the query execution depends on - * the specification of the type of the criteria query object - * created as well as the arguments to the multiselect method. - * An argument to the multiselect method must not be a tuple- - * or array-valued compound selection item. - * The semantics of this method are as follows: - * - * If the type of the criteria query is CriteriaQuery<Tuple> - * (i.e., a criteria query object created by either the - * createTupleQuery method or by passing a Tuple class argument - * to the createQuery method), a Tuple object corresponding to - * the arguments of the multiselect method will be instantiated - * and returned for each row that results from the query execution. - * - * If the type of the criteria query is CriteriaQuery<X> for - * some user-defined class X (i.e., a criteria query object - * created by passing a X class argument to the createQuery - * method), then the arguments to the multiselect method will be - * passed to the X constructor and an instance of type X will be - * returned for each row. - * - * If the type of the criteria query is CriteriaQuery<X[]> for - * some class X, an instance of type X[] will be returned for - * each row. The elements of the array will correspond to the - * arguments of the multiselect method. - * - * If the type of the criteria query is CriteriaQuery<Object> - * or if the criteria query was created without specifying a type, - * and only a single argument is passed to the multiselect method, - * an instance of type Object will be returned for each row. - * - * If the type of the criteria query is CriteriaQuery<Object> - * or if the criteria query was created without specifying a type, - * and more than one argument is passed to the multiselect method, - * an instance of type Object[] will be instantiated and returned - * for each row. The elements of the array will correspond to the - * arguments to the multiselect method. - * - * @param selections selection items corresponding to the - * results to be returned by the query - * @return the modified query - */ - CriteriaQuery<T> multiselect(Selection<?>... selections); + /** + * Specify the selection items that are to be returned in the + * query result. + * Replaces the previously specified selection(s), if any. + * + * The type of the result of the query execution depends on + * the specification of the type of the criteria query object + * created as well as the arguments to the multiselect method. + * An argument to the multiselect method must not be a tuple- + * or array-valued compound selection item. + * + * The semantics of this method are as follows: + * + * If the type of the criteria query is CriteriaQuery<Tuple> + * (i.e., a criteria query object created by either the + * createTupleQuery method or by passing a Tuple class argument + * to the createQuery method), a Tuple object corresponding to + * the arguments of the multiselect method will be instantiated + * and returned for each row that results from the query + * execution. + * + * If the type of the criteria query is CriteriaQuery<X> for + * some user-defined class X (i.e., a criteria query object + * created by passing a X class argument to the createQuery + * method), the arguments to the multiselect method will be + * passed to the X constructor and an instance of type X will be + * returned for each row. + * + * If the type of the criteria query is CriteriaQuery<X[]> for + * some class X, an instance of type X[] will be returned for + * each row. The elements of the array will correspond to the + * arguments of the multiselect method. + * + * If the type of the criteria query is CriteriaQuery<Object> + * or if the criteria query was created without specifying a + * type, and only a single argument is passed to the multiselect + * method, an instance of type Object will be returned for + * each row. + * + * If the type of the criteria query is CriteriaQuery<Object> + * or if the criteria query was created without specifying a + * type, and more than one argument is passed to the multiselect + * method, an instance of type Object[] will be instantiated + * and returned for each row. The elements of the array will + * correspond to the arguments to the multiselect method. + * + * @param selections selection items corresponding to the + * results to be returned by the query + * @return the modified query + * @throws IllegalArgumentException if a selection item is + * not valid or if more than one selection item has + * the same assigned alias + */ + CriteriaQuery<T> multiselect(Selection<?>... selections); + /** + * Specify the selection items that are to be returned in the + * query result. + * Replaces the previously specified selection(s), if any. + * + * The type of the result of the query execution depends on + * the specification of the type of the criteria query object + * created as well as the argument to the multiselect method. + * An element of the list passed to the multiselect method + * must not be a tuple- or array-valued compound selection item. + * + * The semantics of this method are as follows: + * + * If the type of the criteria query is CriteriaQuery<Tuple> + * (i.e., a criteria query object created by either the + * createTupleQuery method or by passing a Tuple class argument + * to the createQuery method), a Tuple object corresponding to + * the elements of the list passed to the multiselect method + * will be instantiated and returned for each row that results + * from the query execution. + * + * If the type of the criteria query is CriteriaQuery<X> for + * some user-defined class X (i.e., a criteria query object + * created by passing a X class argument to the createQuery + * method), the elements of the list passed to the multiselect + * method will be passed to the X constructor and an instance + * of type X will be returned for each row. + * + * If the type of the criteria query is CriteriaQuery<X[]> for + * some class X, an instance of type X[] will be returned for + * each row. The elements of the array will correspond to the + * elements of the list passed to the multiselect method. + * + * If the type of the criteria query is CriteriaQuery<Object> + * or if the criteria query was created without specifying a + * type, and the list passed to the multiselect method contains + * only a single element, an instance of type Object will be + * returned for each row. + * + * If the type of the criteria query is CriteriaQuery<Object> + * or if the criteria query was created without specifying a + * type, and the list passed to the multiselect method contains + * more than one element, an instance of type Object[] will be + * instantiated and returned for each row. The elements of the + * array will correspond to the elements of the list passed to + * the multiselect method. + * + * @param selectionList list of selection items corresponding + * to the results to be returned by the query + * @return the modified query + * @throws IllegalArgumentException if a selection item is + * not valid or if more than one selection item has + * the same assigned alias + */ + CriteriaQuery<T> multiselect(List<Selection<?>> selectionList); /** - * Specify the selection items that are to be returned in the - * query result. - * Replaces the previously specified selection(s), if any. - * - * The type of the result of the query execution depends on - * the specification of the type of the criteria query object - * created as well as the argument to the multiselect method. - * An element of the list passed to the multiselect method - * must not be a tuple- or array-valued compound selection item. - * The semantics of this method are as follows: - * - * If the type of the criteria query is CriteriaQuery<Tuple> - * (i.e., a criteria query object created by either the - * createTupleQuery method or by passing a Tuple class argument - * to the createQuery method), a Tuple object corresponding to - * the elements of the list passed to the multiselect method - * will be instantiated and returned for each row that results - * from the query execution. - * - * If the type of the criteria query is CriteriaQuery<X> for - * some user-defined class X (i.e., a criteria query object - * created by passing a X class argument to the createQuery - * method), then the elements of the list passed to the - * multiselect method will be passed to the X constructor and - * an instance of type X will be returned for each row. - * - * If the type of the criteria query is CriteriaQuery<X[]> for - * some class X, an instance of type X[] will be returned for - * each row. The elements of the array will correspond to the - * elements of the list passed to the multiselect method. - * - * If the type of the criteria query is CriteriaQuery<Object> - * or if the criteria query was created without specifying a type, - * and the list passed to the multiselect method contains only - * a single element, an instance of type Object will be returned - * for each row. - * - * If the type of the criteria query is CriteriaQuery<Object> - * or if the criteria query was created without specifying a type, - * and the list passed to the multiselect method contains more - * than one element, an instance of type Object[] will be - * instantiated and returned for each row. The elements of the - * array will correspond to the elements of the list passed to - * the multiselect method. - * - * @param selectionList list of selection items corresponding - * to the results to be returned by the query - * @return the modified query - */ - CriteriaQuery<T> multiselect(List<Selection<?>> selectionList); - - - /** * Modify the query to restrict the query result according * to the specified boolean expression. * Replaces the previously added restriction(s), if any. @@ -160,6 +186,19 @@ */ CriteriaQuery<T> groupBy(Expression<?>... grouping); + /** + * Specify the expressions that are used to form groups over + * the query results. + * Replaces the previous specified grouping expressions, if any. + * If no grouping expressions are specified, any previously + * added grouping expressions are simply removed. + * This method only overrides the return type of the + * corresponding AbstractQuery method. + * @param grouping list of zero or more grouping expressions + * @return the modified query + */ + CriteriaQuery<T> groupBy(List<Expression<?>> grouping); + /** * Specify a restriction over the groups of the query. * Replaces the previous having restriction(s), if any. @@ -199,6 +238,21 @@ */ CriteriaQuery<T> orderBy(Order... o); + /** + * Specify the ordering expressions that are used to + * order the query results. + * Replaces the previous ordering expressions, if any. + * If no ordering expressions are specified, the previous + * ordering, if any, is simply removed, and results will + * be returned in no particular order. + * The order of the ordering expressions in the list + * determines the precedence, whereby the first element in the + * list has highest precedence. + * @param o list of zero or more ordering expressions + * @return the modified query. + */ + CriteriaQuery<T> orderBy(List<Order> o); + /** * Specify whether duplicate query results will be eliminated. * A true value will cause duplicates to be eliminated. @@ -215,25 +269,19 @@ CriteriaQuery<T> distinct(boolean distinct); /** - * Return the result type of the query. - * If a result type was specified as an argument to the - * createQuery method, that type will be returned. - * If the query was created using the createTupleQuery - * method, the result type is Tuple. - * Otherwise, the result type is Object. - * @return result type + * Return the ordering expressions in order of precedence. + * Returns empty list if no ordering expressions have been + * specified. + * Modifications to the list do not affect the query. + * @return the list of ordering expressions */ - Class getResultType(); - - /** - * Return the ordering expressions in order of precedence. - * @return the list of ordering expressions - */ List<Order> getOrderList(); - /** - * Return the parameters of the query - * @return the query parameters - */ + /** + * Return the parameters of the query. Returns empty set if + * there are no parameters. + * Modifications to the set do not affect the query. + * @return the query parameters + */ Set<ParameterExpression<?>> getParameters(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/Expression.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/Expression.java 2009-09-17 17:36:24 UTC (rev 17524) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/Expression.java 2009-09-17 20:22:44 UTC (rev 17525) @@ -11,54 +11,58 @@ public interface Expression<T> extends Selection<T> { /** - * Apply a predicate to test whether the expression is null. - * @return predicate testing whether the expression is null + * Create a predicate to test whether the expression is null. + * @return predicate testing whether the expression is null */ Predicate isNull(); /** - * Apply a predicate to test whether the expression is not null. - * @return predicate testing whether the expression is not null. + * Create a predicate to test whether the expression is + * not null. + * @return predicate testing whether the expression is not null. */ Predicate isNotNull(); /** - * Apply a predicate to test whether the expression is a member - * of the argument list. - * @param values - * @return predicate testing for membership in the list + * Create a predicate to test whether the expression is a member + * of the argument list. + * @param values The argument list + * @return predicate testing for membership in the list */ Predicate in(Object... values); /** - * Apply a predicate to test whether the expression is a member - * of the argument list. - * @param values - * @return predicate testing for membership + * Create a predicate to test whether the expression is a member + * of the argument list. + * @param values The argument list + * @return predicate testing for membership in the list */ Predicate in(Expression<?>... values); /** - * Apply a predicate to test whether the expression is a member - * of the collection. - * @param values collection - * @return predicate testing for membership + * Create a predicate to test whether the expression is a member + * of the collection. + * @param values collection + * @return predicate testing for membership */ Predicate in(Collection<?> values); /** - * Apply a predicate to test whether the expression is a member - * of the collection. - * @param values expression corresponding to collection - * @return predicate testing for membership + * Create a predicate to test whether the expression is a member + * of the collection. + * @param values expression corresponding to collection + * @return predicate testing for membership */ Predicate in(Expression<Collection<?>> values); /** - * Perform a typecast upon the expression. - * Warning: may result in a runtime failure. - * @param type - * @return expression + * Perform a typecast upon the expression, returning new + * expression object. + * This method does not cause type conversion: + * the runtime type is not changed. + * Warning: may result in a runtime failure. + * @param type The cast type + * @return new expression of the given type */ <X> Expression<X> as(Class<X> type); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/FetchParent.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/FetchParent.java 2009-09-17 17:36:24 UTC (rev 17524) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/FetchParent.java 2009-09-17 20:22:44 UTC (rev 17525) @@ -15,42 +15,45 @@ public interface FetchParent<Z, X> { /** - * Return the fetch joins that have been made from this type. - * @return fetch joins made from this type + * Return the fetch joins that have been made from this type. + * Returns empty set if no fetch joins have been made from + * this type. + * Modifications to the set do not affect the query. + * @return fetch joins made from this type */ java.util.Set<Fetch<X, ?>> getFetches(); /** - * Fetch join to the specified single-valued attribute - * using an inner join. - * @param attribute target of the join - * @return the resulting fetch join + * Create a fetch join to the specified single-valued attribute + * using an inner join. + * @param attribute target of the join + * @return the resulting fetch join */ <Y> Fetch<X, Y> fetch(SingularAttribute<? super X, Y> attribute); /** - * Fetch join to the specified single-valued attribute using - * the given join type. - * @param attribute target of the join - * @param jt join type - * @return the resulting fetch join + * Create a fetch join to the specified single-valued attribute + * using the given join type. + * @param attribute target of the join + * @param jt join type + * @return the resulting fetch join */ <Y> Fetch<X, Y> fetch(SingularAttribute<? super X, Y> attribute, JoinType jt); /** - * Fetch join to the specified collection-valued attribute - * using an inner join. - * @param attribute target of the join - * @return the resulting join + * Create a fetch join to the specified collection-valued attribute + * using an inner join. + * @param attribute target of the join + * @return the resulting join */ <Y> Fetch<X, Y> fetch(PluralAttribute<? super X, ?, Y> attribute); /** - * Fetch join to the specified collection-valued attribute - * using the given join type. - * @param attribute target of the join - * @param jt join type - * @return the resulting join + * Create a fetch join to the specified collection-valued attribute + * using the given join type. + * @param attribute target of the join + * @param jt join type + * @return the resulting join */ <Y> Fetch<X, Y> fetch(PluralAttribute<? super X, ?, Y> attribute, JoinType jt); @@ -58,32 +61,26 @@ //String-based: /** - * Fetch join to the specified attribute using an inner join. - * - * @param <X> The type of the source of the fetch; note that this method-local <X> hides the <X> defined as a type - * param to {@link FetchParent}; the expectation is that the two types match. - * @param <Y> The type of the fetched attribute/association - * @param attributeName name of the attribute for the - * target of the join - * @return the resulting fetch join - * @throws IllegalArgumentException if attribute of the given - * name does not exist + * Create a fetch join to the specified attribute using an + * inner join. + * @param attributeName name of the attribute for the + * target of the join + * @return the resulting fetch join + * @throws IllegalArgumentException if attribute of the given + * name does not exist */ <X, Y> Fetch<X, Y> fetch(String attributeName); /** - * Fetch join to the specified attribute using the given + * Create a fetch join to the specified attribute using the given * join type. * - * @param <X> The type of the source of the fetch; note that this method-local <X> hides the <X> defined as a type - * param to {@link FetchParent}; the expectation is that the two types match. - * @param <Y> The type of the fetched attribute/association - * @param attributeName name of the attribute for the - * target of the join - * @param jt join type - * @return the resulting fetch join - * @throws IllegalArgumentException if attribute of the given - * name does not exist + * @param attributeName name of the attribute for the + * target of the join + * @param jt join type + * @return the resulting fetch join + * @throws IllegalArgumentException if attribute of the given + * name does not exist */ <X, Y> Fetch<X, Y> fetch(String attributeName, JoinType jt); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/From.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/From.java 2009-09-17 17:36:24 UTC (rev 17524) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/From.java 2009-09-17 20:22:44 UTC (rev 17525) @@ -21,93 +21,94 @@ public interface From<Z, X> extends Path<X>, FetchParent<Z, X> { /** - * Return the joins that have been made from this type. - * @return joins made from this type + * Return the joins that have been made from this bound type. + * Does not include joins from map keys, if any. + * Returns empty set if no joins have been made from this + * bound type. + * Modifications to the set do not affect the query. + * @return joins made from this type */ java.util.Set<Join<X, ?>> getJoins(); /** - * Join to the specified single-valued attribute using an - * inner join. - * @param attribute target of the join - * @return the resulting join + * Create an inner join to the specified single-valued + * attribute. + * @param attribute target of the join + * @return the resulting join */ <Y> Join<X, Y> join(SingularAttribute<? super X, Y> attribute); /** - * Join to the specified single-valued attribute using the - * given join type. - * @param attribute target of the join - * @param jt join type - * @return the resulting join + * Create a join to the specified single-valued attribute + * using the given join type. + * @param attribute target of the join + * @param jt join type + * @return the resulting join */ <Y> Join<X, Y> join(SingularAttribute<? super X, Y> attribute, JoinType jt); /** - * Join to the specified Collection-valued attribute using - * an inner join. - * @param collection target of the join - * @return the resulting join + * Create an inner join to the specified Collection-valued + * attribute. + * @param collection target of the join + * @return the resulting join */ <Y> CollectionJoin<X, Y> join(CollectionAttribute<? super X, Y> collection); /** - * Join to the specified Set-valued attribute using an inner - * join. - * @param set target of the join - * @return the resulting join + * Create an inner join to the specified Set-valued attribute. + * @param set target of the join + * @return the resulting join */ <Y> SetJoin<X, Y> join(SetAttribute<? super X, Y> set); /** - * Join to the specified List-valued attribute using an inner - * join. - * @param list target of the join - * @return the resulting join + * Create an inner join to the specified List-valued attribute. + * @param list target of the join + * @return the resulting join */ <Y> ListJoin<X, Y> join(ListAttribute<? super X, Y> list); /** - * Join to the specified Map-valued attribute using an inner - * join. - * @param map target of the join - * @return the resulting join + * Create an inner join to the specified Map-valued attribute. + * @param map target of the join + * @return the resulting join */ <K, V> MapJoin<X, K, V> join(MapAttribute<? super X, K, V> map); /** - * Join to the specified Collection-valued attribute - * using the given join type. - * @param collection target of the join - * @param jt join type - * @return the resulting join + * Create a join to the specified Collection-valued attribute + * using the given join type. + * @param collection target of the join + * @param jt join type + * @return the resulting join */ <Y> CollectionJoin<X, Y> join(CollectionAttribute<? super X, Y> collection, JoinType jt); /** - * Join to the specified Set-valued attribute using the given - * join type. - * @param set target of the join - * @param jt join type - * @return the resulting join + * Create a join to the specified Set-valued attribute using + * the given join type. + * @param set target of the join + * @param jt join type + * @return the resulting join */ <Y> SetJoin<X, Y> join(SetAttribute<? super X, Y> set, JoinType jt); /** - * Join to the specified List-valued attribute using the - * given join type. - * @param list target of the join - * @param jt join type - * @return the resulting join + * Create a join to the specified List-valued attribute using + * the given join type. + * @param list target of the join + * @param jt join type + * @return the resulting join */ <Y> ListJoin<X, Y> join(ListAttribute<? super X, Y> list, JoinType jt); /** - * Join to the specified Map-valued attribute using the - * given join type. - * @param map target of the join - * @param jt join type - * @return the resulting join + * Create a join to the specified Map-valued attribute using + * the given join type. + * @param map target of the join + * @param jt join type + * @return the resulting join */ <K, V> MapJoin<X, K, V> join(MapAttribute<? super X, K, V> map, JoinType jt); Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/ListJoin.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/ListJoin.java 2009-09-17 17:36:24 UTC (rev 17524) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/ListJoin.java 2009-09-17 20:22:44 UTC (rev 17525) @@ -13,24 +13,23 @@ * @param <Z> The source type of the join * @param <E> The element type of the target List */ -public interface ListJoin<Z, E> - extends PluralJoin<Z, List<E>, E> { +public interface ListJoin<Z, E> extends PluralJoin<Z, List<E>, E> { /** * Return the metamodel representation for the list attribute. * @return metamodel type representing the List that is - * the target of the join + * the target of the join */ ListAttribute<? super Z, E> getModel(); /** - * Return an expression that corresponds to the index of - * the object in the referenced association or element - * collection. - * This method must only be invoked upon an object that - * represents an association or element collection for - * which an order column has been defined. - * @return expression denoting the index + * Create an expression that corresponds to the index of + * the object in the referenced association or element + * collection. + * This method must only be invoked upon an object that + * represents an association or element collection for + * which an order column has been defined. + * @return expression denoting the index */ Expression<Integer> index(); } \ No newline at end of file Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/MapJoin.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/MapJoin.java 2009-09-17 17:36:24 UTC (rev 17524) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/MapJoin.java 2009-09-17 20:22:44 UTC (rev 17525) @@ -14,8 +14,7 @@ * @param <K> The type of the target Map key * @param <V> The type of the target Map value */ -public interface MapJoin<Z, K, V> - extends PluralJoin<Z, Map<K, V>, V> { +public interface MapJoin<Z, K, V> extends PluralJoin<Z, Map<K, V>, V> { /** * Return the metamodel representation for the map attribute. @@ -25,35 +24,35 @@ MapAttribute<? super Z, K, V> getModel(); /** - * Specify an inner join over the map key. - * @return result of joining over the map key + * Create an inner join over the map key. + * @return result of joining over the map key */ Join<Map<K, V>, K> joinKey(); /** - * Specify a join over the map key using the given - * join type. - * @param jt join type - * @return result of joining over the map key + * Create a join over the map key using the given + * join type. + * @param jt join type + * @return result of joining over the map key */ Join<Map<K, V>, K> joinKey(JoinType jt); /** - * Return a path expression that corresponds to the map key. - * @return path corresponding to map key + * Create a path expression that corresponds to the map key. + * @return path corresponding to map key */ Path<K> key(); /** - * Return a path expression that corresponds to the map value. - * This method is for stylistic use only: it just returns this. - * @return path corresponding to the map value + * Create a path expression that corresponds to the map value. + * This method is for stylistic use only: it just returns this. + * @return path corresponding to the map value */ Path<V> value(); /** - * Return an expression that corresponds to the map entry. - * @return expression corresponding to the map entry + * Create an expression that corresponds to the map entry. + * @return expression corresponding to the map entry */ Expression<Map.Entry<K, V>> entry(); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/ParameterExpression.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/ParameterExpression.java 2009-09-17 17:36:24 UTC (rev 17524) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/ParameterExpression.java 2009-09-17 20:22:44 UTC (rev 17525) @@ -9,5 +9,6 @@ * Type of criteria query parameter expressions. * @param <T> the type of the parameter expression */ -public interface ParameterExpression<T> extends Parameter<T>, Expression<T> {} +public interface ParameterExpression<T> extends Parameter<T>, Expression<T> { +} Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/Path.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/Path.java 2009-09-17 17:36:24 UTC (rev 17524) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/Path.java 2009-09-17 20:22:44 UTC (rev 17525) @@ -60,15 +60,35 @@ //String-based: - /** - * Return the path corresponding to the referenced - * attribute. - * @param attributeName name of the attribute - * @return path corresponding to the referenced attribute - * @throws IllegalStateException if invoked on a path that - * corresponds to a basic type - * @throws IllegalArgumentException if attribute of the given - * name does not otherwise exist - */ - <Y> Path<Y> get(String attributeName); + /** + * Create a path corresponding to the referenced attribute. + * + * Note: Applications using the string-based API may need to + * specify the type resulting from the get operation in order + * to avoid the use of Path variables. + * + * For example: + * + * CriteriaQuery<Person> q = qb.createQuery(Person.class); + * Root<Person> p = q.from(Person.class); + * q.select(p) + * .where(qb.isMember(qb.literal("joe"), + * p.<Set<String>>get("nicknames"))); + * + * rather than: + * + * CriteriaQuery<Person> q = qb.createQuery(Person.class); + * Root<Person> p = q.from(Person.class); + * Path<Set<String>> nicknames = p.get("nicknames"); + * q.select(p) + * .where(qb.isMember(qb.literal("joe"), nicknames)); + * + * @param attributeName name of the attribute + * @return path corresponding to the referenced attribute + * @throws IllegalStateException if invoked on a path that + * corresponds to a basic type + * @throws IllegalArgumentException if attribute of the given + * name does not otherwise exist + */ + <Y> Path<Y> get(String attributeName); } Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/Predicate.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/Predicate.java 2009-09-17 17:36:24 UTC (rev 17524) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/Predicate.java 2009-09-17 20:22:44 UTC (rev 17525) @@ -31,7 +31,10 @@ /** * Return the top-level conjuncts or disjuncts of the predicate. - * @return list of boolean expressions forming the predicate + * Returns empty list if there are no top-level conjuncts or + * disjuncts of the predicate. + * Modifications to the list do not affect the query. + * @return list of boolean expressions forming the predicate */ List<Expression<Boolean>> getExpressions(); Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/QueryBuilder.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/QueryBuilder.java 2009-09-17 17:36:24 UTC (rev 17524) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/QueryBuilder.java 2009-09-17 20:22:44 UTC (rev 17525) @@ -239,6 +239,16 @@ Predicate and(Expression<Boolean> x, Expression<Boolean> y); /** + * Create a conjunction of the given restriction predicates. + * A conjunction of zero predicates is true. + * + * @param restrictions zero or more restriction predicates + * + * @return and predicate + */ + Predicate and(Predicate... restrictions); + + /** * Create a disjunction of the given boolean expressions. * * @param x boolean expression @@ -250,19 +260,9 @@ /** * Create a conjunction of the given restriction predicates. - * A conjunction of zero predicates is true. - * - * @param restriction zero or more restriction predicates - * - * @return and predicate - */ - Predicate and(Predicate... restrictions); - - /** - * Create a conjunction of the given restriction predicates. * A disjunction of zero predicates is false. * - * @param restriction zero or more restriction predicates + * @param restrictions zero or more restriction predicates * * @return or predicate */ Modified: jpa-api/trunk/src/main/java/javax/persistence/criteria/Subquery.java =================================================================== --- jpa-api/trunk/src/main/java/javax/persistence/criteria/Subquery.java 2009-09-17 17:36:24 UTC (rev 17524) +++ jpa-api/trunk/src/main/java/javax/persistence/criteria/Subquery.java 2009-09-17 20:22:44 UTC (rev 17525) @@ -2,6 +2,8 @@ // EJB3 Specification Copyright 2004-2009 Sun Microsystems, Inc. package javax.persistence.criteria; +import java.util.List; + /** * The Subquery interface defines functionality that is * specific to subqueries. @@ -12,12 +14,6 @@ public interface Subquery<T> extends AbstractQuery<T>, Expression<T> { /** - * Return the query of which this is a subquery. - * @return the enclosing query or subquery - */ - AbstractQuery<?> getParent(); - - /** * Specify the item that is to be returned in the query result. * Replaces the previously specified selection, if any. * @param expression expression specifying the item that @@ -63,6 +59,19 @@ */ Subquery<T> groupBy(Expression<?>... grouping); + /** + * Specify the expressions that are used to form groups over + * the subquery results. + * Replaces the previous specified grouping expressions, if any. + * If no grouping expressions are specified, any previously + * added grouping expressions are simply removed. + * This method only overrides the return type of the + * corresponding AbstractQuery method. + * @param grouping list of zero or more grouping expressions + * @return the modified subquery + */ + Subquery<T> groupBy(List<Expression<?>> grouping); + /** * Specify a restriction over the groups of the subquery. * Replaces the previous having restriction(s), if any. @@ -103,67 +112,73 @@ Subquery<T> distinct(boolean distinct); /** - * Return the selection expression. - * @return the item to be returned in the subquery result + * Create a subquery root correlated to a root of the + * enclosing query. + * @param parentRoot a root of the containing query + * @return subquery root */ - Expression<T> getSelection(); - - /** - * Correlate a root of the enclosing query to a root of - * the subquery and return the subquery root. - * @param parentRoot a root of the containing query - * @return subquery root - */ <Y> Root<Y> correlate(Root<Y> parentRoot); /** - * Correlate a join of the enclosing query to a join of - * the subquery and return the subquery join. - * @param parentJoin join target of the containing query - * @return subquery join - */ + * Create a subquery join object correlated to a join object + * of the enclosing query. + * @param parentJoin join object of the containing query + * @return subquery join + */ <X, Y> Join<X, Y> correlate(Join<X, Y> parentJoin); /** - * Correlate a join to a Collection-valued association or - * element collection in the enclosing query to a join of - * the subquery and return the subquery join. - * @param parentCollection join target of the containing query - * @return subquery join + * Create a subquery collection join object correlated to a + * collection join object of the enclosing query. + * @param parentCollection join object of the containing query + * @return subquery join */ <X, Y> CollectionJoin<X, Y> correlate(CollectionJoin<X, Y> parentCollection); /** - * Correlate a join to a Set-valued association or - * element collection in the enclosing query to a join of - * the subquery and return the subquery join. - * @param parentSet join target of the containing query - * @return subquery join + * Create a subquery set join object correlated to a set join + * object of the enclosing query. + * @param parentSet join object of the containing query + * @return subquery join */ <X, Y> SetJoin<X, Y> correlate(SetJoin<X, Y> parentSet); /** - * Correlate a join to a List-valued association or - * element collection in the enclosing query to a join of - * the subquery and return the subquery join. - * @param parentList join target of the containing query - * @return subquery join + * Create a subquery list join object correlated to a list join + * object of the enclosing query. + * @param parentList join object of the containing query + * @return subquery join */ <X, Y> ListJoin<X, Y> correlate(ListJoin<X, Y> parentList); /** - * Correlate a join to a Map-valued association or - * element collection in the enclosing query to a join of - * the subquery and return the subquery join. - * @param parentMap join target of the containing query - * @return subquery join + * Create a subquery map join object correlated to a map join + * object of the enclosing query. + * @param parentMap join object of the containing query + * @return subquery join */ <X, K, V> MapJoin<X, K, V> correlate(MapJoin<X, K, V> parentMap); /** - * Return the joins that have been made from the subquery. - * @return joins made from this type + * Return the query of which this is a subquery. + * @return the enclosing query or subquery */ + AbstractQuery<?> getParent(); + + /** + * Return the selection expression. + * @return the item to be returned in the subquery result + */ + Expression<T> getSelection(); + + /** + * Return the joins that have been made from the subquery. + * Does not include joins from map keys, if any. + * Returns empty set if there are no joins made from the + * subquery. + * Modifications to the set do not affect the query. + * @return joins made from this type + */ java.util.Set<Join<?, ?>> getCorrelatedJoins(); } \ No newline at end of file