A utility class to create
com.hazelcast.query.Predicate instances.
Special Attributes
The predicate factory methods accepting an attribute name support two special attributes:
-
QueryConstants#KEY_ATTRIBUTE_NAME - instructs the predicate to act on the key associated
with an item.
-
QueryConstants#THIS_ATTRIBUTE_NAME - 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
nullwill 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
namesattribute.
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,
#greaterEqual,
#lessThan,
#lessEqual,
#between. The predicates produced by these methods intentionally violate
Comparablecontract 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:
-
Number
- 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.
-
java.math.BigInteger type
- Numeric values are converted to
java.math.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
java.math.BigInteger#ONEand
java.math.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
java.math.BigInteger#BigInteger(String) does.
If the representation is invalid,
NumberFormatException will be thrown.
-
java.math.BigDecimal type
- Numeric value are converted to
java.math.BigDecimal by applying widening conversion as
described in JLS 5.1.2 Widening Primitive Conversions.
- Boolean
true and
false are converted to
java.math.BigDecimal#ONEand
java.math.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
java.math.BigDecimal#BigDecimal(String) does.
If the representation is invalid,
NumberFormatException will be thrown.
-
java.sql.Timestamp type
- Date values are converted to
java.sql.Timestamp by applying
Date#getTime() on them.
- String values are interpreted in the same way as
java.sql.Timestamp#valueOf(String) does.
RuntimeException wrapping
java.text.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.
-
java.sql.Date type
- String values are interpreted in the same way as
java.sql.Date#valueOf(String) does.
RuntimeException wrapping
java.text.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
java.util.Locale#US locale in the same way as
java.text.SimpleDateFormat does.
RuntimeException wrapping
java.text.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.
-
java.util.UUID type
- String values are interpreted in the same way as
java.util.UUID#fromString(String) does.
IllegalArgumentException is thrown for invalid representations.