1 /* 2 * Copyright 2002-2005 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</code> 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 * @since 1.1 39 * @see org.springframework.jdbc.core.JdbcTemplate 40 * @see org.springframework.jdbc.object.SqlUpdate 41 */ 42 public interface KeyHolder { 43 44 /** 45 * Retrieve the first item from the first map, assuming that there is just 46 * one item and just one map, and that the item is a number. 47 * This is the typical case: a single, numeric generated key. 48 * <p>Keys are held in a List of Maps, where each item in the list represents 49 * the keys for each row. If there are multiple columns, then the Map will have 50 * multiple entries as well. If this method encounters multiple entries in 51 * either the map or the list meaning that multiple keys were returned, 52 * then an InvalidDataAccessApiUsageException is thrown. 53 * @return the generated key 54 * @throws InvalidDataAccessApiUsageException if multiple keys are encountered. 55 */ 56 Number getKey() throws InvalidDataAccessApiUsageException; 57 58 /** 59 * Retrieve the first map of keys. If there are multiple entries in the list 60 * (meaning that multiple rows had keys returned), then an 61 * InvalidDataAccessApiUsageException is thrown. 62 * @return the Map of generated keys 63 * @throws InvalidDataAccessApiUsageException if keys for multiple rows are encountered 64 */ 65 Map getKeys() throws InvalidDataAccessApiUsageException; 66 67 /** 68 * Return a reference to the List that contains the keys. 69 * Can be used for extracting keys for multiple rows (an unusual case), 70 * and also for adding new maps of keys. 71 * @return the List for the generated keys, with each entry being a Map 72 * of column names and key values 73 */ 74 List getKeyList(); 75 76 } 77