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.
  Version:
    $Id: BeanPropertyValueChangeClosure.java 1454597 2013-03-08 21:58:12Z britter $
  See Also:
    `PropertyUtils`, `Closure`

- - ### Constructor Summary

    Constructors
    Constructor and 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

    Methods
    Modifier and Type | Method and 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 Detail

    - #### 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 Detail

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

Copyright © 2000–2014 The Apache Software Foundation. All rights reserved.