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