01: /*
02: * Copyright 2002-2005 the original author or authors.
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
10: * Unless required by applicable law or agreed to in writing, software
11: * distributed under the License is distributed on an "AS IS" BASIS,
12: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13: * See the License for the specific language governing permissions and
14: * limitations under the License.
15: */
16:
17: package org.springframework.jdbc.core;
18:
19: import java.sql.Connection;
20: import java.sql.SQLException;
21:
22: import org.springframework.dao.DataAccessException;
23:
24: /**
25: * Generic callback interface for code that operates on a JDBC Connection.
26: * Allows to execute any number of operations on a single Connection,
27: * using any type and number of Statements.
28: *
29: * <p>This is particularly useful for delegating to existing data access code
30: * that expects a Connection to work on and throws SQLException. For newly
31: * written code, it is strongly recommended to use JdbcTemplate's more specific
32: * operations, for example a <code>query</code> or <code>update</code> variant.
33: *
34: * @author Juergen Hoeller
35: * @since 1.1.3
36: * @see JdbcTemplate#execute(ConnectionCallback)
37: * @see JdbcTemplate#query
38: * @see JdbcTemplate#update
39: */
40: public interface ConnectionCallback {
41:
42: /**
43: * Gets called by <code>JdbcTemplate.execute</code> with an active JDBC
44: * Connection. Does not need to care about activating or closing the
45: * Connection, or handling transactions.
46: *
47: * <p>If called without a thread-bound JDBC transaction (initiated by
48: * DataSourceTransactionManager), the code will simply get executed on the
49: * JDBC connection with its transactional semantics. If JdbcTemplate is
50: * configured to use a JTA-aware DataSource, the JDBC Connection and thus
51: * the callback code will be transactional if a JTA transaction is active.
52: *
53: * <p>Allows for returning a result object created within the callback, i.e.
54: * a domain object or a collection of domain objects. Note that there's special
55: * support for single step actions: see <code>JdbcTemplate.queryForObject</code>
56: * etc. A thrown RuntimeException is treated as application exception:
57: * it gets propagated to the caller of the template.
58: *
59: * @param con active JDBC Connection
60: * @return a result object, or <code>null</code> if none
61: * @throws SQLException if thrown by a JDBC method, to be auto-converted
62: * to a DataAccessException by a SQLExceptionTranslator
63: * @throws DataAccessException in case of custom exceptions
64: * @see JdbcTemplate#queryForObject(String, Class)
65: * @see JdbcTemplate#queryForRowSet(String)
66: */
67: Object doInConnection(Connection con) throws SQLException,
68: DataAccessException;
69:
70: }
|