org.apache.commons.dbutils
Class BasicRowProcessor

java.lang.Object
  extended byorg.apache.commons.dbutils.BasicRowProcessor
All Implemented Interfaces:
RowProcessor

public class BasicRowProcessor
extends java.lang.Object
implements RowProcessor

Basic implementation of the RowProcessor interface. This class is a thread-safe Singleton.

Author:
Henri Yandell, Juozas Baliuka, David Graham, Yoav Shapira
See Also:
RowProcessor

Nested Class Summary
private static class BasicRowProcessor.CaseInsensitiveHashMap
          A Map that converts all keys to lowercase Strings for case insensitive lookups.
 
Field Summary
private static BasicRowProcessor instance
          The Singleton instance of this class.
private static java.util.Map primitiveDefaults
          Set a bean's primitive properties to these defaults when SQL NULL is returned.
private static int PROPERTY_NOT_FOUND
          Special array index that indicates there is no bean property that matches a column from a ResultSet.
 
Constructor Summary
protected BasicRowProcessor()
          Protected constructor for BasicRowProcessor subclasses only.
 
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, int cols)
          Creates a new object and initializes its fields from the ResultSet.
static BasicRowProcessor instance()
          Returns the Singleton instance of this class.
private  boolean isCompatibleType(java.lang.Object value, java.lang.Class type)
          ResultSet.getObject() returns an Integer object for an INT column.
private  int[] mapColumnsToProperties(java.sql.ResultSetMetaData rsmd, java.beans.PropertyDescriptor[] props)
          The positions in the returned array represent column numbers.
private  java.lang.Object newInstance(java.lang.Class c)
          Returns a new instance of the given Class.
private  java.beans.PropertyDescriptor[] propertyDescriptors(java.lang.Class c)
          Returns a PropertyDescriptor[] for the given Class.
 java.lang.Object[] toArray(java.sql.ResultSet rs)
          Convert a ResultSet row into an Object[].
 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.
 java.util.Map toMap(java.sql.ResultSet rs)
          Convert a ResultSet row into a Map.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

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.


PROPERTY_NOT_FOUND

private static final int PROPERTY_NOT_FOUND
Special array index that indicates there is no bean property that matches a column from a ResultSet.

See Also:
Constant Field Values

instance

private static final BasicRowProcessor instance
The Singleton instance of this class.

Constructor Detail

BasicRowProcessor

protected BasicRowProcessor()
Protected constructor for BasicRowProcessor subclasses only.

Method Detail

instance

public static BasicRowProcessor instance()
Returns the Singleton instance of this class.

Returns:
The single instance of this class.

toArray

public java.lang.Object[] toArray(java.sql.ResultSet rs)
                           throws java.sql.SQLException
Convert a ResultSet row into an Object[]. This implementation copies column values into the array in the same order they're returned from the ResultSet. Array elements will be set to null if the column was SQL NULL.

Specified by:
toArray in interface RowProcessor
Throws:
java.sql.SQLException
See Also:
RowProcessor.toArray(java.sql.ResultSet)

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 property's set method parameter type matches the column type. If the data types do not match, the setter will not be called.

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.

Specified by:
toBean in interface RowProcessor
Throws:
java.sql.SQLException
See Also:
RowProcessor.toBean(java.sql.ResultSet, java.lang.Class)

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 property's set method parameter type matches the column type. If the data types do not match, the setter will not be called.

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.

Specified by:
toBeanList in interface RowProcessor
Returns:
A List of beans with the given type in the order they were returned by the ResultSet.
Throws:
java.sql.SQLException
See Also:
RowProcessor.toBeanList(java.sql.ResultSet, java.lang.Class)

createBean

private java.lang.Object createBean(java.sql.ResultSet rs,
                                    java.lang.Class type,
                                    java.beans.PropertyDescriptor[] props,
                                    int[] columnToProperty,
                                    int cols)
                             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
cols - The number of columns
Returns:
An initialized object.
Throws:
java.sql.SQLException - If a database error occurs

mapColumnsToProperties

private 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 result set meta data containing column information
props - The bean property descriptors
Returns:
An int[] with column index to property index mappings. The 0th element is meaningless as column indexing starts at 1.
Throws:
java.sql.SQLException - If a database error occurs

toMap

public java.util.Map toMap(java.sql.ResultSet rs)
                    throws java.sql.SQLException
Convert a ResultSet row into a Map. This implementation returns a Map with case insensitive column names as keys. Calls to map.get("COL") and map.get("col") return the same value.

Specified by:
toMap in interface RowProcessor
Throws:
java.sql.SQLException
See Also:
RowProcessor.toMap(java.sql.ResultSet)

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

private java.lang.Object newInstance(java.lang.Class c)
                              throws java.sql.SQLException
Returns a new instance of the given Class.

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.