org.kuali.rice.core.framework.persistence.jpa.criteria
Class Criteria

java.lang.Object
  extended by org.kuali.rice.core.framework.persistence.jpa.criteria.Criteria

public class Criteria
extends Object

A criteria builder for JPQL Query objects.

All entities in queries generated by this class will be given an alias, and an initial entity (with an initial alias) is mandatory. If no alias is given or if a constructor without an alias parameter is used, a new alias name will be auto-generated.

The interpretation of the initial entity depends on what type of query is intended. If a SELECT query is desired, the initial entity will be the first to appear in the FROM clause. If a DELETE query is desired, the initial entity will be the one that appears in the DELETE FROM clause. If an UPDATE query is desired, the initial entity will be the one that appears in the UPDATE clause.

Most of the methods of this class rely on String expressions representing entity properties, or functions acting on constants or entity properties. If the expression contains functions or if you wish to reference the property of an entity other than the first aliased entity of the query, then the String expression must include the alias of the entity in the format __JPA_ALIAS[[index]]__ or the format __JPA_ALIAS[['alias']]__ , where "index" is a numeric index pointing to the Nth alias of the current query in the order that the aliases were added to the query (starting at zero), and where "'alias'" is the String name of the entity alias enclosed in single quotes.

If the String expression as defined above does not contain custom JPA aliases, then the initial alias of the current Criteria (and a '.' to separate the alias from the expression) will be prepended to the expression automatically.

If the current Criteria is intended for use as a sub-query, then aliases of the parent Criteria can be referred to by name (so long as they do not conflict with the alias names in the sub-Criteria) or by specifying the bitwise NOT of the alias index in the parent Criteria (-1 for 0, -2 for 1, etc.). When including a sub-query in a parent query, the parent Criteria will handle the updating of the alias indexes and will auto-generate new aliases as needed if any of the sub-query's defined aliases are duplicates of those in the parent query.

For Criteria objects intended to be ANDed or ORed with an existing Criteria, it is assumed that any named or indexed aliases refer to exactly the same aliases as in the existing Criteria. Any auto-prepended aliases as described above will always be referred to by index, so it is safe for them to be included in the Criteria to be ANDed/ORed with the existing one. Both of these details also apply when adding new Criteria to the HAVING clause of an existing Criteria, or when inserting the negation of another Criteria's conditions into an existing Criteria as a "NOT (...)" expression.

Also, during query construction, the Criteria API will automatically include substrings in the format __JPA_PARAM[['parameter']]__ when adding input parameters, where 'parameter' is the auto-generated name of the parameter. Care should be taken to ensure that __JPA_ALIAS[[...]]__ and __JPA_PARAM[[...]]__ expressions are not being added to queries that wish to interpret such String patterns literally.

Note that Criteria instances are not thread-safe, so external synchronization is necessary if operating on them from multiple threads.

TODO: Verify if any other features need to be added to this API.

Author:
Kuali Rice Team (rice.collab@kuali.org)

Field Summary
static String JPA_ALIAS_PREFIX
          The String representing the beginning of a by-name or by-index reference to an entity alias.
static String JPA_ALIAS_SUFFIX
          The String representing the termination of by-name/index references to aliases or input parameters.
static String JPA_PARAM_PREFIX
          The String representing the beginning of a by-name reference to an input parameter.
protected  Map<String,Object> params
           
 
Constructor Summary
Criteria(String entityName)
          Constructs a new Criteria instance that includes the given initial entity.
Criteria(String entityName, boolean includeEntityInSelect)
          Constructs a new Criteria instance that includes the given initial entity.
Criteria(String entityName, String alias)
          Constructs a new Criteria instance that includes the given initial entity.
Criteria(String entityName, String alias, boolean includeEntityAliasInSelect)
          Constructs a new Criteria instance that includes the given initial entity.
 
Method Summary
 void and(Criteria and)
          Takes the conditions from the given Criteria's WHERE clause, surrounds them in parentheses, and ANDs the resulting expression with this instance's WHERE clause (or makes the expression become the new WHERE clause of this instance if its current WHERE clause is empty).
 void between(String attribute, Object value1, Object value2)
          Adds a new BETWEEN condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void distinct(boolean distinct)
          Sets whether or not the query should include the DISTINCT keyword in the SELECT clause, if creating a SELECT query.
 void eq(String attribute, Object value)
          Adds an equality condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void exists(Criteria exists)
          Converts the given Criteria into a sub-SELECT query, surrounds it in parentheses, and adds a new EXISTS condition containing the resulting expression into the WHERE clause, while ANDing the new condition with any existing conditions if necessary.
 String from(String entityName, String alias, boolean includeEntityAliasInSelect)
          Adds a new JPA entity to the FROM clause.
 String fromIn(String collectionName, String alias, boolean includeCollectionAliasInSelect)
          Adds a new "IN (...)" expression containing the given collection expression into the FROM clause.
 String getAlias()
          Retrieves the initial alias of this Criteria instance.
 String getAlias(int index)
          Retrieves the alias associated with the given index.
 List<String> getAliases()
          Retrieves a copy of all the aliases defined for this Criteria instance.
 int getAliasIndex(String alias)
          Retrieves the index that points to the given alias.
 String getEntityName()
           
 Integer getSearchLimit()
          Retrieves the current limit on the result set size for this Criteria, if any (only relevant if creating a SELECT query).
 void groupBy(String attribute)
          Adds a new expression to the GROUP BY clause.
 void gt(String attribute, Object value)
          Adds a greater-than condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void gte(String attribute, Object value)
          Adds a greater-than-or-equal condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void having(Criteria having)
          Takes the conditions from the given Criteria's WHERE clause and then ANDs them with this instance's HAVING clause (or makes them become the new HAVING clause of this instance if its current HAVING clause is empty).
 void in(String attribute, Collection<?> values)
          Takes the individual elements of the provided collection, converts them to literals or assigns them to input parameters as needed, and adds a new "IN (...)" condition to the WHERE clause containing those elements, ANDing it with any existing conditions if necessary.
 void in(String attribute, Criteria in)
          Converts the given Criteria into a sub-SELECT query, surrounds it in parentheses, and adds a new "IN (...)" condition containing the resulting expression into the WHERE clause, while ANDing the new condition with any existing conditions if necessary.
 void in(String attribute, Object... values)
          Takes the provided values, converts them to literals or assigns them to input parameters as needed, and adds a new "IN (...)" condition to the WHERE clause containing those elements, ANDing it with any existing conditions if necessary.
 void isEmpty(String collection)
          Adds an IS EMPTY condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void isNull(String attribute)
          Adds an IS NULL condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 String join(String associationName, String alias, boolean includeAssociationAliasInSelect, boolean innerJoin)
          Adds a new JOIN to the most-recently-added entity in the FROM clause.
 void joinFetch(String associationName, boolean innerJoin)
          Adds a new JOIN FETCH to the most-recently-added entity in the FROM clause.
 void like(String attribute, Object value)
          Adds a new LIKE condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void likeEscape(String attribute, Object value, char escapeChar)
          Adds a new LIKE condition (containing an ESCAPE clause) to the WHERE clause, ANDing it with any existing conditions if necessary.
 void lt(String attribute, Object value)
          Adds a less-than condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void lte(String attribute, Object value)
          Adds a less-than-or-equal condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void memberOf(Object value, String collection)
          Adds a MEMBER OF condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void memberOf(String attribute, String collection)
          Adds a MEMBER OF condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void ne(String attribute, Object value)
          Adds a non-equality condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void not(Criteria not)
          Takes the conditions from the given Criteria's WHERE clause, surrounds them in parentheses, and adds a new "NOT (...)" condition containing the resulting expression to this instance's WHERE clause (or adds a new "AND NOT(...)" condition if the WHERE clause on the existing Criteria is not empty).
 void notBetween(String attribute, Object value1, Object value2)
          Adds a new NOT BETWEEN condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void notEmpty(String collection)
          Adds an IS NOT EMPTY condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void notExists(Criteria notExists)
          Converts the given Criteria into a sub-SELECT query, surrounds it in parentheses, and adds a new NOT EXISTS condition containing the resulting expression into the WHERE clause, while ANDing the new condition with any existing conditions if necessary.
 void notIn(String attribute, Collection<?> values)
          Takes the individual elements of the provided collection, converts them to literals or assigns them to input parameters as needed, and adds a new "IN (...)" condition to the WHERE clause containing those elements, ANDing it with any existing conditions if necessary.
 void notIn(String attribute, Criteria notIn)
          Converts the given Criteria into a sub-SELECT query, surrounds it in parentheses, and adds a new "NOT IN (...)" condition containing the resulting expression into the WHERE clause, while ANDing the new condition with any existing conditions if necessary.
 void notIn(String attribute, Object... values)
          Takes the provided values, converts them to literals or assigns them to input parameters as needed, and adds a new "NOT IN (...)" condition to the WHERE clause containing those elements, ANDing it with any existing conditions if necessary.
 void notLike(String attribute, Object value)
          Adds a new NOT LIKE condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void notLikeEscape(String attribute, Object value, char escapeChar)
          Adds a new NOT LIKE condition (containing an ESCAPE clause) to the WHERE clause, ANDing it with any existing conditions if necessary.
 void notMemberOf(Object value, String collection)
          Adds a NOT MEMBER OF condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void notMemberOf(String attribute, String collection)
          Adds a NOT MEMBER OF condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void notNull(String attribute)
          Adds an IS NOT NULL condition to the WHERE clause, ANDing it with any existing conditions if necessary.
 void or(Criteria or)
          Takes the conditions from the given Criteria's WHERE clause, surrounds them in parentheses, and ORs the resulting expression with this instance's WHERE clause (or makes the expression become the new WHERE clause of this instance if its current WHERE clause is empty).
 void orderBy(String attribute, boolean sortAscending)
          Adds a new expression to the ORDER BY clause.
 void orNot(Criteria orNot)
          Takes the conditions from the given Criteria's WHERE clause, surrounds them in parentheses, and adds a new "OR NOT (...)" condition containing the resulting expression to this instance's WHERE clause (or just adds a new "NOT (...)" condition if its current WHERE clause is empty).
 void prepareParameters(javax.persistence.Query query)
          Populates the given Query instance with the parameters stored in this Criteria.
 void rawJpql(String jpql)
          Inserts raw JPQL into the WHERE clause.
 void select(String resultExpression)
          Adds the given expression to the SELECT clause.
 void set(Map<String,Object> attributes)
          Adds one new attribute assignment expression to the SET clause for each entry in the given Map (for use with UPDATE queries).
 void set(String attributeName, Object value)
          Adds a new attribute assignment expression to the SET clause (for use with UPDATE queries).
 void setSearchLimit(Integer searchLimit)
          Sets the current limit on the result set size for this Criteria (only relevant if creating a SELECT query).
 String toCountQuery()
          Converts the current Criteria instance into a JPQL SELECT query, but replaces the existing SELECT clause with "SELECT COUNT(*)" instead.
 String toQuery(QueryByCriteria.QueryByCriteriaType type)
          Converts the current Criteria instance into a JPQL query.
 String toQuery(QueryByCriteria.QueryByCriteriaType type, String[] queryAttr)
          Converts the current Criteria instance into a JPQL query.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

JPA_ALIAS_PREFIX

public static final String JPA_ALIAS_PREFIX
The String representing the beginning of a by-name or by-index reference to an entity alias.

See Also:
Constant Field Values

JPA_PARAM_PREFIX

public static final String JPA_PARAM_PREFIX
The String representing the beginning of a by-name reference to an input parameter.

See Also:
Constant Field Values

JPA_ALIAS_SUFFIX

public static final String JPA_ALIAS_SUFFIX
The String representing the termination of by-name/index references to aliases or input parameters.

See Also:
Constant Field Values

params

protected Map<String,Object> params
Constructor Detail

Criteria

public Criteria(String entityName)
Constructs a new Criteria instance that includes the given initial entity. An alias will be auto-generated for this entity, and the entity's alias will be included in the SELECT clause if this Criteria is intended to be used as a SELECT query.

Parameters:
entityName - The class name of the initial JPA entity.

Criteria

public Criteria(String entityName,
                String alias)
Constructs a new Criteria instance that includes the given initial entity. The given alias will be used for this entity if it is non-null, and the alias will be included in the SELECT clause if this Criteria is intended to be used as a SELECT query.

Parameters:
entityName - The class name of the initial JPA entity.
alias - The alias to use for this entity; if it is null, a new alias will be auto-generated.

Criteria

public Criteria(String entityName,
                boolean includeEntityInSelect)
Constructs a new Criteria instance that includes the given initial entity. An alias will be auto-generated for this entity, and the extra parameter indicates whether this alias should also be added to the query's SELECT clause (if this Criteria is intended to be used as a SELECT query).

Parameters:
entityName - The class name of the initial JPA entity.
includeEntityInSelect - Indicates whether this entity's alias should be added to the SELECT clause.

Criteria

public Criteria(String entityName,
                String alias,
                boolean includeEntityAliasInSelect)
Constructs a new Criteria instance that includes the given initial entity. The given alias will be used for this entity if it is non-null, and the extra parameter indicates whether the alias should be added to the SELECT clause (if this Criteria is intended to be used as a SELECT query).

Parameters:
entityName - The class name of the initial JPA entity.
alias - The alias to use for this entity; if it is null, a new alias will be auto-generated.
includeEntityAliasInSelect - Indicates whether this entity's alias should be added to the SELECT clause.
Method Detail

select

public void select(String resultExpression)
Adds the given expression to the SELECT clause. If no properly-referenced alias appears in the String expression, it will be assumed that the expression is accessing something on or through the initial entity. See the description of this class for more information on how String expressions are interpreted.

Parameters:
resultExpression - The String expression to add to the SELECT clause.

from

public String from(String entityName,
                   String alias,
                   boolean includeEntityAliasInSelect)
Adds a new JPA entity to the FROM clause. The entity will be given the provided alias if it is non-null and does not conflict with any existing alias names; otherwise, a new alias name will be auto-generated. An extra parameter is also included for indicating whether this Criteria should automatically include the entity's alias in the SELECT clause.

Parameters:
entityName - The class name of the new entity.
alias - The alias to use for this entity.
includeEntityAliasInSelect - Indicates whether to include the entity's alias in the SELECT clause.
Returns:
The provided alias if it's non-null and does not conflict with any existing names, or an auto-generated alias name otherwise.

fromIn

public String fromIn(String collectionName,
                     String alias,
                     boolean includeCollectionAliasInSelect)
Adds a new "IN (...)" expression containing the given collection expression into the FROM clause. The collection will be given the provided alias if it is non-null and does not conflict with any existing alias names; otherwise, a new alias name will be auto-generated. An extra parameter is also included for indicating whether this Criteria should automatically include the collection's alias in the SELECT clause.

If no properly-referenced alias appears in the String expression, it will be assumed that the expression points to a collection that is accessible on or through the initial entity. See the description of this class for more information on how String expressions are interpreted.

Parameters:
collectionName - A String expression that points to an entity collection.
alias - The alias to use for this collection expression.
includeCollectionAliasInSelect - Indicates whether to include the collection's alias in the SELECT clause.
Returns:
The provided alias if it's non-null and does not conflict with any existing names, or an auto-generated alias name otherwise.

join

public String join(String associationName,
                   String alias,
                   boolean includeAssociationAliasInSelect,
                   boolean innerJoin)
Adds a new JOIN to the most-recently-added entity in the FROM clause. The association will be given the provided alias if it is non-null and does not conflict with any existing alias names; otherwise, a new alias name will be auto-generated. An extra parameter is also included for indicating whether this Criteria should automatically include the association's alias in the SELECT clause.

If no properly-referenced alias appears in the String expression, it will be assumed that the expression points to an association that is accessible on or through the initial entity. See the description of this class for more information on how String expressions are interpreted.

Parameters:
associationName - A String expression that points to an entity association.
alias - The alias to use for this association expression.
includeAssociationAliasInSelect - Indicates whether to include the collection's alias in the SELECT clause.
innerJoin - If true, the join will be an inner join; otherwise, it will be a left (outer) join.
Returns:
The provided alias if it's non-null and does not conflict with any existing names, or an auto-generated alias name otherwise.

joinFetch

public void joinFetch(String associationName,
                      boolean innerJoin)
Adds a new JOIN FETCH to the most-recently-added entity in the FROM clause. If no properly-referenced alias appears in the String expression, it will be assumed that the expression points to an association that is accessible on or through the initial entity. See the description of this class for more information on how String expressions are interpreted.

Parameters:
associationName - A String expression that points to an entity association.
innerJoin - If true, the join will be an inner join; otherwise, it will be a left (outer) join.

set

public void set(String attributeName,
                Object value)
Adds a new attribute assignment expression to the SET clause (for use with UPDATE queries). It is assumed that the given attribute belongs to the initial entity, so a custom alias should not be used.

Parameters:
attributeName - An expression pointing to an attribute that is accessible on or through the initial entity.
value - The value to assign to the attribute.

set

public void set(Map<String,Object> attributes)
Adds one new attribute assignment expression to the SET clause for each entry in the given Map (for use with UPDATE queries). It is assumed that the attributes belong to the initial entity, so custom aliases should not be used.

Parameters:
attributes - A Map containing expressions pointing to initial-entity-accessible attributes and their associated values.

between

public void between(String attribute,
                    Object value1,
                    Object value2)
Adds a new BETWEEN condition to the WHERE clause, ANDing it with any existing conditions if necessary.

Parameters:
attribute - An expression representing the subject of the BETWEEN condition.
value1 - The lower value of the BETWEEN condition.
value2 - The upper value of the BETWEEN condition.

notBetween

public void notBetween(String attribute,
                       Object value1,
                       Object value2)
Adds a new NOT BETWEEN condition to the WHERE clause, ANDing it with any existing conditions if necessary.

Parameters:
attribute - An expression representing the subject of the NOT BETWEEN condition.
value1 - The lower value of the NOT BETWEEN condition.
value2 - The upper value of the NOT BETWEEN condition.

eq

public void eq(String attribute,
               Object value)
Adds an equality condition to the WHERE clause, ANDing it with any existing conditions if necessary.

Parameters:
attribute - An expression representing the left-hand side of this condition.
value - The value to check for equality with.

gt

public void gt(String attribute,
               Object value)
Adds a greater-than condition to the WHERE clause, ANDing it with any existing conditions if necessary.

Parameters:
attribute - An expression representing the left-hand side of this condition.
value - The value on the right-hand side of the greater-than condition.

gte

public void gte(String attribute,
                Object value)
Adds a greater-than-or-equal condition to the WHERE clause, ANDing it with any existing conditions if necessary.

Parameters:
attribute - An expression representing the left-hand side of this condition.
value - The value on the right-hand side of the greater-than-or-equal condition.

like

public void like(String attribute,
                 Object value)
Adds a new LIKE condition to the WHERE clause, ANDing it with any existing conditions if necessary. If the provided value is not a String, its toString() representation will be used as the pattern.

Parameters:
attribute - An expression representing the left-hand side of this condition.
value - The pattern to compare with for "likeness".

notLike

public void notLike(String attribute,
                    Object value)
Adds a new NOT LIKE condition to the WHERE clause, ANDing it with any existing conditions if necessary. If the provided value is not a String, its toString() representation will be used as the pattern.

Parameters:
attribute - An expression representing the left-hand side of this condition.
value - The pattern to compare with for "non-likeness".

likeEscape

public void likeEscape(String attribute,
                       Object value,
                       char escapeChar)
Adds a new LIKE condition (containing an ESCAPE clause) to the WHERE clause, ANDing it with any existing conditions if necessary. If the provided value is not a String, its toString() representation will be used as the pattern.

Parameters:
attribute - An expression representing the left-hand side of this condition.
value - The pattern to compare with for "likeness".
escapeChar - The designated wildcard escape character for the given value.

notLikeEscape

public void notLikeEscape(String attribute,
                          Object value,
                          char escapeChar)
Adds a new NOT LIKE condition (containing an ESCAPE clause) to the WHERE clause, ANDing it with any existing conditions if necessary. If the provided value is not a String, its toString() representation will be used as the pattern.

Parameters:
attribute - An expression representing the left-hand side of this condition.
value - The pattern to compare with for "non-likeness".
escapeChar - The designated wildcard escape character for the given value.

lt

public void lt(String attribute,
               Object value)
Adds a less-than condition to the WHERE clause, ANDing it with any existing conditions if necessary.

Parameters:
attribute - An expression representing the left-hand side of this condition.
value - The value on the right-hand side of the less-than condition.

lte

public void lte(String attribute,
                Object value)
Adds a less-than-or-equal condition to the WHERE clause, ANDing it with any existing conditions if necessary.

Parameters:
attribute - An expression representing the left-hand side of this condition.
value - The value on the right-hand side of the less-than-or-equal condition.

ne

public void ne(String attribute,
               Object value)
Adds a non-equality condition to the WHERE clause, ANDing it with any existing conditions if necessary.

Parameters:
attribute - An expression representing the left-hand side of this condition.
value - The value on the right-hand side of the non-equality condition.

isNull

public void isNull(String attribute)
Adds an IS NULL condition to the WHERE clause, ANDing it with any existing conditions if necessary.

Parameters:
attribute - An expression representing what needs the null check.

notNull

public void notNull(String attribute)
Adds an IS NOT NULL condition to the WHERE clause, ANDing it with any existing conditions if necessary.

Parameters:
attribute - An expression representing what needs the not-null check.

memberOf

public void memberOf(Object value,
                     String collection)
Adds a MEMBER OF condition to the WHERE clause, ANDing it with any existing conditions if necessary. Uses an input parameter for the single-value part of the condition.

Parameters:
value - An Object that may or may not be in the specified collection.
collection - An expression representing a collection.

memberOf

public void memberOf(String attribute,
                     String collection)
Adds a MEMBER OF condition to the WHERE clause, ANDing it with any existing conditions if necessary. Uses an expression for the single-value part of the condition.

Parameters:
attribute - An expression pointing to an attribute that may or may not be in the given collection.
collection - An expression representing a collection.

notMemberOf

public void notMemberOf(Object value,
                        String collection)
Adds a NOT MEMBER OF condition to the WHERE clause, ANDing it with any existing conditions if necessary. Uses an input parameter for the single-value part of the condition.

Parameters:
value - An Object that may or may not be in the specified collection.
collection - An expression representing a collection.

notMemberOf

public void notMemberOf(String attribute,
                        String collection)
Adds a NOT MEMBER OF condition to the WHERE clause, ANDing it with any existing conditions if necessary. Uses an expression for the single-value part of the condition.

Parameters:
attribute - An expression pointing to an attribute that may or may not be in the given collection.
collection - An expression representing a collection.

isEmpty

public void isEmpty(String collection)
Adds an IS EMPTY condition to the WHERE clause, ANDing it with any existing conditions if necessary.

Parameters:
collection - An expression representing a collection.

notEmpty

public void notEmpty(String collection)
Adds an IS NOT EMPTY condition to the WHERE clause, ANDing it with any existing conditions if necessary.

Parameters:
collection - An expression representing a collection.

in

public void in(String attribute,
               Criteria in)
Converts the given Criteria into a sub-SELECT query, surrounds it in parentheses, and adds a new "IN (...)" condition containing the resulting expression into the WHERE clause, while ANDing the new condition with any existing conditions if necessary.

Parameters:
attribute - An expression representing the left-hand side of the "IN (...)" condition.
in - The Criteria representing the sub-query of the "IN (...)" condition.

notIn

public void notIn(String attribute,
                  Criteria notIn)
Converts the given Criteria into a sub-SELECT query, surrounds it in parentheses, and adds a new "NOT IN (...)" condition containing the resulting expression into the WHERE clause, while ANDing the new condition with any existing conditions if necessary.

Parameters:
attribute - An expression representing the left-hand side of the "NOT IN (...)" condition.
in - The Criteria representing the sub-query of the "NOT IN (...)" condition.

in

public void in(String attribute,
               Collection<?> values)
Takes the individual elements of the provided collection, converts them to literals or assigns them to input parameters as needed, and adds a new "IN (...)" condition to the WHERE clause containing those elements, ANDing it with any existing conditions if necessary. String, number, boolean, and Class collection elements will be converted into literals, and all other non-null collection elements will be assigned to input parameters.

Parameters:
attribute - An expression representing the left-hand side of the "IN (...)" condition.
values - The collection of values to check against.

notIn

public void notIn(String attribute,
                  Collection<?> values)
Takes the individual elements of the provided collection, converts them to literals or assigns them to input parameters as needed, and adds a new "IN (...)" condition to the WHERE clause containing those elements, ANDing it with any existing conditions if necessary. String, number, boolean, and Class collection elements will be converted into literals, and all other non-null collection elements will be assigned to input parameters.

Parameters:
attribute - An expression representing the left-hand side of the "NOT IN (...)" condition.
values - The collection of values to check against.

in

public void in(String attribute,
               Object... values)
Takes the provided values, converts them to literals or assigns them to input parameters as needed, and adds a new "IN (...)" condition to the WHERE clause containing those elements, ANDing it with any existing conditions if necessary. String, number, boolean, and Class values will be converted into literals, and all other non-null values will be assigned to input parameters.

Parameters:
attribute - An expression representing the left-hand side of the "IN (...)" condition.
values - The values to check against.

notIn

public void notIn(String attribute,
                  Object... values)
Takes the provided values, converts them to literals or assigns them to input parameters as needed, and adds a new "NOT IN (...)" condition to the WHERE clause containing those elements, ANDing it with any existing conditions if necessary. String, number, boolean, and Class values will be converted into literals, and all other non-null values will be assigned to input parameters.

Parameters:
attribute - An expression representing the left-hand side of the "NOT IN (...)" condition.
values - The values to check against.

and

public void and(Criteria and)
Takes the conditions from the given Criteria's WHERE clause, surrounds them in parentheses, and ANDs the resulting expression with this instance's WHERE clause (or makes the expression become the new WHERE clause of this instance if its current WHERE clause is empty). Any input parameters from the given Criteria will be copied over to this Criteria, and will be renamed as needed if conflicts arise.

Parameters:
and - The Criteria instance whose conditions should be ANDed with those in this Criteria instance.

not

public void not(Criteria not)
Takes the conditions from the given Criteria's WHERE clause, surrounds them in parentheses, and adds a new "NOT (...)" condition containing the resulting expression to this instance's WHERE clause (or adds a new "AND NOT(...)" condition if the WHERE clause on the existing Criteria is not empty). Any input parameters from the given Criteria will be copied over to this Criteria, and will be renamed as needed if conflicts arise.

Parameters:
not - The Criteria instance whose group of conditions should be negated.

or

public void or(Criteria or)
Takes the conditions from the given Criteria's WHERE clause, surrounds them in parentheses, and ORs the resulting expression with this instance's WHERE clause (or makes the expression become the new WHERE clause of this instance if its current WHERE clause is empty). Any input parameters from the given Criteria will be copied over to this Criteria, and will be renamed as needed if conflicts arise.

Parameters:
or - The Criteria instance whose conditions should be ORed with those in this Criteria instance.

orNot

public void orNot(Criteria orNot)
Takes the conditions from the given Criteria's WHERE clause, surrounds them in parentheses, and adds a new "OR NOT (...)" condition containing the resulting expression to this instance's WHERE clause (or just adds a new "NOT (...)" condition if its current WHERE clause is empty). Any input parameters from the given Criteria will be copied over to this Criteria, and will be renamed as needed if conflicts arise.

Parameters:
orNot - The Criteria instance whose group of conditions should be negated and then ORed with those in this Criteria instance.

exists

public void exists(Criteria exists)
Converts the given Criteria into a sub-SELECT query, surrounds it in parentheses, and adds a new EXISTS condition containing the resulting expression into the WHERE clause, while ANDing the new condition with any existing conditions if necessary.

Parameters:
exists - The Criteria instance representing the sub-query of the EXISTS condition.

notExists

public void notExists(Criteria notExists)
Converts the given Criteria into a sub-SELECT query, surrounds it in parentheses, and adds a new NOT EXISTS condition containing the resulting expression into the WHERE clause, while ANDing the new condition with any existing conditions if necessary.

Parameters:
exists - The Criteria instance representing the sub-query of the NOT EXISTS condition.

rawJpql

public void rawJpql(String jpql)
Inserts raw JPQL into the WHERE clause. An extra whitespace character will automatically be prepended (if the WHERE clause is non-empty) and appended to the JPQL string.

Parameters:
jpql - The raw JPQL to insert.

groupBy

public void groupBy(String attribute)
Adds a new expression to the GROUP BY clause. If no properly-referenced alias appears in the String expression, it will be assumed that the expression points to something that is accessible on or through the initial entity. See the description of this class for more information on how String expressions are interpreted.

Parameters:
attribute - The expression representing what the query results should be grouped by.

having

public void having(Criteria having)
Takes the conditions from the given Criteria's WHERE clause and then ANDs them with this instance's HAVING clause (or makes them become the new HAVING clause of this instance if its current HAVING clause is empty). Any input parameters from the given Criteria will be copied over to this Criteria, and will be renamed as needed if conflicts arise.

Parameters:
having - The Criteria instance whose WHERE clause should represent this instance's HAVING clause (or a piece of it).

orderBy

public void orderBy(String attribute,
                    boolean sortAscending)
Adds a new expression to the ORDER BY clause. If no properly-referenced alias appears in the String expression, it will be assumed that the expression points to something that is accessible on or through the initial entity. See the description of this class for more information on how String expressions are interpreted.

Parameters:
attribute - The expression representing what the query results should be ordered by.
sortAscending - If true, the order will be ascending; otherwise, it will be descending.

toQuery

public String toQuery(QueryByCriteria.QueryByCriteriaType type)
Converts the current Criteria instance into a JPQL query.

Parameters:
type - An indicator of what type of query should be generated (SELECT, UPDATE, or DELETE).
Returns:
A String representing the JPQL query generated by this Criteria instance.

toQuery

public String toQuery(QueryByCriteria.QueryByCriteriaType type,
                      String[] queryAttr)
Converts the current Criteria instance into a JPQL query. If a SELECT query is desired, then alternative String expressions to insert into the SELECT clause can be specified, though doing so is not required and must be done with care (see below).

WARNING! If queryAttr is non-null and has a length greater than zero, and if a SELECT query is desired, then this method will completely overwrite the SELECT clause so that it only contains the expressions given by the queryAttr array.

Parameters:
type - An indicator of what type of query should be generated (SELECT, UPDATE, or DELETE).
queryAttr - (Optional) An array of String expressions to use as the values to be returned by the SELECT clause (if creating a SELECT query).
Returns:
A String representing the JPQL query generated by this Criteria instance.

toCountQuery

public String toCountQuery()
Converts the current Criteria instance into a JPQL SELECT query, but replaces the existing SELECT clause with "SELECT COUNT(*)" instead.

Returns:
A JPQL query String given by this Criteria, but with "SELECT COUNT(*)" as the SELECT clause instead.

prepareParameters

public void prepareParameters(javax.persistence.Query query)
Populates the given Query instance with the parameters stored in this Criteria. It is assumed that the given query is using this Criteria's toQuery() or toCountQuery() value as its JPQL String.

Parameters:
query - A JPA Query instance containing this Criteria's toQuery() or toCountQuery() value for its JPQL String.

getSearchLimit

public Integer getSearchLimit()
Retrieves the current limit on the result set size for this Criteria, if any (only relevant if creating a SELECT query).

Returns:
The current limit on the number of results to be returned by this Criteria's query, or null (default) if no such limit has been set.

setSearchLimit

public void setSearchLimit(Integer searchLimit)
Sets the current limit on the result set size for this Criteria (only relevant if creating a SELECT query).

Parameters:
searchLimit - The new limit on the number of results to be returned by this Criteria's query.

distinct

public void distinct(boolean distinct)
Sets whether or not the query should include the DISTINCT keyword in the SELECT clause, if creating a SELECT query. If this property is not set explicitly, it is assumed that DISTINCT should *not* be included in the SELECT clause.

Parameters:
distinct - An indicator for whether to do a SELECT DISTINCT or just a SELECT.

getAlias

public String getAlias()
Retrieves the initial alias of this Criteria instance.

Returns:
The initial alias.

getAlias

public String getAlias(int index)
Retrieves the alias associated with the given index.

Parameters:
index - The index pointing to a given alias.
Returns:
The alias at the given index.

getAliasIndex

public int getAliasIndex(String alias)
Retrieves the index that points to the given alias.

Parameters:
alias - The indexed alias.
Returns:
The index of the alias, or -1 if no such index was found.

getAliases

public List<String> getAliases()
Retrieves a copy of all the aliases defined for this Criteria instance. The index of a given alias corresponds to the index at which the alias is located at in the returned List.

Returns:
A List containing all the defined aliases of this Criteria instance.

getEntityName

public String getEntityName()
Returns:
the name of the class of the initial Entity this Criteria will search for


Copyright © 2005-2012 The Kuali Foundation. All Rights Reserved.