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

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

  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 Details

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

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

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