Java tutorial
/******************************************************************************* * Copyright (c) 2008 - 2013 Oracle Corporation. All rights reserved. * * This program and the accompanying materials are made available under the * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0 * which accompanies this distribution. * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html * and the Eclipse Distribution License is available at * http://www.eclipse.org/org/documents/edl-v10.php. * * Contributors: * Linda DeMichiel - Java Persistence 2.1 * Linda DeMichiel - Java Persistence 2.0 * ******************************************************************************/ package javax.persistence.criteria; import java.util.List; import java.util.Set; /** * The <code>CriteriaQuery</code> interface defines functionality that is specific * to top-level queries. * * @param <T> the type of the defined result * * @since Java Persistence 2.0 */ 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. * * <p> 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. * * <pre> * For example: * * CriteriaQuery<String> q = cb.createQuery(String.class); * Root<Order> order = q.from(Order.class); * q.select(order.get("shippingAddress").<String>get("state")); * * CriteriaQuery<Product> q2 = cb.createQuery(Product.class); * q2.select(q2.from(Order.class) * .join("items") * .<Item,Product>join("product")); * * </pre> * @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. * <p> An argument to the multiselect method must not be a tuple- * or array-valued compound selection item. * * <p>The semantics of this method are as follows: * <ul> * <li> * If the type of the criteria query is * <code>CriteriaQuery<Tuple></code> (i.e., a criteria * query object created by either the * <code>createTupleQuery</code> method or by passing a * <code>Tuple</code> class argument to the * <code>createQuery</code> method), a <code>Tuple</code> object * corresponding to the arguments of the <code>multiselect</code> * method, in the specified order, will be instantiated and * returned for each row that results from the query execution. * * <li> If the type of the criteria query is <code>CriteriaQuery<X></code> for * some user-defined class X (i.e., a criteria query object * created by passing a X class argument to the <code>createQuery</code> * method), the arguments to the <code>multiselect</code> method will be * passed to the X constructor and an instance of type X will be * returned for each row. * * <li> If the type of the criteria query is <code>CriteriaQuery<X[]></code> 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 <code>multiselect</code> method, in the * specified order. * * <li> If the type of the criteria query is <code>CriteriaQuery<Object></code> * or if the criteria query was created without specifying a * type, and only a single argument is passed to the <code>multiselect</code> * method, an instance of type <code>Object</code> will be returned for * each row. * * <li> If the type of the criteria query is <code>CriteriaQuery<Object></code> * or if the criteria query was created without specifying a * type, and more than one argument is passed to the <code>multiselect</code> * method, an instance of type <code>Object[]</code> will be instantiated * and returned for each row. The elements of the array will * correspond to the arguments to the <code> multiselect</code> method, * in the specified order. * </ul> * * @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. * * <p> 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 <code>multiselect</code> method. * An element of the list passed to the <code>multiselect</code> method * must not be a tuple- or array-valued compound selection item. * * <p> The semantics of this method are as follows: * <ul> * <li> If the type of the criteria query is <code>CriteriaQuery<Tuple></code> * (i.e., a criteria query object created by either the * <code>createTupleQuery</code> method or by passing a <code>Tuple</code> class argument * to the <code>createQuery</code> method), a <code>Tuple</code> object corresponding to * the elements of the list passed to the <code>multiselect</code> method, * in the specified order, will be instantiated and returned for each * row that results from the query execution. * * <li> If the type of the criteria query is <code>CriteriaQuery<X></code> for * some user-defined class X (i.e., a criteria query object * created by passing a X class argument to the <code>createQuery</code> * method), the elements of the list passed to the <code>multiselect</code> * method will be passed to the X constructor and an instance * of type X will be returned for each row. * * <li> If the type of the criteria query is <code>CriteriaQuery<X[]></code> 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 <code>multiselect</code> method, * in the specified order. * * <li> If the type of the criteria query is <code>CriteriaQuery<Object></code> * or if the criteria query was created without specifying a * type, and the list passed to the <code>multiselect</code> method contains * only a single element, an instance of type <code>Object</code> will be * returned for each row. * * <li> If the type of the criteria query is <code>CriteriaQuery<Object></code> * or if the criteria query was created without specifying a * type, and the list passed to the <code>multiselect</code> method contains * more than one element, an instance of type <code>Object[]</code> will be * instantiated and returned for each row. The elements of the * array will correspond to the elements of the list passed to * the <code>multiselect</code> method, in the specified order. * </ul> * * @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); /** * Modify the query to restrict the query result according * to the specified boolean expression. * Replaces the previously added restriction(s), if any. * This method only overrides the return type of the * corresponding <code>AbstractQuery</code> method. * @param restriction a simple or compound boolean expression * @return the modified query */ CriteriaQuery<T> where(Expression<Boolean> restriction); /** * Modify the query to restrict the query result according * to the conjunction of the specified restriction predicates. * Replaces the previously added restriction(s), if any. * If no restrictions are specified, any previously added * restrictions are simply removed. * This method only overrides the return type of the * corresponding <code>AbstractQuery</code> method. * @param restrictions zero or more restriction predicates * @return the modified query */ CriteriaQuery<T> where(Predicate... restrictions); /** * 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 <code>AbstractQuery</code> method. * @param grouping zero or more grouping expressions * @return the modified query */ 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 <code>AbstractQuery</code> 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. * This method only overrides the return type of the * corresponding <code>AbstractQuery</code> method. * @param restriction a simple or compound boolean expression * @return the modified query */ CriteriaQuery<T> having(Expression<Boolean> restriction); /** * Specify restrictions over the groups of the query * according the conjunction of the specified restriction * predicates. * Replaces the previously added having restriction(s), if any. * If no restrictions are specified, any previously added * restrictions are simply removed. * This method only overrides the return type of the * corresponding <code>AbstractQuery</code> method. * @param restrictions zero or more restriction predicates * @return the modified query */ CriteriaQuery<T> having(Predicate... restrictions); /** * 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 left-to-right sequence of the ordering expressions * determines the precedence, whereby the leftmost has highest * precedence. * @param o zero or more ordering expressions * @return the modified query */ 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. * A false value will cause duplicates to be retained. * If distinct has not been specified, duplicate results must * be retained. * This method only overrides the return type of the * corresponding <code>AbstractQuery</code> method. * @param distinct boolean value specifying whether duplicate * results must be eliminated from the query result or * whether they must be retained * @return the modified query. */ CriteriaQuery<T> distinct(boolean distinct); /** * 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 */ List<Order> getOrderList(); /** * 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(); }