https://github.com/javaee/jpa-spec: Java(TM) Persistence API 
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

/*******************************************************************************
 * 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;
import javax.persistence.metamodel.EntityType;


The AbstractQuery interface defines functionality that is common
to both top-level queries and subqueries.
It is not intended to be used directly in query construction.

 All queries must have:
        a set of root entities (which may in turn own joins).

 All queries may have:
        a conjunction of restrictions.

Type parameters:
  • <T> –  the type of the result
Since:Java Persistence 2.0
/**
 * The <code>AbstractQuery</code> interface defines functionality that is common
 * to both top-level queries and subqueries.
 * It is not intended to be used directly in query construction.
 *
 * <p> All queries must have:
 *         a set of root entities (which may in turn own joins).
 * <p> All queries may have:
 *         a conjunction of restrictions.
 *
 * @param <T>  the type of the result
 *
 * @since Java Persistence 2.0
 */
public interface AbstractQuery<T> extends CommonAbstractCriteria {

    
Create and add a query root corresponding to the given entity,
forming a cartesian product with any existing roots.

Params:
  • entityClass –  the entity class
Returns:query root corresponding to the given entity
/**
     * Create and add a query root corresponding to the given entity,
     * forming a cartesian product with any existing roots.
     * @param entityClass  the entity class
     * @return query root corresponding to the given entity
     */
    <X> Root<X> from(Class<X> entityClass);

    
Create and add a query root corresponding to the given entity,
forming a cartesian product with any existing roots.

Params:
  • entity –  metamodel entity representing the entity
               of type X
Returns:query root corresponding to the given entity
/**
     * Create and 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
     * @return query root corresponding to the given entity
     */
    <X> Root<X> from(EntityType<X> entity);

    
Modify the query to restrict the query results according
to the specified boolean expression.
Replaces the previously added restriction(s), if any.

Params:
  • restriction –  a simple or compound boolean expression
Returns:the modified query
/**
     * Modify the query to restrict the query results according
     * to the specified boolean expression.
     * Replaces the previously added restriction(s), if any.
     * @param restriction  a simple or compound boolean expression
     * @return the modified query
     */    
    AbstractQuery<T> where(Expression<Boolean> restriction);

    
Modify the query to restrict the query results 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.

Params:
  • restrictions –  zero or more restriction predicates
Returns:the modified query
/**
     * Modify the query to restrict the query results 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.
     * @param restrictions  zero or more restriction predicates
     * @return the modified query
     */
    AbstractQuery<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.

Params:
  • grouping –  zero or more grouping expressions
Returns:the modified query
/**
     * 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  zero or more grouping expressions
     * @return the modified query
     */
    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.

Params:
  • grouping –  list of zero or more grouping expressions
Returns:the modified query
/**
     * 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.

Params:
  • restriction –  a simple or compound boolean expression
Returns:the modified query
/**
     * Specify a restriction over the groups of the query.
     * Replaces the previous having restriction(s), if any.
     * @param restriction  a simple or compound boolean expression
     * @return the modified query
     */
    AbstractQuery<T> having(Expression<Boolean> restriction);

    
Specify restrictions over the groups of the query
according the conjunction of the specified restriction 
predicates.
Replaces the previously having added restriction(s), if any.
If no restrictions are specified, any previously added
restrictions are simply removed.

Params:
  • restrictions –  zero or more restriction predicates
Returns:the modified query
/**
     * Specify restrictions over the groups of the query
     * according the conjunction of the specified restriction 
     * predicates.
     * Replaces the previously having added restriction(s), if any.
     * If no restrictions are specified, any previously added
     * restrictions are simply removed.
     * @param restrictions  zero or more restriction predicates
     * @return the modified query
     */
    AbstractQuery<T> having(Predicate... restrictions);

    
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.

Params:
  • distinct –  boolean value specifying whether duplicate
       results must be eliminated from the query result or
       whether they must be retained
Returns:the modified query
/**
     * 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.
     * @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
     */
    AbstractQuery<T> distinct(boolean distinct);

    
Return the query roots.  These are the roots that have
been defined for the CriteriaQuery or Subquery itself,
including any subquery roots defined as a result of
correlation. Returns empty set if no roots have been defined.
Modifications to the set do not affect the query.

Returns:the set of query roots
/**
     * Return the query roots.  These are the roots that have
     * been defined for the <code>CriteriaQuery</code> or <code>Subquery</code> itself,
     * including any subquery roots defined as a result of
     * correlation. Returns empty set if no roots have been defined.
     * Modifications to the set do not affect the query.
     * @return the set of query roots
     */   
    Set<Root<?>> getRoots();

    
 Return the selection of the query, or null if no selection
 has been set.
 @return selection item 

/**
     *  Return the selection of the query, or null if no selection
     *  has been set.
     *  @return selection item 
     */
    Selection<T> getSelection();

    
Return a list of the grouping expressions.  Returns empty
list if no grouping expressions have been specified.
Modifications to the list do not affect the query.

Returns:the list of grouping expressions
/**
     * Return a list of the grouping expressions.  Returns empty
     * list if no grouping expressions have been specified.
     * Modifications to the list do not affect the query.
     * @return the list of grouping expressions
     */
    List<Expression<?>> getGroupList();

    
Return the predicate that corresponds to the restriction(s)
over the grouping items, or null if no restrictions have 
been specified.

Returns:having clause predicate
/**
     * Return the predicate that corresponds to the restriction(s)
     * over the grouping items, or null if no restrictions have 
     * been specified.
     * @return having clause predicate
     */
    Predicate getGroupRestriction();

    
Return whether duplicate query results must be eliminated or
retained.

Returns:boolean indicating whether duplicate query results 
        must be eliminated
/**
     * Return whether duplicate query results must be eliminated or
     * retained.
     * @return boolean indicating whether duplicate query results 
     *         must be eliminated
     */
    boolean isDistinct();

    
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.

Returns:result type
/**
     * Return the result type of the query or subquery.  If a result
     * type was specified as an argument to the
     * <code>createQuery</code> or <code>subquery</code> method, that
     * type will be returned.  If the query was created using the
     * <code>createTupleQuery</code> method, the result type is
     * <code>Tuple</code>.  Otherwise, the result type is
     * <code>Object</code>.
     * @return result type
     */
    Class<T> getResultType();  	
}