Package org.apache.commons.beanutils2

# Class BeanPropertyValueChangeConsumer<T,V>

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

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

All Implemented Interfaces:
  `Consumer<T>`

public class BeanPropertyValueChangeConsumer<T,V> extends Object implements Consumer<T>

`Closure` that sets a property.

An implementation of `Consumer` that updates a specified property on the object provided with a specified value. The `BeanPropertyValueChangeClosure` constructor takes two parameters which determine what property will be updated and with what value.

`public BeanPropertyValueChangeClosure( String propertyName, Object propertyValue )`
  Will create a `Closure` that will update an object by setting the property specified by `propertyName</code> to the value specified by <code>propertyValue`.

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
     BeanPropertyValueChangeClosure closure =
        new BeanPropertyValueChangeClosure( "activeEmployee", Boolean.TRUE );

     // update the Collection
     CollectionUtils.forAllDo( peopleCollection, closure );

This would take a `Collection` of person objects and update the `activeEmployee</code> property of each object in the <code>Collection` to `true`. Assuming...

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

See Also:
  - `PropertyUtils`
  - `Consumer`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BeanPropertyValueChangeConsumer(String propertyName, V propertyValue)`
  Constructor which takes the name of the property to be changed, the new value to set the property to, and assumes `ignoreNull</code> to be <code>false`.
  `BeanPropertyValueChangeConsumer(String propertyName, V propertyValue, boolean ignoreNull)`
  Constructor which takes the name of the property to be changed, the new value to set the property to 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
  `void`
  `accept(Object object)`
  Updates the target object provided using the property update criteria provided when this `BeanPropertyValueChangeClosure` was constructed.
  `String`
  `getPropertyName()`
  Returns the name of the property which will be updated when this `Closure` executes.
  `V`
  `getPropertyValue()`
  Returns the value that the property specified by `propertyName` will be updated to when this `Closure` executes.
  `boolean`
  `isIgnoreNull()`
  Returns the flag that 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 leading up to the target property evaluate to `null</code> then the <code>IllegalArgumentException` throw by `PropertyUtils</code> will be logged but not re-thrown. If set to <code>false` then if any objects in the property path leading up to the target property evaluate to `null</code> then the <code>IllegalArgumentException` throw by `PropertyUtils` will be logged and re-thrown.

  ### 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.Consumer

  `andThen`

- ## Constructor Details

  - ### BeanPropertyValueChangeConsumer

    public BeanPropertyValueChangeConsumer(String propertyName, V propertyValue)
    Constructor which takes the name of the property to be changed, the new value to set the property to, and assumes `ignoreNull</code> to be <code>false`.
    Parameters:
      `propertyName` - The name of the property that will be updated with the value specified by `propertyValue`.
      `propertyValue` - The value that `propertyName` will be set to on the target object.
    Throws:
      `IllegalArgumentException` - If the propertyName provided is null or empty.

  - ### BeanPropertyValueChangeConsumer

    public BeanPropertyValueChangeConsumer(String propertyName, V propertyValue, boolean ignoreNull)
    Constructor which takes the name of the property to be changed, the new value to set the property to 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 updated with the value specified by `propertyValue`.
      `propertyValue` - The value that `propertyName` will be set to on the target object.
      `ignoreNull` - Determines whether `null` objects in the property path will generate an `IllegalArgumentException` or not.
    Throws:
      `IllegalArgumentException` - If the propertyName provided is null or empty.

- ## Method Details

  - ### accept

    public void accept(Object object)
    Updates the target object provided using the property update criteria provided when this `BeanPropertyValueChangeClosure` was constructed. 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</code> attribute. By default, <code>ignoreNull` is `false</code> and would result in an <code>IllegalArgumentException` if an object in the property path leading up to the target property is `null`. @param object The object to be updated.
    Specified by:
      `accept` in interface `Consumer<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`.

  - ### getPropertyName

    public String getPropertyName()
    Returns the name of the property which will be updated when this `Closure` executes.
    Returns:
      The name of the property which will be updated when this `Closure` executes.

  - ### getPropertyValue

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

  - ### isIgnoreNull

    public boolean isIgnoreNull()
    Returns the flag that 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 leading up to the target property evaluate to `null</code> then the <code>IllegalArgumentException` throw by `PropertyUtils</code> will be logged but not re-thrown. If set to <code>false` then if any objects in the property path leading up to the target property evaluate to `null</code> then the <code>IllegalArgumentException` throw by `PropertyUtils` will be logged and re-thrown.
    Returns:
      The flag that determines whether `null` objects in the property path will generate an `IllegalArgumentException` or not.