001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.dbutils.handlers;
018    
019    import java.sql.ResultSet;
020    import java.sql.SQLException;
021    import java.util.HashMap;
022    import java.util.Map;
023    
024    import org.apache.commons.dbutils.ResultSetHandler;
025    
026    /**
027     * <p>
028     * <code>ResultSetHandler</code> implementation that returns a Map.
029     * <code>ResultSet</code> rows are converted into objects (Vs) which are then stored
030     * in a Map under the given keys (Ks).
031     * </p>
032     *
033     * @param <K> the type of keys maintained by the returned map
034     * @param <V> the type of mapped values
035     * @see org.apache.commons.dbutils.ResultSetHandler
036     * @since DbUtils 1.3
037     */
038    public abstract class AbstractKeyedHandler<K, V> implements ResultSetHandler<Map<K, V>> {
039    
040    
041        /**
042         * Convert each row's columns into a Map and store then
043         * in a <code>Map</code> under <code>ResultSet.getObject(key)</code> key.
044         * @param rs <code>ResultSet</code> to process.
045         * @return A <code>Map</code>, never <code>null</code>.
046         * @throws SQLException if a database access error occurs
047         * @see org.apache.commons.dbutils.ResultSetHandler#handle(java.sql.ResultSet)
048         */
049        public Map<K, V> handle(ResultSet rs) throws SQLException {
050            Map<K, V> result = createMap();
051            while (rs.next()) {
052                result.put(createKey(rs), createRow(rs));
053            }
054            return result;
055        }
056    
057        /**
058         * This factory method is called by <code>handle()</code> to create the Map
059         * to store records in.  This implementation returns a <code>HashMap</code>
060         * instance.
061         *
062         * @return Map to store records in
063         */
064        protected Map<K, V> createMap() {
065            return new HashMap<K, V>();
066        }
067    
068        /**
069         * This factory method is called by <code>handle()</code> to retrieve the
070         * key value from the current <code>ResultSet</code> row.
071         * @param rs ResultSet to create a key from
072         * @return K from the configured key column name/index
073         * @throws SQLException if a database access error occurs
074         */
075        protected abstract K createKey(ResultSet rs) throws SQLException;
076    
077        /**
078         * This factory method is called by <code>handle()</code> to store the
079         * current <code>ResultSet</code> row in some object.
080         * @param rs ResultSet to create a row from
081         * @return V object created from the current row
082         * @throws SQLException if a database access error occurs
083         */
084        protected abstract V createRow(ResultSet rs) throws SQLException;
085    
086    }