com.hazelcast.query

Class Predicates

java.lang.Object

com.hazelcast.query.Predicates

public final class Predicates
extends Object

A utility class to create 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 Predicate	and(Predicate... predicates) Creates an and predicate that will perform the logical and operation on the given predicates.
static Predicate	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 Predicate	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 Predicate	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 Predicate	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 Predicate	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 Predicate	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 Predicate	instanceOf(Class klass) Creates an instance of predicate that will pass entries for which the value class is an instanceof the given klass.
static Predicate	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 Predicate	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 Predicate	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 Predicate	not(Predicate predicate) Creates a not predicate that will negate the result of the given predicate.
static Predicate	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 Predicate	or(Predicate... predicates) Creates an or predicate that will perform the logical or operation on the given predicates.
static Predicate	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.

Methods inherited from class java.lang.Object

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

Method Detail

alwaysTrue

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

Creates an always true predicate that will pass all items.

alwaysFalse

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

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

instanceOf

public static Predicate instanceOf(Class klass)

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

Parameters:

klass - the class the created predicate will check for.

Returns:

the created instance of predicate.

and

public static Predicate 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.

Parameters:

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

Returns:

the created and predicate instance.

not

public static Predicate not(Predicate predicate)

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

Parameters:

predicate - the predicate to negate the value of.

Returns:

the created not predicate instance.

or

public static Predicate 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.

Parameters:

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

Returns:

the created or predicate instance.

notEqual

public static Predicate 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.

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 Predicate 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.

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 Predicate 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.

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 Predicate 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.

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 Predicate 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.

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 Predicate 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.

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 Predicate 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.

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 Predicate 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.

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 Predicate 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.

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 Predicate 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.

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 Predicate 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.

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.