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