Package org.apache.commons.beanutils2

# Class BeanPropertyValueEqualsPredicate<T,V>

java.lang.Object
org.apache.commons.beanutils2.BeanPropertyValueEqualsPredicate<T,V>

Type Parameters:
  `T` - The type of the input to the predicate.
  `V` - The property value type.

All Implemented Interfaces:
  `Predicate<T>`

public class BeanPropertyValueEqualsPredicate<T,V> extends Object implements Predicate<T>

`Predicate` that evaluates a property value against a specified value.

An implementation of `Predicate` that evaluates a property value on the object provided against a specified value and returns `true` if equal; `false` otherwise. The `BeanPropertyValueEqualsPredicate` constructor takes two parameters which determine what property will be evaluated on the target object and what its expected value should be.

`public BeanPropertyValueEqualsPredicate( String propertyName, Object propertyValue )`
  Will create a `Predicate` that will evaluate the target object and return `true</code> if the property specified by <code>propertyName` has a value which is equal to the value specified by `propertyValue`. Or return `false` otherwise.

Note: Property names can be a simple, nested, indexed, or mapped property as defined by `org.apache.commons.beanutils2.PropertyUtils`. If any object in the property path specified by `propertyName</code> is <code>null` then the outcome is based on the value of the `ignoreNull` attribute.

A typical usage might look like:

     // create the closure
     BeanPropertyValueEqualsPredicate predicate =
        new BeanPropertyValueEqualsPredicate( "activeEmployee", Boolean.FALSE );

     // filter the Collection
     CollectionUtils.filter( peopleCollection, predicate );

This would take a `Collection` of person objects and filter out any people whose `activeEmployee</code> property is <code>false`. Assuming...

- The top level object in the `peopleCollection` is an object which represents a person.
- The person object has a `getActiveEmployee()` method which returns the boolean value for the object's `activeEmployee` property.

Another typical usage might look like:

     // create the closure
     BeanPropertyValueEqualsPredicate predicate =
        new BeanPropertyValueEqualsPredicate( "personId", "456-12-1234" );

     // search the Collection
     CollectionUtils.find( peopleCollection, predicate );

This would search a `Collection` of person objects and return the first object whose `personId</code> property value equals <code>456-12-1234`. Assuming...

- The top level object in the `peopleCollection` is an object which represents a person.
- The person object has a `getPersonId()` method which returns the value for the object's `personId` property.

See Also:
  - `PropertyUtils`
  - `Predicate`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BeanPropertyValueEqualsPredicate(String propertyName, V propertyValue)`
  Constructor which takes the name of the property, its expected value to be used in evaluation, and assumes `ignoreNull</code> to be <code>false`.
  `BeanPropertyValueEqualsPredicate(String propertyName, V propertyValue, boolean ignoreNull)`
  Constructor which takes the name of the property, its expected value to be used in evaluation, and a boolean which determines whether `null` objects in the property path will generate an `IllegalArgumentException` or not.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected boolean`
  `evaluateValue(V expected, Object actual)`
  Utility method which evaluates whether the actual property value equals the expected property value.
  `String`
  `getPropertyName()`
  Returns the name of the property which will be evaluated when this `Predicate` is executed.
  `V`
  `getPropertyValue()`
  Returns the value that the property specified by `propertyName` will be compared to when this `Predicate` executes.
  `boolean`
  `isIgnoreNull()`
  Returns the flag which determines whether `null` objects in the property path will generate an `IllegalArgumentException</code> or not. If set to <code>true` then if any objects in the property path evaluate to `null` then the `IllegalArgumentException</code> throw by <code>PropertyUtils` will be logged but not re-thrown and `false</code> will be returned. If set to <code>false` then if any objects in the property path evaluate to `null` then the `IllegalArgumentException</code> throw by <code>PropertyUtils` will be logged and re-thrown.
  `boolean`
  `test(T object)`
  Evaluates the object provided against the criteria specified when this `BeanPropertyValueEqualsPredicate` was constructed.

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface java.util.function.Predicate

  `and, negate, or`

- ## Constructor Details

  - ### BeanPropertyValueEqualsPredicate

    public BeanPropertyValueEqualsPredicate(String propertyName, V propertyValue)
    Constructor which takes the name of the property, its expected value to be used in evaluation, and assumes `ignoreNull</code> to be <code>false`.
    Parameters:
      `propertyName` - The name of the property that will be evaluated against the expected value.
      `propertyValue` - The value to use in object evaluation.
    Throws:
      `IllegalArgumentException` - If the property name provided is null or empty.

  - ### BeanPropertyValueEqualsPredicate

    public BeanPropertyValueEqualsPredicate(String propertyName, V propertyValue, boolean ignoreNull)
    Constructor which takes the name of the property, its expected value to be used in evaluation, and a boolean which determines whether `null` objects in the property path will generate an `IllegalArgumentException` or not.
    Parameters:
      `propertyName` - The name of the property that will be evaluated against the expected value.
      `propertyValue` - The value to use in object evaluation.
      `ignoreNull` - Determines whether `null` objects in the property path will generate an `IllegalArgumentException` or not.
    Throws:
      `IllegalArgumentException` - If the property name provided is null or empty.

- ## Method Details

  - ### evaluateValue

    protected boolean evaluateValue(V expected, Object actual)
    Utility method which evaluates whether the actual property value equals the expected property value.
    Parameters:
      `expected` - The expected value.
      `actual` - The actual value.
    Returns:
      True if they are equal; false otherwise.

  - ### getPropertyName

    public String getPropertyName()
    Returns the name of the property which will be evaluated when this `Predicate` is executed.
    Returns:
      The name of the property which will be evaluated when this `Predicate` is executed.

  - ### getPropertyValue

    public V getPropertyValue()
    Returns the value that the property specified by `propertyName` will be compared to when this `Predicate` executes.
    Returns:
      The value that the property specified by `propertyName` will be compared to when this `Predicate` executes.

  - ### isIgnoreNull

    public boolean isIgnoreNull()
    Returns the flag which determines whether `null` objects in the property path will generate an `IllegalArgumentException</code> or not. If set to <code>true` then if any objects in the property path evaluate to `null` then the `IllegalArgumentException</code> throw by <code>PropertyUtils` will be logged but not re-thrown and `false</code> will be returned. If set to <code>false` then if any objects in the property path evaluate to `null` then the `IllegalArgumentException</code> throw by <code>PropertyUtils` will be logged and re-thrown.
    Returns:
      The flag which determines whether `null` objects in the property path will generate an `IllegalArgumentException` or not.

  - ### test

    public boolean test(T object)
    Evaluates the object provided against the criteria specified when this `BeanPropertyValueEqualsPredicate` was constructed. Equality is based on either reference or logical equality as defined by the property object's equals method. If any object in the property path leading up to the target property is `null` then the outcome will be based on the value of the `ignoreNull` attribute. By default, `ignoreNull</code> is <code>false` and would result in an `IllegalArgumentException` if an object in the property path leading up to the target property is `null`. @param object The object to be evaluated. @return True if the object provided meets all the criteria for this `Predicate`; false otherwise.
    Specified by:
      `test` in interface `Predicate<T>`
    Throws:
      `IllegalArgumentException` - If an IllegalAccessException, InvocationTargetException, or NoSuchMethodException is thrown when trying to access the property specified on the object provided. Or if an object in the property path provided is `null` and `ignoreNull</code> is set to <code>false`.