/******************************************************************************* | |
* 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); | |
} |