org.apache.commons.dbutils.handlers
Class KeyedHandler

java.lang.Object
  org.apache.commons.dbutils.handlers.KeyedHandler

All Implemented Interfaces:

ResultSetHandler

public class KeyedHandler

extends java.lang.Object

implements ResultSetHandler

ResultSetHandler implementation that returns a Map of Maps. ResultSet rows are converted into Maps which are then stored in a Map under the given key. Although this implementation uses Maps to store row contents, subclasses are encouraged to override the createRow() method to convert the rows into any kind of object.

If you had a Person table with a primary key column called ID, you could retrieve rows from the table like this:

 ResultSetHandler h = new KeyedHandler("id");
 Map found = (Map) queryRunner.query("select id, name, age from person", h);
 Map jane = (Map) found.get(new Long(1)); // jane's id is 1
 String janesName = (String) jane.get("name");
 Integer janesAge = (Integer) jane.get("age");
 

Note that the "id" passed to KeyedHandler and "name" and "age" passed to the returned Map's get() method can be in any case. The data types returned for name and age are dependent upon how your JDBC driver converts SQL column types from the Person table into Java types.

To avoid these type issues you could subclass KeyedHandler and override createRow() to store rows in Java bean instances (ie. a Person class).

This class is thread safe.

Since:

DbUtils 1.1

See Also:

ResultSetHandler

Field Summary

protected int	columnIndex The column index to retrieve key values from.
protected java.lang.String	columnName The column name to retrieve key values from.
protected RowProcessor	convert The RowProcessor implementation to use when converting rows into Objects.

Constructor Summary

KeyedHandler()
Creates a new instance of KeyedHandler.

KeyedHandler(int columnIndex)
Creates a new instance of KeyedHandler.

KeyedHandler(RowProcessor convert)
Creates a new instance of KeyedHandler.

KeyedHandler(java.lang.String columnName)
Creates a new instance of KeyedHandler.

Method Summary

protected java.lang.Object	createKey(java.sql.ResultSet rs) This factory method is called by handle() to retrieve the key value from the current ResultSet row.
protected java.util.Map	createMap() This factory method is called by handle() to create the Map to store records in.
protected java.lang.Object	createRow(java.sql.ResultSet rs) This factory method is called by handle() to store the current ResultSet row in some object.
java.lang.Object	handle(java.sql.ResultSet rs) Convert each row's columns into a Map and store then in a Map under ResultSet.getObject(key) key.

Methods inherited from class java.lang.Object

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

Field Detail

convert

protected RowProcessor convert

The RowProcessor implementation to use when converting rows into Objects.

columnIndex

protected int columnIndex

The column index to retrieve key values from. Defaults to 1.

columnName

protected java.lang.String columnName

The column name to retrieve key values from. Either columnName or columnIndex will be used but never both.

Constructor Detail

KeyedHandler

public KeyedHandler()

Creates a new instance of KeyedHandler. The value of the first column of each row will be a key in the Map.

KeyedHandler

public KeyedHandler(RowProcessor convert)

Creates a new instance of KeyedHandler. The value of the first column of each row will be a key in the Map.

Parameters:

convert - The RowProcessor implementation to use when converting rows into Maps

KeyedHandler

public KeyedHandler(int columnIndex)

Creates a new instance of KeyedHandler.

Parameters:

columnIndex - The values to use as keys in the Map are retrieved from the column at this index.

KeyedHandler

public KeyedHandler(java.lang.String columnName)

Creates a new instance of KeyedHandler.

Parameters:

columnName - The values to use as keys in the Map are retrieved from the column with this name.

Method Detail

handle

public java.lang.Object handle(java.sql.ResultSet rs)
                        throws java.sql.SQLException

Convert each row's columns into a Map and store then in a Map under ResultSet.getObject(key) key.

Specified by:

handle in interface ResultSetHandler

Parameters:

rs - The ResultSet to handle. It has not been touched before being passed to this method.

Returns:

A Map of Maps, never null.

Throws:

java.sql.SQLException - if a database access error occurs

See Also:

ResultSetHandler.handle(java.sql.ResultSet)

createMap

protected java.util.Map createMap()

This factory method is called by handle() to create the Map to store records in. This implementation returns a HashMap instance.

Returns:

Map to store records in

createKey

protected java.lang.Object createKey(java.sql.ResultSet rs)
                              throws java.sql.SQLException

This factory method is called by handle() to retrieve the key value from the current ResultSet row. This implementation returns ResultSet.getObject() for the configured key column name or index.

Parameters:

rs - ResultSet to create a key from

Returns:

Object from the configured key column name/index

Throws:

java.sql.SQLException - if a database access error occurs

createRow

protected java.lang.Object createRow(java.sql.ResultSet rs)
                              throws java.sql.SQLException

This factory method is called by handle() to store the current ResultSet row in some object. 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.

Parameters:

rs - ResultSet to create a row from

Returns:

Object typed Map containing column names to values

Throws:

java.sql.SQLException - if a database access error occurs