blob: 786cf827c67e33a827ad69500894b12d5e479ada [file] [log] [blame]
/*******************************************************************************
* Copyright (c) 1998, 2009 Oracle. 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.
*
* The API for this class and its comments are derived from the JPA 2.0 specification
* which is developed under the Java Community Process (JSR 317) and is copyright
* Sun Microsystems, Inc.
*
* Contributors:
* dclarke - Java Persistence API 2.0 Public Draft
* Specification and licensing terms available from
* http://jcp.org/en/jsr/detail?id=317
*
* IMPORTANT: The Criteria API is defined as per the public draft specification
* but is not implemented in the EclipseLink's early access.
*
* EARLY ACCESS - PUBLIC DRAFT
* This is an implementation of an early-draft specification developed under the
* Java Community Process (JCP) and is made available for testing and evaluation
* purposes only. The code is not compatible with any specification of the JCP.
******************************************************************************/
package javax.persistence;
import java.util.Calendar;
import java.util.Date;
import java.util.List;
/**
* Interface for construction of query definitions
*
* @since Java Persistence API 2.0
*/
public interface QueryDefinition {
/**
* Add a query root corresponding to the given entity, forming a cartesian
* product with any existing roots. The domain object that is returned is
* bound as a component of the given query. The argument must be an entity
* class.
*
* @param cls
* - an entity class
* @return DomainObject corresponding to the specified entity class.
*/
DomainObject addRoot(Class cls);
/**
* Add a root derived from a domain object of the containing query
* definition to a query definition used as a subquery. Provides support for
* correlated subqueries. Joins against the resulting domain object do not
* affect the query domain of the containing query. The path expression must
* correspond to an entity class. The path expression must not be a domain
* object of the containing query.
*
* @param path
* - path expression corresponding to the domain object used to
* derive the subquery root.
* @return the subquery DomainObject
*/
DomainObject addSubqueryRoot(PathExpression path);
/**
* Specify the objects / values to be returned. Replaces the previous select
* list, if any. If no select items are specified and there is only one
* query root, the root entity is assumed to be the result.
*
* @param selectItems
* - one or more SelectItem instances
* @return the modified query definition instance
*/
QueryDefinition select(SelectItem... selectItems);
/**
* Specify the objects / values to be returned. Replaces the previous select
* list, if any. If no select items are specified and there is only one
* query root, the root entity is assumed to be the result.
*
* @param selectItemList
* - a list containing one or more SelectItem instances
* @return the modified query definition instance
*/
QueryDefinition select(List<SelectItem> selectItemList);
/**
* Specify the objects / values to be returned. Duplicate results will be
* eliminated. Replaces the previous select list, if any. If no select items
* are specified and there is only one query root, the root entity is
* assumed to be the result.
*
* @param selectItems
* - one or more SelectItem instances
* @return the modified query definition instance
*/
QueryDefinition selectDistinct(SelectItem... selectItems);
/**
* Specify the objects / values to be returned. Duplicate results will be
* eliminated. Replaces the previous select list, if any. If no select items
* are specified, and there is only one query root, the root entity is
* assumed to be the result. is assumed to be the result.
*
* @param selectItemList
* - a list containing one or more SelectItem instances
* @return the modified query definition instance
*/
QueryDefinition selectDistinct(List<SelectItem> selectItemList);
/**
* Modifies the query definition to restrict the result of the query
* according to the specified predicate. Replaces the previously added
* restriction(s), if any.
*
* @param predicate
* - a simple or compound conditional predicate
* @return the modified QueryDefinition instance
*/
QueryDefinition where(Predicate predicate);
/**
* Specify the items of the select list that are used in ordering the query
* results. Replaces the previous order-by list, if any.
*
* @param orderByItems
* - one or more OrderByItem instances
* @return the modified QueryDefinition instance
*/
QueryDefinition orderBy(OrderByItem... orderByItems);
/**
* Specify the items of the select list that are used in ordering the query
* results. Replaces the previous order-by list, if any.
*
* @param orderByItemList
* - a list containing one or more OrderByItem instances
* @return the modified QueryDefinition instance
*/
QueryDefinition orderBy(List<OrderByItem> orderByItemList);
/**
* Specify the items that are used to form groups over the query results.
* Replaces the previous group-by list, if any.
*
* @param pathExprs
* @return the modified QueryDefinition instance
*/
QueryDefinition groupBy(PathExpression... pathExprs);
/**
* Specify the items that are used to form groups over the query results.
* Replaces the previous group-by list, if any.
*
* @param pathExprList
* @return the modified QueryDefinition instance
*/
QueryDefinition groupBy(List<PathExpression> pathExprList);
/**
* Specify the restrictions over the groups of a query. Replaces the
* previous having restriction(s), if any.
*
* @param predicate
* @return the modified QueryDefinition Instance
*/
QueryDefinition having(Predicate predicate);
/**
* Specify that a constructor for the given class is to be applied to the
* corresponding query results after the query is executed. The class must
* have a constructor that accepts the Java argument types corresponding to
* the given select items.
*
* @param cls
* - a class with the correponding constructor
* @param args
* - select items that correspond to result types that are valid
* as arguments to the constructor
* @result SelectItem instance representing the constructor
*/
SelectItem newInstance(Class cls, SelectItem... args);
/**
* Use the query definition instance as a subquery in an exists predicate.
*
* @return the resulting predicate
*/
Predicate exists();
/**
* Use the query definition object in a subquery in an all expression.
*
* @return the resulting Subquery
*/
Subquery all();
/**
* Use the query definition object in a subquery in an any expression.
*
* @return the resulting Subquery
*/
Subquery any();
/**
* Use the query definition object in a subquery in a some expression.
*
* @return the resulting Subquery
*/
Subquery some();
/**
* Create an empty general case expression. A general case expression is of
* the form:
*
* generalCase() .when(conditional-predicate).then(scalar-expression)
* .when(conditional-predicate).then(scalar-expression) ...
* .elseCase(scalar-expression)
*
* @return empty general case expression
*/
CaseExpression generalCase();
/**
* Create a simple case expression with the given case operand. A simple
* case expression is of the form:
*
* simpleCase(case-operand) .when(scalar-expression).then(scalar-expression)
* .when(scalar-expression).then(scalar-expression) ...
* .elseCase(scalar-expression)
*
* @param caseOperand
* - expression used for testing against the when scalar
* expressions
* @return case expression with the given case operand
*/
CaseExpression simpleCase(Expression caseOperand);
/**
* Create a simple case expression with the given case operand. A simple
* case expression is of the form:
*
* simpleCase(case-operand) .when(scalar-expression).then(scalar-expression)
* .when(scalar-expression).then(scalar-expression) ...
* .elseCase(scalar-expression)
*
* @param caseOperand
* - numeric value used for testing against the when scalar
* expressions
* @return case expression with the given case operand
*/
CaseExpression simpleCase(Number caseOperand);
/**
* Create a simple case expression with the given case operand. A simple
* case expression is of the form:
*
* simpleCase(case-operand) .when(scalar-expression).then(scalar-expression)
* .when(scalar-expression).then(scalar-expression) ...
* .elseCase(scalar-expression)
*
* @param caseOperand
* - value used for testing against the when scalar expressions
* @return case expression with the given case operand
*/
CaseExpression simpleCase(String caseOperand);
/**
* Create a simple case expression with the given case operand. A simple
* case expression is of the form:
*
* simpleCase(case-operand) .when(scalar-expression).then(scalar-expression)
* .when(scalar-expression).then(scalar-expression) ...
* .elseCase(scalar-expression)
*
* @param caseOperand
* - value used for testing against the when scalar expressions
* @return case expression with the given case operand
*/
CaseExpression simpleCase(Date caseOperand);
/**
* Create a simple case expression with the given case operand. A simple
* case expression is of the form:
*
* simpleCase(case-operand) .when(scalar-expression).then(scalar-expression)
* .when(scalar-expression).then(scalar-expression) ...
* .elseCase(scalar-expression)
*
* @param caseOperand
* - value used for testing against the when scalar expressions
* @return case expression with the given case operand
*/
CaseExpression simpleCase(Calendar caseOperand);
/**
* Create a simple case expression with the given case operand. A simple
* case expression is of the form:
*
* simpleCase(case-operand) .when(scalar-expression).then(scalar-expression)
* .when(scalar-expression).then(scalar-expression) ...
* .elseCase(scalar-expression)
*
* @param caseOperand
* - value used for testing against the when scalar expressions
* @return case expression with the given case operand
*/
CaseExpression simpleCase(Class caseOperand);
/**
* Create a simple case expression with the given case operand. A simple
* case expression is of the form:
*
* simpleCase(case-operand) .when(scalar-expression).then(scalar-expression)
* .when(scalar-expression).then(scalar-expression) ...
* .elseCase(scalar-expression)
*
* @param caseOperand
* - value used for testing against the when scalar expressions
* @return case expression with the given case operand
*/
CaseExpression simpleCase(Enum<?> caseOperand);
/**
* coalesce This is equivalent to a case expression that returns null if all
* its arguments evaluate to null, and the value of its first non-null
* argument otherwise.
*
* @param exp
* - expressions to be used for testing against null
* @return Expression corresponding to the given coalesce expression
*/
Expression coalesce(Expression... exp);
/**
* coalesce This is equivalent to a case expression that returns null if all
* its arguments evaluate to null, and the value of its first non-null
* argument otherwise.
*
* @param exp
* - expressions to be used for testing against null
* @return Expression corresponding to the given coalesce expression
*/
Expression coalesce(String... exp);
/**
* coalesce This is equivalent to a case expression that returns null if all
* its arguments evaluate to null, and the value of its first non-null
* argument otherwise.
*
* @param exp
* - expressions to be used for testing against null
* @return Expression corresponding to the given coalesce expression
*/
Expression coalesce(Date... exp);
/**
* coalesce This is equivalent to a case expression that returns null if all
* its arguments evaluate to null, and the value of its first non-null
* argument otherwise.
*
* @param exp
* - expressions to be used for testing against null
* @return Expression corresponding to the given coalesce expression
*/
Expression coalesce(Calendar... exp);
/**
* nullif This is equivalent to a case expression that tests whether its
* arguments are equal, returning null if they are and the value of the
* first expression if they are not.
*
* @param exp1
* @param exp2
* @return Expression corresponding to the given nullif expression
*/
Expression nullif(Expression exp1, Expression exp2);
/**
* nullif This is equivalent to a case expression that tests whether its
* arguments are equal, returning null if they are and the value of the
* first expression if they are not.
*
* @param arg1
* @param arg2
* @return Expression corresponding to the given nullif expression
*/
Expression nullif(Number arg1, Number arg2);
/**
* nullif This is equivalent to a case expression that tests whether its
* arguments are equal, returning null if they are and the value of the
* first expression if they are not.
*
* @param arg1
* @param arg2
* @return Expression corresponding to the given nullif expression
*/
Expression nullif(String arg1, String arg2);
/**
* nullif This is equivalent to a case expression that tests whether its
* arguments are equal, returning null if they are and the value of the
* first expression if they are not.
*
* @param arg1
* @param arg2
* @return Expression corresponding to the given nullif expression
*/
Expression nullif(Date arg1, Date arg2);
/**
* nullif This is equivalent to a case expression that tests whether its
* arguments are equal, returning null if they are and the value of the
* first expression if they are not.
*
* @param arg1
* @param arg2
* @return Expression corresponding to the given nullif expression
*/
Expression nullif(Calendar arg1, Calendar arg2);
/**
* nullif This is equivalent to a case expression that tests whether its
* arguments are equal, returning null if they are and the value of the
* first expression if they are not.
*
* @param arg1
* @param arg2
* @return Expression corresponding to the given nullif expression
*/
Expression nullif(Class arg1, Class arg2);
/**
* nullif This is equivalent to a case expression that tests whether its
* arguments are equal, returning null if they are and the value of the
* first expression if they are not.
*
* @param arg1
* @param arg2
* @return Expression corresponding to the given nullif expression
*/
Expression nullif(Enum<?> arg1, Enum<?> arg2);
/**
* Create a predicate value from the given boolean.
*
* @param b
* boolean value
* @return a true or false predicate
*/
Predicate predicate(boolean b);
/**
* Create an Expression corresponding to the current time on the database
* server at the time of query execution.
*
* @return the corresponding Expression
*/
Expression currentTime();
/**
* Create an Expression corresponding to the current date on the database
* server at the time of query execution.
*
* @return the corresponding Expression
*/
Expression currentDate();
/**
* Create an Expression corresponding to the current timestamp on the
* database server at the time of query execution.
*
* @return the corresponding Expression
*/
Expression currentTimestamp();
/**
* Create an Expression corresponding to a String value.
*
* @param s
* - string value
* @return the corresponding Expression literal
*/
Expression literal(String s);
/**
* Create an Expression corresponding to a numeric value.
*
* @param n
* - numeric value
* @return the corresponding Expression literal
*/
Expression literal(Number n);
/**
* Create an Expression corresponding to a boolean value.
*
* @param b
* - boolean value
* @return the corresponding Expression literal
*/
Expression literal(boolean b);
/**
* Create an Expression corresponding to a Calendar value.
*
* @param c
* - Calendar value
* @return the corresponding Expression literal
*/
Expression literal(Calendar c);
/**
* Create an Expression corresponding to a Date value.
*
* @param d
* - Date value
* @return the corresponding Expression literal
*/
Expression literal(Date d);
/**
* Create an Expression corresponding to a character value.
*
* @param character
* value
* @return the corresponding Expression literal
*/
Expression literal(char c);
/**
* Create an Expression corresponding to an entity class.
*
* @param cls
* - entity class
* @return the corresponding Expression literal
*/
Expression literal(Class cls);
/**
* Create an Expression corresponding to an enum.
*
* @param e
* - enum
* @return the corresponding Expression literal
*/
Expression literal(Enum<?> e);
/**
* Create an Expression corresponding to a null value.
*
* @return the corresponding Expression literal
*/
Expression nullLiteral();
/**
* Specify use of a parameter of the given name.
*
* @param parameter
* name
* @return an Expression corresponding to a named parameter
*/
Expression param(String name);
}