All Downloads are FREE. Search and download functionalities are using the official Maven repository.

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

Go to download

The Java Persistence API (JPA) : a standard interface-based Java model abstraction of persistence, developed by the JCP.

There is a newer version: 2.2.4
Show newest version
/*
 * Copyright (c) 2008, 2009, 2011 Oracle, Inc. 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.
 */
package javax.persistence.criteria;

import javax.persistence.Tuple;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.Collection;
import java.util.Map;
import java.util.Set;

/**
 * Used to construct criteria queries, compound selections, expressions, predicates, orderings.
 * 

 * Note that Predicate is used instead of Expression<Boolean> 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 CriteriaQuery object.
     * @return criteria query object
     */
    CriteriaQuery createQuery();

    /**
     * Create a CriteriaQuery object with the specified result type.
     * @param resultClass type of the query result
     * @return criteria query object
     * @param  type
     */
     CriteriaQuery createQuery(Class resultClass);

    /**
     * Create a CriteriaQuery object that returns a tuple of objects as its result.
     * @return criteria query object
     */
    CriteriaQuery createTupleQuery();

    // methods to construct queries for bulk updates and deletes:

    /**
     * Create a query object to perform a bulk update operation.
     * @param targetEntity target type for update operation
     * @return the query object
     * @param  type
     */
     CriteriaUpdate createCriteriaUpdate(Class targetEntity);

    /**
     * Create a query object to perform a bulk delete operation.
     * @param targetEntity target type for delete operation
     * @return the query object
     * @param  type
     */
     CriteriaDelete createCriteriaDelete(Class 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
     * @param  type
     */
     CompoundSelection construct(Class 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(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 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
     * @param  number type
     */
     Expression avg(Expression x);

    /**
     * Create an aggregate expression applying the sum operation.
     * @param x expression representing input value to sum operation
     * @return sum expression
     * @param  number type
     */
     Expression sum(Expression 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 sumAsLong(Expression 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 sumAsDouble(Expression x);

    /**
     * Create an aggregate expression applying the numerical max operation.
     * @param x expression representing input value to max operation
     * @return max expression
     * @param  number type
     */
     Expression max(Expression x);

    /**
     * Create an aggregate expression applying the numerical min operation.
     * @param x expression representing input value to min operation
     * @return min expression
     * @param  number type
     */
     Expression min(Expression 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
     * @param  type
     */
    > Expression greatest(Expression 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
     * @param  type
     */
    > Expression least(Expression x);

    /**
     * Create an aggregate expression applying the count operation.
     * @param x expression representing input value to count operation
     * @return count expression
     */
    Expression 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 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
     * @param  type
     */
     Expression all(Subquery subquery);

    /**
     * Create a some expression over the subquery results. This expression is equivalent to an
     * any expression.
     * @param subquery subquery
     * @return some expression
     * @param  type
     */
     Expression some(Subquery subquery);

    /**
     * Create an any expression over the subquery results. This expression is equivalent to a
     * some expression.
     * @param subquery subquery
     * @return any expression
     * @param  type
     */
     Expression any(Subquery 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 x, Expression 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 x, Expression 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 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 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 x);

    /**
     * Create a predicate testing for a false value.
     * @param x expression to be tested
     * @return predicate
     */
    Predicate isFalse(Expression 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
     * @param  type
     */
    > Predicate greaterThan(Expression x, Expression 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
     * @param  type
     */
    > Predicate greaterThan(Expression 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
     * @param  type
     */
    > Predicate greaterThanOrEqualTo(Expression x, Expression 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
     * @param  type
     */
    > Predicate greaterThanOrEqualTo(Expression 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
     * @param  type
     */
    > Predicate lessThan(Expression x, Expression 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
     * @param  type
     */
    > Predicate lessThan(Expression 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
     * @param  type
     */
    > Predicate lessThanOrEqualTo(Expression x, Expression 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
     * @param  type
     */
    > Predicate lessThanOrEqualTo(Expression 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
     * @param  type
     */
    > Predicate between(Expression v, Expression x, Expression 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
     * @param  type
     */
    > Predicate between(Expression 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 x, Expression 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 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 x, Expression 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 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 x, Expression 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 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 x, Expression 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 x, Number y);

    // numerical operations:

    /**
     * Create an expression that returns the arithmetic negation of its argument.
     * @param x expression
     * @return arithmetic negation
     * @param  type
     */
     Expression neg(Expression x);

    /**
     * Create an expression that returns the absolute value of its argument.
     * @param x expression
     * @return absolute value
     * @param  type
     */
     Expression abs(Expression x);

    /**
     * Create an expression that returns the sum of its arguments.
     * @param x expression
     * @param y expression
     * @return sum
     * @param  type
     */
     Expression sum(Expression x, Expression y);

    /**
     * Create an expression that returns the sum of its arguments.
     * @param x expression
     * @param y value
     * @return sum
     * @param  type
     */
     Expression sum(Expression x, N y);

    /**
     * Create an expression that returns the sum of its arguments.
     * @param x value
     * @param y expression
     * @return sum
     * @param  type
     */
     Expression sum(N x, Expression y);

    /**
     * Create an expression that returns the product of its arguments.
     * @param x expression
     * @param y expression
     * @return product
     * @param  type
     */
     Expression prod(Expression x, Expression y);

    /**
     * Create an expression that returns the product of its arguments.
     * @param x expression
     * @param y value
     * @return product
     * @param  type
     */
     Expression prod(Expression x, N y);

    /**
     * Create an expression that returns the product of its arguments.
     * @param x value
     * @param y expression
     * @return product
     * @param  type
     */
     Expression prod(N x, Expression y);

    /**
     * Create an expression that returns the difference between its arguments.
     * @param x expression
     * @param y expression
     * @return difference
     * @param  type
     */
     Expression diff(Expression x, Expression y);

    /**
     * Create an expression that returns the difference between its arguments.
     * @param x expression
     * @param y value
     * @return difference
     * @param  type
     */
     Expression diff(Expression x, N y);

    /**
     * Create an expression that returns the difference between its arguments.
     * @param x value
     * @param y expression
     * @return difference
     * @param  type
     */
     Expression diff(N x, Expression y);

    /**
     * Create an expression that returns the quotient of its arguments.
     * @param x expression
     * @param y expression
     * @return quotient
     */
    Expression quot(Expression x, Expression y);

    /**
     * Create an expression that returns the quotient of its arguments.
     * @param x expression
     * @param y value
     * @return quotient
     */
    Expression quot(Expression x, Number y);

    /**
     * Create an expression that returns the quotient of its arguments.
     * @param x value
     * @param y expression
     * @return quotient
     */
    Expression quot(Number x, Expression y);

    /**
     * Create an expression that returns the modulus of its arguments.
     * @param x expression
     * @param y expression
     * @return modulus
     */
    Expression mod(Expression x, Expression y);

    /**
     * Create an expression that returns the modulus of its arguments.
     * @param x expression
     * @param y value
     * @return modulus
     */
    Expression mod(Expression x, Integer y);

    /**
     * Create an expression that returns the modulus of its arguments.
     * @param x value
     * @param y expression
     * @return modulus
     */
    Expression mod(Integer x, Expression y);

    /**
     * Create an expression that returns the square root of its argument.
     * @param x expression
     * @return square root
     */
    Expression sqrt(Expression x);

    // typecasts:

    /**
     * Typecast. Returns same expression object.
     * @param number numeric expression
     * @return Expression<Long>
     */
    Expression toLong(Expression number);

    /**
     * Typecast. Returns same expression object.
     * @param number numeric expression
     * @return Expression<Integer>
     */
    Expression toInteger(Expression number);

    /**
     * Typecast. Returns same expression object.
     * @param number numeric expression
     * @return Expression<Float>
     */
    Expression toFloat(Expression number);

    /**
     * Typecast. Returns same expression object.
     * @param number numeric expression
     * @return Expression<Double>
     */
    Expression toDouble(Expression number);

    /**
     * Typecast. Returns same expression object.
     * @param number numeric expression
     * @return Expression<BigDecimal>
     */
    Expression toBigDecimal(Expression number);

    /**
     * Typecast. Returns same expression object.
     * @param number numeric expression
     * @return Expression<BigInteger>
     */
    Expression toBigInteger(Expression number);

    /**
     * Typecast. Returns same expression object.
     * @param character expression
     * @return Expression<String>
     */
    Expression toString(Expression character);

    // literals:

    /**
     * Create an expression for a literal.
     * @param value value represented by the expression
     * @return expression literal
     * @throws IllegalArgumentException if value is null
     * @param  type
     */
     Expression 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
     * @param  type
     */
     Expression nullLiteral(Class resultClass);

    // parameters:

    /**
     * Create a parameter expression.
     * @param paramClass parameter class
     * @return parameter expression
     * @param  type
     */
     ParameterExpression parameter(Class 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
     * @param  type
     */
     ParameterExpression parameter(Class paramClass, String name);

    // collection operations:

    /**
     * Create a predicate that tests whether a collection is empty.
     * @param collection expression
     * @return is-empty predicate
     * @param  collection type
     */
    > Predicate isEmpty(Expression collection);

    /**
     * Create a predicate that tests whether a collection is not empty.
     * @param collection expression
     * @return is-not-empty predicate
     * @param  collection type
     */
    > Predicate isNotEmpty(Expression collection);

    /**
     * Create an expression that tests the size of a collection.
     * @param collection expression
     * @return size expression
     * @param  collection type
     */
    > Expression size(Expression collection);

    /**
     * Create an expression that tests the size of a collection.
     * @param collection collection
     * @return size expression
     * @param  collection type
     */
    > Expression 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
     * @param  collection type
     * @param  element type
     */
    > Predicate isMember(Expression elem, Expression 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
     * @param  collection type
     * @param  element type
     */
    > Predicate isMember(E elem, Expression 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
     * @param  collection type
     * @param  element type
     */
    > Predicate isNotMember(Expression elem, Expression 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
     * @param  collection type
     * @param  element type
     */
    > Predicate isNotMember(E elem, Expression 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
     * @param  value type
     * @param  map type
     */
    > Expression> values(M map);

    /**
     * Create an expression that returns the keys of a map.
     * @param map map
     * @return set expression
     * @param  key type
     * @param  map type
     */
    > Expression> 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 x, Expression 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 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 x, Expression pattern, Expression 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 x, Expression 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 x, String pattern, Expression 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 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 x, Expression 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 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 x, Expression pattern, Expression 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 x, Expression 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 x, String pattern, Expression 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 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 concat(Expression x, Expression y);

    /**
     * Create an expression for string concatenation.
     * @param x string expression
     * @param y string
     * @return expression corresponding to concatenation
     */
    Expression concat(Expression x, String y);

    /**
     * Create an expression for string concatenation.
     * @param x string
     * @param y string expression
     * @return expression corresponding to concatenation
     */
    Expression concat(String x, Expression 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 substring(Expression x, Expression 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 substring(Expression 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 substring(Expression x, Expression from, Expression 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 substring(Expression 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 trim(Expression x);

    /**
     * Create expression to trim blanks from a string.
     * @param ts trim specification
     * @param x expression for string to trim
     * @return trim expression
     */
    Expression trim(Trimspec ts, Expression 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 trim(Expression t, Expression 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 trim(Trimspec ts, Expression t, Expression 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 trim(char t, Expression 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 trim(Trimspec ts, char t, Expression x);

    /**
     * Create expression for converting a string to lowercase.
     * @param x string expression
     * @return expression to convert to lowercase
     */
    Expression lower(Expression x);

    /**
     * Create expression for converting a string to uppercase.
     * @param x string expression
     * @return expression to convert to uppercase
     */
    Expression upper(Expression x);

    /**
     * Create expression to return length of a string.
     * @param x string expression
     * @return length expression
     */
    Expression length(Expression 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 locate(Expression x, Expression 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 locate(Expression 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 locate(Expression x, Expression pattern, Expression 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 locate(Expression x, String pattern, int from);

    // Date/time/timestamp functions:

    /**
     * Create expression to return current date.
     * @return expression for current date
     */
    Expression currentDate();

    /**
     * Create expression to return current timestamp.
     * @return expression for current timestamp
     */
    Expression currentTimestamp();

    /**
     * Create expression to return current time.
     * @return expression for current time
     */
    Expression currentTime();

    // TODO Also allow for java.time types?
    /**
     * Create expression for getting the year from a date.
     * Note that this is a DataNucleus extension, post JPA2.1
     * @param x date expression
     * @return expression for the year
     */
    Expression year(Expression x);

    /**
     * Create expression for getting the month from a date.
     * Note that this is a DataNucleus extension, post JPA2.1
     * @param x date expression
     * @return expression for the month
     */
    Expression month(Expression x);

    /**
     * Create expression for getting the day (of the month) from a date.
     * Note that this is a DataNucleus extension, post JPA2.1
     * @param x date expression
     * @return expression for the day
     */
    Expression day(Expression x);

    /**
     * Create expression for getting the hour from a date.
     * Note that this is a DataNucleus extension, post JPA2.1
     * @param x date expression
     * @return expression for the hour
     */
    Expression hour(Expression x);

    /**
     * Create expression for getting the minute from a date.
     * Note that this is a DataNucleus extension, post JPA2.1
     * @param x date expression
     * @return expression for the minute
     */
    Expression minute(Expression x);

    /**
     * Create expression for getting the second from a date.
     * Note that this is a DataNucleus extension, post JPA2.1
     * @param x date expression
     * @return expression for the second
     */
    Expression second(Expression x);

    // in builders:

    /**
     * Interface used to build in predicates.
     */
    public static interface In extends Predicate
    {

        /**
         * Return the expression to be tested against the list of values.
         * @return expression
         */
        Expression getExpression();

        /**
         * Add to list of values to be tested against.
         * @param value value
         * @return in predicate
         */
        In value(T value);

        /**
         * Add to list of values to be tested against.
         * @param value expression
         * @return in predicate
         */
        In value(Expression 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
     * @param  type
     */
     In in(Expression 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
     * @param  type
     */
     Expression coalesce(Expression x, Expression 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
     * @param  type
     */
     Expression coalesce(Expression 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
     * @param  type
     */
     Expression nullif(Expression 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
     * @param  type
     */
     Expression nullif(Expression 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 extends Expression
    {

        /**
         * Add an argument to the coalesce expression.
         * @param value value
         * @return coalesce expression
         */
        Coalesce value(T value);

        /**
         * Add an argument to the coalesce expression.
         * @param value expression
         * @return coalesce expression
         */
        Coalesce value(Expression value);
    }

    /**
     * Create a coalesce expression.
     * @return coalesce expression
     * @param  type
     */
     Coalesce 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 extends Expression
    {

        /**
         * Return the expression to be tested against the conditions.
         * @return expression
         */
        Expression getExpression();

        /**
         * Add a when/then clause to the case expression.
         * @param condition "when" condition
         * @param result "then" result value
         * @return simple case expression
         */
        SimpleCase 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 when(C condition, Expression result);

        /**
         * Add an "else" clause to the case expression.
         * @param result "else" result
         * @return expression
         */
        Expression otherwise(R result);

        /**
         * Add an "else" clause to the case expression.
         * @param result "else" result expression
         * @return expression
         */
        Expression otherwise(Expression result);
    }

    /**
     * Create a simple case expression.
     * @param expression to be tested against the case conditions
     * @return simple case expression
     * @param  type
     * @param  type
     */
     SimpleCase selectCase(Expression expression);

    /**
     * Interface used to build general case expressions. Case conditions are evaluated in the order in which
     * they are specified.
     */
    public static interface Case extends Expression
    {

        /**
         * Add a when/then clause to the case expression.
         * @param condition "when" condition
         * @param result "then" result value
         * @return general case expression
         */
        Case when(Expression 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 when(Expression condition, Expression result);

        /**
         * Add an "else" clause to the case expression.
         * @param result "else" result
         * @return expression
         */
        Expression otherwise(R result);

        /**
         * Add an "else" clause to the case expression.
         * @param result "else" result expression
         * @return expression
         */
        Expression otherwise(Expression result);
    }

    /**
     * Create a general case expression.
     * @return general case expression
     * @param  type
     */
     Case 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
     * @param  type
     */
     Expression function(String name, Class type, Expression... args);

    /**
     * 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
     * @param  type
     * @param  type
     * @param  type
     */
     Join treat(Join join, Class 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
     * @param  type
     * @param  type
     * @param  type
     */
     CollectionJoin treat(CollectionJoin join, Class 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
     * @param  type
     * @param  type
     * @param  type
     */
     SetJoin treat(SetJoin join, Class 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
     * @param  type
     * @param  type
     * @param  type
     */
     ListJoin treat(ListJoin join, Class 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
     * @param  type
     * @param  type
     * @param  key type
     * @param  value type
     */
     MapJoin treat(MapJoin join, Class 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
     * @param  type
     * @param  type
     */
     Path treat(Path path, Class type);

    /**
     * Downcast Root object to the specified type.
     * @param root root
     * @param type type to be downcast to
     * @return Path object of the specified type
     * @param  type
     * @param  type
     */
     Root treat(Root root, Class type);
}
    

    

    

            

    

            



    
    






    
© 2015 - 2024 Weber Informatics LLC | Privacy Policy