Package org.apache.commons.dbutils.handlers

## Class KeyedHandler<K>

- java.lang.Object
- - org.apache.commons.dbutils.handlers.AbstractKeyedHandler<K,​Map<String,​Object>>
  - - org.apache.commons.dbutils.handlers.KeyedHandler<K>

- Type Parameters:
    `K` - The type of the key
  All Implemented Interfaces:
    `ResultSetHandler<Map<K,​Map<String,​Object>>>`

      public class KeyedHandler<K>
      extends AbstractKeyedHandler<K,​Map<String,​Object>>

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

  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. </p>

  This class is thread safe.

  Since:
    1.1
  See Also:
    `ResultSetHandler`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected int` | `columnIndex` | The column index to retrieve key values from.
    `protected 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

    Constructors
    Constructor | Description
    --- | ---
    `KeyedHandler()` | Creates a new instance of KeyedHandler.
    `KeyedHandler​(int columnIndex)` | Creates a new instance of KeyedHandler.
    `KeyedHandler​(String columnName)` | Creates a new instance of KeyedHandler.
    `KeyedHandler​(RowProcessor convert)` | Creates a new instance of KeyedHandler.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected K` | `createKey​(ResultSet rs)` | This factory method is called by `handle()` to retrieve the key value from the current `ResultSet` row.
    `protected Map<String,​Object>` | `createRow​(ResultSet resultSet)` | This factory method is called by `handle()` to store the current `ResultSet` row in some object.

    - ### Methods inherited from class org.apache.commons.dbutils.handlers.AbstractKeyedHandler

      `createMap, handle`

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

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

- - ### Field Detail

    - #### convert

          protected final RowProcessor convert

      The RowProcessor implementation to use when converting rows into Objects.

    - #### columnIndex

          protected final int columnIndex

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

    - #### columnName

          protected final 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​(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​(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​(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

    - #### createKey

          protected K createKey​(ResultSet rs)
                         throws 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.
      Specified by:
        `createKey` in class `AbstractKeyedHandler<K,​Map<String,​Object>>`
      Parameters:
        `rs` - ResultSet to create a key from
      Returns:
        Object from the configured key column name/index
      Throws:
        `SQLException` - if a database access error occurs
        `ClassCastException` - if the class datatype does not match the column type

    - #### createRow

          protected Map<String,​Object> createRow​(ResultSet resultSet)
                                                throws 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.
      Specified by:
        `createRow` in class `AbstractKeyedHandler<K,​Map<String,​Object>>`
      Parameters:
        `resultSet` - ResultSet to create a row from
      Returns:
        Object typed Map containing column names to values
      Throws:
        `SQLException` - if a database access error occurs