Java > Open Source Codes > org > springframework > jdbc > core > JdbcOperations


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;
18
19 import java.util.List ;
20 import java.util.Map ;
21
22 import org.springframework.dao.DataAccessException;
23 import org.springframework.dao.IncorrectResultSizeDataAccessException;
24 import org.springframework.jdbc.support.KeyHolder;
25 import org.springframework.jdbc.support.rowset.SqlRowSet;
26
27 /**
28  * Interface specifying a basic set of JDBC operations.
29  * Implemented by JdbcTemplate. Not often used directly, but a useful option
30  * to enhance testability, as it can easily be mocked or stubbed.
31  *
32  * <p>Alternatively, the standard JDBC infrastructure can be mocked.
33  * However, mocking this interface constitutes significantly less work.
34  * As an alternative to a mock objects approach to testing
35  * data access code, consider the powerful integration
36  * testing support provided in the org.springframework.test
37  * package, shipped in spring-mock.jar.
38  *
39  * @author Rod Johnson
40  * @author Juergen Hoeller
41  * @see JdbcTemplate
42  */
43 public interface JdbcOperations {
44
45     //-------------------------------------------------------------------------
46 // Methods dealing with a plain java.sql.Connection
47 //-------------------------------------------------------------------------
48
49     /**
50      * Execute a JDBC data access operation, implemented as callback action
51      * working on a JDBC Connection. This allows for implementing arbitrary
52      * data access operations, within Spring's managed JDBC environment:
53      * that is, participating in Spring-managed transactions and converting
54      * JDBC SQLExceptions into Spring's DataAccessException hierarchy.
55      * <p>The callback action can return a result object, for example a
56      * domain object or a collection of domain objects.
57      * @param action the callback object that specifies the action
58      * @return a result object returned by the action, or <code>null</code>
59      * @throws DataAccessException if there is any problem
60      */
61     Object execute(ConnectionCallback action) throws DataAccessException;
62
63
64     //-------------------------------------------------------------------------
65 // Methods dealing with static SQL (java.sql.Statement)
66 //-------------------------------------------------------------------------
67
68     /**
69      * Execute a JDBC data access operation, implemented as callback action
70      * working on a JDBC Statement. This allows for implementing arbitrary data
71      * access operations on a single Statement, within Spring's managed JDBC
72      * environment: that is, participating in Spring-managed transactions and
73      * converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
74      * <p>The callback action can return a result object, for example a
75      * domain object or a collection of domain objects.
76      * @param action callback object that specifies the action
77      * @return a result object returned by the action, or <code>null</code>
78      * @throws DataAccessException if there is any problem
79      */
80     Object execute(StatementCallback action) throws DataAccessException;
81
82     /**
83      * Issue a single SQL execute, typically a DDL statement.
84      * @param sql static SQL to execute
85      * @throws DataAccessException if there is any problem
86      */
87     void execute(String sql) throws DataAccessException;
88
89     /**
90      * Execute a query given static SQL, reading the ResultSet with a
91      * ResultSetExtractor.
92      * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
93      * execute a static query with a PreparedStatement, use the overloaded
94      * <code>query</code> method with <code>null</code> as argument array.
95      * @param sql SQL query to execute
96      * @param rse object that will extract all rows of results
97      * @return an arbitrary result object, as returned by the ResultSetExtractor
98      * @throws DataAccessException if there is any problem executing the query
99      * @see #query(String, Object[], ResultSetExtractor)
100      */
101     Object query(String sql, ResultSetExtractor rse) throws DataAccessException;
102
103     /**
104      * Execute a query given static SQL, reading the ResultSet on a per-row
105      * basis with a RowCallbackHandler.
106      * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
107      * execute a static query with a PreparedStatement, use the overloaded
108      * <code>query</code> method with <code>null</code> as argument array.
109      * @param sql SQL query to execute
110      * @param rch object that will extract results, one row at a time
111      * @throws DataAccessException if there is any problem executing the query
112      * @see #query(String, Object[], RowCallbackHandler)
113      */
114     void query(String sql, RowCallbackHandler rch) throws DataAccessException;
115
116     /**
117      * Execute a query given static SQL, mapping each row to a Java object
118      * via a RowMapper.
119      * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
120      * execute a static query with a PreparedStatement, use the overloaded
121      * <code>query</code> method with <code>null</code> as argument array.
122      * @param sql SQL query to execute
123      * @param rowMapper object that will map one object per row
124      * @return the result List, containing mapped objects
125      * @throws DataAccessException if there is any problem executing the query
126      * @see #query(String, Object[], RowMapper)
127      */
128     List query(String sql, RowMapper rowMapper) throws DataAccessException;
129
130     /**
131      * Execute a query given static SQL, mapping a single result row to a Java
132      * object via a RowMapper.
133      * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
134      * execute a static query with a PreparedStatement, use the overloaded
135      * <code>queryForObject</code> method with <code>null</code> as argument array.
136      * @param sql SQL query to execute
137      * @param rowMapper object that will map one object per row
138      * @return the single mapped object
139      * @throws IncorrectResultSizeDataAccessException if the query does not
140      * return exactly one row
141      * @throws DataAccessException if there is any problem executing the query
142      * @see #queryForObject(String, Object[], RowMapper)
143      */
144     Object queryForObject(String sql, RowMapper rowMapper) throws DataAccessException;
145
146     /**
147      * Execute a query for a result object, given static SQL.
148      * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
149      * execute a static query with a PreparedStatement, use the overloaded
150      * <code>queryForObject</code> method with <code>null</code> as argument array.
151      * <p>This method is useful for running static SQL with a known outcome.
152      * The query is expected to be a single row/single column query; the returned
153      * result will be directly mapped to the corresponding object type.
154      * @param sql SQL query to execute
155      * @param requiredType the type that the result object is expected to match
156      * @return the result object of the required type, or <code>null</code> in case of SQL NULL
157      * @throws IncorrectResultSizeDataAccessException if the query does not return
158      * exactly one row, or does not return exactly one column in that row
159      * @throws DataAccessException if there is any problem executing the query
160      * @see #queryForObject(String, Object[], Class)
161      */
162     Object queryForObject(String sql, Class requiredType) throws DataAccessException;
163
164     /**
165      * Execute a query for a result Map, given static SQL.
166      * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
167      * execute a static query with a PreparedStatement, use the overloaded
168      * <code>queryForMap</code> method with <code>null</code> as argument array.
169      * <p>The query is expected to be a single row query; the result row will be
170      * mapped to a Map (one entry for each column, using the column name as the key).
171      * @param sql SQL query to execute
172      * @return the result Map (one entry for each column, using the
173      * column name as the key)
174      * @throws IncorrectResultSizeDataAccessException if the query does not
175      * return exactly one row
176      * @throws DataAccessException if there is any problem executing the query
177      * @see #queryForMap(String, Object[])
178      * @see ColumnMapRowMapper
179      */
180     Map queryForMap(String sql) throws DataAccessException;
181
182     /**
183      * Execute a query that results in a long value, given static SQL.
184      * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
185      * execute a static query with a PreparedStatement, use the overloaded
186      * <code>queryForLong</code> method with <code>null</code> as argument array.
187      * <p>This method is useful for running static SQL with a known outcome.
188      * The query is expected to be a single row/single column query that results
189      * in a long value.
190      * @param sql SQL query to execute
191      * @return the long value, or 0 in case of SQL NULL
192      * @throws IncorrectResultSizeDataAccessException if the query does not return
193      * exactly one row, or does not return exactly one column in that row
194      * @throws DataAccessException if there is any problem executing the query
195      * @see #queryForLong(String, Object[])
196      */
197     long queryForLong(String sql) throws DataAccessException;
198
199     /**
200      * Execute a query that results in an int value, given static SQL.
201      * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
202      * execute a static query with a PreparedStatement, use the overloaded
203      * <code>queryForInt</code> method with <code>null</code> as argument array.
204      * <p>This method is useful for running static SQL with a known outcome.
205      * The query is expected to be a single row/single column query that results
206      * in an int value.
207      * @param sql SQL query to execute
208      * @return the int value, or 0 in case of SQL NULL
209      * @throws IncorrectResultSizeDataAccessException if the query does not return
210      * exactly one row, or does not return exactly one column in that row
211      * @throws DataAccessException if there is any problem executing the query
212      * @see #queryForInt(String, Object[])
213      */
214     int queryForInt(String sql) throws DataAccessException;
215
216     /**
217      * Execute a query for a result list, given static SQL.
218      * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
219      * execute a static query with a PreparedStatement, use the overloaded
220      * <code>queryForList</code> method with <code>null</code> as argument array.
221      * <p>The results will be mapped to a List (one entry for each row) of
222      * result objects, each of them matching the specified element type.
223      * @param sql SQL query to execute
224      * @param elementType the required type of element in the result list
225      * (for example, <code>Integer.class</code>)
226      * @return a List of objects that match the specified element type
227      * @throws DataAccessException if there is any problem executing the query
228      * @see #queryForList(String, Object[], Class)
229      * @see SingleColumnRowMapper
230      */
231     List queryForList(String sql, Class elementType) throws DataAccessException;
232
233     /**
234      * Execute a query for a result list, given static SQL.
235      * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
236      * execute a static query with a PreparedStatement, use the overloaded
237      * <code>queryForList</code> method with <code>null</code> as argument array.
238      * <p>The results will be mapped to a List (one entry for each row) of
239      * Maps (one entry for each column using the column name as the key).
240      * Each element in the list will be of the form returned by this interface's
241      * queryForMap() methods.
242      * @param sql SQL query to execute
243      * @return an List that contains a Map per row
244      * @throws DataAccessException if there is any problem executing the query
245      * @see #queryForList(String, Object[])
246      */
247     List queryForList(String sql) throws DataAccessException;
248
249     /**
250      * Execute a query for a SqlRowSet, given static SQL.
251      * <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
252      * execute a static query with a PreparedStatement, use the overloaded
253      * <code>queryForRowSet</code> method with <code>null</code> as argument array.
254      * <p>The results will be mapped to an SqlRowSet which holds the data in a
255      * disconnected fashion. This wrapper will translate any SQLExceptions thrown.
256      * <p>Note that that, for the default implementation, JDBC RowSet support needs to
257      * be available at runtime: by default, Sun's <code>com.sun.rowset.CachedRowSetImpl</code>
258      * class is used, which is part of JDK 1.5+ and also available separately as part of
259      * Sun's JDBC RowSet Implementations download (rowset.jar).
260      * @param sql SQL query to execute
261      * @return a SqlRowSet representation (possibly a wrapper around a
262      * <code>javax.sql.rowset.CachedRowSet</code>)
263      * @throws DataAccessException if there is any problem executing the query
264      * @see #queryForRowSet(String, Object[])
265      * @see SqlRowSetResultSetExtractor
266      * @see javax.sql.rowset.CachedRowSet
267      */
268     SqlRowSet queryForRowSet(String sql) throws DataAccessException;
269
270     /**
271      * Issue a single SQL update.
272      * @param sql static SQL to execute
273      * @return the number of rows affected
274      * @throws DataAccessException if there is any problem.
275      */
276     int update(String sql) throws DataAccessException;
277
278     /**
279      * Issue multiple SQL updates on a single Statement, using JDBC 2.0 batching.
280      * <p>Will fall back to separate updates on a single Statement if the JDBC
281      * driver does not support batch updates.
282      * @param sql defining an array of SQL statements that will be executed.
283      * @return an array of the number of rows affected by each statement
284      * @throws DataAccessException if there is any problem executing the batch
285      */
286     int[] batchUpdate(String [] sql) throws DataAccessException;
287
288
289     //-------------------------------------------------------------------------
290 // Methods dealing with prepared statements
291 //-------------------------------------------------------------------------
292
293     /**
294      * Execute a JDBC data access operation, implemented as callback action
295      * working on a JDBC PreparedStatement. This allows for implementing arbitrary
296      * data access operations on a single Statement, within Spring's managed
297      * JDBC environment: that is, participating in Spring-managed transactions
298      * and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
299      * <p>The callback action can return a result object, for example a
300      * domain object or a collection of domain objects.
301      * @param psc object that can create a PreparedStatement given a Connection
302      * @param action callback object that specifies the action
303      * @return a result object returned by the action, or <code>null</code>
304      * @throws DataAccessException if there is any problem
305      */
306     Object execute(PreparedStatementCreator psc, PreparedStatementCallback action)
307             throws DataAccessException;
308
309     /**
310      * Execute a JDBC data access operation, implemented as callback action
311      * working on a JDBC PreparedStatement. This allows for implementing arbitrary
312      * data access operations on a single Statement, within Spring's managed
313      * JDBC environment: that is, participating in Spring-managed transactions
314      * and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
315      * <p>The callback action can return a result object, for example a
316      * domain object or a collection of domain objects.
317      * @param sql SQL to execute
318      * @param action callback object that specifies the action
319      * @return a result object returned by the action, or <code>null</code>
320      * @throws DataAccessException if there is any problem
321      */
322     Object execute(String sql, PreparedStatementCallback action) throws DataAccessException;
323
324     /**
325      * Query using a prepared statement, reading the ResultSet with a
326      * ResultSetExtractor.
327      * <p>A PreparedStatementCreator can either be implemented directly or
328      * configured through a PreparedStatementCreatorFactory.
329      * @param psc object that can create a PreparedStatement given a Connection
330      * @param rse object that will extract results
331      * @return an arbitrary result object, as returned by the ResultSetExtractor
332      * @throws DataAccessException if there is any problem
333      * @see PreparedStatementCreatorFactory
334      */
335     Object query(PreparedStatementCreator psc, ResultSetExtractor rse) throws DataAccessException;
336
337     /**
338      * Query using a prepared statement, reading the ResultSet with a
339      * ResultSetExtractor.
340      * @param sql SQL query to execute
341      * @param pss object that knows how to set values on the prepared statement.
342      * If this is <code>null</code>, the SQL will be assumed to contain no bind parameters.
343      * Even if there are no bind parameters, this object may be used to
344      * set fetch size and other performance options.
345      * @param rse object that will extract results
346      * @return an arbitrary result object, as returned by the ResultSetExtractor
347      * @throws DataAccessException if there is any problem
348      */
349     Object query(String sql, PreparedStatementSetter pss, ResultSetExtractor rse)
350             throws DataAccessException;
351
352     /**
353      * Query given SQL to create a prepared statement from SQL and a list
354      * of arguments to bind to the query, reading the ResultSet with a
355      * ResultSetExtractor.
356      * @param sql SQL query to execute
357      * @param args arguments to bind to the query
358      * @param argTypes SQL types of the arguments
359      * (constants from <code>java.sql.Types</code>)
360      * @param rse object that will extract results
361      * @return an arbitrary result object, as returned by the ResultSetExtractor
362      * @throws DataAccessException if the query fails
363      * @see java.sql.Types
364      */
365     Object query(String sql, Object [] args, int[] argTypes, ResultSetExtractor rse)
366         throws DataAccessException;
367
368     /**
369      * Query given SQL to create a prepared statement from SQL and a list
370      * of arguments to bind to the query, reading the ResultSet with a
371      * ResultSetExtractor.
372      * @param sql SQL query to execute
373      * @param args arguments to bind to the query
374      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
375      * @param rse object that will extract results
376      * @return an arbitrary result object, as returned by the ResultSetExtractor
377      * @throws DataAccessException if the query fails
378      */
379     Object query(String sql, Object [] args, ResultSetExtractor rse) throws DataAccessException;
380
381     /**
382      * Query using a prepared statement, reading the ResultSet on a per-row
383      * basis with a RowCallbackHandler.
384      * <p>A PreparedStatementCreator can either be implemented directly or
385      * configured through a PreparedStatementCreatorFactory.
386      * @param psc object that can create a PreparedStatement given a Connection
387      * @param rch object that will extract results, one row at a time
388      * @throws DataAccessException if there is any problem
389      * @see PreparedStatementCreatorFactory
390      */
391     void query(PreparedStatementCreator psc, RowCallbackHandler rch) throws DataAccessException;
392     
393     /**
394      * Query given SQL to create a prepared statement from SQL and a
395      * PreparedStatementSetter implementation that knows how to bind values
396      * to the query, reading the ResultSet on a per-row basis with a
397      * RowCallbackHandler.
398      * @param sql SQL query to execute
399      * @param pss object that knows how to set values on the prepared statement.
400      * If this is <code>null</code>, the SQL will be assumed to contain no bind parameters.
401      * Even if there are no bind parameters, this object may be used to
402      * set fetch size and other performance options.
403      * @param rch object that will extract results, one row at a time
404      * @throws DataAccessException if the query fails
405      */
406     void query(String sql, PreparedStatementSetter pss, RowCallbackHandler rch)
407         throws DataAccessException;
408     
409     /**
410      * Query given SQL to create a prepared statement from SQL and a list of
411      * arguments to bind to the query, reading the ResultSet on a per-row basis
412      * with a RowCallbackHandler.
413      * @param sql SQL query to execute
414      * @param args arguments to bind to the query
415      * @param argTypes SQL types of the arguments
416      * (constants from <code>java.sql.Types</code>)
417      * @param rch object that will extract results, one row at a time
418      * @throws DataAccessException if the query fails
419      * @see java.sql.Types
420      */
421     void query(String sql, Object [] args, int[] argTypes, RowCallbackHandler rch)
422         throws DataAccessException;
423
424     /**
425      * Query given SQL to create a prepared statement from SQL and a list of
426      * arguments to bind to the query, reading the ResultSet on a per-row basis
427      * with a RowCallbackHandler.
428      * @param sql SQL query to execute
429      * @param args arguments to bind to the query
430      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
431      * @param rch object that will extract results, one row at a time
432      * @throws DataAccessException if the query fails
433      */
434     void query(String sql, Object [] args, RowCallbackHandler rch) throws DataAccessException;
435
436     /**
437      * Query using a prepared statement, mapping each row to a Java object
438      * via a RowMapper.
439      * <p>A PreparedStatementCreator can either be implemented directly or
440      * configured through a PreparedStatementCreatorFactory.
441      * @param psc object that can create a PreparedStatement given a Connection
442      * @param rowMapper object that will map one object per row
443      * @return the result List, containing mapped objects
444      * @throws DataAccessException if there is any problem
445      * @see PreparedStatementCreatorFactory
446      */
447     List query(PreparedStatementCreator psc, RowMapper rowMapper) throws DataAccessException;
448
449     /**
450      * Query given SQL to create a prepared statement from SQL and a
451      * PreparedStatementSetter implementation that knows how to bind values
452      * to the query, mapping each row to a Java object via a RowMapper.
453      * @param sql SQL query to execute
454      * @param pss object that knows how to set values on the prepared statement.
455      * If this is <code>null</code>, the SQL will be assumed to contain no bind parameters.
456      * Even if there are no bind parameters, this object may be used to
457      * set fetch size and other performance options.
458      * @param rowMapper object that will map one object per row
459      * @return the result List, containing mapped objects
460      * @throws DataAccessException if the query fails
461      */
462     List query(String sql, PreparedStatementSetter pss, RowMapper rowMapper)
463             throws DataAccessException;
464
465     /**
466      * Query given SQL to create a prepared statement from SQL and a list
467      * of arguments to bind to the query, mapping each row to a Java object
468      * via a RowMapper.
469      * @param sql SQL query to execute
470      * @param args arguments to bind to the query
471      * @param argTypes SQL types of the arguments
472      * (constants from <code>java.sql.Types</code>)
473      * @param rowMapper object that will map one object per row
474      * @return the result List, containing mapped objects
475      * @throws DataAccessException if the query fails
476      * @see java.sql.Types
477      */
478     List query(String sql, Object [] args, int[] argTypes, RowMapper rowMapper)
479         throws DataAccessException;
480
481     /**
482      * Query given SQL to create a prepared statement from SQL and a list
483      * of arguments to bind to the query, mapping each row to a Java object
484      * via a RowMapper.
485      * @param sql SQL query to execute
486      * @param args arguments to bind to the query
487      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
488      * @param rowMapper object that will map one object per row
489      * @return the result List, containing mapped objects
490      * @throws DataAccessException if the query fails
491      */
492     List query(String sql, Object [] args, RowMapper rowMapper) throws DataAccessException;
493
494     /**
495      * Query given SQL to create a prepared statement from SQL and a list
496      * of arguments to bind to the query, mapping a single result row to a
497      * Java object via a RowMapper.
498      * @param sql SQL query to execute
499      * @param args arguments to bind to the query
500      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
501      * @param argTypes SQL types of the arguments
502      * (constants from <code>java.sql.Types</code>)
503      * @param rowMapper object that will map one object per row
504      * @return the single mapped object
505      * @throws IncorrectResultSizeDataAccessException if the query does not
506      * return exactly one row
507      * @throws DataAccessException if the query fails
508      */
509     Object queryForObject(String sql, Object [] args, int[] argTypes, RowMapper rowMapper)
510             throws DataAccessException;
511
512     /**
513      * Query given SQL to create a prepared statement from SQL and a list
514      * of arguments to bind to the query, mapping a single result row to a
515      * Java object via a RowMapper.
516      * @param sql SQL query to execute
517      * @param args arguments to bind to the query
518      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
519      * @param rowMapper object that will map one object per row
520      * @return the single mapped object
521      * @throws IncorrectResultSizeDataAccessException if the query does not
522      * return exactly one row
523      * @throws DataAccessException if the query fails
524      */
525     Object queryForObject(String sql, Object [] args, RowMapper rowMapper)
526             throws DataAccessException;
527
528     /**
529      * Query given SQL to create a prepared statement from SQL and a
530      * list of arguments to bind to the query, expecting a result object.
531      * <p>The query is expected to be a single row/single column query; the returned
532      * result will be directly mapped to the corresponding object type.
533      * @param sql SQL query to execute
534      * @param args arguments to bind to the query
535      * @param argTypes SQL types of the arguments
536      * (constants from <code>java.sql.Types</code>)
537      * @param requiredType the type that the result object is expected to match
538      * @return the result object of the required type, or <code>null</code> in case of SQL NULL
539      * @throws IncorrectResultSizeDataAccessException if the query does not return
540      * exactly one row, or does not return exactly one column in that row
541      * @throws DataAccessException if the query fails
542      * @see #queryForObject(String, Class)
543      * @see java.sql.Types
544      */
545     Object queryForObject(String sql, Object [] args, int[] argTypes, Class requiredType)
546         throws DataAccessException;
547
548     /**
549      * Query given SQL to create a prepared statement from SQL and a
550      * list of arguments to bind to the query, expecting a result object.
551      * <p>The query is expected to be a single row/single column query; the returned
552      * result will be directly mapped to the corresponding object type.
553      * @param sql SQL query to execute
554      * @param args arguments to bind to the query
555      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
556      * @param requiredType the type that the result object is expected to match
557      * @return the result object of the required type, or <code>null</code> in case of SQL NULL
558      * @throws IncorrectResultSizeDataAccessException if the query does not return
559      * exactly one row, or does not return exactly one column in that row
560      * @throws DataAccessException if the query fails
561      * @see #queryForObject(String, Class)
562      */
563     Object queryForObject(String sql, Object [] args, Class requiredType) throws DataAccessException;
564
565     /**
566      * Query given SQL to create a prepared statement from SQL and a
567      * list of arguments to bind to the query, expecting a result Map.
568      * <p>The query is expected to be a single row query; the result row will be
569      * mapped to a Map (one entry for each column, using the column name as the key).
570      * @param sql SQL query to execute
571      * @param args arguments to bind to the query
572      * @param argTypes SQL types of the arguments
573      * (constants from <code>java.sql.Types</code>)
574      * @return the result Map (one entry for each column, using the
575      * column name as the key)
576      * @throws IncorrectResultSizeDataAccessException if the query does not
577      * return exactly one row
578      * @throws DataAccessException if the query fails
579      * @see #queryForMap(String)
580      * @see ColumnMapRowMapper
581      * @see java.sql.Types
582      */
583     Map queryForMap(String sql, Object [] args, int[] argTypes) throws DataAccessException;
584
585     /**
586      * Query given SQL to create a prepared statement from SQL and a
587      * list of arguments to bind to the query, expecting a result Map.
588      * The queryForMap() methods defined by this interface are appropriate
589      * when you don't have a domain model. Otherwise, consider using
590      * one of the queryForObject() methods.
591      * <p>The query is expected to be a single row query; the result row will be
592      * mapped to a Map (one entry for each column, using the column name as the key).
593      * @param sql SQL query to execute
594      * @param args arguments to bind to the query
595      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
596      * @return the result Map (one entry for each column, using the
597      * column name as the key)
598      * @throws IncorrectResultSizeDataAccessException if the query does not
599      * return exactly one row
600      * @throws DataAccessException if the query fails
601      * @see #queryForMap(String)
602      * @see ColumnMapRowMapper
603      */
604     Map queryForMap(String sql, Object [] args) throws DataAccessException;
605
606     /**
607      * Query given SQL to create a prepared statement from SQL and a
608      * list of arguments to bind to the query, resulting in a long value.
609      * <p>The query is expected to be a single row/single column query that
610      * results in a long value.
611      * @param sql SQL query to execute
612      * @param args arguments to bind to the query
613      * @param argTypes SQL types of the arguments
614      * (constants from <code>java.sql.Types</code>)
615      * @return the long value, or 0 in case of SQL NULL
616      * @throws IncorrectResultSizeDataAccessException if the query does not return
617      * exactly one row, or does not return exactly one column in that row
618      * @throws DataAccessException if the query fails
619      * @see #queryForLong(String)
620      * @see java.sql.Types
621      */
622     long queryForLong(String sql, Object [] args, int[] argTypes) throws DataAccessException;
623
624     /**
625      * Query given SQL to create a prepared statement from SQL and a
626      * list of arguments to bind to the query, resulting in a long value.
627      * <p>The query is expected to be a single row/single column query that
628      * results in a long value.
629      * @param sql SQL query to execute
630      * @param args arguments to bind to the query
631      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
632      * @return the long value, or 0 in case of SQL NULL
633      * @throws IncorrectResultSizeDataAccessException if the query does not return
634      * exactly one row, or does not return exactly one column in that row
635      * @throws DataAccessException if the query fails
636      * @see #queryForLong(String)
637      */
638     long queryForLong(String sql, Object [] args) throws DataAccessException;
639
640     /**
641      * Query given SQL to create a prepared statement from SQL and a
642      * list of arguments to bind to the query, resulting in an int value.
643      * <p>The query is expected to be a single row/single column query that
644      * results in an int value.
645      * @param sql SQL query to execute
646      * @param args arguments to bind to the query
647      * @param argTypes SQL types of the arguments
648      * (constants from <code>java.sql.Types</code>)
649      * @return the int value, or 0 in case of SQL NULL
650      * @throws IncorrectResultSizeDataAccessException if the query does not return
651      * exactly one row, or does not return exactly one column in that row
652      * @throws DataAccessException if the query fails
653      * @see #queryForInt(String)
654      * @see java.sql.Types
655      */
656     int queryForInt(String sql, Object [] args, int[] argTypes) throws DataAccessException;
657
658     /**
659      * Query given SQL to create a prepared statement from SQL and a
660      * list of arguments to bind to the query, resulting in an int value.
661      * <p>The query is expected to be a single row/single column query that
662      * results in an int value.
663      * @param sql SQL query to execute
664      * @param args arguments to bind to the query
665      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
666      * @return the int value, or 0 in case of SQL NULL
667      * @throws IncorrectResultSizeDataAccessException if the query does not return
668      * exactly one row, or does not return exactly one column in that row
669      * @throws DataAccessException if the query fails
670      * @see #queryForInt(String)
671      */
672     int queryForInt(String sql, Object [] args) throws DataAccessException;
673
674     /**
675      * Query given SQL to create a prepared statement from SQL and a
676      * list of arguments to bind to the query, expecting a result list.
677      * <p>The results will be mapped to a List (one entry for each row) of
678      * result objects, each of them matching the specified element type.
679      * @param sql SQL query to execute
680      * @param args arguments to bind to the query
681      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
682      * @param argTypes SQL types of the arguments
683      * (constants from <code>java.sql.Types</code>)
684      * @param elementType the required type of element in the result list
685      * (for example, <code>Integer.class</code>)
686      * @return a List of objects that match the specified element type
687      * @throws DataAccessException if the query fails
688      * @see #queryForList(String, Class)
689      * @see SingleColumnRowMapper
690      */
691     List queryForList(String sql, Object [] args, int[] argTypes, Class elementType)
692             throws DataAccessException;
693
694     /**
695      * Query given SQL to create a prepared statement from SQL and a
696      * list of arguments to bind to the query, expecting a result list.
697      * <p>The results will be mapped to a List (one entry for each row) of
698      * result objects, each of them matching the specified element type.
699      * @param sql SQL query to execute
700      * @param args arguments to bind to the query
701      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
702      * @param elementType the required type of element in the result list
703      * (for example, <code>Integer.class</code>)
704      * @return a List of objects that match the specified element type
705      * @throws DataAccessException if the query fails
706      * @see #queryForList(String, Class)
707      * @see SingleColumnRowMapper
708      */
709     List queryForList(String sql, Object [] args, Class elementType) throws DataAccessException;
710
711     /**
712      * Query given SQL to create a prepared statement from SQL and a
713      * list of arguments to bind to the query, expecting a result list.
714      * <p>The results will be mapped to a List (one entry for each row) of
715      * Maps (one entry for each column, using the column name as the key).
716      * Thus Each element in the list will be of the form returned by this interface's
717      * queryForMap() methods.
718      * @param sql SQL query to execute
719      * @param args arguments to bind to the query
720      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
721      * @param argTypes SQL types of the arguments
722      * (constants from <code>java.sql.Types</code>)
723      * @return a List that contains a Map per row
724      * @throws DataAccessException if the query fails
725      * @see #queryForList(String)
726      * @see java.sql.Types
727      */
728     List queryForList(String sql, Object [] args, int[] argTypes) throws DataAccessException;
729
730     /**
731      * Query given SQL to create a prepared statement from SQL and a
732      * list of arguments to bind to the query, expecting a result list.
733      * <p>The results will be mapped to a List (one entry for each row) of
734      * Maps (one entry for each column, using the column name as the key).
735      * Each element in the list will be of the form returned by this interface's
736      * queryForMap() methods.
737      * @param sql SQL query to execute
738      * @param args arguments to bind to the query
739      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
740      * @return a List that contains a Map per row
741      * @throws DataAccessException if the query fails
742      * @see #queryForList(String)
743      */
744     List queryForList(String sql, Object [] args) throws DataAccessException;
745
746     /**
747      * Query given SQL to create a prepared statement from SQL and a
748      * list of arguments to bind to the query, expecting a SqlRowSet.
749      * <p>The results will be mapped to an SqlRowSet which holds the data in a
750      * disconnected fashion. This wrapper will translate any SQLExceptions thrown.
751      * <p>Note that that, for the default implementation, JDBC RowSet support needs to
752      * be available at runtime: by default, Sun's <code>com.sun.rowset.CachedRowSetImpl</code>
753      * class is used, which is part of JDK 1.5+ and also available separately as part of
754      * Sun's JDBC RowSet Implementations download (rowset.jar).
755      * @param sql SQL query to execute
756      * @param args arguments to bind to the query
757      * @param argTypes SQL types of the arguments
758      * (constants from <code>java.sql.Types</code>)
759      * @return a SqlRowSet representation (possibly a wrapper around a
760      * <code>javax.sql.rowset.CachedRowSet</code>)
761      * @throws DataAccessException if there is any problem executing the query
762      * @see #queryForRowSet(String)
763      * @see SqlRowSetResultSetExtractor
764      * @see javax.sql.rowset.CachedRowSet
765      * @see java.sql.Types
766      */
767     SqlRowSet queryForRowSet(String sql, Object [] args, int[] argTypes) throws DataAccessException;
768
769     /**
770      * Query given SQL to create a prepared statement from SQL and a
771      * list of arguments to bind to the query, expecting a SqlRowSet.
772      * <p>The results will be mapped to an SqlRowSet which holds the data in a
773      * disconnected fashion. This wrapper will translate any SQLExceptions thrown.
774      * <p>Note that that, for the default implementation, JDBC RowSet support needs to
775      * be available at runtime: by default, Sun's <code>com.sun.rowset.CachedRowSetImpl</code>
776      * class is used, which is part of JDK 1.5+ and also available separately as part of
777      * Sun's JDBC RowSet Implementations download (rowset.jar).
778      * @param sql SQL query to execute
779      * @param args arguments to bind to the query
780      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
781      * @return a SqlRowSet representation (possibly a wrapper around a
782      * <code>javax.sql.rowset.CachedRowSet</code>)
783      * @throws DataAccessException if there is any problem executing the query
784      * @see #queryForRowSet(String)
785      * @see SqlRowSetResultSetExtractor
786      * @see javax.sql.rowset.CachedRowSet
787      */
788     SqlRowSet queryForRowSet(String sql, Object [] args) throws DataAccessException;
789
790     /**
791      * Issue an update using a PreparedStatementCreator to provide SQL and any
792      * required parameters.
793      * <p>A PreparedStatementCreator can either be implemented directly or
794      * configured through a PreparedStatementCreatorFactory.
795      * @param psc object that provides SQL and any necessary parameters
796      * @return the number of rows affected
797      * @throws DataAccessException if there is any problem issuing the update
798      * @see PreparedStatementCreatorFactory
799      */
800     int update(PreparedStatementCreator psc) throws DataAccessException;
801
802     /**
803      * Issue an update using a PreparedStatementCreator to provide SQL and any
804      * required parameters. Generated keys will be put into the given KeyHolder.
805      * <p>Note that the given PreparedStatementCreator has to create a statement
806      * with activated extraction of generated keys (a JDBC 3.0 feature). This can
807      * either be done directly or through using a PreparedStatementCreatorFactory.
808      * @param psc object that provides SQL and any necessary parameters
809      * @param generatedKeyHolder KeyHolder that will hold the generated keys
810      * @return the number of rows affected
811      * @throws DataAccessException if there is any problem issuing the update
812      * @see PreparedStatementCreatorFactory
813      * @see org.springframework.jdbc.support.GeneratedKeyHolder
814      */
815     int update(PreparedStatementCreator psc, KeyHolder generatedKeyHolder) throws DataAccessException;
816
817     /**
818      * Issue an update using a PreparedStatementSetter to set bind parameters,
819      * with given SQL. Simpler than using a PreparedStatementCreator as this
820      * method will create the PreparedStatement: The PreparedStatementSetter
821      * just needs to set parameters.
822      * @param sql SQL containing bind parameters
823      * @param pss helper that sets bind parameters. If this is <code>null</code>
824      * we run an update with static SQL.
825      * @return the number of rows affected
826      * @throws DataAccessException if there is any problem issuing the update
827      */
828     int update(String sql, PreparedStatementSetter pss) throws DataAccessException;
829     
830     /**
831      * Issue an update via a prepared statement, binding the given arguments.
832      * @param sql SQL containing bind parameters
833      * @param args arguments to bind to the query
834      * @param argTypes SQL types of the arguments
835      * (constants from <code>java.sql.Types</code>)
836      * @return the number of rows affected
837      * @throws DataAccessException if there is any problem issuing the update
838      * @see java.sql.Types
839      */
840     int update(String sql, Object [] args, int[] argTypes) throws DataAccessException;
841
842     /**
843      * Issue an update via a prepared statement, binding the given arguments.
844      * @param sql SQL containing bind parameters
845      * @param args arguments to bind to the query
846      * (leaving it to the PreparedStatement to guess the corresponding SQL type)
847      * @return the number of rows affected
848      * @throws DataAccessException if there is any problem issuing the update
849      */
850     int update(String sql, Object [] args) throws DataAccessException;
851
852     /**
853      * Issue multiple updates on a single PreparedStatement, using JDBC 2.0
854      * batch updates and a BatchPreparedStatementSetter to set values.
855      * <p>Will fall back to separate updates on a single PreparedStatement
856      * if the JDBC driver does not support batch updates.
857      * @param sql defining PreparedStatement that will be reused.
858      * All statements in the batch will use the same SQL.
859      * @param pss object to set parameters on the PreparedStatement
860      * created by this method
861      * @return an array of the number of rows affected by each statement
862      * @throws DataAccessException if there is any problem issuing the update
863      */
864     int[] batchUpdate(String sql, BatchPreparedStatementSetter pss) throws DataAccessException;
865
866
867     //-------------------------------------------------------------------------
868 // Methods dealing with callable statements
869 //-------------------------------------------------------------------------
870
871     /**
872      * Execute a JDBC data access operation, implemented as callback action
873      * working on a JDBC CallableStatement. This allows for implementing arbitrary
874      * data access operations on a single Statement, within Spring's managed
875      * JDBC environment: that is, participating in Spring-managed transactions
876      * and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
877      * <p>The callback action can return a result object, for example a
878      * domain object or a collection of domain objects.
879      * @param csc object that can create a CallableStatement given a Connection
880      * @param action callback object that specifies the action
881      * @return a result object returned by the action, or <code>null</code>
882      * @throws DataAccessException if there is any problem
883      */
884     Object execute(CallableStatementCreator csc, CallableStatementCallback action)
885             throws DataAccessException;
886
887     /**
888      * Execute a JDBC data access operation, implemented as callback action
889      * working on a JDBC CallableStatement. This allows for implementing arbitrary
890      * data access operations on a single Statement, within Spring's managed
891      * JDBC environment: that is, participating in Spring-managed transactions
892      * and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
893      * <p>The callback action can return a result object, for example a
894      * domain object or a collection of domain objects.
895      * @param callString the SQL call string to execute
896      * @param action callback object that specifies the action
897      * @return a result object returned by the action, or <code>null</code>
898      * @throws DataAccessException if there is any problem
899      */
900     Object execute(String callString, CallableStatementCallback action) throws DataAccessException;
901
902     /**
903      * Execute a SQL call using a CallableStatementCreator to provide SQL and any
904      * required parameters.
905      * @param csc object that provides SQL and any necessary parameters
906      * @param declaredParameters list of declared SqlParameter objects
907      * @return Map of extracted out parameters
908      * @throws DataAccessException if there is any problem issuing the update
909      */
910     Map call(CallableStatementCreator csc, List declaredParameters) throws DataAccessException;
911
912 }
913

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags