1 /* 2 * Copyright 2002-2012 the original author or authors. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package org.springframework.jdbc.support; 18 19 import java.util.List; 20 import java.util.Map; 21 22 import org.springframework.dao.InvalidDataAccessApiUsageException; 23 24 /** 25 * Interface for retrieving keys, typically used for auto-generated keys 26 * as potentially returned by JDBC insert statements. 27 * 28 * <p>Implementations of this interface can hold any number of keys. 29 * In the general case, the keys are returned as a List containing one Map 30 * for each row of keys. 31 * 32 * <p>Most applications only use on key per row and process only one row at a 33 * time in an insert statement. In these cases, just call {@code getKey} 34 * to retrieve the key. The returned value is a Number here, which is the 35 * usual type for auto-generated keys. 36 * 37 * @author Thomas Risberg 38 * @author Juergen Hoeller 39 * @since 1.1 40 * @see org.springframework.jdbc.core.JdbcTemplate 41 * @see org.springframework.jdbc.object.SqlUpdate 42 */ 43 public interface KeyHolder { 44 45 /** 46 * Retrieve the first item from the first map, assuming that there is just 47 * one item and just one map, and that the item is a number. 48 * This is the typical case: a single, numeric generated key. 49 * <p>Keys are held in a List of Maps, where each item in the list represents 50 * the keys for each row. If there are multiple columns, then the Map will have 51 * multiple entries as well. If this method encounters multiple entries in 52 * either the map or the list meaning that multiple keys were returned, 53 * then an InvalidDataAccessApiUsageException is thrown. 54 * @return the generated key 55 * @throws InvalidDataAccessApiUsageException if multiple keys are encountered. 56 */ 57 Number getKey() throws InvalidDataAccessApiUsageException; 58 59 /** 60 * Retrieve the first map of keys. If there are multiple entries in the list 61 * (meaning that multiple rows had keys returned), then an 62 * InvalidDataAccessApiUsageException is thrown. 63 * @return the Map of generated keys 64 * @throws InvalidDataAccessApiUsageException if keys for multiple rows are encountered 65 */ 66 Map<String, Object> getKeys() throws InvalidDataAccessApiUsageException; 67 68 /** 69 * Return a reference to the List that contains the keys. 70 * Can be used for extracting keys for multiple rows (an unusual case), 71 * and also for adding new maps of keys. 72 * @return the List for the generated keys, with each entry being a Map 73 * of column names and key values 74 */ 75 List<Map<String, Object>> getKeyList(); 76 77 }