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.object; 018 019import java.sql.ResultSet; 020import java.sql.SQLException; 021import java.util.Map; 022 023import javax.sql.DataSource; 024 025import org.springframework.jdbc.core.RowMapper; 026import org.springframework.lang.Nullable; 027 028/** 029 * Reusable RDBMS query in which concrete subclasses must implement 030 * the abstract mapRow(ResultSet, int) method to map each row of 031 * the JDBC ResultSet into an object. 032 * 033 * <p>Such manual mapping is usually preferable to "automatic" 034 * mapping using reflection, which can become complex in non-trivial 035 * cases. For example, the present class allows different objects 036 * to be used for different rows (for example, if a subclass is indicated). 037 * It allows computed fields to be set. And there's no need for 038 * ResultSet columns to have the same names as bean properties. 039 * The Pareto Principle in action: going the extra mile to automate 040 * the extraction process makes the framework much more complex 041 * and delivers little real benefit. 042 * 043 * <p>Subclasses can be constructed providing SQL, parameter types 044 * and a DataSource. SQL will often vary between subclasses. 045 * 046 * @author Rod Johnson 047 * @author Thomas Risberg 048 * @author Jean-Pierre Pawlak 049 * @param <T> the result type 050 * @see org.springframework.jdbc.object.MappingSqlQuery 051 * @see org.springframework.jdbc.object.SqlQuery 052 */ 053public abstract class MappingSqlQueryWithParameters<T> extends SqlQuery<T> { 054 055 /** 056 * Constructor to allow use as a JavaBean. 057 */ 058 public MappingSqlQueryWithParameters() { 059 } 060 061 /** 062 * Convenient constructor with DataSource and SQL string. 063 * @param ds the DataSource to use to get connections 064 * @param sql the SQL to run 065 */ 066 public MappingSqlQueryWithParameters(DataSource ds, String sql) { 067 super(ds, sql); 068 } 069 070 071 /** 072 * Implementation of protected abstract method. This invokes the subclass's 073 * implementation of the mapRow() method. 074 */ 075 @Override 076 protected RowMapper<T> newRowMapper(@Nullable Object[] parameters, @Nullable Map<?, ?> context) { 077 return new RowMapperImpl(parameters, context); 078 } 079 080 /** 081 * Subclasses must implement this method to convert each row 082 * of the ResultSet into an object of the result type. 083 * @param rs the ResultSet we're working through 084 * @param rowNum row number (from 0) we're up to 085 * @param parameters to the query (passed to the execute() method). 086 * Subclasses are rarely interested in these. 087 * It can be {@code null} if there are no parameters. 088 * @param context passed to the execute() method. 089 * It can be {@code null} if no contextual information is need. 090 * @return an object of the result type 091 * @throws SQLException if there's an error extracting data. 092 * Subclasses can simply not catch SQLExceptions, relying on the 093 * framework to clean up. 094 */ 095 @Nullable 096 protected abstract T mapRow(ResultSet rs, int rowNum, @Nullable Object[] parameters, @Nullable Map<?, ?> context) 097 throws SQLException; 098 099 100 /** 101 * Implementation of RowMapper that calls the enclosing 102 * class's {@code mapRow} method for each row. 103 */ 104 protected class RowMapperImpl implements RowMapper<T> { 105 106 @Nullable 107 private final Object[] params; 108 109 @Nullable 110 private final Map<?, ?> context; 111 112 /** 113 * Use an array results. More efficient if we know how many results to expect. 114 */ 115 public RowMapperImpl(@Nullable Object[] parameters, @Nullable Map<?, ?> context) { 116 this.params = parameters; 117 this.context = context; 118 } 119 120 @Override 121 @Nullable 122 public T mapRow(ResultSet rs, int rowNum) throws SQLException { 123 return MappingSqlQueryWithParameters.this.mapRow(rs, rowNum, this.params, this.context); 124 } 125 } 126 127}