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.namedparam;
018:
019: import java.util.List;
020: import java.util.Map;
021:
022: import org.springframework.dao.DataAccessException;
023: import org.springframework.jdbc.core.JdbcOperations;
024: import org.springframework.jdbc.core.PreparedStatementCallback;
025: import org.springframework.jdbc.core.ResultSetExtractor;
026: import org.springframework.jdbc.core.RowCallbackHandler;
027: import org.springframework.jdbc.core.RowMapper;
028: import org.springframework.jdbc.support.KeyHolder;
029: import org.springframework.jdbc.support.rowset.SqlRowSet;
030:
031: /**
032: * Interface specifying a basic set of JDBC operations allowing the use
033: * of named parameters rather than the traditional '?' placeholders.
034: *
035: * <p>This is an alternative to the classic
036: * {@link org.springframework.jdbc.core.JdbcOperations} interface,
037: * implemented by {@link NamedParameterJdbcTemplate}. This interface is not
038: * often used directly, but provides a useful option to enhance testability,
039: * as it can easily be mocked or stubbed.
040: *
041: * @author Thomas Risberg
042: * @author Juergen Hoeller
043: * @since 2.0
044: * @see NamedParameterJdbcTemplate
045: * @see org.springframework.jdbc.core.JdbcOperations
046: */
047: public interface NamedParameterJdbcOperations {
048:
049: /**
050: * Expose the classic Spring JdbcTemplate to allow invocation of
051: * classic JDBC operations.
052: */
053: JdbcOperations getJdbcOperations();
054:
055: /**
056: * Execute a JDBC data access operation, implemented as callback action
057: * working on a JDBC PreparedStatement. This allows for implementing arbitrary
058: * data access operations on a single Statement, within Spring's managed
059: * JDBC environment: that is, participating in Spring-managed transactions
060: * and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
061: * <p>The callback action can return a result object, for example a
062: * domain object or a collection of domain objects.
063: * @param sql SQL to execute
064: * @param paramSource container of arguments to bind to the query
065: * @param action callback object that specifies the action
066: * @return a result object returned by the action, or <code>null</code>
067: * @throws DataAccessException if there is any problem
068: */
069: Object execute(String sql, SqlParameterSource paramSource,
070: PreparedStatementCallback action)
071: throws DataAccessException;
072:
073: /**
074: * Execute a JDBC data access operation, implemented as callback action
075: * working on a JDBC PreparedStatement. This allows for implementing arbitrary
076: * data access operations on a single Statement, within Spring's managed
077: * JDBC environment: that is, participating in Spring-managed transactions
078: * and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
079: * <p>The callback action can return a result object, for example a
080: * domain object or a collection of domain objects.
081: * @param sql SQL to execute
082: * @param paramMap map of parameters to bind to the query
083: * (leaving it to the PreparedStatement to guess the corresponding SQL type)
084: * @param action callback object that specifies the action
085: * @return a result object returned by the action, or <code>null</code>
086: * @throws DataAccessException if there is any problem
087: */
088: Object execute(String sql, Map paramMap,
089: PreparedStatementCallback action)
090: throws DataAccessException;
091:
092: /**
093: * Query given SQL to create a prepared statement from SQL and a list
094: * of arguments to bind to the query, reading the ResultSet with a
095: * ResultSetExtractor.
096: * @param sql SQL query to execute
097: * @param paramSource container of arguments to bind to the query
098: * @param rse object that will extract results
099: * @return an arbitrary result object, as returned by the ResultSetExtractor
100: * @throws DataAccessException if the query fails
101: */
102: Object query(String sql, SqlParameterSource paramSource,
103: ResultSetExtractor rse) throws DataAccessException;
104:
105: /**
106: * Query given SQL to create a prepared statement from SQL and a list
107: * of arguments to bind to the query, reading the ResultSet with a
108: * ResultSetExtractor.
109: * @param sql SQL query to execute
110: * @param paramMap map of parameters to bind to the query
111: * (leaving it to the PreparedStatement to guess the corresponding SQL type)
112: * @param rse object that will extract results
113: * @return an arbitrary result object, as returned by the ResultSetExtractor
114: * @throws org.springframework.dao.DataAccessException if the query fails
115: */
116: Object query(String sql, Map paramMap, ResultSetExtractor rse)
117: throws DataAccessException;
118:
119: /**
120: * Query given SQL to create a prepared statement from SQL and a list of
121: * arguments to bind to the query, reading the ResultSet on a per-row basis
122: * with a RowCallbackHandler.
123: * @param sql SQL query to execute
124: * @param paramSource container of arguments to bind to the query
125: * @param rch object that will extract results, one row at a time
126: * @throws DataAccessException if the query fails
127: */
128: void query(String sql, SqlParameterSource paramSource,
129: RowCallbackHandler rch) throws DataAccessException;
130:
131: /**
132: * Query given SQL to create a prepared statement from SQL and a list of
133: * arguments to bind to the query, reading the ResultSet on a per-row basis
134: * with a RowCallbackHandler.
135: * @param sql SQL query to execute
136: * @param paramMap map of parameters to bind to the query
137: * (leaving it to the PreparedStatement to guess the corresponding SQL type)
138: * @param rch object that will extract results, one row at a time
139: * @throws org.springframework.dao.DataAccessException if the query fails
140: */
141: void query(String sql, Map paramMap, RowCallbackHandler rch)
142: throws DataAccessException;
143:
144: /**
145: * Query given SQL to create a prepared statement from SQL and a list
146: * of arguments to bind to the query, mapping each row to a Java object
147: * via a RowMapper.
148: * @param sql SQL query to execute
149: * @param paramSource container of arguments to bind to the query
150: * @param rowMapper object that will map one object per row
151: * @return the result List, containing mapped objects
152: * @throws org.springframework.dao.DataAccessException if the query fails
153: */
154: List query(String sql, SqlParameterSource paramSource,
155: RowMapper rowMapper) throws DataAccessException;
156:
157: /**
158: * Query given SQL to create a prepared statement from SQL and a list
159: * of arguments to bind to the query, mapping each row to a Java object
160: * via a RowMapper.
161: * @param sql SQL query to execute
162: * @param paramMap map of parameters to bind to the query
163: * (leaving it to the PreparedStatement to guess the corresponding SQL type)
164: * @param rowMapper object that will map one object per row
165: * @return the result List, containing mapped objects
166: * @throws org.springframework.dao.DataAccessException if the query fails
167: */
168: List query(String sql, Map paramMap, RowMapper rowMapper)
169: throws DataAccessException;
170:
171: /**
172: * Query given SQL to create a prepared statement from SQL and a list
173: * of arguments to bind to the query, mapping a single result row to a
174: * Java object via a RowMapper.
175: * @param sql SQL query to execute
176: * @param paramSource container of arguments to bind to the query
177: * @param rowMapper object that will map one object per row
178: * @return the single mapped object
179: * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
180: * if the query does not return exactly one row, or does not return exactly
181: * one column in that row
182: * @throws org.springframework.dao.DataAccessException if the query fails
183: */
184: Object queryForObject(String sql, SqlParameterSource paramSource,
185: RowMapper rowMapper) throws DataAccessException;
186:
187: /**
188: * Query given SQL to create a prepared statement from SQL and a list
189: * of arguments to bind to the query, mapping a single result row to a
190: * Java object via a RowMapper.
191: * @param sql SQL query to execute
192: * @param paramMap map of parameters to bind to the query
193: * (leaving it to the PreparedStatement to guess the corresponding SQL type)
194: * @param rowMapper object that will map one object per row
195: * @return the single mapped object
196: * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
197: * if the query does not return exactly one row, or does not return exactly
198: * one column in that row
199: * @throws org.springframework.dao.DataAccessException if the query fails
200: */
201: Object queryForObject(String sql, Map paramMap, RowMapper rowMapper)
202: throws DataAccessException;
203:
204: /**
205: * Query given SQL to create a prepared statement from SQL and a
206: * list of arguments to bind to the query, expecting a result object.
207: * <p>The query is expected to be a single row/single column query; the returned
208: * result will be directly mapped to the corresponding object type.
209: * @param sql SQL query to execute
210: * @param paramSource container of arguments to bind to the query
211: * @param requiredType the type that the result object is expected to match
212: * @return the result object of the required type, or <code>null</code> in case of SQL NULL
213: * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
214: * if the query does not return exactly one row, or does not return exactly
215: * one column in that row
216: * @throws org.springframework.dao.DataAccessException if the query fails
217: * @see org.springframework.jdbc.core.JdbcTemplate#queryForObject(String, Class)
218: */
219: Object queryForObject(String sql, SqlParameterSource paramSource,
220: Class requiredType) throws DataAccessException;
221:
222: /**
223: * Query given SQL to create a prepared statement from SQL and a
224: * list of arguments to bind to the query, expecting a result object.
225: * <p>The query is expected to be a single row/single column query; the returned
226: * result will be directly mapped to the corresponding object type.
227: * @param sql SQL query to execute
228: * @param paramMap map of parameters to bind to the query
229: * (leaving it to the PreparedStatement to guess the corresponding SQL type)
230: * @param requiredType the type that the result object is expected to match
231: * @return the result object of the required type, or <code>null</code> in case of SQL NULL
232: * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
233: * if the query does not return exactly one row, or does not return exactly
234: * one column in that row
235: * @throws org.springframework.dao.DataAccessException if the query fails
236: * @see org.springframework.jdbc.core.JdbcTemplate#queryForObject(String, Class)
237: */
238: Object queryForObject(String sql, Map paramMap, Class requiredType)
239: throws DataAccessException;
240:
241: /**
242: * Query given SQL to create a prepared statement from SQL and a
243: * list of arguments to bind to the query, expecting a result Map.
244: * <p>The query is expected to be a single row query; the result row will be
245: * mapped to a Map (one entry for each column, using the column name as the key).
246: * @param sql SQL query to execute
247: * @param paramSource container of arguments to bind to the query
248: * @return the result Map (one entry for each column, using the column name as the key)
249: * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
250: * if the query does not return exactly one row, or does not return exactly
251: * one column in that row
252: * @throws org.springframework.dao.DataAccessException if the query fails
253: * @see org.springframework.jdbc.core.JdbcTemplate#queryForMap(String)
254: * @see org.springframework.jdbc.core.ColumnMapRowMapper
255: */
256: Map queryForMap(String sql, SqlParameterSource paramSource)
257: throws DataAccessException;
258:
259: /**
260: * Query given SQL to create a prepared statement from SQL and a
261: * list of arguments to bind to the query, expecting a result Map.
262: * The queryForMap() methods defined by this interface are appropriate
263: * when you don't have a domain model. Otherwise, consider using
264: * one of the queryForObject() methods.
265: * <p>The query is expected to be a single row query; the result row will be
266: * mapped to a Map (one entry for each column, using the column name as the key).
267: * @param sql SQL query to execute
268: * @param paramMap map of parameters to bind to the query
269: * (leaving it to the PreparedStatement to guess the corresponding SQL type)
270: * @return the result Map (one entry for each column, using the column name as the key)
271: * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
272: * if the query does not return exactly one row, or does not return exactly
273: * one column in that row
274: * @throws org.springframework.dao.DataAccessException if the query fails
275: * @see org.springframework.jdbc.core.JdbcTemplate#queryForMap(String)
276: * @see org.springframework.jdbc.core.ColumnMapRowMapper
277: */
278: Map queryForMap(String sql, Map paramMap)
279: throws DataAccessException;
280:
281: /**
282: * Query given SQL to create a prepared statement from SQL and a
283: * list of arguments to bind to the query, resulting in a long value.
284: * <p>The query is expected to be a single row/single column query that
285: * results in a long value.
286: * @param sql SQL query to execute
287: * @param paramSource container of arguments to bind to the query
288: * @return the long value, or 0 in case of SQL NULL
289: * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
290: * if the query does not return exactly one row, or does not return exactly
291: * one column in that row
292: * @throws org.springframework.dao.DataAccessException if the query fails
293: * @see org.springframework.jdbc.core.JdbcTemplate#queryForLong(String)
294: */
295: long queryForLong(String sql, SqlParameterSource paramSource)
296: throws DataAccessException;
297:
298: /**
299: * Query given SQL to create a prepared statement from SQL and a
300: * list of arguments to bind to the query, resulting in a long value.
301: * <p>The query is expected to be a single row/single column query that
302: * results in a long value.
303: * @param sql SQL query to execute
304: * @param paramMap map of parameters to bind to the query
305: * (leaving it to the PreparedStatement to guess the corresponding SQL type)
306: * @return the long value, or 0 in case of SQL NULL
307: * @throws org.springframework.dao.IncorrectResultSizeDataAccessException
308: * if the query does not return exactly one row, or does not return exactly
309: * one column in that row
310: * @throws org.springframework.dao.DataAccessException if the query fails
311: * @see org.springframework.jdbc.core.JdbcTemplate#queryForLong(String)
312: */
313: long queryForLong(String sql, Map paramMap)
314: throws DataAccessException;
315:
316: /**
317: * Query given SQL to create a prepared statement from SQL and a
318: * list of arguments to bind to the query, resulting in an int value.
319: * <p>The query is expected to be a single row/single column query that
320: * results in an int value.
321: * @param sql SQL query to execute
322: * @param paramSource container of arguments to bind to the query
323: * @return the int value, or 0 in case of SQL NULL
324: * @throws org.springframework.dao.IncorrectResultSizeDataAccessException if the query does not return
325: * exactly one row, or does not return exactly one column in that row
326: * @throws org.springframework.dao.DataAccessException if the query fails
327: * @see org.springframework.jdbc.core.JdbcTemplate#queryForInt(String)
328: */
329: int queryForInt(String sql, SqlParameterSource paramSource)
330: throws DataAccessException;
331:
332: /**
333: * Query given SQL to create a prepared statement from SQL and a
334: * list of arguments to bind to the query, resulting in an int value.
335: * <p>The query is expected to be a single row/single column query that
336: * results in an int value.
337: * @param sql SQL query to execute
338: * @param paramMap map of parameters to bind to the query
339: * (leaving it to the PreparedStatement to guess the corresponding SQL type)
340: * @return the int value, or 0 in case of SQL NULL
341: * @throws org.springframework.dao.IncorrectResultSizeDataAccessException if the query does not return
342: * exactly one row, or does not return exactly one column in that row
343: * @throws org.springframework.dao.DataAccessException if the query fails
344: * @see org.springframework.jdbc.core.JdbcTemplate#queryForInt(String)
345: */
346: int queryForInt(String sql, Map paramMap)
347: throws DataAccessException;
348:
349: /**
350: * Query given SQL to create a prepared statement from SQL and a
351: * list of arguments to bind to the query, expecting a result list.
352: * <p>The results will be mapped to a List (one entry for each row) of
353: * result objects, each of them matching the specified element type.
354: * @param sql SQL query to execute
355: * @param paramSource container of arguments to bind to the query
356: * @param elementType the required type of element in the result list
357: * (for example, <code>Integer.class</code>)
358: * @return a List of objects that match the specified element type
359: * @throws org.springframework.dao.DataAccessException if the query fails
360: * @see org.springframework.jdbc.core.JdbcTemplate#queryForList(String, Class)
361: * @see org.springframework.jdbc.core.SingleColumnRowMapper
362: */
363: List queryForList(String sql, SqlParameterSource paramSource,
364: Class elementType) throws DataAccessException;
365:
366: /**
367: * Query given SQL to create a prepared statement from SQL and a
368: * list of arguments to bind to the query, expecting a result list.
369: * <p>The results will be mapped to a List (one entry for each row) of
370: * result objects, each of them matching the specified element type.
371: * @param sql SQL query to execute
372: * @param paramMap map of parameters to bind to the query
373: * (leaving it to the PreparedStatement to guess the corresponding SQL type)
374: * @param elementType the required type of element in the result list
375: * (for example, <code>Integer.class</code>)
376: * @return a List of objects that match the specified element type
377: * @throws org.springframework.dao.DataAccessException if the query fails
378: * @see org.springframework.jdbc.core.JdbcTemplate#queryForList(String, Class)
379: * @see org.springframework.jdbc.core.SingleColumnRowMapper
380: */
381: List queryForList(String sql, Map paramMap, Class elementType)
382: throws DataAccessException;
383:
384: /**
385: * Query given SQL to create a prepared statement from SQL and a
386: * list of arguments to bind to the query, expecting a result list.
387: * <p>The results will be mapped to a List (one entry for each row) of
388: * Maps (one entry for each column, using the column name as the key).
389: * Thus Each element in the list will be of the form returned by this interface's
390: * queryForMap() methods.
391: * @param sql SQL query to execute
392: * @param paramSource container of arguments to bind to the query
393: * @return a List that contains a Map per row
394: * @throws org.springframework.dao.DataAccessException if the query fails
395: * @see org.springframework.jdbc.core.JdbcTemplate#queryForList(String)
396: */
397: List queryForList(String sql, SqlParameterSource paramSource)
398: throws DataAccessException;
399:
400: /**
401: * Query given SQL to create a prepared statement from SQL and a
402: * list of arguments to bind to the query, expecting a result list.
403: * <p>The results will be mapped to a List (one entry for each row) of
404: * Maps (one entry for each column, using the column name as the key).
405: * Each element in the list will be of the form returned by this interface's
406: * queryForMap() methods.
407: * @param sql SQL query to execute
408: * @param paramMap map of parameters to bind to the query
409: * (leaving it to the PreparedStatement to guess the corresponding SQL type)
410: * @return a List that contains a Map per row
411: * @throws org.springframework.dao.DataAccessException if the query fails
412: * @see org.springframework.jdbc.core.JdbcTemplate#queryForList(String)
413: */
414: List queryForList(String sql, Map paramMap)
415: throws DataAccessException;
416:
417: /**
418: * Query given SQL to create a prepared statement from SQL and a
419: * list of arguments to bind to the query, expecting a SqlRowSet.
420: * <p>The results will be mapped to an SqlRowSet which holds the data in a
421: * disconnected fashion. This wrapper will translate any SQLExceptions thrown.
422: * <p>Note that that, for the default implementation, JDBC RowSet support needs to
423: * be available at runtime: by default, Sun's <code>com.sun.rowset.CachedRowSetImpl</code>
424: * class is used, which is part of JDK 1.5+ and also available separately as part of
425: * Sun's JDBC RowSet Implementations download (rowset.jar).
426: * @param sql SQL query to execute
427: * @param paramSource container of arguments to bind to the query
428: * @return a SqlRowSet representation (possibly a wrapper around a
429: * <code>javax.sql.rowset.CachedRowSet</code>)
430: * @throws org.springframework.dao.DataAccessException if there is any problem executing the query
431: * @see org.springframework.jdbc.core.JdbcTemplate#queryForRowSet(String)
432: * @see org.springframework.jdbc.core.SqlRowSetResultSetExtractor
433: * @see javax.sql.rowset.CachedRowSet
434: */
435: SqlRowSet queryForRowSet(String sql, SqlParameterSource paramSource)
436: throws DataAccessException;
437:
438: /**
439: * Query given SQL to create a prepared statement from SQL and a
440: * list of arguments to bind to the query, expecting a SqlRowSet.
441: * <p>The results will be mapped to an SqlRowSet which holds the data in a
442: * disconnected fashion. This wrapper will translate any SQLExceptions thrown.
443: * <p>Note that that, for the default implementation, JDBC RowSet support needs to
444: * be available at runtime: by default, Sun's <code>com.sun.rowset.CachedRowSetImpl</code>
445: * class is used, which is part of JDK 1.5+ and also available separately as part of
446: * Sun's JDBC RowSet Implementations download (rowset.jar).
447: * @param sql SQL query to execute
448: * @param paramMap map of parameters to bind to the query
449: * (leaving it to the PreparedStatement to guess the corresponding SQL type)
450: * @return a SqlRowSet representation (possibly a wrapper around a
451: * <code>javax.sql.rowset.CachedRowSet</code>)
452: * @throws org.springframework.dao.DataAccessException if there is any problem executing the query
453: * @see org.springframework.jdbc.core.JdbcTemplate#queryForRowSet(String)
454: * @see org.springframework.jdbc.core.SqlRowSetResultSetExtractor
455: * @see javax.sql.rowset.CachedRowSet
456: */
457: SqlRowSet queryForRowSet(String sql, Map paramMap)
458: throws DataAccessException;
459:
460: /**
461: * Issue an update via a prepared statement, binding the given arguments.
462: * @param sql SQL containing named parameters
463: * @param paramSource container of arguments and SQL types to bind to the query
464: * @return the number of rows affected
465: * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
466: */
467: int update(String sql, SqlParameterSource paramSource)
468: throws DataAccessException;
469:
470: /**
471: * Issue an update via a prepared statement, binding the given arguments.
472: * @param sql SQL containing named parameters
473: * @param paramMap map of parameters to bind to the query
474: * (leaving it to the PreparedStatement to guess the corresponding SQL type)
475: * @return the number of rows affected
476: * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
477: */
478: int update(String sql, Map paramMap) throws DataAccessException;
479:
480: /**
481: * Issue an update via a prepared statement, binding the given arguments,
482: * returning generated keys.
483: * @param sql SQL containing named parameters
484: * @param paramSource container of arguments and SQL types to bind to the query
485: * @param generatedKeyHolder KeyHolder that will hold the generated keys
486: * @return the number of rows affected
487: * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
488: * @see MapSqlParameterSource
489: * @see org.springframework.jdbc.support.GeneratedKeyHolder
490: */
491: int update(String sql, SqlParameterSource paramSource,
492: KeyHolder generatedKeyHolder) throws DataAccessException;
493:
494: /**
495: * Issue an update via a prepared statement, binding the given arguments,
496: * returning generated keys.
497: * @param sql SQL containing named parameters
498: * @param paramSource container of arguments and SQL types to bind to the query
499: * @param generatedKeyHolder KeyHolder that will hold the generated keys
500: * @param keyColumnNames names of the columns that will have keys generated for them
501: * @return the number of rows affected
502: * @throws org.springframework.dao.DataAccessException if there is any problem issuing the update
503: * @see MapSqlParameterSource
504: * @see org.springframework.jdbc.support.GeneratedKeyHolder
505: */
506: int update(String sql, SqlParameterSource paramSource,
507: KeyHolder generatedKeyHolder, String[] keyColumnNames)
508: throws DataAccessException;
509:
510: }
|