Package org.apache.commons.dbutils

## Class BeanProcessor

- java.lang.Object
- - org.apache.commons.dbutils.BeanProcessor

- Direct Known Subclasses:
    `GenerousBeanProcessor`

      public class BeanProcessor
      extends Object

  `BeanProcessor` matches column names to bean property names and converts `ResultSet` columns into objects for those bean properties. Subclasses should override the methods in the processing chain to customize behavior.

  This class is thread-safe.

  Since:
    1.1
  See Also:
    `BasicRowProcessor`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected static int` | `PROPERTY_NOT_FOUND` | Special array value used by `mapColumnsToProperties` that indicates there is no bean property that matches a column from a `ResultSet`.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `BeanProcessor()` | Constructor for BeanProcessor.
    `BeanProcessor​(Map<String,​String> columnToPropertyOverrides)` | Constructor for BeanProcessor configured with column to property name overrides.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected Method` | `getWriteMethod​(Object target, PropertyDescriptor prop, Object value)` | Get the write method to use when setting `value` to the `target`.
    `protected int[]` | `mapColumnsToProperties​(ResultSetMetaData rsmd, PropertyDescriptor[] props)` | The positions in the returned array represent column numbers.
    `protected <T> T` | `newInstance​(Class<T> c)` | Factory method that returns a new instance of the given Class.
    `<T> T` | `populateBean​(ResultSet resultSet, T bean)` | Initializes the fields of the provided bean from the ResultSet.
    `protected Object` | `processColumn​(ResultSet resultSet, int index, Class<?> propType)` | Convert a `ResultSet` column into an object.
    `<T> T` | `toBean​(ResultSet rs, Class<? extends T> type)` | Convert a `ResultSet` row into a JavaBean.
    `<T> List<T>` | `toBeanList​(ResultSet resultSet, Class<? extends T> type)` | Convert a `ResultSet` into a `List` of JavaBeans.

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

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

- - ### Field Detail

    - #### PROPERTY_NOT_FOUND

          protected static final int PROPERTY_NOT_FOUND

      Special array value used by `mapColumnsToProperties` that indicates there is no bean property that matches a column from a `ResultSet`.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### BeanProcessor

          public BeanProcessor()

      Constructor for BeanProcessor.

    - #### BeanProcessor

          public BeanProcessor​(Map<String,​String> columnToPropertyOverrides)

      Constructor for BeanProcessor configured with column to property name overrides.
      Parameters:
        `columnToPropertyOverrides` - ResultSet column to bean property name overrides
      Since:
        1.5

  - ### Method Detail

    - #### getWriteMethod

          protected Method getWriteMethod​(Object target,
                                          PropertyDescriptor prop,
                                          Object value)

      Get the write method to use when setting `value` to the `target`.
      Parameters:
        `target` - Object where the write method will be called.
        `prop` - BeanUtils information.
        `value` - The value that will be passed to the write method.
      Returns:
        The `Method` to call on `target` to write `value` or `null` if there is no suitable write method.

    - #### mapColumnsToProperties

          protected int[] mapColumnsToProperties​(ResultSetMetaData rsmd,
                                                 PropertyDescriptor[] props)
                                          throws SQLException

      The positions in the returned array represent column numbers. The values stored at each position represent the index in the `PropertyDescriptor[]` for the bean property that matches the column name. If no bean property was found for a column, the position is set to `PROPERTY_NOT_FOUND`.
      Parameters:
        `rsmd` - The `ResultSetMetaData` containing column information.
        `props` - The bean property descriptors.
      Returns:
        An int[] with column index to property index mappings. The 0th element is meaningless because JDBC column indexing starts at 1.
      Throws:
        `SQLException` - if a database access error occurs

    - #### newInstance

          protected <T> T newInstance​(Class<T> c)
                               throws SQLException

      Factory method that returns a new instance of the given Class. This is called at the start of the bean creation process and may be overridden to provide custom behavior like returning a cached bean instance.
      Type Parameters:
        `T` - The type of object to create
      Parameters:
        `c` - The Class to create an object from.
      Returns:
        A newly created object of the Class.
      Throws:
        `SQLException` - if creation failed.

    - #### populateBean

          public <T> T populateBean​(ResultSet resultSet,
                                    T bean)
                             throws SQLException

      Initializes the fields of the provided bean from the ResultSet.
      Type Parameters:
        `T` - The type of bean
      Parameters:
        `resultSet` - The result set.
        `bean` - The bean to be populated.
      Returns:
        An initialized object.
      Throws:
        `SQLException` - if a database error occurs.

    - #### processColumn

          protected Object processColumn​(ResultSet resultSet,
                                         int index,
                                         Class<?> propType)
                                  throws SQLException

      Convert a `ResultSet` column into an object. Simple implementations could just call `rs.getObject(index)` while more complex implementations could perform type manipulation to match the column's type to the bean property type.

      This implementation calls the appropriate `ResultSet` getter method for the given property type to perform the type conversion. If the property type doesn't match one of the supported `ResultSet` types, `getObject` is called.

      Parameters:
        `resultSet` - The `ResultSet` currently being processed. It is positioned on a valid row before being passed into this method.
        `index` - The current column index being processed.
        `propType` - The bean property type that this column needs to be converted into.
      Returns:
        The object from the `ResultSet` at the given column index after optional type processing or `null` if the column value was SQL NULL.
      Throws:
        `SQLException` - if a database access error occurs

    - #### toBean

          public <T> T toBean​(ResultSet rs,
                              Class<? extends T> type)
                       throws SQLException

      Convert a `ResultSet` row into a JavaBean. This implementation uses reflection and `BeanInfo` classes to match column names to bean property names. Properties are matched to columns based on several factors: <br/> <ol> <li> The class has a writable property with the same name as a column. The name comparison is case insensitive. </li> <li> The column type can be converted to the property's set method parameter type with a ResultSet.get* method. If the conversion fails (ie. the property was an int and the column was a Timestamp) an SQLException is thrown. </li> </ol> <p> Primitive bean properties are set to their defaults when SQL NULL is returned from the `ResultSet`. Numeric fields are set to 0 and booleans are set to false. Object bean properties are set to `null` when SQL NULL is returned. This is the same behavior as the `ResultSet` get* methods. </p>
      Type Parameters:
        `T` - The type of bean to create
      Parameters:
        `rs` - ResultSet that supplies the bean data
        `type` - Class from which to create the bean instance
      Returns:
        the newly created bean
      Throws:
        `SQLException` - if a database access error occurs

    - #### toBeanList

          public <T> List<T> toBeanList​(ResultSet resultSet,
                                        Class<? extends T> type)
                                 throws SQLException

      Convert a `ResultSet` into a `List` of JavaBeans. This implementation uses reflection and `BeanInfo` classes to match column names to bean property names. Properties are matched to columns based on several factors: <br/> <ol> <li> The class has a writable property with the same name as a column. The name comparison is case insensitive. </li> <li> The column type can be converted to the property's set method parameter type with a ResultSet.get* method. If the conversion fails (ie. the property was an int and the column was a Timestamp) an SQLException is thrown. </li> </ol>

      Primitive bean properties are set to their defaults when SQL NULL is returned from the `ResultSet`. Numeric fields are set to 0 and booleans are set to false. Object bean properties are set to `null` when SQL NULL is returned. This is the same behavior as the `ResultSet` get* methods. </p>

      Type Parameters:
        `T` - The type of bean to create
      Parameters:
        `resultSet` - ResultSet that supplies the bean data
        `type` - Class from which to create the bean instance
      Returns:
        the newly created List of beans
      Throws:
        `SQLException` - if a database access error occurs