Package org.apache.commons.beanutils2

# Class BeanToPropertyValueTransformer<T,R>

java.lang.Object
org.apache.commons.beanutils2.BeanToPropertyValueTransformer<T,R>

Type Parameters:
  `T` - the type of the input to the function
  `R` - the type of the result of the function

All Implemented Interfaces:
  `Function<T,R>`

public class BeanToPropertyValueTransformer<T,R> extends Object implements Function<T,R>

`Transformer` that outputs a property value.

An implementation of `Function` 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.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 transformer
     BeanToPropertyValueTransformer transformer = new BeanToPropertyValueTransformer( "person.address.city" );

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

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

- The top level object in the `peopleCollection` 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.

See Also:
  - `PropertyUtils`
  - `Function`

- ## Constructor Summary

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

  Modifier and Type
  Method
  Description
  `R`
  `apply(T object)`
  Returns the value of the property named in the transformer's constructor for the object provided.
  `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 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 `null</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.

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

  `andThen, compose`

- ## Constructor Details

  - ### 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</code> to be <code>false`.
    Parameters:
      `propertyName` - The name of the property that will be used in the transformation.
    Throws:
      `IllegalArgumentException` - If the `propertyName</code> is <code>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 generate 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 generate an `IllegalArgumentException` or not.
    Throws:
      `IllegalArgumentException` - If the `propertyName</code> is <code>null` or empty.

- ## Method Details

  - ### apply

    public R apply(T 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</code> then the outcome will be based on the value of the <code>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 transformed. @return The value of the property named in the transformer's constructor for the object provided.
    Specified by:
      `apply` in interface `Function<T,R>`
    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 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 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 `null</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.