Package org.apache.commons.beanutils

# Class BeanPropertyValueChangeClosure

java.lang.Object
org.apache.commons.beanutils.BeanPropertyValueChangeClosure

All Implemented Interfaces:
  `org.apache.commons.collections.Closure`

public class BeanPropertyValueChangeClosure extends Object implements org.apache.commons.collections.Closure

`Closure` that sets a property.

An implementation of `org.apache.commons.collections.Closure` 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` to the value specified by `propertyValue`.

Note: Property names can be a simple, nested, indexed, or mapped property as defined by `org.apache.commons.beanutils.PropertyUtils`. If any object in the property path specified by `propertyName` is `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` property of each object in the `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`
  - `Closure`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BeanPropertyValueChangeClosure(String propertyName, Object propertyValue)`
  Constructor which takes the name of the property to be changed, the new value to set the property to, and assumes `ignoreNull` to be `false`.
  `BeanPropertyValueChangeClosure(String propertyName, Object 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 genenerate an `IllegalArgumentException` or not.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `execute(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.
  `Object`
  `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 genenerate an `IllegalArgumentException` or not.

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

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

- ## Constructor Details

  - ### BeanPropertyValueChangeClosure

    public BeanPropertyValueChangeClosure(String propertyName, Object propertyValue)
    Constructor which takes the name of the property to be changed, the new value to set the property to, and assumes `ignoreNull` to be `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.

  - ### BeanPropertyValueChangeClosure

    public BeanPropertyValueChangeClosure(String propertyName, Object 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 genenerate 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 genenerate an `IllegalArgumentException` or not.
    Throws:
      `IllegalArgumentException` - If the propertyName provided is null or empty.

- ## Method Details

  - ### execute

    public void execute(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` attribute. By default, `ignoreNull` is `false` and would result in an `IllegalArgumentException` if an object in the property path leading up to the target property is `null`.
    Specified by:
      `execute` in interface `org.apache.commons.collections.Closure`
    Parameters:
      `object` - The object to be updated.
    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` is set to `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 Object 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 genenerate an `IllegalArgumentException` or not. If set to `true` then if any objects in the property path leading up to the target property evaluate to `null` then the `IllegalArgumentException` throw by `PropertyUtils` will be logged but not rethrown. If set to `false` then if any objects in the property path leading up to the target property evaluate to `null` then the `IllegalArgumentException` throw by `PropertyUtils` will be logged and rethrown.
    Returns:
      The flag that determines whether `null` objects in the property path will genenerate an `IllegalArgumentException` or not.