PageRenderTime 57ms CodeModel.GetById 21ms RepoModel.GetById 0ms app.codeStats 0ms

/SpringSource-spring-framework-79c9ca1/org.springframework.jdbc/src/main/java/org/springframework/jdbc/core/JdbcOperations.java

#
Java | 1068 lines | 88 code | 75 blank | 905 comment | 0 complexity | 321a9a0bb4b157b7f58cb13fe352be72 MD5 | raw file
Possible License(s): Apache-2.0

Large files files are truncated, but you can click here to view the full file

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

Large files files are truncated, but you can click here to view the full file