javax.persistence.criteria.Subquery Maven / Gradle / Ivy

Go to download
package javax.persistence.criteria;

import java.util.List;
import java.util.Set;

/**
 * The Subquery interface defines functionality that is specific to subqueries.
 * 
 * A subquery has an expression as its selection item.
 * 
 * @param 
 *            the type of the selection item.
 */
public interface Subquery extends AbstractQuery, Expression {

	/**
	 * Create a subquery collection join object correlated to a collection join object of the enclosing query.
	 * 
	 * @param parentCollection
	 *            join object of the containing query
	 * @param 
	 *            the source type of the join
	 * @param 
	 *            the element type of the target Collection
	 * @return subquery join
	 */
	 CollectionJoin correlate(CollectionJoin parentCollection);

	/**
	 * Create a subquery join object correlated to a join object of the enclosing query.
	 * 
	 * @param parentJoin
	 *            join object of the containing query
	 * @param 
	 *            the source type of the join
	 * @param 
	 *            the element type of the target Collection
	 * @return subquery join
	 */
	 Join correlate(Join parentJoin);

	/**
	 * Create a subquery list join object correlated to a list join object of the enclosing query.
	 * 
	 * @param parentList
	 *            join object of the containing query
	 * @param 
	 *            the source type of the join
	 * @param 
	 *            the element type of the target Collection
	 * @return subquery join
	 */
	 ListJoin correlate(ListJoin parentList);

	/**
	 * Create a subquery map join object correlated to a map join object of the enclosing query.
	 * 
	 * @param parentMap
	 *            join object of the containing query
	 * @param 
	 *            the source type of the join
	 * @param 
	 *            the type of the target Map key
	 * @param 
	 *            the type of the target Map value
	 * @return subquery join
	 */
	 MapJoin correlate(MapJoin parentMap);

	/**
	 * Create a subquery root correlated to a root of the enclosing query.
	 * 
	 * @param parentRoot
	 *            a root of the containing query
	 * @param 
	 *            the type of the root
	 * @return subquery root
	 */
	 Root correlate(Root parentRoot);

	/**
	 * Create a subquery set join object correlated to a set join object of the enclosing query.
	 * 
	 * @param parentSet
	 *            join object of the containing query
	 * @param 
	 *            the source type of the join
	 * @param 
	 *            the element type of the target Collection
	 * @return subquery join
	 */
	 SetJoin correlate(SetJoin parentSet);

	/**
	 * 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 AbstractQuery method.
	 * 
	 * @param distinct
	 *            boolean value specifying whether duplicate results must be eliminated from the subquery result or whether they must be
	 *            retained
	 * @return the modified subquery.
	 */
	@Override
	Subquery distinct(boolean distinct);

	/**
	 * Return the correlated joins of the subquery (Join objects obtained as a result of the use of the correlate method). Returns empty set
	 * if the subquery has no correlated joins. Modifications to the set do not affect the query.
	 * 
	 * @return the correlated joins of the subquery
	 */
	Set> getCorrelatedJoins();

	/**
	 * 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
	 */
	@Override
	Expression getSelection();

	/**
	 * 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
	 *            zero or more grouping expressions
	 * @return the modified subquery
	 */
	@Override
	Subquery 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
	 */
	@Override
	Subquery groupBy(List> grouping);

	/**
	 * Specify a restriction over the groups of the subquery. Replaces the previous having restriction(s), if any. This method only
	 * overrides the return type of the corresponding AbstractQuery method.
	 * 
	 * @param restriction
	 *            a simple or compound boolean expression
	 * @return the modified subquery
	 */
	@Override
	Subquery having(Expression restriction);

	/**
	 * Specify restrictions over the groups of the subquery 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 AbstractQuery method.
	 * 
	 * @param restrictions
	 *            zero or more restriction predicates
	 * @return the modified subquery
	 */
	@Override
	Subquery having(Predicate... restrictions);

	/**
	 * Specify the item that is to be returned as the subquery result. Replaces the previously specified selection, if any.
	 * 
	 * @param expression
	 *            expression specifying the item that is to be returned as the subquery result
	 * @return the modified subquery
	 */
	Subquery select(Expression expression);

	/**
	 * Modify the subquery to restrict the 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 AbstractQuery method.
	 * 
	 * @param restriction
	 *            a simple or compound boolean expression
	 * @return the modified subquery
	 */
	@Override
	Subquery where(Expression restriction);

	/**
	 * Modify the subquery to restrict the 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 AbstractQuery method.
	 * 
	 * @param restrictions
	 *            zero or more restriction predicates
	 * @return the modified subquery
	 */
	@Override
	Subquery where(Predicate... restrictions);
}