001 package com.alexkasko.springjdbc.iterable;
002
003 import org.springframework.dao.DataAccessException;
004 import org.springframework.jdbc.core.PreparedStatementCreator;
005 import org.springframework.jdbc.core.PreparedStatementSetter;
006 import org.springframework.jdbc.core.RowMapper;
007
008 import java.util.Map;
009
010 /**
011 * Extension interface for {@code JdbcOperations}. All methods, that return {@code List}
012 * mirrored with {@code queryForIter} methods that return {@link CloseableIterator}.
013 * Javadocs borrowed from {@code JdbcOperations}.
014 *
015 * @author alexkasko
016 * Date: 11/7/12
017 * @see IterableNamedParameterJdbcOperations
018 */
019 public interface IterableJdbcOperations {
020 /**
021 * Query using a prepared statement, mapping each row to a Java object
022 * via a RowMapper.
023 * <p>A PreparedStatementCreator can either be implemented directly or
024 * configured through a PreparedStatementCreatorFactory.
025 *
026 * @param psc object that can create a PreparedStatement given a Connection
027 * If this is null, the SQL will be assumed to contain no bind parameters.
028 * @param rowMapper object that will map one object per row
029 * @return the result Iterator, containing mapped objects
030 * @throws DataAccessException if there is any problem
031 * @see org.springframework.jdbc.core.PreparedStatementCreatorFactory
032 */
033 <T> CloseableIterator<T> queryForIter(PreparedStatementCreator psc, RowMapper<T> rowMapper) throws DataAccessException;
034
035 /**
036 * Query using a prepared statement, mapping each row to a Java object
037 * via a RowMapper.
038 * <p>A PreparedStatementCreator can either be implemented directly or
039 * configured through a PreparedStatementCreatorFactory.
040 *
041 * @param psc object that can create a PreparedStatement given a Connection
042 * @param pss object that knows how to set values on the prepared statement.
043 * If this is null, the SQL will be assumed to contain no bind parameters.
044 * @param rowMapper object that will map one object per row
045 * @return the result Iterator, containing mapped objects
046 * @throws DataAccessException if there is any problem
047 * @see org.springframework.jdbc.core.PreparedStatementCreatorFactory
048 */
049 <T> CloseableIterator<T> queryForIter(PreparedStatementCreator psc, PreparedStatementSetter pss, RowMapper<T> rowMapper)
050 throws DataAccessException;
051
052 /**
053 * Execute a query given static SQL, mapping each row to a Java object
054 * via a RowMapper.
055 * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
056 * execute a static query with a PreparedStatement, use the overloaded
057 * <code>queryForIter</code> method with <code>null</code> as argument array.
058 *
059 * @param sql SQL query to execute
060 * @param rowMapper object that will map one object per row
061 * @return the result Iterator, containing mapped objects
062 * @throws DataAccessException if there is any problem executing the query
063 * @see #queryForIter(String, Object[], RowMapper)
064 */
065 <T> CloseableIterator<T> queryForIter(String sql, RowMapper<T> rowMapper) throws DataAccessException;
066
067 /**
068 * Execute a query for a result шterator, given static SQL.
069 * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
070 * execute a static query with a PreparedStatement, use the overloaded
071 * <code>queryForIter</code> method with <code>null</code> as argument array.
072 * <p>The results will be mapped to a Iterator (one entry for each row) of
073 * result objects, each of them matching the specified element type.
074 *
075 * @param sql SQL query to execute
076 * @param elementType the required type of element in the result шterator
077 * (for example, <code>Integer.class</code>)
078 * @return an Iterator of objects that match the specified element type
079 * @throws DataAccessException if there is any problem executing the query
080 * @see #queryForIter(String, Object[], Class)
081 * @see org.springframework.jdbc.core.SingleColumnRowMapper
082 */
083 <T> CloseableIterator<T> queryForIter(String sql, Class<T> elementType) throws DataAccessException;
084
085 /**
086 * Execute a query for a result iterator, given static SQL.
087 * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
088 * execute a static query with a PreparedStatement, use the overloaded
089 * <code>queryForIter</code> method with <code>null</code> as argument array.
090 * <p>The results will be mapped to a Iterator (one entry for each row) of
091 * Maps (one entry for each column using the column name as the key).
092 * Each element in the iterator will be of the form returned by this interface's
093 * queryForMap() methods.
094 *
095 * @param sql SQL query to execute
096 * @return an Iterator that contains a Map per row
097 * @throws DataAccessException if there is any problem executing the query
098 * @see #queryForIter(String, Object[])
099 */
100 CloseableIterator<Map<String, Object>> queryForIter(String sql) throws DataAccessException;
101
102 /**
103 * Query given SQL to create a prepared statement from SQL and a
104 * PreparedStatementSetter implementation that knows how to bind values
105 * to the query, mapping each row to a Java object via a RowMapper.
106 *
107 * @param sql SQL query to execute
108 * @param pss object that knows how to set values on the prepared statement.
109 * If this is <code>null</code>, the SQL will be assumed to contain no bind parameters.
110 * Even if there are no bind parameters, this object may be used to
111 * set fetch size and other performance options.
112 * @param rowMapper object that will map one object per row
113 * @return the result Iterator, containing mapped objects
114 * @throws DataAccessException if the query fails
115 */
116 <T> CloseableIterator<T> queryForIter(String sql, PreparedStatementSetter pss, RowMapper<T> rowMapper)
117 throws DataAccessException;
118
119 /**
120 * Query given SQL to create a prepared statement from SQL and a list
121 * of arguments to bind to the query, mapping each row to a Java object
122 * via a RowMapper.
123 *
124 * @param sql SQL query to execute
125 * @param args arguments to bind to the query
126 * @param argTypes SQL types of the arguments
127 * (constants from <code>java.sql.Types</code>)
128 * @param rowMapper object that will map one object per row
129 * @return the result Iterator, containing mapped objects
130 * @throws DataAccessException if the query fails
131 * @see java.sql.Types
132 */
133 <T> CloseableIterator<T> queryForIter(String sql, Object[] args, int[] argTypes, RowMapper<T> rowMapper)
134 throws DataAccessException;
135
136 /**
137 * Query given SQL to create a prepared statement from SQL and a list
138 * of arguments to bind to the query, mapping each row to a Java object
139 * via a RowMapper.
140 *
141 * @param sql SQL query to execute
142 * @param args arguments to bind to the query
143 * (leaving it to the PreparedStatement to guess the corresponding SQL type);
144 * may also contain {@link org.springframework.jdbc.core.SqlParameterValue} objects which indicate not
145 * only the argument value but also the SQL type and optionally the scale
146 * @param rowMapper object that will map one object per row
147 * @return the result Iterator, containing mapped objects
148 * @throws DataAccessException if the query fails
149 */
150 <T> CloseableIterator<T> queryForIter(String sql, Object[] args, RowMapper<T> rowMapper) throws DataAccessException;
151
152 /**
153 * Query given SQL to create a prepared statement from SQL and a list
154 * of arguments to bind to the query, mapping each row to a Java object
155 * via a RowMapper.
156 *
157 * @param sql SQL query to execute
158 * @param rowMapper object that will map one object per row
159 * @param args arguments to bind to the query
160 * (leaving it to the PreparedStatement to guess the corresponding SQL type);
161 * may also contain {@link org.springframework.jdbc.core.SqlParameterValue} objects which indicate not
162 * only the argument value but also the SQL type and optionally the scale
163 * @return the result List, containing mapped objects
164 * @throws DataAccessException if the query fails
165 */
166 <T> CloseableIterator<T> queryForIter(String sql, RowMapper<T> rowMapper, Object... args) throws DataAccessException;
167
168 /**
169 * Query given SQL to create a prepared statement from SQL and a
170 * list of arguments to bind to the query, expecting a result iterator.
171 * <p>The results will be mapped to a Iterator (one entry for each row) of
172 * result objects, each of them matching the specified element type.
173 *
174 * @param sql SQL query to execute
175 * @param args arguments to bind to the query
176 * @param argTypes SQL types of the arguments
177 * (constants from <code>java.sql.Types</code>)
178 * @param elementType the required type of element in the result iterator
179 * (for example, <code>Integer.class</code>)
180 * @return a Iterator of objects that match the specified element type
181 * @throws DataAccessException if the query fails
182 * @see #queryForIter(String, Class)
183 * @see org.springframework.jdbc.core.SingleColumnRowMapper
184 */
185 <T> CloseableIterator<T> queryForIter(String sql, Object[] args, int[] argTypes, Class<T> elementType)
186 throws DataAccessException;
187
188 /**
189 * Query given SQL to create a prepared statement from SQL and a
190 * list of arguments to bind to the query, expecting a result iterator.
191 * <p>The results will be mapped to an Iterator (one entry for each row) of
192 * result objects, each of them matching the specified element type.
193 *
194 * @param sql SQL query to execute
195 * @param args arguments to bind to the query
196 * (leaving it to the PreparedStatement to guess the corresponding SQL type);
197 * may also contain {@link org.springframework.jdbc.core.SqlParameterValue} objects which indicate not
198 * only the argument value but also the SQL type and optionally the scale
199 * @param elementType the required type of element in the result iterator
200 * (for example, <code>Integer.class</code>)
201 * @return an Iterator of objects that match the specified element type
202 * @throws DataAccessException if the query fails
203 * @see #queryForIter(String, Class)
204 * @see org.springframework.jdbc.core.SingleColumnRowMapper
205 */
206 <T> CloseableIterator<T> queryForIter(String sql, Object[] args, Class<T> elementType) throws DataAccessException;
207
208 /**
209 * Query given SQL to create a prepared statement from SQL and a
210 * list of arguments to bind to the query, expecting a result iterator.
211 * <p>The results will be mapped to an Iterator (one entry for each row) of
212 * result objects, each of them matching the specified element type.
213 *
214 * @param sql SQL query to execute
215 * @param elementType the required type of element in the result iterator
216 * (for example, <code>Integer.class</code>)
217 * @param args arguments to bind to the query
218 * (leaving it to the PreparedStatement to guess the corresponding SQL type);
219 * may also contain {@link org.springframework.jdbc.core.SqlParameterValue} objects which indicate not
220 * only the argument value but also the SQL type and optionally the scale
221 * @return an Iterator of objects that match the specified element type
222 * @throws DataAccessException if the query fails
223 * @see #queryForIter(String, Class)
224 * @see org.springframework.jdbc.core.SingleColumnRowMapper
225 */
226 <T> CloseableIterator<T> queryForIter(String sql, Class<T> elementType, Object... args) throws DataAccessException;
227
228 /**
229 * Query given SQL to create a prepared statement from SQL and a
230 * list of arguments to bind to the query, expecting a result iterator.
231 * <p>The results will be mapped to an Iterator (one entry for each row) of
232 * Maps (one entry for each column, using the column name as the key).
233 * Thus Each element in the iterator will be of the form returned by {@code JdbcOperations}'
234 * queryForMap() methods.
235 *
236 * @param sql SQL query to execute
237 * @param args arguments to bind to the query
238 * @param argTypes SQL types of the arguments
239 * (constants from <code>java.sql.Types</code>)
240 * @return an Iterator that contains a Map per row
241 * @throws DataAccessException if the query fails
242 * @see #queryForIter(String)
243 * @see java.sql.Types
244 */
245 CloseableIterator<Map<String, Object>> queryForIter(String sql, Object[] args, int[] argTypes) throws DataAccessException;
246
247 /**
248 * Query given SQL to create a prepared statement from SQL and a
249 * list of arguments to bind to the query, expecting a result iterator.
250 * <p>The results will be mapped to an Iterator (one entry for each row) of
251 * Maps (one entry for each column, using the column name as the key).
252 * Each element in the iterator will be of the form returned by this interface's
253 * queryForMap() methods.
254 *
255 * @param sql SQL query to execute
256 * @param args arguments to bind to the query
257 * (leaving it to the PreparedStatement to guess the corresponding SQL type);
258 * may also contain {@link org.springframework.jdbc.core.SqlParameterValue} objects which indicate not
259 * only the argument value but also the SQL type and optionally the scale
260 * @return an Iterator that contains a Map per row
261 * @throws DataAccessException if the query fails
262 * @see #queryForIter(String)
263 */
264 CloseableIterator<Map<String, Object>> queryForIter(String sql, Object... args) throws DataAccessException;
265 }