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

    All Methods Static Methods Concrete Methods
    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.

Copyright © 2018. All rights reserved.