org.apache.commons.beanutils

## Class BeanToPropertyValueTransformer

- java.lang.Object
- - org.apache.commons.beanutils.BeanToPropertyValueTransformer

- All Implemented Interfaces:
    org.apache.commons.collections.Transformer

      public class BeanToPropertyValueTransformer
      extends Object
      implements org.apache.commons.collections.Transformer

  `Transformer` that outputs a property value.

  An implementation of `org.apache.commons.collections.Transformer` that transforms the object provided by returning the value of a specified property of the object. The constructor for `BeanToPropertyValueTransformer` requires the name of the property that will be used in the transformation. The property 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 transformer
       BeanToPropertyValueTransformer transformer = new BeanToPropertyValueTransformer( "person.address.city" );

       // transform the Collection
       Collection peoplesCities = CollectionUtils.collect( peopleCollection, transformer );

  This would take a `Collection` of person objects and return a `Collection` of objects which represents the cities in which each person lived. Assuming...

  - The top level object in the `peeopleCollection` is an object which represents a person.
  - The person object has a `getAddress()` method which returns an object which represents a person's address.
  - The address object has a `getCity()` method which returns an object which represents the city in which a person lives.
  Version:
    $Id: BeanToPropertyValueTransformer.java 1454597 2013-03-08 21:58:12Z britter $
  See Also:
    `PropertyUtils`, `Transformer`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `BeanToPropertyValueTransformer(String propertyName)` Constructs a Transformer which does not ignore nulls.
    `BeanToPropertyValueTransformer(String propertyName, boolean ignoreNull)` Constructs a Transformer and sets ignoreNull.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `getPropertyName()` Returns the name of the property that will be used in the transformation of the bean.
    `boolean` | `isIgnoreNull()` Returns the flag which determines whether `null` objects in the property path will genenerate an `IllegalArgumentException` or not.
    `Object` | `transform(Object object)` Returns the value of the property named in the transformer's constructor for the object provided.

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

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

- - ### Constructor Detail

    - #### BeanToPropertyValueTransformer

          public BeanToPropertyValueTransformer(String propertyName)

      Constructs a Transformer which does not ignore nulls. Constructor which takes the name of the property that will be used in the transformation and assumes `ignoreNull` to be `false`.
      Parameters:
        `propertyName` - The name of the property that will be used in the transformation.
      Throws:
        `IllegalArgumentException` - If the `propertyName` is `null` or empty.

    - #### BeanToPropertyValueTransformer

          public BeanToPropertyValueTransformer(String propertyName,
                                        boolean ignoreNull)

      Constructs a Transformer and sets ignoreNull. Constructor which takes the name of the property that will be used in the transformation 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 used in the transformation.
        `ignoreNull` - Determines whether `null` objects in the property path will genenerate an `IllegalArgumentException` or not.
      Throws:
        `IllegalArgumentException` - If the `propertyName` is `null` or empty.

  - ### Method Detail

    - #### transform

          public Object transform(Object object)

      Returns the value of the property named in the transformer's constructor for the object provided. 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:
        `transform` in interface `org.apache.commons.collections.Transformer`
      Parameters:
        `object` - The object to be transformed.
      Returns:
        The value of the property named in the transformer's constructor for the object provided.
      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 that will be used in the transformation of the bean.
      Returns:
        The name of the property that will be used in the transformation of the bean.

    - #### isIgnoreNull

          public boolean isIgnoreNull()

      Returns the flag which 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 evaluate to `null` then the `IllegalArgumentException` throw by `PropertyUtils` will be logged but not rethrown and `null` will be returned. If set to `false` then if any objects in the property path evaluate to `null` then the `IllegalArgumentException` throw by `PropertyUtils` will be logged and rethrown.
      Returns:
        The flag which determines whether `null` objects in the property path will genenerate an `IllegalArgumentException` or not.

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