/*******************************************************************************
* 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.math.
BigDecimal;
import java.math.
BigInteger;
import java.util.
Collection;
import java.util.
Map;
import java.util.
Set;
import javax.persistence.
Tuple;
/**
* Used to construct criteria queries, compound selections,
* expressions, predicates, orderings.
*
* <p> Note that <code>Predicate</code> is used instead of <code>Expression<Boolean></code>
* in this API in order to work around the fact that Java
* generics are not compatible with varags.
*
* @since Java Persistence 2.0
*/
public interface
CriteriaBuilder {
/**
* Create a <code>CriteriaQuery</code> object.
* @return criteria query object
*/
CriteriaQuery<
Object>
createQuery();
/**
* Create a <code>CriteriaQuery</code> object with the specified result
* type.
* @param resultClass type of the query result
* @return criteria query object
*/
<T>
CriteriaQuery<T>
createQuery(
Class<T>
resultClass);
/**
* Create a <code>CriteriaQuery</code> object that returns a tuple of
* objects as its result.
* @return criteria query object
*/
CriteriaQuery<
Tuple>
createTupleQuery();
// methods to construct queries for bulk updates and deletes:
/**
* Create a <code>CriteriaUpdate</code> query object to perform a bulk update operation.
* @param targetEntity target type for update operation
* @return the query object
* @since Java Persistence 2.1
*/
<T>
CriteriaUpdate<T>
createCriteriaUpdate(
Class<T>
targetEntity);
/**
* Create a <code>CriteriaDelete</code> query object to perform a bulk delete operation.
* @param targetEntity target type for delete operation
* @return the query object
* @since Java Persistence 2.1
*/
<T>
CriteriaDelete<T>
createCriteriaDelete(
Class<T>
targetEntity);
// selection construction methods:
/**
* Create a selection item corresponding to a constructor.
* This method is used to specify a constructor that will be
* applied to the results of the query execution. If the
* constructor is for an entity class, the resulting entities
* will be in the new state after the query is executed.
* @param resultClass class whose instance is to be constructed
* @param selections arguments to the constructor
* @return compound selection item
* @throws IllegalArgumentException if an argument is a
* tuple- or array-valued selection item
*/
<Y>
CompoundSelection<Y>
construct(
Class<Y>
resultClass,
Selection<?>...
selections);
/**
* Create a tuple-valued selection item.
* @param selections selection items
* @return tuple-valued compound selection
* @throws IllegalArgumentException if an argument is a
* tuple- or array-valued selection item
*/
CompoundSelection<
Tuple>
tuple(
Selection<?>...
selections);
/**
* Create an array-valued selection item.
* @param selections selection items
* @return array-valued compound selection
* @throws IllegalArgumentException if an argument is a
* tuple- or array-valued selection item
*/
CompoundSelection<
Object[]>
array(
Selection<?>...
selections);
//ordering:
/**
* Create an ordering by the ascending value of the expression.
* @param x expression used to define the ordering
* @return ascending ordering corresponding to the expression
*/
Order asc(
Expression<?>
x);
/**
* Create an ordering by the descending value of the expression.
* @param x expression used to define the ordering
* @return descending ordering corresponding to the expression
*/
Order desc(
Expression<?>
x);
//aggregate functions:
/**
* Create an aggregate expression applying the avg operation.
* @param x expression representing input value to avg operation
* @return avg expression
*/
<N extends
Number>
Expression<
Double>
avg(
Expression<N>
x);
/**
* Create an aggregate expression applying the sum operation.
* @param x expression representing input value to sum operation
* @return sum expression
*/
<N extends
Number>
Expression<N>
sum(
Expression<N>
x);
/**
* Create an aggregate expression applying the sum operation to an
* Integer-valued expression, returning a Long result.
* @param x expression representing input value to sum operation
* @return sum expression
*/
Expression<
Long>
sumAsLong(
Expression<
Integer>
x);
/**
* Create an aggregate expression applying the sum operation to a
* Float-valued expression, returning a Double result.
* @param x expression representing input value to sum operation
* @return sum expression
*/
Expression<
Double>
sumAsDouble(
Expression<
Float>
x);
/**
* Create an aggregate expression applying the numerical max
* operation.
* @param x expression representing input value to max operation
* @return max expression
*/
<N extends
Number>
Expression<N>
max(
Expression<N>
x);
/**
* Create an aggregate expression applying the numerical min
* operation.
* @param x expression representing input value to min operation
* @return min expression
*/
<N extends
Number>
Expression<N>
min(
Expression<N>
x);
/**
* Create an aggregate expression for finding the greatest of
* the values (strings, dates, etc).
* @param x expression representing input value to greatest
* operation
* @return greatest expression
*/
<X extends
Comparable<? super X>>
Expression<X>
greatest(
Expression<X>
x);
/**
* Create an aggregate expression for finding the least of
* the values (strings, dates, etc).
* @param x expression representing input value to least
* operation
* @return least expression
*/
<X extends
Comparable<? super X>>
Expression<X>
least(
Expression<X>
x);
/**
* Create an aggregate expression applying the count operation.
* @param x expression representing input value to count
* operation
* @return count expression
*/
Expression<
Long>
count(
Expression<?>
x);
/**
* Create an aggregate expression applying the count distinct
* operation.
* @param x expression representing input value to
* count distinct operation
* @return count distinct expression
*/
Expression<
Long>
countDistinct(
Expression<?>
x);
//subqueries:
/**
* Create a predicate testing the existence of a subquery result.
* @param subquery subquery whose result is to be tested
* @return exists predicate
*/
Predicate exists(
Subquery<?>
subquery);
/**
* Create an all expression over the subquery results.
* @param subquery subquery
* @return all expression
*/
<Y>
Expression<Y>
all(
Subquery<Y>
subquery);
/**
* Create a some expression over the subquery results.
* This expression is equivalent to an <code>any</code> expression.
* @param subquery subquery
* @return some expression
*/
<Y>
Expression<Y>
some(
Subquery<Y>
subquery);
/**
* Create an any expression over the subquery results.
* This expression is equivalent to a <code>some</code> expression.
* @param subquery subquery
* @return any expression
*/
<Y>
Expression<Y>
any(
Subquery<Y>
subquery);
//boolean functions:
/**
* Create a conjunction of the given boolean expressions.
* @param x boolean expression
* @param y boolean expression
* @return and predicate
*/
Predicate and(
Expression<
Boolean>
x,
Expression<
Boolean>
y);
/**
* Create a conjunction of the given restriction predicates.
* A conjunction of zero predicates is true.
* @param restrictions zero or more restriction predicates
* @return and predicate
*/
Predicate and(
Predicate...
restrictions);
/**
* Create a disjunction of the given boolean expressions.
* @param x boolean expression
* @param y boolean expression
* @return or predicate
*/
Predicate or(
Expression<
Boolean>
x,
Expression<
Boolean>
y);
/**
* Create a disjunction of the given restriction predicates.
* A disjunction of zero predicates is false.
* @param restrictions zero or more restriction predicates
* @return or predicate
*/
Predicate or(
Predicate...
restrictions);
/**
* Create a negation of the given restriction.
* @param restriction restriction expression
* @return not predicate
*/
Predicate not(
Expression<
Boolean>
restriction);
/**
* Create a conjunction (with zero conjuncts).
* A conjunction with zero conjuncts is true.
* @return and predicate
*/
Predicate conjunction();
/**
* Create a disjunction (with zero disjuncts).
* A disjunction with zero disjuncts is false.
* @return or predicate
*/
Predicate disjunction();
//turn Expression<Boolean> into a Predicate
//useful for use with varargs methods
/**
* Create a predicate testing for a true value.
* @param x expression to be tested
* @return predicate
*/
Predicate isTrue(
Expression<
Boolean>
x);
/**
* Create a predicate testing for a false value.
* @param x expression to be tested
* @return predicate
*/
Predicate isFalse(
Expression<
Boolean>
x);
//null tests:
/**
* Create a predicate to test whether the expression is null.
* @param x expression
* @return is-null predicate
*/
Predicate isNull(
Expression<?>
x);
/**
* Create a predicate to test whether the expression is not null.
* @param x expression
* @return is-not-null predicate
*/
Predicate isNotNull(
Expression<?>
x);
//equality:
/**
* Create a predicate for testing the arguments for equality.
* @param x expression
* @param y expression
* @return equality predicate
*/
Predicate equal(
Expression<?>
x,
Expression<?>
y);
/**
* Create a predicate for testing the arguments for equality.
* @param x expression
* @param y object
* @return equality predicate
*/
Predicate equal(
Expression<?>
x,
Object y);
/**
* Create a predicate for testing the arguments for inequality.
* @param x expression
* @param y expression
* @return inequality predicate
*/
Predicate notEqual(
Expression<?>
x,
Expression<?>
y);
/**
* Create a predicate for testing the arguments for inequality.
* @param x expression
* @param y object
* @return inequality predicate
*/
Predicate notEqual(
Expression<?>
x,
Object y);
//comparisons for generic (non-numeric) operands:
/**
* Create a predicate for testing whether the first argument is
* greater than the second.
* @param x expression
* @param y expression
* @return greater-than predicate
*/
<Y extends
Comparable<? super Y>>
Predicate greaterThan(
Expression<? extends Y>
x,
Expression<? extends Y>
y);
/**
* Create a predicate for testing whether the first argument is
* greater than the second.
* @param x expression
* @param y value
* @return greater-than predicate
*/
<Y extends
Comparable<? super Y>>
Predicate greaterThan(
Expression<? extends Y>
x, Y
y);
/**
* Create a predicate for testing whether the first argument is
* greater than or equal to the second.
* @param x expression
* @param y expression
* @return greater-than-or-equal predicate
*/
<Y extends
Comparable<? super Y>>
Predicate greaterThanOrEqualTo(
Expression<? extends Y>
x,
Expression<? extends Y>
y);
/**
* Create a predicate for testing whether the first argument is
* greater than or equal to the second.
* @param x expression
* @param y value
* @return greater-than-or-equal predicate
*/
<Y extends
Comparable<? super Y>>
Predicate greaterThanOrEqualTo(
Expression<? extends Y>
x, Y
y);
/**
* Create a predicate for testing whether the first argument is
* less than the second.
* @param x expression
* @param y expression
* @return less-than predicate
*/
<Y extends
Comparable<? super Y>>
Predicate lessThan(
Expression<? extends Y>
x,
Expression<? extends Y>
y);
/**
* Create a predicate for testing whether the first argument is
* less than the second.
* @param x expression
* @param y value
* @return less-than predicate
*/
<Y extends
Comparable<? super Y>>
Predicate lessThan(
Expression<? extends Y>
x, Y
y);
/**
* Create a predicate for testing whether the first argument is
* less than or equal to the second.
* @param x expression
* @param y expression
* @return less-than-or-equal predicate
*/
<Y extends
Comparable<? super Y>>
Predicate lessThanOrEqualTo(
Expression<? extends Y>
x,
Expression<? extends Y>
y);
/**
* Create a predicate for testing whether the first argument is
* less than or equal to the second.
* @param x expression
* @param y value
* @return less-than-or-equal predicate
*/
<Y extends
Comparable<? super Y>>
Predicate lessThanOrEqualTo(
Expression<? extends Y>
x, Y
y);
/**
* Create a predicate for testing whether the first argument is
* between the second and third arguments in value.
* @param v expression
* @param x expression
* @param y expression
* @return between predicate
*/
<Y extends
Comparable<? super Y>>
Predicate between(
Expression<? extends Y>
v,
Expression<? extends Y>
x,
Expression<? extends Y>
y);
/**
* Create a predicate for testing whether the first argument is
* between the second and third arguments in value.
* @param v expression
* @param x value
* @param y value
* @return between predicate
*/
<Y extends
Comparable<? super Y>>
Predicate between(
Expression<? extends Y>
v, Y
x, Y
y);
//comparisons for numeric operands:
/**
* Create a predicate for testing whether the first argument is
* greater than the second.
* @param x expression
* @param y expression
* @return greater-than predicate
*/
Predicate gt(
Expression<? extends
Number>
x,
Expression<? extends
Number>
y);
/**
* Create a predicate for testing whether the first argument is
* greater than the second.
* @param x expression
* @param y value
* @return greater-than predicate
*/
Predicate gt(
Expression<? extends
Number>
x,
Number y);
/**
* Create a predicate for testing whether the first argument is
* greater than or equal to the second.
* @param x expression
* @param y expression
* @return greater-than-or-equal predicate
*/
Predicate ge(
Expression<? extends
Number>
x,
Expression<? extends
Number>
y);
/**
* Create a predicate for testing whether the first argument is
* greater than or equal to the second.
* @param x expression
* @param y value
* @return greater-than-or-equal predicate
*/
Predicate ge(
Expression<? extends
Number>
x,
Number y);
/**
* Create a predicate for testing whether the first argument is
* less than the second.
* @param x expression
* @param y expression
* @return less-than predicate
*/
Predicate lt(
Expression<? extends
Number>
x,
Expression<? extends
Number>
y);
/**
* Create a predicate for testing whether the first argument is
* less than the second.
* @param x expression
* @param y value
* @return less-than predicate
*/
Predicate lt(
Expression<? extends
Number>
x,
Number y);
/**
* Create a predicate for testing whether the first argument is
* less than or equal to the second.
* @param x expression
* @param y expression
* @return less-than-or-equal predicate
*/
Predicate le(
Expression<? extends
Number>
x,
Expression<? extends
Number>
y);
/**
* Create a predicate for testing whether the first argument is
* less than or equal to the second.
* @param x expression
* @param y value
* @return less-than-or-equal predicate
*/
Predicate le(
Expression<? extends
Number>
x,
Number y);
//numerical operations:
/**
* Create an expression that returns the arithmetic negation
* of its argument.
* @param x expression
* @return arithmetic negation
*/
<N extends
Number>
Expression<N>
neg(
Expression<N>
x);
/**
* Create an expression that returns the absolute value
* of its argument.
* @param x expression
* @return absolute value
*/
<N extends
Number>
Expression<N>
abs(
Expression<N>
x);
/**
* Create an expression that returns the sum
* of its arguments.
* @param x expression
* @param y expression
* @return sum
*/
<N extends
Number>
Expression<N>
sum(
Expression<? extends N>
x,
Expression<? extends N>
y);
/**
* Create an expression that returns the sum
* of its arguments.
* @param x expression
* @param y value
* @return sum
*/
<N extends
Number>
Expression<N>
sum(
Expression<? extends N>
x, N
y);
/**
* Create an expression that returns the sum
* of its arguments.
* @param x value
* @param y expression
* @return sum
*/
<N extends
Number>
Expression<N>
sum(N
x,
Expression<? extends N>
y);
/**
* Create an expression that returns the product
* of its arguments.
* @param x expression
* @param y expression
* @return product
*/
<N extends
Number>
Expression<N>
prod(
Expression<? extends N>
x,
Expression<? extends N>
y);
/**
* Create an expression that returns the product
* of its arguments.
* @param x expression
* @param y value
* @return product
*/
<N extends
Number>
Expression<N>
prod(
Expression<? extends N>
x, N
y);
/**
* Create an expression that returns the product
* of its arguments.
* @param x value
* @param y expression
* @return product
*/
<N extends
Number>
Expression<N>
prod(N
x,
Expression<? extends N>
y);
/**
* Create an expression that returns the difference
* between its arguments.
* @param x expression
* @param y expression
* @return difference
*/
<N extends
Number>
Expression<N>
diff(
Expression<? extends N>
x,
Expression<? extends N>
y);
/**
* Create an expression that returns the difference
* between its arguments.
* @param x expression
* @param y value
* @return difference
*/
<N extends
Number>
Expression<N>
diff(
Expression<? extends N>
x, N
y);
/**
* Create an expression that returns the difference
* between its arguments.
* @param x value
* @param y expression
* @return difference
*/
<N extends
Number>
Expression<N>
diff(N
x,
Expression<? extends N>
y);
/**
* Create an expression that returns the quotient
* of its arguments.
* @param x expression
* @param y expression
* @return quotient
*/
Expression<
Number>
quot(
Expression<? extends
Number>
x,
Expression<? extends
Number>
y);
/**
* Create an expression that returns the quotient
* of its arguments.
* @param x expression
* @param y value
* @return quotient
*/
Expression<
Number>
quot(
Expression<? extends
Number>
x,
Number y);
/**
* Create an expression that returns the quotient
* of its arguments.
* @param x value
* @param y expression
* @return quotient
*/
Expression<
Number>
quot(
Number x,
Expression<? extends
Number>
y);
/**
* Create an expression that returns the modulus
* of its arguments.
* @param x expression
* @param y expression
* @return modulus
*/
Expression<
Integer>
mod(
Expression<
Integer>
x,
Expression<
Integer>
y);
/**
* Create an expression that returns the modulus
* of its arguments.
* @param x expression
* @param y value
* @return modulus
*/
Expression<
Integer>
mod(
Expression<
Integer>
x,
Integer y);
/**
* Create an expression that returns the modulus
* of its arguments.
* @param x value
* @param y expression
* @return modulus
*/
Expression<
Integer>
mod(
Integer x,
Expression<
Integer>
y);
/**
* Create an expression that returns the square root
* of its argument.
* @param x expression
* @return square root
*/
Expression<
Double>
sqrt(
Expression<? extends
Number>
x);
//typecasts:
/**
* Typecast. Returns same expression object.
* @param number numeric expression
* @return Expression<Long>
*/
Expression<
Long>
toLong(
Expression<? extends
Number>
number);
/**
* Typecast. Returns same expression object.
* @param number numeric expression
* @return Expression<Integer>
*/
Expression<
Integer>
toInteger(
Expression<? extends
Number>
number);
/**
* Typecast. Returns same expression object.
* @param number numeric expression
* @return Expression<Float>
*/
Expression<
Float>
toFloat(
Expression<? extends
Number>
number);
/**
* Typecast. Returns same expression object.
* @param number numeric expression
* @return Expression<Double>
*/
Expression<
Double>
toDouble(
Expression<? extends
Number>
number);
/**
* Typecast. Returns same expression object.
* @param number numeric expression
* @return Expression<BigDecimal>
*/
Expression<
BigDecimal>
toBigDecimal(
Expression<? extends
Number>
number);
/**
* Typecast. Returns same expression object.
* @param number numeric expression
* @return Expression<BigInteger>
*/
Expression<
BigInteger>
toBigInteger(
Expression<? extends
Number>
number);
/**
* Typecast. Returns same expression object.
* @param character expression
* @return Expression<String>
*/
Expression<
String>
toString(
Expression<
Character>
character);
//literals:
/**
* Create an expression for a literal.
* @param value value represented by the expression
* @return expression literal
* @throws IllegalArgumentException if value is null
*/
<T>
Expression<T>
literal(T
value);
/**
* Create an expression for a null literal with the given type.
* @param resultClass type of the null literal
* @return null expression literal
*/
<T>
Expression<T>
nullLiteral(
Class<T>
resultClass);
//parameters:
/**
* Create a parameter expression.
* @param paramClass parameter class
* @return parameter expression
*/
<T>
ParameterExpression<T>
parameter(
Class<T>
paramClass);
/**
* Create a parameter expression with the given name.
* @param paramClass parameter class
* @param name name that can be used to refer to
* the parameter
* @return parameter expression
*/
<T>
ParameterExpression<T>
parameter(
Class<T>
paramClass,
String name);
//collection operations:
/**
* Create a predicate that tests whether a collection is empty.
* @param collection expression
* @return is-empty predicate
*/
<C extends
Collection<?>>
Predicate isEmpty(
Expression<C>
collection);
/**
* Create a predicate that tests whether a collection is
* not empty.
* @param collection expression
* @return is-not-empty predicate
*/
<C extends
Collection<?>>
Predicate isNotEmpty(
Expression<C>
collection);
/**
* Create an expression that tests the size of a collection.
* @param collection expression
* @return size expression
*/
<C extends java.util.
Collection<?>>
Expression<
Integer>
size(
Expression<C>
collection);
/**
* Create an expression that tests the size of a collection.
* @param collection collection
* @return size expression
*/
<C extends
Collection<?>>
Expression<
Integer>
size(C
collection);
/**
* Create a predicate that tests whether an element is
* a member of a collection.
* If the collection is empty, the predicate will be false.
* @param elem element expression
* @param collection expression
* @return is-member predicate
*/
<E, C extends
Collection<E>>
Predicate isMember(
Expression<E>
elem,
Expression<C>
collection);
/**
* Create a predicate that tests whether an element is
* a member of a collection.
* If the collection is empty, the predicate will be false.
* @param elem element
* @param collection expression
* @return is-member predicate
*/
<E, C extends
Collection<E>>
Predicate isMember(E
elem,
Expression<C>
collection);
/**
* Create a predicate that tests whether an element is
* not a member of a collection.
* If the collection is empty, the predicate will be true.
* @param elem element expression
* @param collection expression
* @return is-not-member predicate
*/
<E, C extends
Collection<E>>
Predicate isNotMember(
Expression<E>
elem,
Expression<C>
collection);
/**
* Create a predicate that tests whether an element is
* not a member of a collection.
* If the collection is empty, the predicate will be true.
* @param elem element
* @param collection expression
* @return is-not-member predicate
*/
<E, C extends
Collection<E>>
Predicate isNotMember(E
elem,
Expression<C>
collection);
//get the values and keys collections of the Map, which may then
//be passed to size(), isMember(), isEmpty(), etc
/**
* Create an expression that returns the values of a map.
* @param map map
* @return collection expression
*/
<V, M extends
Map<?, V>>
Expression<
Collection<V>>
values(M
map);
/**
* Create an expression that returns the keys of a map.
* @param map map
* @return set expression
*/
<K, M extends
Map<K, ?>>
Expression<
Set<K>>
keys(M
map);
//string functions:
/**
* Create a predicate for testing whether the expression
* satisfies the given pattern.
* @param x string expression
* @param pattern string expression
* @return like predicate
*/
Predicate like(
Expression<
String>
x,
Expression<
String>
pattern);
/**
* Create a predicate for testing whether the expression
* satisfies the given pattern.
* @param x string expression
* @param pattern string
* @return like predicate
*/
Predicate like(
Expression<
String>
x,
String pattern);
/**
* Create a predicate for testing whether the expression
* satisfies the given pattern.
* @param x string expression
* @param pattern string expression
* @param escapeChar escape character expression
* @return like predicate
*/
Predicate like(
Expression<
String>
x,
Expression<
String>
pattern,
Expression<
Character>
escapeChar);
/**
* Create a predicate for testing whether the expression
* satisfies the given pattern.
* @param x string expression
* @param pattern string expression
* @param escapeChar escape character
* @return like predicate
*/
Predicate like(
Expression<
String>
x,
Expression<
String>
pattern, char
escapeChar);
/**
* Create a predicate for testing whether the expression
* satisfies the given pattern.
* @param x string expression
* @param pattern string
* @param escapeChar escape character expression
* @return like predicate
*/
Predicate like(
Expression<
String>
x,
String pattern,
Expression<
Character>
escapeChar);
/**
* Create a predicate for testing whether the expression
* satisfies the given pattern.
* @param x string expression
* @param pattern string
* @param escapeChar escape character
* @return like predicate
*/
Predicate like(
Expression<
String>
x,
String pattern, char
escapeChar);
/**
* Create a predicate for testing whether the expression
* does not satisfy the given pattern.
* @param x string expression
* @param pattern string expression
* @return not-like predicate
*/
Predicate notLike(
Expression<
String>
x,
Expression<
String>
pattern);
/**
* Create a predicate for testing whether the expression
* does not satisfy the given pattern.
* @param x string expression
* @param pattern string
* @return not-like predicate
*/
Predicate notLike(
Expression<
String>
x,
String pattern);
/**
* Create a predicate for testing whether the expression
* does not satisfy the given pattern.
* @param x string expression
* @param pattern string expression
* @param escapeChar escape character expression
* @return not-like predicate
*/
Predicate notLike(
Expression<
String>
x,
Expression<
String>
pattern,
Expression<
Character>
escapeChar);
/**
* Create a predicate for testing whether the expression
* does not satisfy the given pattern.
* @param x string expression
* @param pattern string expression
* @param escapeChar escape character
* @return not-like predicate
*/
Predicate notLike(
Expression<
String>
x,
Expression<
String>
pattern, char
escapeChar);
/**
* Create a predicate for testing whether the expression
* does not satisfy the given pattern.
* @param x string expression
* @param pattern string
* @param escapeChar escape character expression
* @return not-like predicate
*/
Predicate notLike(
Expression<
String>
x,
String pattern,
Expression<
Character>
escapeChar);
/**
* Create a predicate for testing whether the expression
* does not satisfy the given pattern.
* @param x string expression
* @param pattern string
* @param escapeChar escape character
* @return not-like predicate
*/
Predicate notLike(
Expression<
String>
x,
String pattern, char
escapeChar);
/**
* Create an expression for string concatenation.
* @param x string expression
* @param y string expression
* @return expression corresponding to concatenation
*/
Expression<
String>
concat(
Expression<
String>
x,
Expression<
String>
y);
/**
* Create an expression for string concatenation.
* @param x string expression
* @param y string
* @return expression corresponding to concatenation
*/
Expression<
String>
concat(
Expression<
String>
x,
String y);
/**
* Create an expression for string concatenation.
* @param x string
* @param y string expression
* @return expression corresponding to concatenation
*/
Expression<
String>
concat(
String x,
Expression<
String>
y);
/**
* Create an expression for substring extraction.
* Extracts a substring starting at the specified position
* through to end of the string.
* First position is 1.
* @param x string expression
* @param from start position expression
* @return expression corresponding to substring extraction
*/
Expression<
String>
substring(
Expression<
String>
x,
Expression<
Integer>
from);
/**
* Create an expression for substring extraction.
* Extracts a substring starting at the specified position
* through to end of the string.
* First position is 1.
* @param x string expression
* @param from start position
* @return expression corresponding to substring extraction
*/
Expression<
String>
substring(
Expression<
String>
x, int
from);
/**
* Create an expression for substring extraction.
* Extracts a substring of given length starting at the
* specified position.
* First position is 1.
* @param x string expression
* @param from start position expression
* @param len length expression
* @return expression corresponding to substring extraction
*/
Expression<
String>
substring(
Expression<
String>
x,
Expression<
Integer>
from,
Expression<
Integer>
len);
/**
* Create an expression for substring extraction.
* Extracts a substring of given length starting at the
* specified position.
* First position is 1.
* @param x string expression
* @param from start position
* @param len length
* @return expression corresponding to substring extraction
*/
Expression<
String>
substring(
Expression<
String>
x, int
from, int
len);
/**
* Used to specify how strings are trimmed.
*/
public static enum
Trimspec {
/**
* Trim from leading end.
*/
LEADING,
/**
* Trim from trailing end.
*/
TRAILING,
/**
* Trim from both ends.
*/
BOTH
}
/**
* Create expression to trim blanks from both ends of
* a string.
* @param x expression for string to trim
* @return trim expression
*/
Expression<
String>
trim(
Expression<
String>
x);
/**
* Create expression to trim blanks from a string.
* @param ts trim specification
* @param x expression for string to trim
* @return trim expression
*/
Expression<
String>
trim(
Trimspec ts,
Expression<
String>
x);
/**
* Create expression to trim character from both ends of
* a string.
* @param t expression for character to be trimmed
* @param x expression for string to trim
* @return trim expression
*/
Expression<
String>
trim(
Expression<
Character>
t,
Expression<
String>
x);
/**
* Create expression to trim character from a string.
* @param ts trim specification
* @param t expression for character to be trimmed
* @param x expression for string to trim
* @return trim expression
*/
Expression<
String>
trim(
Trimspec ts,
Expression<
Character>
t,
Expression<
String>
x);
/**
* Create expression to trim character from both ends of
* a string.
* @param t character to be trimmed
* @param x expression for string to trim
* @return trim expression
*/
Expression<
String>
trim(char
t,
Expression<
String>
x);
/**
* Create expression to trim character from a string.
* @param ts trim specification
* @param t character to be trimmed
* @param x expression for string to trim
* @return trim expression
*/
Expression<
String>
trim(
Trimspec ts, char
t,
Expression<
String>
x);
/**
* Create expression for converting a string to lowercase.
* @param x string expression
* @return expression to convert to lowercase
*/
Expression<
String>
lower(
Expression<
String>
x);
/**
* Create expression for converting a string to uppercase.
* @param x string expression
* @return expression to convert to uppercase
*/
Expression<
String>
upper(
Expression<
String>
x);
/**
* Create expression to return length of a string.
* @param x string expression
* @return length expression
*/
Expression<
Integer>
length(
Expression<
String>
x);
/**
* Create expression to locate the position of one string
* within another, returning position of first character
* if found.
* The first position in a string is denoted by 1. If the
* string to be located is not found, 0 is returned.
* @param x expression for string to be searched
* @param pattern expression for string to be located
* @return expression corresponding to position
*/
Expression<
Integer>
locate(
Expression<
String>
x,
Expression<
String>
pattern);
/**
* Create expression to locate the position of one string
* within another, returning position of first character
* if found.
* The first position in a string is denoted by 1. If the
* string to be located is not found, 0 is returned.
* @param x expression for string to be searched
* @param pattern string to be located
* @return expression corresponding to position
*/
Expression<
Integer>
locate(
Expression<
String>
x,
String pattern);
/**
* Create expression to locate the position of one string
* within another, returning position of first character
* if found.
* The first position in a string is denoted by 1. If the
* string to be located is not found, 0 is returned.
* @param x expression for string to be searched
* @param pattern expression for string to be located
* @param from expression for position at which to start search
* @return expression corresponding to position
*/
Expression<
Integer>
locate(
Expression<
String>
x,
Expression<
String>
pattern,
Expression<
Integer>
from);
/**
* Create expression to locate the position of one string
* within another, returning position of first character
* if found.
* The first position in a string is denoted by 1. If the
* string to be located is not found, 0 is returned.
* @param x expression for string to be searched
* @param pattern string to be located
* @param from position at which to start search
* @return expression corresponding to position
*/
Expression<
Integer>
locate(
Expression<
String>
x,
String pattern, int
from);
// Date/time/timestamp functions:
/**
* Create expression to return current date.
* @return expression for current date
*/
Expression<java.sql.
Date>
currentDate();
/**
* Create expression to return current timestamp.
* @return expression for current timestamp
*/
Expression<java.sql.
Timestamp>
currentTimestamp();
/**
* Create expression to return current time.
* @return expression for current time
*/
Expression<java.sql.
Time>
currentTime();
//in builders:
/**
* Interface used to build in predicates.
*/
public static interface
In<T> extends
Predicate {
/**
* Return the expression to be tested against the
* list of values.
* @return expression
*/
Expression<T>
getExpression();
/**
* Add to list of values to be tested against.
* @param value value
* @return in predicate
*/
In<T>
value(T
value);
/**
* Add to list of values to be tested against.
* @param value expression
* @return in predicate
*/
In<T>
value(
Expression<? extends T>
value);
}
/**
* Create predicate to test whether given expression
* is contained in a list of values.
* @param expression to be tested against list of values
* @return in predicate
*/
<T>
In<T>
in(
Expression<? extends T>
expression);
// coalesce, nullif:
/**
* Create an expression that returns null if all its arguments
* evaluate to null, and the value of the first non-null argument
* otherwise.
* @param x expression
* @param y expression
* @return coalesce expression
*/
<Y>
Expression<Y>
coalesce(
Expression<? extends Y>
x,
Expression<? extends Y>
y);
/**
* Create an expression that returns null if all its arguments
* evaluate to null, and the value of the first non-null argument
* otherwise.
* @param x expression
* @param y value
* @return coalesce expression
*/
<Y>
Expression<Y>
coalesce(
Expression<? extends Y>
x, Y
y);
/**
* Create an expression that tests whether its argument are
* equal, returning null if they are and the value of the
* first expression if they are not.
* @param x expression
* @param y expression
* @return nullif expression
*/
<Y>
Expression<Y>
nullif(
Expression<Y>
x,
Expression<?>
y);
/**
* Create an expression that tests whether its argument are
* equal, returning null if they are and the value of the
* first expression if they are not.
* @param x expression
* @param y value
* @return nullif expression
*/
<Y>
Expression<Y>
nullif(
Expression<Y>
x, Y
y);
// coalesce builder:
/**
* Interface used to build coalesce expressions.
*
* A coalesce expression 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.
*/
public static interface
Coalesce<T> extends
Expression<T> {
/**
* Add an argument to the coalesce expression.
* @param value value
* @return coalesce expression
*/
Coalesce<T>
value(T
value);
/**
* Add an argument to the coalesce expression.
* @param value expression
* @return coalesce expression
*/
Coalesce<T>
value(
Expression<? extends T>
value);
}
/**
* Create a coalesce expression.
* @return coalesce expression
*/
<T>
Coalesce<T>
coalesce();
//case builders:
/**
* Interface used to build simple case expressions.
* Case conditions are evaluated in the order in which
* they are specified.
*/
public static interface
SimpleCase<C,R> extends
Expression<R> {
/**
* Return the expression to be tested against the
* conditions.
* @return expression
*/
Expression<C>
getExpression();
/**
* Add a when/then clause to the case expression.
* @param condition "when" condition
* @param result "then" result value
* @return simple case expression
*/
SimpleCase<C, R>
when(C
condition, R
result);
/**
* Add a when/then clause to the case expression.
* @param condition "when" condition
* @param result "then" result expression
* @return simple case expression
*/
SimpleCase<C, R>
when(C
condition,
Expression<? extends R>
result);
/**
* Add an "else" clause to the case expression.
* @param result "else" result
* @return expression
*/
Expression<R>
otherwise(R
result);
/**
* Add an "else" clause to the case expression.
* @param result "else" result expression
* @return expression
*/
Expression<R>
otherwise(
Expression<? extends R>
result);
}
/**
* Create a simple case expression.
* @param expression to be tested against the case conditions
* @return simple case expression
*/
<C, R>
SimpleCase<C,R>
selectCase(
Expression<? extends C>
expression);
/**
* Interface used to build general case expressions.
* Case conditions are evaluated in the order in which
* they are specified.
*/
public static interface
Case<R> extends
Expression<R> {
/**
* Add a when/then clause to the case expression.
* @param condition "when" condition
* @param result "then" result value
* @return general case expression
*/
Case<R>
when(
Expression<
Boolean>
condition, R
result);
/**
* Add a when/then clause to the case expression.
* @param condition "when" condition
* @param result "then" result expression
* @return general case expression
*/
Case<R>
when(
Expression<
Boolean>
condition,
Expression<? extends R>
result);
/**
* Add an "else" clause to the case expression.
* @param result "else" result
* @return expression
*/
Expression<R>
otherwise(R
result);
/**
* Add an "else" clause to the case expression.
* @param result "else" result expression
* @return expression
*/
Expression<R>
otherwise(
Expression<? extends R>
result);
}
/**
* Create a general case expression.
* @return general case expression
*/
<R>
Case<R>
selectCase();
/**
* Create an expression for the execution of a database
* function.
* @param name function name
* @param type expected result type
* @param args function arguments
* @return expression
*/
<T>
Expression<T>
function(
String name,
Class<T>
type,
Expression<?>...
args);
// methods for downcasting:
/**
* Downcast Join object to the specified type.
* @param join Join object
* @param type type to be downcast to
* @return Join object of the specified type
* @since Java Persistence 2.1
*/
<X, T, V extends T>
Join<X, V>
treat(
Join<X, T>
join,
Class<V>
type);
/**
* Downcast CollectionJoin object to the specified type.
* @param join CollectionJoin object
* @param type type to be downcast to
* @return CollectionJoin object of the specified type
* @since Java Persistence 2.1
*/
<X, T, E extends T>
CollectionJoin<X, E>
treat(
CollectionJoin<X, T>
join,
Class<E>
type);
/**
* Downcast SetJoin object to the specified type.
* @param join SetJoin object
* @param type type to be downcast to
* @return SetJoin object of the specified type
* @since Java Persistence 2.1
*/
<X, T, E extends T>
SetJoin<X, E>
treat(
SetJoin<X, T>
join,
Class<E>
type);
/**
* Downcast ListJoin object to the specified type.
* @param join ListJoin object
* @param type type to be downcast to
* @return ListJoin object of the specified type
* @since Java Persistence 2.1
*/
<X, T, E extends T>
ListJoin<X, E>
treat(
ListJoin<X, T>
join,
Class<E>
type);
/**
* Downcast MapJoin object to the specified type.
* @param join MapJoin object
* @param type type to be downcast to
* @return MapJoin object of the specified type
* @since Java Persistence 2.1
*/
<X, K, T, V extends T>
MapJoin<X, K, V>
treat(
MapJoin<X, K, T>
join,
Class<V>
type);
/**
* Downcast Path object to the specified type.
* @param path path
* @param type type to be downcast to
* @return Path object of the specified type
* @since Java Persistence 2.1
*/
<X, T extends X>
Path<T>
treat(
Path<X>
path,
Class<T>
type);
/**
* Downcast Root object to the specified type.
* @param root root
* @param type type to be downcast to
* @return Root object of the specified type
* @since Java Persistence 2.1
*/
<X, T extends X>
Root<T>
treat(
Root<X>
root,
Class<T>
type);
}