001/*
002 * Copyright 2002-2018 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.core;
018
019import java.sql.ResultSet;
020import java.sql.SQLException;
021import java.util.ArrayList;
022import java.util.List;
023
024import org.springframework.util.Assert;
025
026/**
027 * Adapter implementation of the ResultSetExtractor interface that delegates
028 * to a RowMapper which is supposed to create an object for each row.
029 * Each object is added to the results List of this ResultSetExtractor.
030 *
031 * <p>Useful for the typical case of one object per row in the database table.
032 * The number of entries in the results list will match the number of rows.
033 *
034 * <p>Note that a RowMapper object is typically stateless and thus reusable;
035 * just the RowMapperResultSetExtractor adapter is stateful.
036 *
037 * <p>A usage example with JdbcTemplate:
038 *
039 * <pre class="code">JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource);  // reusable object
040 * RowMapper rowMapper = new UserRowMapper();  // reusable object
041 *
042 * List allUsers = (List) jdbcTemplate.query(
043 *     "select * from user",
044 *     new RowMapperResultSetExtractor(rowMapper, 10));
045 *
046 * User user = (User) jdbcTemplate.queryForObject(
047 *     "select * from user where id=?", new Object[] {id},
048 *     new RowMapperResultSetExtractor(rowMapper, 1));</pre>
049 *
050 * <p>Alternatively, consider subclassing MappingSqlQuery from the {@code jdbc.object}
051 * package: Instead of working with separate JdbcTemplate and RowMapper objects,
052 * you can have executable query objects (containing row-mapping logic) there.
053 *
054 * @author Juergen Hoeller
055 * @since 1.0.2
056 * @param <T> the result element type
057 * @see RowMapper
058 * @see JdbcTemplate
059 * @see org.springframework.jdbc.object.MappingSqlQuery
060 */
061public class RowMapperResultSetExtractor<T> implements ResultSetExtractor<List<T>> {
062
063        private final RowMapper<T> rowMapper;
064
065        private final int rowsExpected;
066
067
068        /**
069         * Create a new RowMapperResultSetExtractor.
070         * @param rowMapper the RowMapper which creates an object for each row
071         */
072        public RowMapperResultSetExtractor(RowMapper<T> rowMapper) {
073                this(rowMapper, 0);
074        }
075
076        /**
077         * Create a new RowMapperResultSetExtractor.
078         * @param rowMapper the RowMapper which creates an object for each row
079         * @param rowsExpected the number of expected rows
080         * (just used for optimized collection handling)
081         */
082        public RowMapperResultSetExtractor(RowMapper<T> rowMapper, int rowsExpected) {
083                Assert.notNull(rowMapper, "RowMapper is required");
084                this.rowMapper = rowMapper;
085                this.rowsExpected = rowsExpected;
086        }
087
088
089        @Override
090        public List<T> extractData(ResultSet rs) throws SQLException {
091                List<T> results = (this.rowsExpected > 0 ? new ArrayList<>(this.rowsExpected) : new ArrayList<>());
092                int rowNum = 0;
093                while (rs.next()) {
094                        results.add(this.rowMapper.mapRow(rs, rowNum++));
095                }
096                return results;
097        }
098
099}