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
/*******************************************************************************
 * 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.
 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/**
 * Used to construct criteria queries, compound selections, 
 * expressions, predicates, orderings.
 *
 * <p> Note that <code>Predicate</code> is used instead of <code>Expression&#060;Boolean&#062;</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 CriteriaQuery object.
 @return criteria query object
/**
     *  Create a <code>CriteriaQuery</code> object.
     *  @return criteria query object
     */
    CriteriaQuery<Object> createQuery();

    
 Create a CriteriaQuery object with the specified result 
 type.
 @param resultClass  type of the query result
 @return criteria query object
/**
     *  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 CriteriaQuery object that returns a tuple of 
 objects as its result.
 @return criteria query object
/**
     *  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 CriteriaUpdate query object to perform a bulk update operation.
 @param targetEntity  target type for update operation
 @return the query object
 @since Java Persistence 2.1
/**
     *  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 CriteriaDelete query object to perform a bulk delete operation.
 @param targetEntity  target type for delete operation
 @return the query object
 @since Java Persistence 2.1
/**
     *  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.
Params:
resultClass –  class whose instance is to be constructed
selections –  arguments to the constructor
Throws:
IllegalArgumentException – if an argument is a 
        tuple- or array-valued selection item
Returns:
compound selection item/**
     * 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.
Params:
selections –  selection items
Throws:
IllegalArgumentException – if an argument is a 
        tuple- or array-valued selection item
Returns:
tuple-valued compound selection/**
     * 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.
Params:
selections –  selection items
Throws:
IllegalArgumentException – if an argument is a 
        tuple- or array-valued selection item
Returns:
array-valued compound selection/**
     * 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.
Params:
x –  expression used to define the ordering
Returns:
ascending ordering corresponding to the expression/**
     * 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.
Params:
x –  expression used to define the ordering
Returns:
descending ordering corresponding to the expression/**
     * 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.
Params:
x –  expression representing input value to avg operation
Returns:
avg expression/**
     * 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.
Params:
x –  expression representing input value to sum operation
Returns:
sum expression/**
     * 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.
Params:
x –  expression representing input value to sum operation
Returns:
sum expression/**
     * 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.
Params:
x –  expression representing input value to sum operation
Returns:
sum expression/**
     * 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.
Params:
x –  expression representing input value to max operation
Returns:
max expression/**
     * 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.
Params:
x –  expression representing input value to min operation
Returns:
min expression/**
     * 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).
Params:
x –  expression representing input value to greatest
          operation
Returns:
greatest expression/**
     * 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).
Params:
x –  expression representing input value to least
          operation
Returns:
least expression/**
     * 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.
Params:
x –  expression representing input value to count 
          operation
Returns:
count expression/**
     * 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.
Params:
x –  expression representing input value to 
       count distinct operation
Returns:
count distinct expression/**
     * 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.
Params:
subquery –  subquery whose result is to be tested
Returns:
exists predicate/**
     * 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.
Params:
subquery –  subquery
Returns:
all expression/**
     * 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 any expression.
Params:
subquery –  subquery
Returns:
some expression/**
     * 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 some expression.
Params:
subquery –  subquery
Returns:
any expression/**
     * 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.
Params:
x –  boolean expression
y –  boolean expression
Returns:
and predicate/**
     * 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.
Params:
restrictions –  zero or more restriction predicates
Returns:
and predicate/**
     * 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.
Params:
x –  boolean expression
y –  boolean expression
Returns:
or predicate/**
     * 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.
Params:
restrictions –  zero or more restriction predicates
Returns:
or predicate/**
     * 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. 
Params:
restriction –  restriction expression
Returns:
not predicate/**
     * 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.
Returns:
and predicate/**
     * 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.
Returns:
or predicate/**
     * 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.
Params:
x –  expression to be tested
Returns:
predicate/**
     * 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.
Params:
x –  expression to be tested
Returns:
predicate/**
     * 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.
Params:
x – expression
Returns:
is-null predicate/**
     * 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.
Params:
x – expression
Returns:
is-not-null predicate/**
     * 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.
Params:
x –  expression
y –  expression
Returns:
equality predicate/**
     * 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.
Params:
x –  expression
y –  object
Returns:
equality predicate/**
     * 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.
Params:
x –  expression
y –  expression
Returns:
inequality predicate/**
     * 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.
Params:
x –  expression
y –  object
Returns:
inequality predicate/**
     * 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.
Params:
x –  expression
y –  expression
Returns:
greater-than predicate/**
     * 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.
Params:
x –  expression
y –  value
Returns:
greater-than predicate/**
     * 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.
Params:
x –  expression
y –  expression
Returns:
greater-than-or-equal predicate/**
     * 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.
Params:
x –  expression
y –  value
Returns:
greater-than-or-equal predicate/**
     * 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.
Params:
x –  expression
y –  expression
Returns:
less-than predicate/**
     * 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.
Params:
x –  expression
y –  value
Returns:
less-than predicate/**
     * 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.
Params:
x –  expression
y –  expression
Returns:
less-than-or-equal predicate/**
     * 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.
Params:
x –  expression
y –  value
Returns:
less-than-or-equal predicate/**
     * 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.
Params:
v –  expression
x –  expression
y –  expression
Returns:
between predicate/**
     * 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.
Params:
v –  expression
x –  value
y –  value
Returns:
between predicate/**
     * 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.
Params:
x –  expression
y –  expression
Returns:
greater-than predicate/**
     * 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.
Params:
x –  expression
y –  value
Returns:
greater-than predicate/**
     * 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.
Params:
x –  expression
y –  expression
Returns:
greater-than-or-equal predicate/**
     * 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.
Params:
x –  expression
y –  value
Returns:
greater-than-or-equal predicate/**
     * 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.
Params:
x –  expression
y –  expression
Returns:
less-than predicate/**
     * 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.
Params:
x –  expression
y –  value
Returns:
less-than predicate/**
     * 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.
Params:
x –  expression
y –  expression
Returns:
less-than-or-equal predicate/**
     * 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.
Params:
x –  expression
y –  value
Returns:
less-than-or-equal predicate/**
     * 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.
Params:
x – expression
Returns:
arithmetic negation/**
     * 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.
Params:
x – expression
Returns:
absolute value/**
     * 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.
Params:
x – expression
y – expression
Returns:
sum/**
     * 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.
Params:
x – expression
y – value
Returns:
sum/**
     * 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.
Params:
x – value
y – expression
Returns:
sum/**
     * 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.
Params:
x – expression
y – expression
Returns:
product/**
     * 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.
Params:
x – expression
y – value
Returns:
product/**
     * 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.
Params:
x – value
y – expression
Returns:
product/**
     * 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.
Params:
x – expression
y – expression
Returns:
difference/**
     * 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.
Params:
x – expression
y – value
Returns:
difference/**
     * 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.
Params:
x – value
y – expression
Returns:
difference/**
     * 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.
Params:
x – expression
y – expression
Returns:
quotient/**
     * 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.
Params:
x – expression
y – value
Returns:
quotient/**
     * 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.
Params:
x – value
y – expression
Returns:
quotient/**
     * 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.
Params:
x – expression
y – expression
Returns:
modulus/**
     * 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.
Params:
x – expression
y – value
Returns:
modulus/**
     * 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.
Params:
x – value
y – expression
Returns:
modulus/**
     * 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.
Params:
x – expression
Returns:
square root/**
     * 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.
Params:
number –  numeric expression
Returns:
Expression<Long>/**
     * Typecast.  Returns same expression object.
     * @param number  numeric expression
     * @return Expression&#060;Long&#062;
     */
    Expression<Long> toLong(Expression<? extends Number> number);

    
Typecast.  Returns same expression object.
Params:
number –  numeric expression
Returns:
Expression<Integer>/**
     * Typecast.  Returns same expression object.
     * @param number  numeric expression
     * @return Expression&#060;Integer&#062;
     */
    Expression<Integer> toInteger(Expression<? extends Number> number);

    
Typecast. Returns same expression object.
Params:
number –  numeric expression
Returns:
Expression<Float>/**
     * Typecast. Returns same expression object.
     * @param number  numeric expression
     * @return Expression&#060;Float&#062;
     */
    Expression<Float> toFloat(Expression<? extends Number> number);

    
Typecast.  Returns same expression object.
Params:
number –  numeric expression
Returns:
Expression<Double>/**
     * Typecast.  Returns same expression object.
     * @param number  numeric expression
     * @return Expression&#060;Double&#062;
     */
    Expression<Double> toDouble(Expression<? extends Number> number);

    
Typecast.  Returns same expression object.
Params:
number –  numeric expression
Returns:
Expression<BigDecimal>/**
     * Typecast.  Returns same expression object.
     * @param number  numeric expression
     * @return Expression&#060;BigDecimal&#062;
     */
    Expression<BigDecimal> toBigDecimal(Expression<? extends Number> number);

    
Typecast.  Returns same expression object.
Params:
number –  numeric expression
Returns:
Expression<BigInteger>/**
     * Typecast.  Returns same expression object.
     * @param number  numeric expression
     * @return Expression&#060;BigInteger&#062;
     */
    Expression<BigInteger> toBigInteger(Expression<? extends Number> number);
	
    
Typecast.  Returns same expression object.
Params:
character – expression
Returns:
Expression<String>/**
     * Typecast.  Returns same expression object.
     * @param character expression
     * @return Expression&#060;String&#062;
     */
    Expression<String> toString(Expression<Character> character);

	
    //literals:

    
Create an expression for a literal.
Params:
value –  value represented by the expression
Throws:
IllegalArgumentException – if value is null
Returns:
expression literal/**
     * 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.
Params:
resultClass –  type of the null literal
Returns:
null expression literal/**
     * 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.
Params:
paramClass – parameter class
Returns:
parameter expression/**
     * 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.
Params:
paramClass – parameter class
name –  name that can be used to refer to 
             the parameter
Returns:
parameter expression/**
     * 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
/**
     *  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
/**
     *  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.
Params:
collection – expression
Returns:
size expression/**
     * 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.
Params:
collection – collection
Returns:
size expression/**
     * 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
/**
     *  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
/**
     *  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
/**
     *  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
/**
     *  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.
Params:
map –  map
Returns:
collection expression/**
     * 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.
Params:
map –  map
Returns:
set expression/**
     * 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.
Params:
x –  string expression
pattern –  string expression
Returns:
like predicate/**
     * 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.
Params:
x –  string expression
pattern –  string
Returns:
like predicate/**
     * 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.
Params:
x –  string expression
pattern –  string expression
escapeChar –  escape character expression
Returns:
like predicate/**
     * 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.
Params:
x –  string expression
pattern –  string expression
escapeChar –  escape character
Returns:
like predicate/**
     * 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.
Params:
x –  string expression
pattern –  string
escapeChar –  escape character expression
Returns:
like predicate/**
     * 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.
Params:
x –  string expression
pattern –  string
escapeChar –  escape character
Returns:
like predicate/**
     * 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.
Params:
x –  string expression
pattern –  string expression
Returns:
not-like predicate/**
     * 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.
Params:
x –  string expression
pattern –  string
Returns:
not-like predicate/**
     * 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.
Params:
x –  string expression
pattern –  string expression
escapeChar –  escape character expression
Returns:
not-like predicate/**
     * 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.
Params:
x –  string expression
pattern –  string expression
escapeChar –  escape character
Returns:
not-like predicate/**
     * 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.
Params:
x –  string expression
pattern –  string
escapeChar –  escape character expression
Returns:
not-like predicate/**
     * 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.
Params:
x –  string expression
pattern –  string
escapeChar –  escape character
Returns:
not-like predicate/**
     * 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
/**
     *  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
/**
     *  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
/**
     *  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
/**
     *  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
/**
     *  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
/**
     *  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
/**
     *  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.
/**
     *  Used to specify how strings are trimmed.
     */
    public static enum Trimspec { 

        
Trim from leading end.
/**
         * Trim from leading end.
         */
        LEADING,
 
        
Trim from trailing end.
/**
         * Trim from trailing end.
         */
        TRAILING, 

        
Trim from both ends.
/**
         * Trim from both ends.
         */
        BOTH 
    }
	
    
Create expression to trim blanks from both ends of
a string.
Params:
x –  expression for string to trim
Returns:
trim expression/**
     * 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.
Params:
ts –  trim specification
x –  expression for string to trim
Returns:
trim expression/**
     * 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.
Params:
t –  expression for character to be trimmed
x –  expression for string to trim
Returns:
trim expression/**
     * 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.
Params:
ts –  trim specification
t –  expression for character to be trimmed
x –  expression for string to trim
Returns:
trim expression/**
     * 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.
Params:
t –  character to be trimmed
x –  expression for string to trim
Returns:
trim expression/**
     * 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.
Params:
ts –  trim specification
t –  character to be trimmed
x –  expression for string to trim
Returns:
trim expression/**
     * 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.
Params:
x –  string expression
Returns:
expression to convert to lowercase/**
     * 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.
Params:
x –  string expression
Returns:
expression to convert to uppercase/**
     * 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.
Params:
x –  string expression
Returns:
length expression/**
     * 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.
Params:
x –  expression for string to be searched
pattern –  expression for string to be located
Returns:
expression corresponding to position/**
     * 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.
Params:
x –  expression for string to be searched
pattern –  string to be located
Returns:
expression corresponding to position/**
     * 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.
Params:
x –  expression for string to be searched
pattern –  expression for string to be located
from –  expression for position at which to start search
Returns:
expression corresponding to position/**
     * 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.
Params:
x –  expression for string to be searched
pattern –  string to be located
from –  position at which to start search
Returns:
expression corresponding to position/**
     * 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
/**
     *  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
/**
     *  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
/**
     *  Create expression to return current time.
     *  @return expression for current time
     */	
    Expression<java.sql.Time> currentTime();
	

    //in builders:
	
    
 Interface used to build in predicates.
/**
     *  Interface used to build in predicates.
     */
    public static interface In<T> extends Predicate {

         
Return the expression to be tested against the
list of values.
Returns:
expression/**
          * 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
/**
          *  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
/**
          *  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
/**
     *  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.
Params:
x – expression
y – expression
Returns:
coalesce expression/**
     * 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.
Params:
x – expression
y – value
Returns:
coalesce expression/**
     * 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.
Params:
x – expression
y – expression
Returns:
nullif expression/**
     * 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.
Params:
x – expression
y – value
Returns:
nullif expression/**
     * 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.
/**
     *  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.
Params:
value –  value
Returns:
coalesce expression/**
          * 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.
Params:
value – expression
Returns:
coalesce expression/**
          * Add an argument to the coalesce expression.
          * @param value expression
          * @return coalesce expression
          */
         Coalesce<T> value(Expression<? extends T> value);
	}
	
    
Create a coalesce expression.
Returns:
coalesce expression/**
     * 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.
/**
     *  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.
Returns:
expression/**
		 * Return the expression to be tested against the
		 * conditions.
		 * @return expression
		 */
		Expression<C> getExpression();

		
Add a when/then clause to the case expression.
Params:
condition –  "when" condition
result –  "then" result value
Returns:
simple case expression/**
		 * 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.
Params:
condition –  "when" condition
result –  "then" result expression
Returns:
simple case expression/**
		 * 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.
Params:
result –  "else" result
Returns:
expression/**
		 * 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.
Params:
result –  "else" result expression
Returns:
expression/**
		 * 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
/**
     *  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.
/**
     *  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.
Params:
condition –  "when" condition
result –  "then" result value
Returns:
general case expression/**
		 * 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.
Params:
condition –  "when" condition
result –  "then" result expression
Returns:
general case expression/**
		 * 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.
Params:
result –  "else" result
Returns:
expression/**
		 * 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.
Params:
result –  "else" result expression
Returns:
expression/**
		 * 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
/**
     *  Create a general case expression.
     *  @return general case expression
     */
    <R> Case<R> selectCase();

    
Create an expression for the execution of a database
function.
Params:
name –  function name
type –  expected result type
args –  function arguments
Returns:
expression/**
     * 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
/**
     *  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
/**
     *  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
/**
     *  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
/**
     *  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
/**
     *  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
/**
     *  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
/**
     *  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);

}