Class Predicates
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 produceNumberFormatException
. - 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.
- Strings are parsed in attempt to extract the represented numeric value from them in the same way as
Boolean
type- A string that case-insensitively equals to
"true"
is converted totrue
, all other strings are converted tofalse
. - Any non-zero numeric value is converted to
true
, the zero is converted tofalse
.
- A string that case-insensitively equals to
- 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.
- The first character of a string is used for the conversion. Empty strings are not allowed and will produce
- Enum types
- Any non-string value is converted to a string using
Object.toString()
, which is interpreted as a case-sensitive enum member name.
- Any non-string value is converted to a string using
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
andfalse
are converted toBigInteger.ONE
andBigInteger.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 asBigInteger(String)
does. If the representation is invalid,NumberFormatException
will be thrown.
- Numeric values are converted to
BigDecimal
type- Numeric value are converted to
BigDecimal
by applying widening conversion as described in JLS 5.1.2 Widening Primitive Conversions. - Boolean
true
andfalse
are converted toBigDecimal.ONE
andBigDecimal.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 asBigDecimal(String)
does. If the representation is invalid,NumberFormatException
will be thrown.
- Numeric value are converted to
SQL Timestamp
type- Date values are converted to
SQL Timestamp
by applyingDate.getTime()
on them. - String values are interpreted in the same way as
Timestamp.valueOf(String)
does.RuntimeException
wrappingParseException
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 values are converted to
SQL Date
type- String values are interpreted in the same way as
Date.valueOf(String)
does.RuntimeException
wrappingParseException
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.
- String values are interpreted in the same way as
Date
type- String values are interpreted as having EEE MMM dd HH:mm:ss zzz yyyy format and
US
locale in the same way asSimpleDateFormat
does.RuntimeException
wrappingParseException
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.
- String values are interpreted as having EEE MMM dd HH:mm:ss zzz yyyy format and
UUID
type- String values are interpreted in the same way as
UUID.fromString(String)
does.IllegalArgumentException
is thrown for invalid representations.
- String values are interpreted in the same way as
-
Method Summary
Modifier and TypeMethodDescriptionstatic <K,
V> Predicate<K, V> Creates an always false predicate that will filter out all items.static <K,
V> Predicate<K, V> Creates an always true predicate that will pass all items.static <K,
V> Predicate<K, V> Creates an and predicate that will perform the logical and operation on the givenpredicates
.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 itemattribute
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 givenvalue
and the value stored under the given itemattribute
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 itemattribute
is greater than or equal to the givenvalue
.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 itemattribute
is greater than the givenvalue
.static <K,
V> Predicate<K, V> Creates a case-insensitive like predicate that will pass items if the givenpattern
matches the value stored under the given itemattribute
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 itemattribute
is a member of the givenvalues
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 aninstanceof
the givenklass
.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 itemattribute
is less than or equal to the givenvalue
.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 itemattribute
is less than the givenvalue
.static <K,
V> Predicate<K, V> Creates a like predicate that will pass items if the givenpattern
matches the value stored under the given itemattribute
.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
Creates a new instance ofPredicateBuilder
.static <K,
V> Predicate<K, V> Creates a not predicate that will negate the result of the givenpredicate
.static <K,
V> Predicate<K, V> notEqual
(String attribute, Comparable value) Creates a not equal predicate that will pass items if the givenvalue
and the value stored under the given itemattribute
are not equal.static <K,
V> Predicate<K, V> Creates an or predicate that will perform the logical or operation on the givenpredicates
.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> 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> 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> Creates a regex predicate that will pass items if the givenpattern
matches the value stored under the given itemattribute
.static <K,
V> Predicate<K, V> Creates a predicate that will pass items that match the given SQL 'where' expression.
-
Method Details
-
newPredicateBuilder
Creates a new instance ofPredicateBuilder
.- Returns:
- the new
PredicateBuilder
instance.
-
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
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
Creates an instance of predicate that will pass entries for which the value class is aninstanceof
the givenklass
.- 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
Creates an and predicate that will perform the logical and operation on the givenpredicates
.If the given
predicates
list is empty, the created predicate will always evaluate totrue
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
Creates a not predicate that will negate the result of the givenpredicate
.- 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
Creates an or predicate that will perform the logical or operation on the givenpredicates
.If the given
predicates
list is empty, the created predicate will always evaluate tofalse
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
Creates a not equal predicate that will pass items if the givenvalue
and the value stored under the given itemattribute
are not equal.See also Special Attributes, Attribute Paths, Handling of
null
and Implicit Type Conversion sections ofPredicates
.- 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 benull
.- Returns:
- the created not equal predicate instance.
- Throws:
IllegalArgumentException
- if theattribute
does not exist.
-
equal
Creates an equal predicate that will pass items if the givenvalue
and the value stored under the given itemattribute
are equal.See also Special Attributes, Attribute Paths, Handling of
null
and Implicit Type Conversion sections ofPredicates
.- 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 benull
.- Returns:
- the created equal predicate instance.
- Throws:
IllegalArgumentException
- if theattribute
does not exist.
-
like
Creates a like predicate that will pass items if the givenpattern
matches the value stored under the given itemattribute
.See also Special Attributes, Attribute Paths and Handling of
null
sections ofPredicates
.- 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 benull
.- Returns:
- the created like predicate instance.
- Throws:
IllegalArgumentException
- if theattribute
does not exist.- See Also:
-
ilike
Creates a case-insensitive like predicate that will pass items if the givenpattern
matches the value stored under the given itemattribute
in a case-insensitive manner.See also Special Attributes, Attribute Paths and Handling of
null
sections ofPredicates
.- 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 benull
.- Returns:
- the created case-insensitive like predicate instance.
- Throws:
IllegalArgumentException
- if theattribute
does not exist.- See Also:
-
regex
Creates a regex predicate that will pass items if the givenpattern
matches the value stored under the given itemattribute
.See also Special Attributes, Attribute Paths and Handling of
null
sections ofPredicates
.- 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 inPattern
. Can benull
.- Returns:
- the created regex predicate instance.
- Throws:
IllegalArgumentException
- if theattribute
does not exist.- See Also:
-
greaterThan
Creates a greater than predicate that will pass items if the value stored under the given itemattribute
is greater than the givenvalue
.See also Special Attributes, Attribute Paths, Handling of
null
and Implicit Type Conversion sections ofPredicates
.- 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 theattribute
does not exist.
-
greaterEqual
Creates a greater than or equal to predicate that will pass items if the value stored under the given itemattribute
is greater than or equal to the givenvalue
.See also Special Attributes, Attribute Paths, Handling of
null
and Implicit Type Conversion sections ofPredicates
.- 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 theattribute
does not exist.
-
lessThan
Creates a less than predicate that will pass items if the value stored under the given itemattribute
is less than the givenvalue
.See also Special Attributes, Attribute Paths, Handling of
null
and Implicit Type Conversion sections ofPredicates
.- 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 theattribute
does not exist.
-
lessEqual
Creates a less than or equal to predicate that will pass items if the value stored under the given itemattribute
is less than or equal to the givenvalue
.See also Special Attributes, Attribute Paths, Handling of
null
and Implicit Type Conversion sections ofPredicates
.- 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 theattribute
does not exist.
-
between
Creates a between predicate that will pass items if the value stored under the given itemattribute
is contained inside the given range. The range begins at the givenfrom
bound and ends at the givento
bound. The bounds are inclusive.See also Special Attributes, Attribute Paths, Handling of
null
and Implicit Type Conversion sections ofPredicates
.- 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 theattribute
does not exist.
-
in
Creates a in predicate that will pass items if the value stored under the given itemattribute
is a member of the givenvalues
set.See also Special Attributes, Attribute Paths, Handling of
null
and Implicit Type Conversion sections ofPredicates
.- 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 benull
.- Returns:
- the created in predicate.
- Throws:
IllegalArgumentException
- if theattribute
does not exist.
-
sql
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
andNOT
. 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 ofPredicates
.Differences to standard SQL:
- we don't use ternary boolean logic.
field=10
evaluates tofalse
, iffield
isnull
, in standard SQL it evaluates toUNKNOWN
. 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.
- we don't use ternary boolean logic.
-
pagingPredicate
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
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 filteredpageSize
- the page size- Throws:
IllegalArgumentException
- if pageSize is not greater than 0IllegalArgumentException
- 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 orderedpageSize
- 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 filteredcomparator
- the comparator through which results will be orderedpageSize
- the page size- Throws:
IllegalArgumentException
- if pageSize is not greater than 0IllegalArgumentException
- if inner predicate is also aPagingPredicate
-
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 keytarget
- the targetPredicate
- Throws:
NullPointerException
- if partitionKey or target predicate arenull
-
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 keystarget
- the targetPredicate
- Throws:
NullPointerException
- if partitionKeys or target predicate arenull
IllegalArgumentException
- if partitionkeys is an empty set
-