org.apache.commons.dbutils
Class BeanProcessor

java.lang.Object
  extended by org.apache.commons.dbutils.BeanProcessor

public class BeanProcessor
extends java.lang.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:
DbUtils 1.1
See Also:
BasicRowProcessor

Field Summary
private static java.util.Map primitiveDefaults
          Set a bean's primitive properties to these defaults when SQL NULL is returned.
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
BeanProcessor()
          Constructor for BeanProcessor.
 
Method Summary
private  void callSetter(java.lang.Object target, java.beans.PropertyDescriptor prop, java.lang.Object value)
          Calls the setter method on the target object for the given property.
private  java.lang.Object createBean(java.sql.ResultSet rs, java.lang.Class type, java.beans.PropertyDescriptor[] props, int[] columnToProperty)
          Creates a new object and initializes its fields from the ResultSet.
private  boolean isCompatibleType(java.lang.Object value, java.lang.Class type)
          ResultSet.getObject() returns an Integer object for an INT column.
protected  int[] mapColumnsToProperties(java.sql.ResultSetMetaData rsmd, java.beans.PropertyDescriptor[] props)
          The positions in the returned array represent column numbers.
protected  java.lang.Object newInstance(java.lang.Class c)
          Factory method that returns a new instance of the given Class.
protected  java.lang.Object processColumn(java.sql.ResultSet rs, int index, java.lang.Class propType)
          Convert a ResultSet column into an object.
private  java.beans.PropertyDescriptor[] propertyDescriptors(java.lang.Class c)
          Returns a PropertyDescriptor[] for the given Class.
 java.lang.Object toBean(java.sql.ResultSet rs, java.lang.Class type)
          Convert a ResultSet row into a JavaBean.
 java.util.List toBeanList(java.sql.ResultSet rs, java.lang.Class 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

primitiveDefaults

private static final java.util.Map primitiveDefaults
Set a bean's primitive properties to these defaults when SQL NULL is returned. These are the same as the defaults that ResultSet get* methods return in the event of a NULL column.

Constructor Detail

BeanProcessor

public BeanProcessor()
Constructor for BeanProcessor.

Method Detail

toBean

public java.lang.Object toBean(java.sql.ResultSet rs,
                               java.lang.Class type)
                        throws java.sql.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:
  1. The class has a writable property with the same name as a column. The name comparison is case insensitive.
  2. 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.

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.

Parameters:
rs - ResultSet that supplies the bean data
type - Class from which to create the bean instance
Returns:
the newly created bean
Throws:
java.sql.SQLException - if a database access error occurs

toBeanList

public java.util.List toBeanList(java.sql.ResultSet rs,
                                 java.lang.Class type)
                          throws java.sql.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:
  1. The class has a writable property with the same name as a column. The name comparison is case insensitive.
  2. 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.

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.

Parameters:
rs - ResultSet that supplies the bean data
type - Class from which to create the bean instance
Returns:
the newly created List of beans
Throws:
java.sql.SQLException - if a database access error occurs

createBean

private java.lang.Object createBean(java.sql.ResultSet rs,
                                    java.lang.Class type,
                                    java.beans.PropertyDescriptor[] props,
                                    int[] columnToProperty)
                             throws java.sql.SQLException
Creates a new object and initializes its fields from the ResultSet.

Parameters:
rs - The result set.
type - The bean type (the return type of the object).
props - The property descriptors.
columnToProperty - The column indices in the result set.
Returns:
An initialized object.
Throws:
java.sql.SQLException - if a database error occurs.

callSetter

private void callSetter(java.lang.Object target,
                        java.beans.PropertyDescriptor prop,
                        java.lang.Object value)
                 throws java.sql.SQLException
Calls the setter method on the target object for the given property. If no setter method exists for the property, this method does nothing.

Parameters:
target - The object to set the property on.
prop - The property to set.
value - The value to pass into the setter.
Throws:
java.sql.SQLException - if an error occurs setting the property.

isCompatibleType

private boolean isCompatibleType(java.lang.Object value,
                                 java.lang.Class type)
ResultSet.getObject() returns an Integer object for an INT column. The setter method for the property might take an Integer or a primitive int. This method returns true if the value can be successfully passed into the setter method. Remember, Method.invoke() handles the unwrapping of Integer into an int.

Parameters:
value - The value to be passed into the setter method.
type - The setter's parameter type.
Returns:
boolean True if the value is compatible.

newInstance

protected java.lang.Object newInstance(java.lang.Class c)
                                throws java.sql.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.

Parameters:
c - The Class to create an object from.
Returns:
A newly created object of the Class.
Throws:
java.sql.SQLException - if creation failed.

propertyDescriptors

private java.beans.PropertyDescriptor[] propertyDescriptors(java.lang.Class c)
                                                     throws java.sql.SQLException
Returns a PropertyDescriptor[] for the given Class.

Parameters:
c - The Class to retrieve PropertyDescriptors for.
Returns:
A PropertyDescriptor[] describing the Class.
Throws:
java.sql.SQLException - if introspection failed.

mapColumnsToProperties

protected int[] mapColumnsToProperties(java.sql.ResultSetMetaData rsmd,
                                       java.beans.PropertyDescriptor[] props)
                                throws java.sql.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:
java.sql.SQLException - if a database access error occurs

processColumn

protected java.lang.Object processColumn(java.sql.ResultSet rs,
                                         int index,
                                         java.lang.Class propType)
                                  throws java.sql.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:
rs - 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:
java.sql.SQLException - if a database access error occurs