org.springframework.jdbc.support

## Interface KeyHolder

- All Known Implementing Classes:
    GeneratedKeyHolder

      public interface KeyHolder

  Interface for retrieving keys, typically used for auto-generated keys as potentially returned by JDBC insert statements.

  Implementations of this interface can hold any number of keys. In the general case, the keys are returned as a List containing one Map for each row of keys.

  Most applications only use one key per row and process only one row at a time in an insert statement. In these cases, just call `getKey` or `getKeyAs` to retrieve the key. The value returned by `getKey` is a `Number`, which is the usual type for auto-generated keys. For any other auto-generated key type, use `getKeyAs` instead.

  Since:
    1.1
  Author:
    Thomas Risberg, Juergen Hoeller, Slawomir Dymitrow
  See Also:
    `JdbcTemplate`, `SqlUpdate`

- - ### Method Summary

    All Methods Instance Methods Abstract 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.
    `<T> T` | `getKeyAs(Class<T> keyType)` Retrieve the first item from the first map, assuming that there is just one item and just one map, and that the item is an instance of specified type.
    `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.

- - ### Method Detail

    - #### getKey

          @Nullable
          Number getKey()
                           throws InvalidDataAccessApiUsageException

      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.

      Returns:
        the generated key as a number
      Throws:
        `InvalidDataAccessApiUsageException` - if multiple keys are encountered
      See Also:
        `getKeyAs(Class)`

    - #### getKeyAs

          @Nullable
          <T> T getKeyAs(Class<T> keyType)
                            throws InvalidDataAccessApiUsageException

      Retrieve the first item from the first map, assuming that there is just one item and just one map, and that the item is an instance of specified type. This is a common case: a single generated key of the specified type.

      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.

      Parameters:
        `keyType` - the type of the auto-generated key
      Returns:
        the generated key as an instance of specified type
      Throws:
        `InvalidDataAccessApiUsageException` - if multiple keys are encountered
      Since:
        5.3
      See Also:
        `getKey()`

    - #### getKeys

          @Nullable
          Map<String,Object> getKeys()
                                        throws InvalidDataAccessApiUsageException

      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.

      Returns:
        the Map of generated keys for a single row
      Throws:
        `InvalidDataAccessApiUsageException` - if keys for multiple rows are encountered

    - #### getKeyList

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

      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.

      Returns:
        the List for the generated keys, with each entry representing an individual row through a Map of column names and key values