KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * Copyright 2002-2005 the original author or authors.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16
17 package org.springframework.jdbc.core;
18
19 import java.sql.CallableStatement JavaDoc;
20 import java.sql.SQLException JavaDoc;
21
22 import org.springframework.dao.DataAccessException;
23
24 /**
25  * Generic callback interface for code that operates on a CallableStatement.
26  * Allows to execute any number of operations on a single CallableStatement,
27  * for example a single execute call or repeated execute calls with varying
28  * parameters.
29  *
30  * <p>Used internally by JdbcTemplate, but also useful for application code.
31  * Note that the passed-in CallableStatement can have been created by the
32  * framework or by a custom CallableStatementCreator. However, the latter is
33  * hardly ever necessary, as most custom callback actions will perform updates
34  * in which case a standard CallableStatement is fine. Custom actions will
35  * always set parameter values themselves, so that CallableStatementCreator
36  * capability is not needed either.
37  *
38  * @author Juergen Hoeller
39  * @since 16.03.2004
40  * @see JdbcTemplate#execute(String, CallableStatementCallback)
41  * @see JdbcTemplate#execute(CallableStatementCreator, CallableStatementCallback)
42  */

43 public interface CallableStatementCallback {
44
45     /**
46      * Gets called by <code>JdbcTemplate.execute</code> with an active JDBC
47      * CallableStatement. Does not need to care about closing the Statement
48      * or the Connection, or about handling transactions: this will all be
49      * handled by Spring's JdbcTemplate.
50      *
51      * <p><b>NOTE:</b> Any ResultSets opened should be closed in finally blocks
52      * within the callback implementation. Spring will close the Statement
53      * object after the callback returned, but this does not necessarily imply
54      * that the ResultSet resources will be closed: the Statement objects might
55      * get pooled by the connection pool, with <code>close</code> calls only
56      * returning the object to the pool but not physically closing the resources.
57      *
58      * <p>If called without a thread-bound JDBC transaction (initiated by
59      * DataSourceTransactionManager), the code will simply get executed on the
60      * JDBC connection with its transactional semantics. If JdbcTemplate is
61      * configured to use a JTA-aware DataSource, the JDBC connection and thus
62      * the callback code will be transactional if a JTA transaction is active.
63      *
64      * <p>Allows for returning a result object created within the callback, i.e.
65      * a domain object or a collection of domain objects. A thrown RuntimeException
66      * is treated as application exception: it gets propagated to the caller of
67      * the template.
68      *
69      * @param cs active JDBC CallableStatement
70      * @return a result object, or <code>null</code> if none
71      * @throws SQLException if thrown by a JDBC method, to be auto-converted
72      * into a DataAccessException by a SQLExceptionTranslator
73      * @throws DataAccessException in case of custom exceptions
74      */

75     Object JavaDoc doInCallableStatement(CallableStatement JavaDoc cs) throws SQLException JavaDoc, DataAccessException;
76
77 }
78
Popular Tags