001/* 002 * Copyright 2002-2019 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.jdbc.support; 018 019import java.util.List; 020import java.util.Map; 021 022import org.springframework.dao.InvalidDataAccessApiUsageException; 023 024/** 025 * Interface for retrieving keys, typically used for auto-generated keys 026 * as potentially returned by JDBC insert statements. 027 * 028 * <p>Implementations of this interface can hold any number of keys. 029 * In the general case, the keys are returned as a List containing one Map 030 * for each row of keys. 031 * 032 * <p>Most applications only use one key per row and process only one row at a 033 * time in an insert statement. In these cases, just call {@code getKey} 034 * to retrieve the key. The returned value is a Number here, which is the 035 * usual type for auto-generated keys. 036 * 037 * @author Thomas Risberg 038 * @author Juergen Hoeller 039 * @since 1.1 040 * @see org.springframework.jdbc.core.JdbcTemplate 041 * @see org.springframework.jdbc.object.SqlUpdate 042 */ 043public interface KeyHolder { 044 045 /** 046 * Retrieve the first item from the first map, assuming that there is just 047 * one item and just one map, and that the item is a number. 048 * This is the typical case: a single, numeric generated key. 049 * <p>Keys are held in a List of Maps, where each item in the list represents 050 * the keys for each row. If there are multiple columns, then the Map will have 051 * multiple entries as well. If this method encounters multiple entries in 052 * either the map or the list meaning that multiple keys were returned, 053 * then an InvalidDataAccessApiUsageException is thrown. 054 * @return the generated key as a number 055 * @throws InvalidDataAccessApiUsageException if multiple keys are encountered 056 */ 057 Number getKey() throws InvalidDataAccessApiUsageException; 058 059 /** 060 * Retrieve the first map of keys. 061 * <p>If there are multiple entries in the list (meaning that multiple rows 062 * had keys returned), then an InvalidDataAccessApiUsageException is thrown. 063 * @return the Map of generated keys for a single row 064 * @throws InvalidDataAccessApiUsageException if keys for multiple rows are encountered 065 */ 066 Map<String, Object> getKeys() throws InvalidDataAccessApiUsageException; 067 068 /** 069 * Return a reference to the List that contains the keys. 070 * <p>Can be used for extracting keys for multiple rows (an unusual case), 071 * and also for adding new maps of keys. 072 * @return the List for the generated keys, with each entry representing 073 * an individual row through a Map of column names and key values 074 */ 075 List<Map<String, Object>> getKeyList(); 076 077}