GeneratedKeyHolder (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.jdbc.support

## Class GeneratedKeyHolder

- java.lang.Object
- - org.springframework.jdbc.support.GeneratedKeyHolder

- All Implemented Interfaces:
    KeyHolder

      public class GeneratedKeyHolder
      extends Object
      implements KeyHolder

  Default implementation of the `KeyHolder` interface, to be used for holding auto-generated keys (as potentially returned by JDBC insert statements).

  Create an instance of this class for each insert operation, and pass it to the corresponding `JdbcTemplate` or {org.springframework.jdbc.object.SqlUpdate} methods.

  Since:
    1.1
  Author:
    Thomas Risberg, Juergen Hoeller

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `GeneratedKeyHolder()` Create a new GeneratedKeyHolder with a default list.
    `GeneratedKeyHolder(List<Map<String,Object>> keyList)` Create a new GeneratedKeyHolder with a given list.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Number` | `getKey()` Retrieve the first item from the first map, assuming that there is just one item and just one map, and that the item is a number.
    `List<Map<String,Object>>` | `getKeyList()` Return a reference to the List that contains the keys.
    `Map<String,Object>` | `getKeys()` Retrieve the first map of keys.

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

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

- - ### Constructor Detail

    - #### GeneratedKeyHolder

          public GeneratedKeyHolder()

      Create a new GeneratedKeyHolder with a default list.

    - #### GeneratedKeyHolder

          public GeneratedKeyHolder(List<Map<String,Object>> keyList)

      Create a new GeneratedKeyHolder with a given list.
      Parameters:
        `keyList` - a list to hold maps of keys

  - ### Method Detail

    - #### getKey

          public Number getKey()
                        throws InvalidDataAccessApiUsageException,
                               DataRetrievalFailureException

      Description copied from interface: `KeyHolder`
      Retrieve the first item from the first map, assuming that there is just one item and just one map, and that the item is a number. This is the typical case: a single, numeric generated key.

      Keys are held in a List of Maps, where each item in the list represents the keys for each row. If there are multiple columns, then the Map will have multiple entries as well. If this method encounters multiple entries in either the map or the list meaning that multiple keys were returned, then an InvalidDataAccessApiUsageException is thrown.

      Specified by:
        `getKey` in interface `KeyHolder`
      Returns:
        the generated key
      Throws:
        `InvalidDataAccessApiUsageException` - if multiple keys are encountered.
        `DataRetrievalFailureException`

    - #### getKeys

          public Map<String,Object> getKeys()
                                     throws InvalidDataAccessApiUsageException

      Description copied from interface: `KeyHolder`
      Retrieve the first map of keys. If there are multiple entries in the list (meaning that multiple rows had keys returned), then an InvalidDataAccessApiUsageException is thrown.
      Specified by:
        `getKeys` in interface `KeyHolder`
      Returns:
        the Map of generated keys
      Throws:
        `InvalidDataAccessApiUsageException` - if keys for multiple rows are encountered

    - #### getKeyList

          public List<Map<String,Object>> getKeyList()

      Description copied from interface: `KeyHolder`
      Return a reference to the List that contains the keys. Can be used for extracting keys for multiple rows (an unusual case), and also for adding new maps of keys.
      Specified by:
        `getKeyList` in interface `KeyHolder`
      Returns:
        the List for the generated keys, with each entry being a Map of column names and key values