com.hazelcast.query

Class Predicates

java.lang.Object

com.hazelcast.query.Predicates

public final class Predicates
extends Object

A utility class to create new PredicateBuilder and Predicate instances.

Special Attributes

The predicate factory methods accepting an attribute name support two special attributes:

• "__key" - instructs the predicate to act on the key associated with an item.
• "this" - instructs the predicate to act on the value associated with an item.

Attribute Paths

Dot notation may be used for attribute name to instruct the predicate to act on the attribute located at deeper level of an item: given "fullName.firstName" path the predicate will act on firstName attribute of the value fetched by fullName attribute from the item itself. If any of the attributes along the path can't be resolved, IllegalArgumentException will be thrown. Reading of any attribute from null will produce null value.

Square brackets notation may be used to instruct the predicate to act on the array/collection element at the specified index: given "names[0]" path the predicate will act on the first item of the array/collection fetched by names attribute from the item. The index must be non-negative, otherwise IllegalArgumentException will be thrown. Reading from the index pointing beyond the end of the collection/array will produce null value.

Special any keyword may be used to act on every array/collection element: given "names[any].fullName.firstName" path the predicate will act on firstName attribute of the value fetched by fullName attribute from every array/collection element stored in the item itself under names attribute.

Handling of null

The predicate factory methods can accept null as a value to compare with or a pattern to match against if and only if that is explicitly stated in the method documentation. In this case, the usual null equality logic applies: if null is provided, the predicate passes an item if and only if the value stored under the item attribute in question is also null.

Special care must be taken while comparing with null values stored inside items being filtered through the predicates created by the following methods: greaterThan(java.lang.String, java.lang.Comparable), greaterEqual(java.lang.String, java.lang.Comparable), lessThan(java.lang.String, java.lang.Comparable), lessEqual(java.lang.String, java.lang.Comparable), between(java.lang.String, java.lang.Comparable, java.lang.Comparable). The predicates produced by these methods intentionally violate Comparable contract by not throwing NullPointerException for null values. Instead, they always evaluate to false and therefore never pass such items.

Implicit Type Conversion

If the type of the stored value doesn't match the type of the value provided to the predicate, implicit type conversion is performed before predicate evaluation. The provided value is converted to match the type of the stored attribute value. If no conversion matching the type exists, IllegalArgumentException is thrown.

Depending on the attribute type following conversions may apply:

• Numeric types
  • Strings are parsed in attempt to extract the represented numeric value from them in the same way as Integer.parseInt(String) and analogous methods of other types do. Strings containing no meaningful representation will produce NumberFormatException.
  • Widening conversion may be performed in the same way as described in JLS 5.1.2 Widening Primitive Conversions.
  • Narrowing conversion may be performed in the same way as described in JLS 5.1.3 Narrowing Primitive Conversions.
• Boolean type
  • A string that case-insensitively equals to "true" is converted to true, all other strings are converted to false.
  • Any non-zero numeric value is converted to true, the zero is converted to false.
• String type
  • Object.toString() is invoked to produce the string representation for non-string values.
• Character type
  • The first character of a string is used for the conversion. Empty strings are not allowed and will produce IllegalArgumentException.
  • Any numeric value is converted to an integer value representing a single UTF-16 code unit to create a character from. This process may involve widening and narrowing conversions as described in JLS 5.1.2 Widening Primitive Conversions and 5.1.3 Narrowing Primitive Conversions.
• Enum types
  • Any non-string value is converted to a string using Object.toString(), which is interpreted as a case-sensitive enum member name.
• BigInteger type
  • Numeric values are converted to BigInteger by applying widening or narrowing conversion as described in JLS 5.1.2 Widening Primitive Conversions and 5.1.3 Narrowing Primitive Conversions.
  • Boolean true and false are converted to BigInteger.ONE and BigInteger.ZERO respectively.
  • A value of any other type is converted to string using Object.toString(), which is interpreted as a base 10 representation in the same way as BigInteger(String) does. If the representation is invalid, NumberFormatException will be thrown.
• BigDecimal type
  • Numeric value are converted to BigDecimal by applying widening conversion as described in JLS 5.1.2 Widening Primitive Conversions.
  • Boolean true and false are converted to BigDecimal.ONE and BigDecimal.ZERO respectively.
  • A value of any other type is converted to string using Object.toString(), which is interpreted as a base 10 representation in the same way as BigDecimal(String) does. If the representation is invalid, NumberFormatException will be thrown.
• SQL Timestamp type
  • Date values are converted to SQL Timestamp by applying Date.getTime() on them.
  • String values are interpreted in the same way as Timestamp.valueOf(String) does. RuntimeException wrapping ParseException is thrown for invalid representations.
  • Any numeric value is interpreted as the number of milliseconds since January 1, 1970, 00:00:00 GMT by applying widening or narrowing conversion as described in JLS 5.1.2 Widening Primitive Conversions and 5.1.3 Narrowing Primitive Conversions.
• SQL Date type
  • String values are interpreted in the same way as Date.valueOf(String) does. RuntimeException wrapping ParseException is thrown for invalid representations.
  • Any numeric value is interpreted as the number of milliseconds since January 1, 1970, 00:00:00 GMT by applying widening or narrowing conversion as described in JLS 5.1.2 Widening Primitive Conversions and 5.1.3 Narrowing Primitive Conversions.
• Date type
  • String values are interpreted as having EEE MMM dd HH:mm:ss zzz yyyy format and US locale in the same way as SimpleDateFormat does. RuntimeException wrapping ParseException is thrown for invalid representations.
  • Any numeric value is interpreted as the number of milliseconds since January 1, 1970, 00:00:00 GMT by applying widening or narrowing conversion as described in JLS 5.1.2 Widening Primitive Conversions and 5.1.3 Narrowing Primitive Conversions.
• UUID type
  • String values are interpreted in the same way as UUID.fromString(String) does. IllegalArgumentException is thrown for invalid representations.

Method Summary

Modifier and Type	Method and Description
static <K,V> Predicate<K,V>	alwaysFalse() Creates an always false predicate that will filter out all items.
static <K,V> Predicate<K,V>	alwaysTrue() Creates an always true predicate that will pass all items.
static <K,V> Predicate<K,V>	and(Predicate... predicates) Creates an and predicate that will perform the logical and operation on the given predicates.
static <K,V> Predicate<K,V>	between(String attribute, Comparable from, Comparable to) Creates a between predicate that will pass items if the value stored under the given item attribute is contained inside the given range.
static <K,V> Predicate<K,V>	equal(String attribute, Comparable value) Creates an equal predicate that will pass items if the given value and the value stored under the given item attribute are equal.
static <K,V> Predicate<K,V>	greaterEqual(String attribute, Comparable value) Creates a greater than or equal to predicate that will pass items if the value stored under the given item attribute is greater than or equal to the given value.
static <K,V> Predicate<K,V>	greaterThan(String attribute, Comparable value) Creates a greater than predicate that will pass items if the value stored under the given item attribute is greater than the given value.
static <K,V> Predicate<K,V>	ilike(String attribute, String pattern) Creates a case-insensitive like predicate that will pass items if the given pattern matches the value stored under the given item attribute in a case-insensitive manner.
static <K,V> Predicate<K,V>	in(String attribute, Comparable... values) Creates a in predicate that will pass items if the value stored under the given item attribute is a member of the given values set.
static <K,V> Predicate<K,V>	instanceOf(Class klass) Creates an instance of predicate that will pass entries for which the value class is an instanceof the given klass.
static <K,V> Predicate<K,V>	lessEqual(String attribute, Comparable value) Creates a less than or equal to predicate that will pass items if the value stored under the given item attribute is less than or equal to the given value.
static <K,V> Predicate<K,V>	lessThan(String attribute, Comparable value) Creates a less than predicate that will pass items if the value stored under the given item attribute is less than the given value.
static <K,V> Predicate<K,V>	like(String attribute, String pattern) Creates a like predicate that will pass items if the given pattern matches the value stored under the given item attribute.
static <K,V> PartitionPredicate<K,V>	multiPartitionPredicate(Set<? extends Object> partitionKeys, Predicate<K,V> target) Creates a new partition predicate that restricts the execution of the target predicate to a subset of partitions.
static PredicateBuilder	newPredicateBuilder() Creates a new instance of PredicateBuilder.
static <K,V> Predicate<K,V>	not(Predicate predicate) Creates a not predicate that will negate the result of the given predicate.
static <K,V> Predicate<K,V>	notEqual(String attribute, Comparable value) Creates a not equal predicate that will pass items if the given value and the value stored under the given item attribute are not equal.
static <K,V> Predicate<K,V>	or(Predicate... predicates) Creates an or predicate that will perform the logical or operation on the given predicates.
static <K,V> PagingPredicate<K,V>	pagingPredicate(Comparator<Map.Entry<K,V>> comparator, int pageSize) Creates a paging predicate with a comparator and page size.
static <K,V> PagingPredicate<K,V>	pagingPredicate(int pageSize) Creates a paging predicate with a page size.
static <K,V> PagingPredicate<K,V>	pagingPredicate(Predicate<K,V> predicate, Comparator<Map.Entry<K,V>> comparator, int pageSize) Creates a paging predicate with an inner predicate, comparator and page size.
static <K,V> PagingPredicate<K,V>	pagingPredicate(Predicate predicate, int pageSize) Creates a paging predicate with an inner predicate and page size.
static <K,V> PartitionPredicate<K,V>	partitionPredicate(Object partitionKey, Predicate<K,V> target) Creates a new partition predicate that restricts the execution of the target predicate to a single partition.
static <K,V> Predicate<K,V>	regex(String attribute, String pattern) Creates a regex predicate that will pass items if the given pattern matches the value stored under the given item attribute.
static <K,V> Predicate<K,V>	sql(String expression) Creates a predicate that will pass items that match the given SQL 'where' expression.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newPredicateBuilder

public static PredicateBuilder newPredicateBuilder()

Creates a new instance of PredicateBuilder.

Returns:

the new PredicateBuilder instance.

alwaysTrue

public static <K,V> Predicate<K,V> alwaysTrue()

Creates an always true predicate that will pass all items.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

alwaysFalse

public static <K,V> Predicate<K,V> alwaysFalse()

Creates an always false predicate that will filter out all items.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

instanceOf

public static <K,V> Predicate<K,V> instanceOf(Class klass)

Creates an instance of predicate that will pass entries for which the value class is an instanceof the given klass.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

klass - the class the created predicate will check for.

Returns:

the created instance of predicate.

and

public static <K,V> Predicate<K,V> and(Predicate... predicates)

Creates an and predicate that will perform the logical and operation on the given predicates.

If the given predicates list is empty, the created predicate will always evaluate to true and will pass any item.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

predicates - the child predicates to form the resulting and predicate from.

Returns:

the created and predicate instance.

not

public static <K,V> Predicate<K,V> not(Predicate predicate)

Creates a not predicate that will negate the result of the given predicate.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

predicate - the predicate to negate the value of.

Returns:

the created not predicate instance.

or

public static <K,V> Predicate<K,V> or(Predicate... predicates)

Creates an or predicate that will perform the logical or operation on the given predicates.

If the given predicates list is empty, the created predicate will always evaluate to false and will never pass any items.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

predicates - the child predicates to form the resulting or predicate from.

Returns:

the created or predicate instance.

notEqual

public static <K,V> Predicate<K,V> notEqual(String attribute,
                                            Comparable value)

Creates a not equal predicate that will pass items if the given value and the value stored under the given item attribute are not equal.

See also Special Attributes, Attribute Paths, Handling of null and Implicit Type Conversion sections of Predicates.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

attribute - the attribute to fetch the value for comparison from.

value - the value to compare the attribute value against. Can be null.

Returns:

the created not equal predicate instance.

Throws:

IllegalArgumentException - if the attribute does not exist.

equal

public static <K,V> Predicate<K,V> equal(String attribute,
                                         Comparable value)

Creates an equal predicate that will pass items if the given value and the value stored under the given item attribute are equal.

See also Special Attributes, Attribute Paths, Handling of null and Implicit Type Conversion sections of Predicates.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

attribute - the attribute to fetch the value for comparison from.

value - the value to compare the attribute value against. Can be null.

Returns:

the created equal predicate instance.

Throws:

IllegalArgumentException - if the attribute does not exist.

like

public static <K,V> Predicate<K,V> like(String attribute,
                                        String pattern)

Creates a like predicate that will pass items if the given pattern matches the value stored under the given item attribute.

See also Special Attributes, Attribute Paths and Handling of null sections of Predicates.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

attribute - the attribute to fetch the value for matching from.

pattern - the pattern to match the attribute value against. The % (percentage sign) is a placeholder for multiple characters, the _ (underscore) is a placeholder for a single character. If you need to match the percentage sign or the underscore character itself, escape it with the backslash, for example "\\%" string will match the percentage sign. Can be null.

Returns:

the created like predicate instance.

Throws:

IllegalArgumentException - if the attribute does not exist.

See Also:

ilike(String, String), regex(String, String)

ilike

public static <K,V> Predicate<K,V> ilike(String attribute,
                                         String pattern)

Creates a case-insensitive like predicate that will pass items if the given pattern matches the value stored under the given item attribute in a case-insensitive manner.

See also Special Attributes, Attribute Paths and Handling of null sections of Predicates.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

attribute - the attribute to fetch the value for matching from.

pattern - the pattern to match the attribute value against. The % (percentage sign) is a placeholder for multiple characters, the _ (underscore) is a placeholder for a single character. If you need to match the percentage sign or the underscore character itself, escape it with the backslash, for example "\\%" string will match the percentage sign. Can be null.

Returns:

the created case-insensitive like predicate instance.

Throws:

IllegalArgumentException - if the attribute does not exist.

See Also:

like(String, String), regex(String, String)

regex

public static <K,V> Predicate<K,V> regex(String attribute,
                                         String pattern)

Creates a regex predicate that will pass items if the given pattern matches the value stored under the given item attribute.

See also Special Attributes, Attribute Paths and Handling of null sections of Predicates.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

attribute - the attribute to fetch the value for matching from.

pattern - the pattern to match the attribute value against. The pattern interpreted exactly the same as described in Pattern. Can be null.

Returns:

the created regex predicate instance.

Throws:

IllegalArgumentException - if the attribute does not exist.

See Also:

like(String, String), ilike(String, String)

greaterThan

public static <K,V> Predicate<K,V> greaterThan(String attribute,
                                               Comparable value)

Creates a greater than predicate that will pass items if the value stored under the given item attribute is greater than the given value.

See also Special Attributes, Attribute Paths, Handling of null and Implicit Type Conversion sections of Predicates.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

attribute - the left-hand side attribute to fetch the value for comparison from.

value - the right-hand side value to compare the attribute value against.

Returns:

the created greater than predicate.

Throws:

IllegalArgumentException - if the attribute does not exist.

greaterEqual

public static <K,V> Predicate<K,V> greaterEqual(String attribute,
                                                Comparable value)

Creates a greater than or equal to predicate that will pass items if the value stored under the given item attribute is greater than or equal to the given value.

See also Special Attributes, Attribute Paths, Handling of null and Implicit Type Conversion sections of Predicates.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

attribute - the left-hand side attribute to fetch the value for comparison from.

value - the right-hand side value to compare the attribute value against.

Returns:

the created greater than or equal to predicate.

Throws:

IllegalArgumentException - if the attribute does not exist.

lessThan

public static <K,V> Predicate<K,V> lessThan(String attribute,
                                            Comparable value)

Creates a less than predicate that will pass items if the value stored under the given item attribute is less than the given value.

See also Special Attributes, Attribute Paths, Handling of null and Implicit Type Conversion sections of Predicates.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

attribute - the left-hand side attribute to fetch the value for comparison from.

value - the right-hand side value to compare the attribute value against.

Returns:

the created less than predicate.

Throws:

IllegalArgumentException - if the attribute does not exist.

lessEqual

public static <K,V> Predicate<K,V> lessEqual(String attribute,
                                             Comparable value)

Creates a less than or equal to predicate that will pass items if the value stored under the given item attribute is less than or equal to the given value.

See also Special Attributes, Attribute Paths, Handling of null and Implicit Type Conversion sections of Predicates.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

attribute - the left-hand side attribute to fetch the value for comparison from.

value - the right-hand side value to compare the attribute value against.

Returns:

the created less than or equal to predicate.

Throws:

IllegalArgumentException - if the attribute does not exist.

between

public static <K,V> Predicate<K,V> between(String attribute,
                                           Comparable from,
                                           Comparable to)

Creates a between predicate that will pass items if the value stored under the given item attribute is contained inside the given range. The range begins at the given from bound and ends at the given to bound. The bounds are inclusive.

See also Special Attributes, Attribute Paths, Handling of null and Implicit Type Conversion sections of Predicates.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

attribute - the attribute to fetch the value to check from.

from - the inclusive lower bound of the range to check.

to - the inclusive upper bound of the range to check.

Returns:

the created between predicate.

Throws:

IllegalArgumentException - if the attribute does not exist.

in

public static <K,V> Predicate<K,V> in(String attribute,
                                      Comparable... values)

Creates a in predicate that will pass items if the value stored under the given item attribute is a member of the given values set.

See also Special Attributes, Attribute Paths, Handling of null and Implicit Type Conversion sections of Predicates.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

attribute - the attribute to fetch the value to test from.

values - the values set to test the membership in. Individual values can be null.

Returns:

the created in predicate.

Throws:

IllegalArgumentException - if the attribute does not exist.

sql

public static <K,V> Predicate<K,V> sql(String expression)

Creates a predicate that will pass items that match the given SQL 'where' expression. The following operators are supported: =, <, >, <=, >=, ==, !=, <>, BETWEEN, IN, LIKE, ILIKE, REGEX, AND, OR and NOT. The operators are case-insensitive, but attribute names are case sensitive.

Example: active AND (age > 20 OR salary < 60000)

See also Special Attributes, Attribute Paths, Handling of null and Implicit Type Conversion sections of Predicates.

Differences to standard SQL:

• we don't use ternary boolean logic. field=10 evaluates to false, if field is null, in standard SQL it evaluates to UNKNOWN.
• IS [NOT] NULL is not supported, use =NULL or <>NULL
• IS [NOT] DISTINCT FROM is not supported, but = and <> behave like it.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

expression - the 'where' expression.

Returns:

the created sql predicate instance.

Throws:

IllegalArgumentException - if the SQL expression is invalid.

pagingPredicate

public static <K,V> PagingPredicate<K,V> pagingPredicate(int pageSize)

Creates a paging predicate with a page size. Results will not be filtered and will be returned in natural order.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

pageSize - page size

Throws:

IllegalArgumentException - if pageSize is not greater than 0

pagingPredicate

public static <K,V> PagingPredicate<K,V> pagingPredicate(Predicate predicate,
                                                         int pageSize)

Creates a paging predicate with an inner predicate and page size. Results will be filtered via inner predicate and will be returned in natural order.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

predicate - the inner predicate through which results will be filtered

pageSize - the page size

Throws:

IllegalArgumentException - if pageSize is not greater than 0

IllegalArgumentException - if inner predicate is also a paging predicate

pagingPredicate

public static <K,V> PagingPredicate<K,V> pagingPredicate(Comparator<Map.Entry<K,V>> comparator,
                                                         int pageSize)

Creates a paging predicate with a comparator and page size. Results will not be filtered and will be ordered via comparator.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

comparator - the comparator through which results will be ordered

pageSize - the page size

Throws:

IllegalArgumentException - if pageSize is not greater than 0

pagingPredicate

public static <K,V> PagingPredicate<K,V> pagingPredicate(Predicate<K,V> predicate,
                                                         Comparator<Map.Entry<K,V>> comparator,
                                                         int pageSize)

Creates a paging predicate with an inner predicate, comparator and page size. Results will be filtered via inner predicate and will be ordered via comparator.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

predicate - the inner predicate through which results will be filtered

comparator - the comparator through which results will be ordered

pageSize - the page size

Throws:

IllegalArgumentException - if pageSize is not greater than 0

IllegalArgumentException - if inner predicate is also a PagingPredicate

partitionPredicate

public static <K,V> PartitionPredicate<K,V> partitionPredicate(Object partitionKey,
                                                               Predicate<K,V> target)

Creates a new partition predicate that restricts the execution of the target predicate to a single partition.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

partitionKey - the partition key

target - the target Predicate

Throws:

NullPointerException - if partitionKey or target predicate are null

multiPartitionPredicate

public static <K,V> PartitionPredicate<K,V> multiPartitionPredicate(Set<? extends Object> partitionKeys,
                                                                    Predicate<K,V> target)

Creates a new partition predicate that restricts the execution of the target predicate to a subset of partitions.

Type Parameters:

K - the type of keys the predicate operates on.

V - the type of values the predicate operates on.

Parameters:

partitionKeys - the partition keys

target - the target Predicate

Throws:

NullPointerException - if partitionKeys or target predicate are null

IllegalArgumentException - if partitionkeys is an empty set