[hibernate-commits] Hibernate SVN: r17525 - jpa-api/trunk/src/main/java/javax/persistence/criteria.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Thu Sep 17 16:22:44 EDT 2009
Author: steve.ebersole at 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
More information about the hibernate-commits
mailing list