NamedParameterJdbcOperations


1   /*
2    * Copyright 2002-2006 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.core.namedparam;
18  
19  import java.util.List  ;
20  import java.util.Map  ;
21  
22  import org.springframework.dao.DataAccessException;
23  import org.springframework.jdbc.core.JdbcOperations;
24  import org.springframework.jdbc.core.RowCallbackHandler;
25  import org.springframework.jdbc.core.RowMapper;
26  import org.springframework.jdbc.support.KeyHolder;
27  import org.springframework.jdbc.support.rowset.SqlRowSet;
28  
29  /**
30   * Interface specifying a basic set of JDBC operations allowing
31   * the use of named parameters rather than the traditional '?' placeholders.
32   *
33   * <p>This is an alternative to the classic JdbcOperations interface,
34   * implemented by NamedParameterJdbcTemplate. This interface is not often used
35   * directly, but provides a useful option to enhance testability, as it can
36   * easily be mocked or stubbed.
37   *
38   * @author Thomas Risberg
39   * @author Juergen Hoeller
40   * @since 2.0
41   * @see NamedParameterJdbcTemplate
42   * @see org.springframework.jdbc.core.JdbcOperations
43   */
44  public interface NamedParameterJdbcOperations {
45  
46      /**
47       * Expose the classic Spring JdbcTemplate to allow invocation of
48       * classic JDBC operations.
49       */
50      JdbcOperations getJdbcOperations();
51  
52  
53      //-------------------------------------------------------------------------
54      // Query operations
55      //-------------------------------------------------------------------------
56  
57      /**
58       * Query given SQL to create a prepared statement from SQL and a list of
59       * arguments to bind to the query, reading the ResultSet on a per-row basis
60       * with a RowCallbackHandler.
61       * @param sql SQL query to execute
62       * @param paramSource container of arguments to bind to the query
63       * @param rch object that will extract results, one row at a time
64       * @throws DataAccessException if the query fails
65       */
66      public void query(String   sql, SqlParameterSource paramSource, RowCallbackHandler rch)
67              throws DataAccessException;
68  
69      /**
70       * Query given SQL to create a prepared statement from SQL and a list of
71       * arguments to bind to the query, reading the ResultSet on a per-row basis
72       * with a RowCallbackHandler.
73       * @param sql SQL query to execute
74       * @param paramMap map of parameters to bind to the query
75       * (leaving it to the PreparedStatement to guess the corresponding SQL type)
76       * @param rch object that will extract results, one row at a time
77       * @throws org.springframework.dao.DataAccessException if the query fails
78       */
79      void query(String   sql, Map   paramMap, RowCallbackHandler rch) throws DataAccessException;
80  
81      /**
82       * Query given SQL to create a prepared statement from SQL and a list
83       * of arguments to bind to the query, mapping each row to a Java object
84       * via a RowMapper.
85       * @param sql SQL query to execute
86       * @param paramSource container of arguments to bind to the query
87       * @param rowMapper object that will map one object per row
88       * @return the result List, containing mapped objects
89       * @throws org.springframework.dao.DataAccessException if the query fails
90       */
91      List   query(String   sql, SqlParameterSource paramSource, RowMapper rowMapper)
92              throws DataAccessException;
93  
94      /**
95       * Query given SQL to create a prepared statement from SQL and a list
96       * of arguments to bind to the query, mapping each row to a Java object
97       * via a RowMapper.
98       * @param sql SQL query to execute
99       * @param paramMap map of parameters to bind to the query
100      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
101      * @param rowMapper object that will map one object per row
102      * @return the result List, containing mapped objects
103      * @throws org.springframework.dao.DataAccessException if the query fails
104      */
105     List   query(String   sql, Map   paramMap, RowMapper rowMapper) throws DataAccessException;
106 
107     /**
108      * Query given SQL to create a prepared statement from SQL and a list
109      * of arguments to bind to the query, mapping a single result row to a
110      * Java object via a RowMapper.
111      * @param sql SQL query to execute
112      * @param paramSource container of arguments to bind to the query
113      * @param rowMapper object that will map one object per row
114      * @return the single mapped object
115      * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
116      * if the query does not return exactly one row, or does not return exactly
117      * one column in that row
118      * @throws org.springframework.dao.DataAccessException if the query fails
119      */
120     Object   queryForObject(String   sql, SqlParameterSource paramSource, RowMapper rowMapper)
121             throws DataAccessException;
122 
123     /**
124      * Query given SQL to create a prepared statement from SQL and a list
125      * of arguments to bind to the query, mapping a single result row to a
126      * Java object via a RowMapper.
127      * @param sql SQL query to execute
128      * @param paramMap map of parameters to bind to the query
129      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
130      * @param rowMapper object that will map one object per row
131      * @return the single mapped object
132      * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
133      * if the query does not return exactly one row, or does not return exactly
134      * one column in that row
135      * @throws org.springframework.dao.DataAccessException if the query fails
136      */
137     Object   queryForObject(String   sql, Map   paramMap, RowMapper rowMapper) throws DataAccessException;
138 
139     /**
140      * Query given SQL to create a prepared statement from SQL and a
141      * list of arguments to bind to the query, expecting a result object.
142      * <p>The query is expected to be a single row/single column query; the returned
143      * result will be directly mapped to the corresponding object type.
144      * @param sql SQL query to execute
145      * @param paramSource container of arguments to bind to the query
146      * @param requiredType the type that the result object is expected to match
147      * @return the result object of the required type, or <code>null</code> in case of SQL NULL
148      * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
149      * if the query does not return exactly one row, or does not return exactly
150      * one column in that row
151      * @throws org.springframework.dao.DataAccessException if the query fails
152      * @see org.springframework.jdbc.core.JdbcTemplate#queryForObject(String, Class)
153      */
154     Object   queryForObject(String   sql, SqlParameterSource paramSource, Class   requiredType)
155             throws DataAccessException;
156 
157     /**
158      * Query given SQL to create a prepared statement from SQL and a
159      * list of arguments to bind to the query, expecting a result object.
160      * <p>The query is expected to be a single row/single column query; the returned
161      * result will be directly mapped to the corresponding object type.
162      * @param sql SQL query to execute
163      * @param paramMap map of parameters to bind to the query
164      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
165      * @param requiredType the type that the result object is expected to match
166      * @return the result object of the required type, or <code>null</code> in case of SQL NULL
167      * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
168      * if the query does not return exactly one row, or does not return exactly
169      * one column in that row
170      * @throws org.springframework.dao.DataAccessException if the query fails
171      * @see org.springframework.jdbc.core.JdbcTemplate#queryForObject(String, Class)
172      */
173     Object   queryForObject(String   sql, Map   paramMap, Class   requiredType) throws DataAccessException;
174 
175     /**
176      * Query given SQL to create a prepared statement from SQL and a
177      * list of arguments to bind to the query, expecting a result Map.
178      * <p>The query is expected to be a single row query; the result row will be
179      * mapped to a Map (one entry for each column, using the column name as the key).
180      * @param sql SQL query to execute
181      * @param paramSource container of arguments to bind to the query
182      * @return the result Map (one entry for each column, using the column name as the key)
183      * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
184      * if the query does not return exactly one row, or does not return exactly
185      * one column in that row
186      * @throws org.springframework.dao.DataAccessException if the query fails
187      * @see org.springframework.jdbc.core.JdbcTemplate#queryForMap(String)
188      * @see org.springframework.jdbc.core.ColumnMapRowMapper
189      */
190     Map   queryForMap(String   sql, SqlParameterSource paramSource) throws DataAccessException;
191 
192     /**
193      * Query given SQL to create a prepared statement from SQL and a
194      * list of arguments to bind to the query, expecting a result Map.
195      * The queryForMap() methods defined by this interface are appropriate
196      * when you don't have a domain model. Otherwise, consider using
197      * one of the queryForObject() methods.
198      * <p>The query is expected to be a single row query; the result row will be
199      * mapped to a Map (one entry for each column, using the column name as the key).
200      * @param sql SQL query to execute
201      * @param paramMap map of parameters to bind to the query
202      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
203      * @return the result Map (one entry for each column, using the column name as the key)
204      * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
205      * if the query does not return exactly one row, or does not return exactly
206      * one column in that row
207      * @throws org.springframework.dao.DataAccessException if the query fails
208      * @see org.springframework.jdbc.core.JdbcTemplate#queryForMap(String)
209      * @see org.springframework.jdbc.core.ColumnMapRowMapper
210      */
211     Map   queryForMap(String   sql, Map   paramMap) throws DataAccessException;
212 
213     /**
214      * Query given SQL to create a prepared statement from SQL and a
215      * list of arguments to bind to the query, resulting in a long value.
216      * <p>The query is expected to be a single row/single column query that
217      * results in a long value.
218      * @param sql SQL query to execute
219      * @param paramSource container of arguments to bind to the query
220      * @return the long value, or 0 in case of SQL NULL
221      * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
222      * if the query does not return exactly one row, or does not return exactly
223      * one column in that row
224      * @throws org.springframework.dao.DataAccessException if the query fails
225      * @see org.springframework.jdbc.core.JdbcTemplate#queryForLong(String)
226      */
227     long queryForLong(String   sql, SqlParameterSource paramSource) throws DataAccessException;
228 
229     /**
230      * Query given SQL to create a prepared statement from SQL and a
231      * list of arguments to bind to the query, resulting in a long value.
232      * <p>The query is expected to be a single row/single column query that
233      * results in a long value.
234      * @param sql SQL query to execute
235      * @param paramMap map of parameters to bind to the query
236      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
237      * @return the long value, or 0 in case of SQL NULL
238      * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
239      * if the query does not return exactly one row, or does not return exactly
240      * one column in that row
241      * @throws org.springframework.dao.DataAccessException if the query fails
242      * @see org.springframework.jdbc.core.JdbcTemplate#queryForLong(String)
243      */
244     long queryForLong(String   sql, Map   paramMap) throws DataAccessException;
245 
246     /**
247      * Query given SQL to create a prepared statement from SQL and a
248      * list of arguments to bind to the query, resulting in an int value.
249      * <p>The query is expected to be a single row/single column query that
250      * results in an int value.
251      * @param sql SQL query to execute
252      * @param paramSource container of arguments to bind to the query
253      * @return the int value, or 0 in case of SQL NULL
254      * @throws org.springframework.dao.IncorrectResultSizeDataAccessException if the query does not return
255      * exactly one row, or does not return exactly one column in that row
256      * @throws org.springframework.dao.DataAccessException if the query fails
257      * @see org.springframework.jdbc.core.JdbcTemplate#queryForInt(String)
258      */
259     int queryForInt(String   sql, SqlParameterSource paramSource) throws DataAccessException;
260 
261     /**
262      * Query given SQL to create a prepared statement from SQL and a
263      * list of arguments to bind to the query, resulting in an int value.
264      * <p>The query is expected to be a single row/single column query that
265      * results in an int value.
266      * @param sql SQL query to execute
267      * @param paramMap map of parameters to bind to the query
268      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
269      * @return the int value, or 0 in case of SQL NULL
270      * @throws org.springframework.dao.IncorrectResultSizeDataAccessException if the query does not return
271      * exactly one row, or does not return exactly one column in that row
272      * @throws org.springframework.dao.DataAccessException if the query fails
273      * @see org.springframework.jdbc.core.JdbcTemplate#queryForInt(String)
274      */
275     int queryForInt(String   sql, Map   paramMap) throws DataAccessException;
276 
277     /**
278      * Query given SQL to create a prepared statement from SQL and a
279      * list of arguments to bind to the query, expecting a result list.
280      * <p>The results will be mapped to a List (one entry for each row) of
281      * result objects, each of them matching the specified element type.
282      * @param sql SQL query to execute
283      * @param paramSource container of arguments to bind to the query
284      * @param elementType the required type of element in the result list
285      * (for example, <code>Integer.class</code>)
286      * @return a List of objects that match the specified element type
287      * @throws org.springframework.dao.DataAccessException if the query fails
288      * @see org.springframework.jdbc.core.JdbcTemplate#queryForList(String, Class)
289      * @see org.springframework.jdbc.core.SingleColumnRowMapper
290      */
291     List   queryForList(String   sql, SqlParameterSource paramSource, Class   elementType)
292             throws DataAccessException;
293 
294     /**
295      * Query given SQL to create a prepared statement from SQL and a
296      * list of arguments to bind to the query, expecting a result list.
297      * <p>The results will be mapped to a List (one entry for each row) of
298      * result objects, each of them matching the specified element type.
299      * @param sql SQL query to execute
300      * @param paramMap map of parameters to bind to the query
301      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
302      * @param elementType the required type of element in the result list
303      * (for example, <code>Integer.class</code>)
304      * @return a List of objects that match the specified element type
305      * @throws org.springframework.dao.DataAccessException if the query fails
306      * @see org.springframework.jdbc.core.JdbcTemplate#queryForList(String, Class)
307      * @see org.springframework.jdbc.core.SingleColumnRowMapper
308      */
309     List   queryForList(String   sql, Map   paramMap, Class   elementType) throws DataAccessException;
310 
311     /**
312      * Query given SQL to create a prepared statement from SQL and a
313      * list of arguments to bind to the query, expecting a result list.
314      * <p>The results will be mapped to a List (one entry for each row) of
315      * Maps (one entry for each column, using the column name as the key).
316      * Thus  Each element in the list will be of the form returned by this interface's
317      * queryForMap() methods.
318      * @param sql SQL query to execute
319      * @param paramSource container of arguments to bind to the query
320      * @return a List that contains a Map per row
321      * @throws org.springframework.dao.DataAccessException if the query fails
322      * @see org.springframework.jdbc.core.JdbcTemplate#queryForList(String)
323      */
324     List   queryForList(String   sql, SqlParameterSource paramSource) throws DataAccessException;
325 
326     /**
327      * Query given SQL to create a prepared statement from SQL and a
328      * list of arguments to bind to the query, expecting a result list.
329      * <p>The results will be mapped to a List (one entry for each row) of
330      * Maps (one entry for each column, using the column name as the key).
331      * Each element in the list will be of the form returned by this interface's
332      * queryForMap() methods.
333      * @param sql SQL query to execute
334      * @param paramMap map of parameters to bind to the query
335      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
336      * @return a List that contains a Map per row
337      * @throws org.springframework.dao.DataAccessException if the query fails
338      * @see org.springframework.jdbc.core.JdbcTemplate#queryForList(String)
339      */
340     List   queryForList(String   sql, Map   paramMap) throws DataAccessException;
341 
342     /**
343      * Query given SQL to create a prepared statement from SQL and a
344      * list of arguments to bind to the query, expecting a SqlRowSet.
345      * <p>The results will be mapped to an SqlRowSet which holds the data in a
346      * disconnected fashion. This wrapper will translate any SQLExceptions thrown.
347      * <p>Note that that, for the default implementation, JDBC RowSet support needs to
348      * be available at runtime: by default, Sun's <code>com.sun.rowset.CachedRowSetImpl</code>
349      * class is used, which is part of JDK 1.5+ and also available separately as part of
350      * Sun's JDBC RowSet Implementations download (rowset.jar).
351      * @param sql SQL query to execute
352      * @param paramSource container of arguments to bind to the query
353      * @return a SqlRowSet representation (possibly a wrapper around a
354      * <code>javax.sql.rowset.CachedRowSet</code>)
355      * @throws org.springframework.dao.DataAccessException if there is any problem executing the query
356      * @see org.springframework.jdbc.core.JdbcTemplate#queryForRowSet(String)
357      * @see org.springframework.jdbc.core.SqlRowSetResultSetExtractor
358      * @see javax.sql.rowset.CachedRowSet
359      */
360     SqlRowSet queryForRowSet(String   sql, SqlParameterSource paramSource) throws DataAccessException;
361 
362     /**
363      * Query given SQL to create a prepared statement from SQL and a
364      * list of arguments to bind to the query, expecting a SqlRowSet.
365      * <p>The results will be mapped to an SqlRowSet which holds the data in a
366      * disconnected fashion. This wrapper will translate any SQLExceptions thrown.
367      * <p>Note that that, for the default implementation, JDBC RowSet support needs to
368      * be available at runtime: by default, Sun's <code>com.sun.rowset.CachedRowSetImpl</code>
369      * class is used, which is part of JDK 1.5+ and also available separately as part of
370      * Sun's JDBC RowSet Implementations download (rowset.jar).
371      * @param sql SQL query to execute
372      * @param paramMap map of parameters to bind to the query
373      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
374      * @return a SqlRowSet representation (possibly a wrapper around a
375      * <code>javax.sql.rowset.CachedRowSet</code>)
376      * @throws org.springframework.dao.DataAccessException if there is any problem executing the query
377      * @see org.springframework.jdbc.core.JdbcTemplate#queryForRowSet(String)
378      * @see org.springframework.jdbc.core.SqlRowSetResultSetExtractor
379      * @see javax.sql.rowset.CachedRowSet
380      */
381     SqlRowSet queryForRowSet(String   sql, Map   paramMap) throws DataAccessException;
382 
383 
384     //-------------------------------------------------------------------------
385     // Update operations
386     //-------------------------------------------------------------------------
387 
388     /**
389      * Issue an update via a prepared statement, binding the given arguments.
390      * @param sql SQL containing named parameters
391      * @param paramSource container of arguments and SQL types to bind to the query
392      * @return the number of rows affected
393      * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
394      */
395     int update(String   sql, SqlParameterSource paramSource) throws DataAccessException;
396 
397     /**
398      * Issue an update via a prepared statement, binding the given arguments.
399      * @param sql SQL containing named parameters
400      * @param paramMap map of parameters to bind to the query
401      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
402      * @return the number of rows affected
403      * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
404      */
405     int update(String   sql, Map   paramMap) throws DataAccessException;
406 
407     /**
408      * Issue an update via a prepared statement, binding the given arguments,
409      * returning generated keys.
410      * @param sql SQL containing named parameters
411      * @param paramSource container of arguments and SQL types to bind to the query
412      * @param generatedKeyHolder KeyHolder that will hold the generated keys
413      * @return the number of rows affected
414      * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
415      * @see MapSqlParameterSource
416      * @see org.springframework.jdbc.support.GeneratedKeyHolder
417      */
418     int update(String   sql, SqlParameterSource paramSource, KeyHolder generatedKeyHolder)
419             throws DataAccessException;
420 
421     /**
422      * Issue an update via a prepared statement, binding the given arguments,
423      * returning generated keys.
424      * @param sql SQL containing named parameters
425      * @param paramSource container of arguments and SQL types to bind to the query
426      * @param generatedKeyHolder KeyHolder that will hold the generated keys
427      * @param keyColumnNames names of the columns that will have keys generated for them
428      * @return the number of rows affected
429      * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
430      * @see MapSqlParameterSource
431      * @see org.springframework.jdbc.support.GeneratedKeyHolder
432      */
433     int update(
434             String   sql, SqlParameterSource paramSource, KeyHolder generatedKeyHolder, String  [] keyColumnNames)
435             throws DataAccessException;
436 
437 }
438
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags