/*
* Copyright 2002-2018 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.jdbc.core;
import java.util.Collection;
import java.util.List;
import java.util.Map;
import org.springframework.dao.DataAccessException;
import org.springframework.dao.IncorrectResultSizeDataAccessException;
import org.springframework.jdbc.support.KeyHolder;
import org.springframework.jdbc.support.rowset.SqlRowSet;
import org.springframework.lang.Nullable;
Interface specifying a basic set of JDBC operations. Implemented by JdbcTemplate
. Not often used directly, but a useful option to enhance testability, as it can easily be mocked or stubbed. Alternatively, the standard JDBC infrastructure can be mocked. However, mocking this interface constitutes significantly less work. As an alternative to a mock objects approach to testing data access code, consider the powerful integration testing support provided in the org.springframework.test
package, shipped in spring-test.jar
.
Author: Rod Johnson, Juergen Hoeller See Also:
/**
* Interface specifying a basic set of JDBC operations.
* Implemented by {@link JdbcTemplate}. Not often used directly, but a useful
* option to enhance testability, as it can easily be mocked or stubbed.
*
* <p>Alternatively, the standard JDBC infrastructure can be mocked.
* However, mocking this interface constitutes significantly less work.
* As an alternative to a mock objects approach to testing data access code,
* consider the powerful integration testing support provided in the
* {@code org.springframework.test} package, shipped in
* {@code spring-test.jar}.
*
* @author Rod Johnson
* @author Juergen Hoeller
* @see JdbcTemplate
*/
public interface JdbcOperations {
//-------------------------------------------------------------------------
// Methods dealing with a plain java.sql.Connection
//-------------------------------------------------------------------------
Execute a JDBC data access operation, implemented as callback action
working on a JDBC Connection. This allows for implementing arbitrary
data access operations, within Spring's managed JDBC environment:
that is, participating in Spring-managed transactions and converting
JDBC SQLExceptions into Spring's DataAccessException hierarchy.
The callback action can return a result object, for example a
domain object or a collection of domain objects.
Params: - action – the callback object that specifies the action
Throws: - DataAccessException – if there is any problem
Returns: a result object returned by the action, or null
/**
* Execute a JDBC data access operation, implemented as callback action
* working on a JDBC Connection. This allows for implementing arbitrary
* data access operations, within Spring's managed JDBC environment:
* that is, participating in Spring-managed transactions and converting
* JDBC SQLExceptions into Spring's DataAccessException hierarchy.
* <p>The callback action can return a result object, for example a
* domain object or a collection of domain objects.
* @param action the callback object that specifies the action
* @return a result object returned by the action, or {@code null}
* @throws DataAccessException if there is any problem
*/
@Nullable
<T> T execute(ConnectionCallback<T> action) throws DataAccessException;
//-------------------------------------------------------------------------
// Methods dealing with static SQL (java.sql.Statement)
//-------------------------------------------------------------------------
Execute a JDBC data access operation, implemented as callback action
working on a JDBC Statement. This allows for implementing arbitrary data
access operations on a single Statement, within Spring's managed JDBC
environment: that is, participating in Spring-managed transactions and
converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
The callback action can return a result object, for example a
domain object or a collection of domain objects.
Params: - action – callback object that specifies the action
Throws: - DataAccessException – if there is any problem
Returns: a result object returned by the action, or null
/**
* Execute a JDBC data access operation, implemented as callback action
* working on a JDBC Statement. This allows for implementing arbitrary data
* access operations on a single Statement, within Spring's managed JDBC
* environment: that is, participating in Spring-managed transactions and
* converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
* <p>The callback action can return a result object, for example a
* domain object or a collection of domain objects.
* @param action callback object that specifies the action
* @return a result object returned by the action, or {@code null}
* @throws DataAccessException if there is any problem
*/
@Nullable
<T> T execute(StatementCallback<T> action) throws DataAccessException;
Issue a single SQL execute, typically a DDL statement.
Params: - sql – static SQL to execute
Throws: - DataAccessException – if there is any problem
/**
* Issue a single SQL execute, typically a DDL statement.
* @param sql static SQL to execute
* @throws DataAccessException if there is any problem
*/
void execute(String sql) throws DataAccessException;
Execute a query given static SQL, reading the ResultSet with a
ResultSetExtractor.
Uses a JDBC Statement, not a PreparedStatement. If you want to execute a static query with a PreparedStatement, use the overloaded query
method with null
as argument array.
Params: - sql – the SQL query to execute
- rse – object that will extract all rows of results
Throws: - DataAccessException – if there is any problem executing the query
See Also: Returns: an arbitrary result object, as returned by the ResultSetExtractor
/**
* Execute a query given static SQL, reading the ResultSet with a
* ResultSetExtractor.
* <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
* execute a static query with a PreparedStatement, use the overloaded
* {@code query} method with {@code null} as argument array.
* @param sql the SQL query to execute
* @param rse object that will extract all rows of results
* @return an arbitrary result object, as returned by the ResultSetExtractor
* @throws DataAccessException if there is any problem executing the query
* @see #query(String, Object[], ResultSetExtractor)
*/
@Nullable
<T> T query(String sql, ResultSetExtractor<T> rse) throws DataAccessException;
Execute a query given static SQL, reading the ResultSet on a per-row
basis with a RowCallbackHandler.
Uses a JDBC Statement, not a PreparedStatement. If you want to execute a static query with a PreparedStatement, use the overloaded query
method with null
as argument array.
Params: - sql – the SQL query to execute
- rch – object that will extract results, one row at a time
Throws: - DataAccessException – if there is any problem executing the query
See Also:
/**
* Execute a query given static SQL, reading the ResultSet on a per-row
* basis with a RowCallbackHandler.
* <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
* execute a static query with a PreparedStatement, use the overloaded
* {@code query} method with {@code null} as argument array.
* @param sql the SQL query to execute
* @param rch object that will extract results, one row at a time
* @throws DataAccessException if there is any problem executing the query
* @see #query(String, Object[], RowCallbackHandler)
*/
void query(String sql, RowCallbackHandler rch) throws DataAccessException;
Execute a query given static SQL, mapping each row to a Java object
via a RowMapper.
Uses a JDBC Statement, not a PreparedStatement. If you want to execute a static query with a PreparedStatement, use the overloaded query
method with null
as argument array.
Params: - sql – the SQL query to execute
- rowMapper – object that will map one object per row
Throws: - DataAccessException – if there is any problem executing the query
See Also: Returns: the result List, containing mapped objects
/**
* Execute a query given static SQL, mapping each row to a Java object
* via a RowMapper.
* <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
* execute a static query with a PreparedStatement, use the overloaded
* {@code query} method with {@code null} as argument array.
* @param sql the SQL query to execute
* @param rowMapper object that will map one object per row
* @return the result List, containing mapped objects
* @throws DataAccessException if there is any problem executing the query
* @see #query(String, Object[], RowMapper)
*/
<T> List<T> query(String sql, RowMapper<T> rowMapper) throws DataAccessException;
Execute a query given static SQL, mapping a single result row to a Java
object via a RowMapper.
Uses a JDBC Statement, not a PreparedStatement. If you want to execute a static query with a PreparedStatement, use the overloaded queryForObject(String, RowMapper<Object>, Object...)
method with null
as argument array.
Params: - sql – the SQL query to execute
- rowMapper – object that will map one object per row
Throws: - IncorrectResultSizeDataAccessException – if the query does not
return exactly one row
- DataAccessException – if there is any problem executing the query
See Also: Returns: the single mapped object (may be null
if the given RowMapper
returned
null)
/**
* Execute a query given static SQL, mapping a single result row to a Java
* object via a RowMapper.
* <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
* execute a static query with a PreparedStatement, use the overloaded
* {@link #queryForObject(String, RowMapper, Object...)} method with
* {@code null} as argument array.
* @param sql the SQL query to execute
* @param rowMapper object that will map one object per row
* @return the single mapped object (may be {@code null} if the given
* {@link RowMapper} returned {@code} null)
* @throws IncorrectResultSizeDataAccessException if the query does not
* return exactly one row
* @throws DataAccessException if there is any problem executing the query
* @see #queryForObject(String, Object[], RowMapper)
*/
@Nullable
<T> T queryForObject(String sql, RowMapper<T> rowMapper) throws DataAccessException;
Execute a query for a result object, given static SQL.
Uses a JDBC Statement, not a PreparedStatement. If you want to execute a static query with a PreparedStatement, use the overloaded queryForObject(String, Class<Object>, Object...)
method with null
as argument array.
This method is useful for running static SQL with a known outcome.
The query is expected to be a single row/single column query; the returned
result will be directly mapped to the corresponding object type.
Params: - sql – the SQL query to execute
- requiredType – the type that the result object is expected to match
Throws: - IncorrectResultSizeDataAccessException – if the query does not return
exactly one row, or does not return exactly one column in that row
- DataAccessException – if there is any problem executing the query
See Also: Returns: the result object of the required type, or null
in case of SQL NULL
/**
* Execute a query for a result object, given static SQL.
* <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
* execute a static query with a PreparedStatement, use the overloaded
* {@link #queryForObject(String, Class, Object...)} method with
* {@code null} as argument array.
* <p>This method is useful for running static SQL with a known outcome.
* The query is expected to be a single row/single column query; the returned
* result will be directly mapped to the corresponding object type.
* @param sql the SQL query to execute
* @param requiredType the type that the result object is expected to match
* @return the result object of the required type, or {@code null} in case of SQL NULL
* @throws IncorrectResultSizeDataAccessException if the query does not return
* exactly one row, or does not return exactly one column in that row
* @throws DataAccessException if there is any problem executing the query
* @see #queryForObject(String, Object[], Class)
*/
@Nullable
<T> T queryForObject(String sql, Class<T> requiredType) throws DataAccessException;
Execute a query for a result Map, given static SQL.
Uses a JDBC Statement, not a PreparedStatement. If you want to execute a static query with a PreparedStatement, use the overloaded queryForMap(String, Object...)
method with null
as argument array.
The query is expected to be a single row query; the result row will be
mapped to a Map (one entry for each column, using the column name as the key).
Params: - sql – the SQL query to execute
Throws: - IncorrectResultSizeDataAccessException – if the query does not
return exactly one row
- DataAccessException – if there is any problem executing the query
See Also: Returns: the result Map (one entry for each column, using the
column name as the key)
/**
* Execute a query for a result Map, given static SQL.
* <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
* execute a static query with a PreparedStatement, use the overloaded
* {@link #queryForMap(String, Object...)} method with {@code null}
* as argument array.
* <p>The query is expected to be a single row query; the result row will be
* mapped to a Map (one entry for each column, using the column name as the key).
* @param sql the SQL query to execute
* @return the result Map (one entry for each column, using the
* column name as the key)
* @throws IncorrectResultSizeDataAccessException if the query does not
* return exactly one row
* @throws DataAccessException if there is any problem executing the query
* @see #queryForMap(String, Object[])
* @see ColumnMapRowMapper
*/
Map<String, Object> queryForMap(String sql) throws DataAccessException;
Execute a query for a result list, given static SQL.
Uses a JDBC Statement, not a PreparedStatement. If you want to execute a static query with a PreparedStatement, use the overloaded queryForList
method with null
as argument array.
The results will be mapped to a List (one entry for each row) of
result objects, each of them matching the specified element type.
Params: - sql – the SQL query to execute
- elementType – the required type of element in the result list (for example,
Integer.class
)
Throws: - DataAccessException – if there is any problem executing the query
See Also: Returns: a List of objects that match the specified element type
/**
* Execute a query for a result list, given static SQL.
* <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
* execute a static query with a PreparedStatement, use the overloaded
* {@code queryForList} method with {@code null} as argument array.
* <p>The results will be mapped to a List (one entry for each row) of
* result objects, each of them matching the specified element type.
* @param sql the SQL query to execute
* @param elementType the required type of element in the result list
* (for example, {@code Integer.class})
* @return a List of objects that match the specified element type
* @throws DataAccessException if there is any problem executing the query
* @see #queryForList(String, Object[], Class)
* @see SingleColumnRowMapper
*/
<T> List<T> queryForList(String sql, Class<T> elementType) throws DataAccessException;
Execute a query for a result list, given static SQL.
Uses a JDBC Statement, not a PreparedStatement. If you want to execute a static query with a PreparedStatement, use the overloaded queryForList
method with null
as argument array.
The results will be mapped to a List (one entry for each row) of
Maps (one entry for each column using the column name as the key).
Each element in the list will be of the form returned by this interface's
queryForMap() methods.
Params: - sql – the SQL query to execute
Throws: - DataAccessException – if there is any problem executing the query
See Also: Returns: an List that contains a Map per row
/**
* Execute a query for a result list, given static SQL.
* <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
* execute a static query with a PreparedStatement, use the overloaded
* {@code queryForList} method with {@code null} as argument array.
* <p>The results will be mapped to a List (one entry for each row) of
* Maps (one entry for each column using the column name as the key).
* Each element in the list will be of the form returned by this interface's
* queryForMap() methods.
* @param sql the SQL query to execute
* @return an List that contains a Map per row
* @throws DataAccessException if there is any problem executing the query
* @see #queryForList(String, Object[])
*/
List<Map<String, Object>> queryForList(String sql) throws DataAccessException;
Execute a query for a SqlRowSet, given static SQL.
Uses a JDBC Statement, not a PreparedStatement. If you want to execute a static query with a PreparedStatement, use the overloaded queryForRowSet
method with null
as argument array.
The results will be mapped to an SqlRowSet which holds the data in a
disconnected fashion. This wrapper will translate any SQLExceptions thrown.
Note that, for the default implementation, JDBC RowSet support needs to be available at runtime: by default, Sun's com.sun.rowset.CachedRowSetImpl
class is used, which is part of JDK 1.5+ and also available separately as part of Sun's JDBC RowSet Implementations download (rowset.jar).
Params: - sql – the SQL query to execute
Throws: - DataAccessException – if there is any problem executing the query
See Also: Returns: a SqlRowSet representation (possibly a wrapper around a javax.sql.rowset.CachedRowSet
)
/**
* Execute a query for a SqlRowSet, given static SQL.
* <p>Uses a JDBC Statement, not a PreparedStatement. If you want to
* execute a static query with a PreparedStatement, use the overloaded
* {@code queryForRowSet} method with {@code null} as argument array.
* <p>The results will be mapped to an SqlRowSet which holds the data in a
* disconnected fashion. This wrapper will translate any SQLExceptions thrown.
* <p>Note that, for the default implementation, JDBC RowSet support needs to
* be available at runtime: by default, Sun's {@code com.sun.rowset.CachedRowSetImpl}
* class is used, which is part of JDK 1.5+ and also available separately as part of
* Sun's JDBC RowSet Implementations download (rowset.jar).
* @param sql the SQL query to execute
* @return a SqlRowSet representation (possibly a wrapper around a
* {@code javax.sql.rowset.CachedRowSet})
* @throws DataAccessException if there is any problem executing the query
* @see #queryForRowSet(String, Object[])
* @see SqlRowSetResultSetExtractor
* @see javax.sql.rowset.CachedRowSet
*/
SqlRowSet queryForRowSet(String sql) throws DataAccessException;
Issue a single SQL update operation (such as an insert, update or delete statement).
Params: - sql – static SQL to execute
Throws: - DataAccessException – if there is any problem.
Returns: the number of rows affected
/**
* Issue a single SQL update operation (such as an insert, update or delete statement).
* @param sql static SQL to execute
* @return the number of rows affected
* @throws DataAccessException if there is any problem.
*/
int update(String sql) throws DataAccessException;
Issue multiple SQL updates on a single JDBC Statement using batching.
Will fall back to separate updates on a single Statement if the JDBC
driver does not support batch updates.
Params: - sql – defining an array of SQL statements that will be executed.
Throws: - DataAccessException – if there is any problem executing the batch
Returns: an array of the number of rows affected by each statement
/**
* Issue multiple SQL updates on a single JDBC Statement using batching.
* <p>Will fall back to separate updates on a single Statement if the JDBC
* driver does not support batch updates.
* @param sql defining an array of SQL statements that will be executed.
* @return an array of the number of rows affected by each statement
* @throws DataAccessException if there is any problem executing the batch
*/
int[] batchUpdate(String... sql) throws DataAccessException;
//-------------------------------------------------------------------------
// Methods dealing with prepared statements
//-------------------------------------------------------------------------
Execute a JDBC data access operation, implemented as callback action
working on a JDBC PreparedStatement. This allows for implementing arbitrary
data access operations on a single Statement, within Spring's managed
JDBC environment: that is, participating in Spring-managed transactions
and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
The callback action can return a result object, for example a
domain object or a collection of domain objects.
Params: - psc – object that can create a PreparedStatement given a Connection
- action – callback object that specifies the action
Throws: - DataAccessException – if there is any problem
Returns: a result object returned by the action, or null
/**
* Execute a JDBC data access operation, implemented as callback action
* working on a JDBC PreparedStatement. This allows for implementing arbitrary
* data access operations on a single Statement, within Spring's managed
* JDBC environment: that is, participating in Spring-managed transactions
* and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
* <p>The callback action can return a result object, for example a
* domain object or a collection of domain objects.
* @param psc object that can create a PreparedStatement given a Connection
* @param action callback object that specifies the action
* @return a result object returned by the action, or {@code null}
* @throws DataAccessException if there is any problem
*/
@Nullable
<T> T execute(PreparedStatementCreator psc, PreparedStatementCallback<T> action) throws DataAccessException;
Execute a JDBC data access operation, implemented as callback action
working on a JDBC PreparedStatement. This allows for implementing arbitrary
data access operations on a single Statement, within Spring's managed
JDBC environment: that is, participating in Spring-managed transactions
and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
The callback action can return a result object, for example a
domain object or a collection of domain objects.
Params: - sql – the SQL to execute
- action – callback object that specifies the action
Throws: - DataAccessException – if there is any problem
Returns: a result object returned by the action, or null
/**
* Execute a JDBC data access operation, implemented as callback action
* working on a JDBC PreparedStatement. This allows for implementing arbitrary
* data access operations on a single Statement, within Spring's managed
* JDBC environment: that is, participating in Spring-managed transactions
* and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
* <p>The callback action can return a result object, for example a
* domain object or a collection of domain objects.
* @param sql the SQL to execute
* @param action callback object that specifies the action
* @return a result object returned by the action, or {@code null}
* @throws DataAccessException if there is any problem
*/
@Nullable
<T> T execute(String sql, PreparedStatementCallback<T> action) throws DataAccessException;
Query using a prepared statement, reading the ResultSet with a
ResultSetExtractor.
A PreparedStatementCreator can either be implemented directly or
configured through a PreparedStatementCreatorFactory.
Params: - psc – object that can create a PreparedStatement given a Connection
- rse – object that will extract results
Throws: - DataAccessException – if there is any problem
See Also: Returns: an arbitrary result object, as returned by the ResultSetExtractor
/**
* Query using a prepared statement, reading the ResultSet with a
* ResultSetExtractor.
* <p>A PreparedStatementCreator can either be implemented directly or
* configured through a PreparedStatementCreatorFactory.
* @param psc object that can create a PreparedStatement given a Connection
* @param rse object that will extract results
* @return an arbitrary result object, as returned by the ResultSetExtractor
* @throws DataAccessException if there is any problem
* @see PreparedStatementCreatorFactory
*/
@Nullable
<T> T query(PreparedStatementCreator psc, ResultSetExtractor<T> rse) throws DataAccessException;
Query using a prepared statement, reading the ResultSet with a
ResultSetExtractor.
Params: - sql – the SQL query to execute
- pss – object that knows how to set values on the prepared statement. If this is
null
, the SQL will be assumed to contain no bind parameters. Even if there are no bind parameters, this object may be used to set fetch size and other performance options. - rse – object that will extract results
Throws: - DataAccessException – if there is any problem
Returns: an arbitrary result object, as returned by the ResultSetExtractor
/**
* Query using a prepared statement, reading the ResultSet with a
* ResultSetExtractor.
* @param sql the SQL query to execute
* @param pss object that knows how to set values on the prepared statement.
* If this is {@code null}, the SQL will be assumed to contain no bind parameters.
* Even if there are no bind parameters, this object may be used to
* set fetch size and other performance options.
* @param rse object that will extract results
* @return an arbitrary result object, as returned by the ResultSetExtractor
* @throws DataAccessException if there is any problem
*/
@Nullable
<T> T query(String sql, @Nullable PreparedStatementSetter pss, ResultSetExtractor<T> rse) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a list
of arguments to bind to the query, reading the ResultSet with a
ResultSetExtractor.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query
- argTypes – the SQL types of the arguments (constants from
java.sql.Types
) - rse – object that will extract results
Throws: - DataAccessException – if the query fails
See Also: Returns: an arbitrary result object, as returned by the ResultSetExtractor
/**
* Query given SQL to create a prepared statement from SQL and a list
* of arguments to bind to the query, reading the ResultSet with a
* ResultSetExtractor.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* @param argTypes the SQL types of the arguments
* (constants from {@code java.sql.Types})
* @param rse object that will extract results
* @return an arbitrary result object, as returned by the ResultSetExtractor
* @throws DataAccessException if the query fails
* @see java.sql.Types
*/
@Nullable
<T> T query(String sql, Object[] args, int[] argTypes, ResultSetExtractor<T> rse) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a list
of arguments to bind to the query, reading the ResultSet with a
ResultSetExtractor.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale - rse – object that will extract results
Throws: - DataAccessException – if the query fails
Returns: an arbitrary result object, as returned by the ResultSetExtractor
/**
* Query given SQL to create a prepared statement from SQL and a list
* of arguments to bind to the query, reading the ResultSet with a
* ResultSetExtractor.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @param rse object that will extract results
* @return an arbitrary result object, as returned by the ResultSetExtractor
* @throws DataAccessException if the query fails
*/
@Nullable
<T> T query(String sql, Object[] args, ResultSetExtractor<T> rse) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a list
of arguments to bind to the query, reading the ResultSet with a
ResultSetExtractor.
Params: - sql – the SQL query to execute
- rse – object that will extract results
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale
Throws: - DataAccessException – if the query fails
Returns: an arbitrary result object, as returned by the ResultSetExtractor Since: 3.0.1
/**
* Query given SQL to create a prepared statement from SQL and a list
* of arguments to bind to the query, reading the ResultSet with a
* ResultSetExtractor.
* @param sql the SQL query to execute
* @param rse object that will extract results
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @return an arbitrary result object, as returned by the ResultSetExtractor
* @throws DataAccessException if the query fails
* @since 3.0.1
*/
@Nullable
<T> T query(String sql, ResultSetExtractor<T> rse, @Nullable Object... args) throws DataAccessException;
Query using a prepared statement, reading the ResultSet on a per-row
basis with a RowCallbackHandler.
A PreparedStatementCreator can either be implemented directly or
configured through a PreparedStatementCreatorFactory.
Params: - psc – object that can create a PreparedStatement given a Connection
- rch – object that will extract results, one row at a time
Throws: - DataAccessException – if there is any problem
See Also:
/**
* Query using a prepared statement, reading the ResultSet on a per-row
* basis with a RowCallbackHandler.
* <p>A PreparedStatementCreator can either be implemented directly or
* configured through a PreparedStatementCreatorFactory.
* @param psc object that can create a PreparedStatement given a Connection
* @param rch object that will extract results, one row at a time
* @throws DataAccessException if there is any problem
* @see PreparedStatementCreatorFactory
*/
void query(PreparedStatementCreator psc, RowCallbackHandler rch) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
PreparedStatementSetter implementation that knows how to bind values
to the query, reading the ResultSet on a per-row basis with a
RowCallbackHandler.
Params: - sql – the SQL query to execute
- pss – object that knows how to set values on the prepared statement. If this is
null
, the SQL will be assumed to contain no bind parameters. Even if there are no bind parameters, this object may be used to set fetch size and other performance options. - rch – object that will extract results, one row at a time
Throws: - DataAccessException – if the query fails
/**
* Query given SQL to create a prepared statement from SQL and a
* PreparedStatementSetter implementation that knows how to bind values
* to the query, reading the ResultSet on a per-row basis with a
* RowCallbackHandler.
* @param sql the SQL query to execute
* @param pss object that knows how to set values on the prepared statement.
* If this is {@code null}, the SQL will be assumed to contain no bind parameters.
* Even if there are no bind parameters, this object may be used to
* set fetch size and other performance options.
* @param rch object that will extract results, one row at a time
* @throws DataAccessException if the query fails
*/
void query(String sql, @Nullable PreparedStatementSetter pss, RowCallbackHandler rch) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a list of
arguments to bind to the query, reading the ResultSet on a per-row basis
with a RowCallbackHandler.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query
- argTypes – the SQL types of the arguments (constants from
java.sql.Types
) - rch – object that will extract results, one row at a time
Throws: - DataAccessException – if the query fails
See Also:
/**
* Query given SQL to create a prepared statement from SQL and a list of
* arguments to bind to the query, reading the ResultSet on a per-row basis
* with a RowCallbackHandler.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* @param argTypes the SQL types of the arguments
* (constants from {@code java.sql.Types})
* @param rch object that will extract results, one row at a time
* @throws DataAccessException if the query fails
* @see java.sql.Types
*/
void query(String sql, Object[] args, int[] argTypes, RowCallbackHandler rch) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a list of
arguments to bind to the query, reading the ResultSet on a per-row basis
with a RowCallbackHandler.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale - rch – object that will extract results, one row at a time
Throws: - DataAccessException – if the query fails
/**
* Query given SQL to create a prepared statement from SQL and a list of
* arguments to bind to the query, reading the ResultSet on a per-row basis
* with a RowCallbackHandler.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @param rch object that will extract results, one row at a time
* @throws DataAccessException if the query fails
*/
void query(String sql, Object[] args, RowCallbackHandler rch) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a list of
arguments to bind to the query, reading the ResultSet on a per-row basis
with a RowCallbackHandler.
Params: - sql – the SQL query to execute
- rch – object that will extract results, one row at a time
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale
Throws: - DataAccessException – if the query fails
Since: 3.0.1
/**
* Query given SQL to create a prepared statement from SQL and a list of
* arguments to bind to the query, reading the ResultSet on a per-row basis
* with a RowCallbackHandler.
* @param sql the SQL query to execute
* @param rch object that will extract results, one row at a time
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @throws DataAccessException if the query fails
* @since 3.0.1
*/
void query(String sql, RowCallbackHandler rch, @Nullable Object... args) throws DataAccessException;
Query using a prepared statement, mapping each row to a Java object
via a RowMapper.
A PreparedStatementCreator can either be implemented directly or
configured through a PreparedStatementCreatorFactory.
Params: - psc – object that can create a PreparedStatement given a Connection
- rowMapper – object that will map one object per row
Throws: - DataAccessException – if there is any problem
See Also: Returns: the result List, containing mapped objects
/**
* Query using a prepared statement, mapping each row to a Java object
* via a RowMapper.
* <p>A PreparedStatementCreator can either be implemented directly or
* configured through a PreparedStatementCreatorFactory.
* @param psc object that can create a PreparedStatement given a Connection
* @param rowMapper object that will map one object per row
* @return the result List, containing mapped objects
* @throws DataAccessException if there is any problem
* @see PreparedStatementCreatorFactory
*/
<T> List<T> query(PreparedStatementCreator psc, RowMapper<T> rowMapper) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
PreparedStatementSetter implementation that knows how to bind values
to the query, mapping each row to a Java object via a RowMapper.
Params: - sql – the SQL query to execute
- pss – object that knows how to set values on the prepared statement. If this is
null
, the SQL will be assumed to contain no bind parameters. Even if there are no bind parameters, this object may be used to set fetch size and other performance options. - rowMapper – object that will map one object per row
Throws: - DataAccessException – if the query fails
Returns: the result List, containing mapped objects
/**
* Query given SQL to create a prepared statement from SQL and a
* PreparedStatementSetter implementation that knows how to bind values
* to the query, mapping each row to a Java object via a RowMapper.
* @param sql the SQL query to execute
* @param pss object that knows how to set values on the prepared statement.
* If this is {@code null}, the SQL will be assumed to contain no bind parameters.
* Even if there are no bind parameters, this object may be used to
* set fetch size and other performance options.
* @param rowMapper object that will map one object per row
* @return the result List, containing mapped objects
* @throws DataAccessException if the query fails
*/
<T> List<T> query(String sql, @Nullable PreparedStatementSetter pss, RowMapper<T> rowMapper) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a list
of arguments to bind to the query, mapping each row to a Java object
via a RowMapper.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query
- argTypes – the SQL types of the arguments (constants from
java.sql.Types
) - rowMapper – object that will map one object per row
Throws: - DataAccessException – if the query fails
See Also: Returns: the result List, containing mapped objects
/**
* Query given SQL to create a prepared statement from SQL and a list
* of arguments to bind to the query, mapping each row to a Java object
* via a RowMapper.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* @param argTypes the SQL types of the arguments
* (constants from {@code java.sql.Types})
* @param rowMapper object that will map one object per row
* @return the result List, containing mapped objects
* @throws DataAccessException if the query fails
* @see java.sql.Types
*/
<T> List<T> query(String sql, Object[] args, int[] argTypes, RowMapper<T> rowMapper) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a list
of arguments to bind to the query, mapping each row to a Java object
via a RowMapper.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale - rowMapper – object that will map one object per row
Throws: - DataAccessException – if the query fails
Returns: the result List, containing mapped objects
/**
* Query given SQL to create a prepared statement from SQL and a list
* of arguments to bind to the query, mapping each row to a Java object
* via a RowMapper.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @param rowMapper object that will map one object per row
* @return the result List, containing mapped objects
* @throws DataAccessException if the query fails
*/
<T> List<T> query(String sql, Object[] args, RowMapper<T> rowMapper) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a list
of arguments to bind to the query, mapping each row to a Java object
via a RowMapper.
Params: - sql – the SQL query to execute
- rowMapper – object that will map one object per row
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale
Throws: - DataAccessException – if the query fails
Returns: the result List, containing mapped objects Since: 3.0.1
/**
* Query given SQL to create a prepared statement from SQL and a list
* of arguments to bind to the query, mapping each row to a Java object
* via a RowMapper.
* @param sql the SQL query to execute
* @param rowMapper object that will map one object per row
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @return the result List, containing mapped objects
* @throws DataAccessException if the query fails
* @since 3.0.1
*/
<T> List<T> query(String sql, RowMapper<T> rowMapper, @Nullable Object... args) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a list
of arguments to bind to the query, mapping a single result row to a
Java object via a RowMapper.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query
(leaving it to the PreparedStatement to guess the corresponding SQL type)
- argTypes – the SQL types of the arguments (constants from
java.sql.Types
) - rowMapper – object that will map one object per row
Throws: - IncorrectResultSizeDataAccessException – if the query does not
return exactly one row
- DataAccessException – if the query fails
Returns: the single mapped object (may be null
if the given RowMapper
returned
null)
/**
* Query given SQL to create a prepared statement from SQL and a list
* of arguments to bind to the query, mapping a single result row to a
* Java object via a RowMapper.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type)
* @param argTypes the SQL types of the arguments
* (constants from {@code java.sql.Types})
* @param rowMapper object that will map one object per row
* @return the single mapped object (may be {@code null} if the given
* {@link RowMapper} returned {@code} null)
* @throws IncorrectResultSizeDataAccessException if the query does not
* return exactly one row
* @throws DataAccessException if the query fails
*/
@Nullable
<T> T queryForObject(String sql, Object[] args, int[] argTypes, RowMapper<T> rowMapper)
throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a list
of arguments to bind to the query, mapping a single result row to a
Java object via a RowMapper.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale - rowMapper – object that will map one object per row
Throws: - IncorrectResultSizeDataAccessException – if the query does not
return exactly one row
- DataAccessException – if the query fails
Returns: the single mapped object (may be null
if the given RowMapper
returned
null)
/**
* Query given SQL to create a prepared statement from SQL and a list
* of arguments to bind to the query, mapping a single result row to a
* Java object via a RowMapper.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @param rowMapper object that will map one object per row
* @return the single mapped object (may be {@code null} if the given
* {@link RowMapper} returned {@code} null)
* @throws IncorrectResultSizeDataAccessException if the query does not
* return exactly one row
* @throws DataAccessException if the query fails
*/
@Nullable
<T> T queryForObject(String sql, Object[] args, RowMapper<T> rowMapper) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a list
of arguments to bind to the query, mapping a single result row to a
Java object via a RowMapper.
Params: - sql – the SQL query to execute
- rowMapper – object that will map one object per row
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale
Throws: - IncorrectResultSizeDataAccessException – if the query does not
return exactly one row
- DataAccessException – if the query fails
Returns: the single mapped object (may be null
if the given RowMapper
returned
null) Since: 3.0.1
/**
* Query given SQL to create a prepared statement from SQL and a list
* of arguments to bind to the query, mapping a single result row to a
* Java object via a RowMapper.
* @param sql the SQL query to execute
* @param rowMapper object that will map one object per row
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @return the single mapped object (may be {@code null} if the given
* {@link RowMapper} returned {@code} null)
* @throws IncorrectResultSizeDataAccessException if the query does not
* return exactly one row
* @throws DataAccessException if the query fails
* @since 3.0.1
*/
@Nullable
<T> T queryForObject(String sql, RowMapper<T> rowMapper, @Nullable Object... args) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
list of arguments to bind to the query, expecting a result object.
The query is expected to be a single row/single column query; the returned
result will be directly mapped to the corresponding object type.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query
- argTypes – the SQL types of the arguments (constants from
java.sql.Types
) - requiredType – the type that the result object is expected to match
Throws: - IncorrectResultSizeDataAccessException – if the query does not return
exactly one row, or does not return exactly one column in that row
- DataAccessException – if the query fails
See Also: Returns: the result object of the required type, or null
in case of SQL NULL
/**
* Query given SQL to create a prepared statement from SQL and a
* list of arguments to bind to the query, expecting a result object.
* <p>The query is expected to be a single row/single column query; the returned
* result will be directly mapped to the corresponding object type.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* @param argTypes the SQL types of the arguments
* (constants from {@code java.sql.Types})
* @param requiredType the type that the result object is expected to match
* @return the result object of the required type, or {@code null} in case of SQL NULL
* @throws IncorrectResultSizeDataAccessException if the query does not return
* exactly one row, or does not return exactly one column in that row
* @throws DataAccessException if the query fails
* @see #queryForObject(String, Class)
* @see java.sql.Types
*/
@Nullable
<T> T queryForObject(String sql, Object[] args, int[] argTypes, Class<T> requiredType)
throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
list of arguments to bind to the query, expecting a result object.
The query is expected to be a single row/single column query; the returned
result will be directly mapped to the corresponding object type.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale - requiredType – the type that the result object is expected to match
Throws: - IncorrectResultSizeDataAccessException – if the query does not return
exactly one row, or does not return exactly one column in that row
- DataAccessException – if the query fails
See Also: Returns: the result object of the required type, or null
in case of SQL NULL
/**
* Query given SQL to create a prepared statement from SQL and a
* list of arguments to bind to the query, expecting a result object.
* <p>The query is expected to be a single row/single column query; the returned
* result will be directly mapped to the corresponding object type.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @param requiredType the type that the result object is expected to match
* @return the result object of the required type, or {@code null} in case of SQL NULL
* @throws IncorrectResultSizeDataAccessException if the query does not return
* exactly one row, or does not return exactly one column in that row
* @throws DataAccessException if the query fails
* @see #queryForObject(String, Class)
*/
@Nullable
<T> T queryForObject(String sql, Object[] args, Class<T> requiredType) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
list of arguments to bind to the query, expecting a result object.
The query is expected to be a single row/single column query; the returned
result will be directly mapped to the corresponding object type.
Params: - sql – the SQL query to execute
- requiredType – the type that the result object is expected to match
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale
Throws: - IncorrectResultSizeDataAccessException – if the query does not return
exactly one row, or does not return exactly one column in that row
- DataAccessException – if the query fails
See Also: Returns: the result object of the required type, or null
in case of SQL NULL Since: 3.0.1
/**
* Query given SQL to create a prepared statement from SQL and a
* list of arguments to bind to the query, expecting a result object.
* <p>The query is expected to be a single row/single column query; the returned
* result will be directly mapped to the corresponding object type.
* @param sql the SQL query to execute
* @param requiredType the type that the result object is expected to match
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @return the result object of the required type, or {@code null} in case of SQL NULL
* @throws IncorrectResultSizeDataAccessException if the query does not return
* exactly one row, or does not return exactly one column in that row
* @throws DataAccessException if the query fails
* @since 3.0.1
* @see #queryForObject(String, Class)
*/
@Nullable
<T> T queryForObject(String sql, Class<T> requiredType, @Nullable Object... args) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
list of arguments to bind to the query, expecting a result Map.
The query is expected to be a single row query; the result row will be
mapped to a Map (one entry for each column, using the column name as the key).
Params: - sql – the SQL query to execute
- args – arguments to bind to the query
- argTypes – the SQL types of the arguments (constants from
java.sql.Types
)
Throws: - IncorrectResultSizeDataAccessException – if the query does not
return exactly one row
- DataAccessException – if the query fails
See Also: Returns: the result Map (one entry for each column, using the
column name as the key)
/**
* Query given SQL to create a prepared statement from SQL and a
* list of arguments to bind to the query, expecting a result Map.
* <p>The query is expected to be a single row query; the result row will be
* mapped to a Map (one entry for each column, using the column name as the key).
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* @param argTypes the SQL types of the arguments
* (constants from {@code java.sql.Types})
* @return the result Map (one entry for each column, using the
* column name as the key)
* @throws IncorrectResultSizeDataAccessException if the query does not
* return exactly one row
* @throws DataAccessException if the query fails
* @see #queryForMap(String)
* @see ColumnMapRowMapper
* @see java.sql.Types
*/
Map<String, Object> queryForMap(String sql, Object[] args, int[] argTypes) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
list of arguments to bind to the query, expecting a result Map.
The queryForMap() methods defined by this interface are appropriate
when you don't have a domain model. Otherwise, consider using
one of the queryForObject() methods.
The query is expected to be a single row query; the result row will be
mapped to a Map (one entry for each column, using the column name as the key).
Params: - sql – the SQL query to execute
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale
Throws: - IncorrectResultSizeDataAccessException – if the query does not
return exactly one row
- DataAccessException – if the query fails
See Also: Returns: the result Map (one entry for each column, using the
column name as the key)
/**
* Query given SQL to create a prepared statement from SQL and a
* list of arguments to bind to the query, expecting a result Map.
* The queryForMap() methods defined by this interface are appropriate
* when you don't have a domain model. Otherwise, consider using
* one of the queryForObject() methods.
* <p>The query is expected to be a single row query; the result row will be
* mapped to a Map (one entry for each column, using the column name as the key).
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @return the result Map (one entry for each column, using the
* column name as the key)
* @throws IncorrectResultSizeDataAccessException if the query does not
* return exactly one row
* @throws DataAccessException if the query fails
* @see #queryForMap(String)
* @see ColumnMapRowMapper
*/
Map<String, Object> queryForMap(String sql, @Nullable Object... args) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
list of arguments to bind to the query, expecting a result list.
The results will be mapped to a List (one entry for each row) of
result objects, each of them matching the specified element type.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query
- argTypes – the SQL types of the arguments (constants from
java.sql.Types
) - elementType – the required type of element in the result list (for example,
Integer.class
)
Throws: - DataAccessException – if the query fails
See Also: Returns: a List of objects that match the specified element type
/**
* Query given SQL to create a prepared statement from SQL and a
* list of arguments to bind to the query, expecting a result list.
* <p>The results will be mapped to a List (one entry for each row) of
* result objects, each of them matching the specified element type.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* @param argTypes the SQL types of the arguments
* (constants from {@code java.sql.Types})
* @param elementType the required type of element in the result list
* (for example, {@code Integer.class})
* @return a List of objects that match the specified element type
* @throws DataAccessException if the query fails
* @see #queryForList(String, Class)
* @see SingleColumnRowMapper
*/
<T>List<T> queryForList(String sql, Object[] args, int[] argTypes, Class<T> elementType)
throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
list of arguments to bind to the query, expecting a result list.
The results will be mapped to a List (one entry for each row) of
result objects, each of them matching the specified element type.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale - elementType – the required type of element in the result list (for example,
Integer.class
)
Throws: - DataAccessException – if the query fails
See Also: Returns: a List of objects that match the specified element type
/**
* Query given SQL to create a prepared statement from SQL and a
* list of arguments to bind to the query, expecting a result list.
* <p>The results will be mapped to a List (one entry for each row) of
* result objects, each of them matching the specified element type.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @param elementType the required type of element in the result list
* (for example, {@code Integer.class})
* @return a List of objects that match the specified element type
* @throws DataAccessException if the query fails
* @see #queryForList(String, Class)
* @see SingleColumnRowMapper
*/
<T> List<T> queryForList(String sql, Object[] args, Class<T> elementType) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
list of arguments to bind to the query, expecting a result list.
The results will be mapped to a List (one entry for each row) of
result objects, each of them matching the specified element type.
Params: - sql – the SQL query to execute
- elementType – the required type of element in the result list (for example,
Integer.class
) - args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale
Throws: - DataAccessException – if the query fails
See Also: Returns: a List of objects that match the specified element type Since: 3.0.1
/**
* Query given SQL to create a prepared statement from SQL and a
* list of arguments to bind to the query, expecting a result list.
* <p>The results will be mapped to a List (one entry for each row) of
* result objects, each of them matching the specified element type.
* @param sql the SQL query to execute
* @param elementType the required type of element in the result list
* (for example, {@code Integer.class})
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @return a List of objects that match the specified element type
* @throws DataAccessException if the query fails
* @since 3.0.1
* @see #queryForList(String, Class)
* @see SingleColumnRowMapper
*/
<T> List<T> queryForList(String sql, Class<T> elementType, @Nullable Object... args) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
list of arguments to bind to the query, expecting a result list.
The results will be mapped to a List (one entry for each row) of
Maps (one entry for each column, using the column name as the key).
Thus Each element in the list will be of the form returned by this interface's
queryForMap() methods.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query
- argTypes – the SQL types of the arguments (constants from
java.sql.Types
)
Throws: - DataAccessException – if the query fails
See Also: Returns: a List that contains a Map per row
/**
* Query given SQL to create a prepared statement from SQL and a
* list of arguments to bind to the query, expecting a result list.
* <p>The results will be mapped to a List (one entry for each row) of
* Maps (one entry for each column, using the column name as the key).
* Thus Each element in the list will be of the form returned by this interface's
* queryForMap() methods.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* @param argTypes the SQL types of the arguments
* (constants from {@code java.sql.Types})
* @return a List that contains a Map per row
* @throws DataAccessException if the query fails
* @see #queryForList(String)
* @see java.sql.Types
*/
List<Map<String, Object>> queryForList(String sql, Object[] args, int[] argTypes) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
list of arguments to bind to the query, expecting a result list.
The results will be mapped to a List (one entry for each row) of
Maps (one entry for each column, using the column name as the key).
Each element in the list will be of the form returned by this interface's
queryForMap() methods.
Params: - sql – the SQL query to execute
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale
Throws: - DataAccessException – if the query fails
See Also: Returns: a List that contains a Map per row
/**
* Query given SQL to create a prepared statement from SQL and a
* list of arguments to bind to the query, expecting a result list.
* <p>The results will be mapped to a List (one entry for each row) of
* Maps (one entry for each column, using the column name as the key).
* Each element in the list will be of the form returned by this interface's
* queryForMap() methods.
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @return a List that contains a Map per row
* @throws DataAccessException if the query fails
* @see #queryForList(String)
*/
List<Map<String, Object>> queryForList(String sql, @Nullable Object... args) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
list of arguments to bind to the query, expecting a SqlRowSet.
The results will be mapped to an SqlRowSet which holds the data in a
disconnected fashion. This wrapper will translate any SQLExceptions thrown.
Note that, for the default implementation, JDBC RowSet support needs to be available at runtime: by default, Sun's com.sun.rowset.CachedRowSetImpl
class is used, which is part of JDK 1.5+ and also available separately as part of Sun's JDBC RowSet Implementations download (rowset.jar).
Params: - sql – the SQL query to execute
- args – arguments to bind to the query
- argTypes – the SQL types of the arguments (constants from
java.sql.Types
)
Throws: - DataAccessException – if there is any problem executing the query
See Also: Returns: a SqlRowSet representation (possibly a wrapper around a javax.sql.rowset.CachedRowSet
)
/**
* Query given SQL to create a prepared statement from SQL and a
* list of arguments to bind to the query, expecting a SqlRowSet.
* <p>The results will be mapped to an SqlRowSet which holds the data in a
* disconnected fashion. This wrapper will translate any SQLExceptions thrown.
* <p>Note that, for the default implementation, JDBC RowSet support needs to
* be available at runtime: by default, Sun's {@code com.sun.rowset.CachedRowSetImpl}
* class is used, which is part of JDK 1.5+ and also available separately as part of
* Sun's JDBC RowSet Implementations download (rowset.jar).
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* @param argTypes the SQL types of the arguments
* (constants from {@code java.sql.Types})
* @return a SqlRowSet representation (possibly a wrapper around a
* {@code javax.sql.rowset.CachedRowSet})
* @throws DataAccessException if there is any problem executing the query
* @see #queryForRowSet(String)
* @see SqlRowSetResultSetExtractor
* @see javax.sql.rowset.CachedRowSet
* @see java.sql.Types
*/
SqlRowSet queryForRowSet(String sql, Object[] args, int[] argTypes) throws DataAccessException;
Query given SQL to create a prepared statement from SQL and a
list of arguments to bind to the query, expecting a SqlRowSet.
The results will be mapped to an SqlRowSet which holds the data in a
disconnected fashion. This wrapper will translate any SQLExceptions thrown.
Note that, for the default implementation, JDBC RowSet support needs to be available at runtime: by default, Sun's com.sun.rowset.CachedRowSetImpl
class is used, which is part of JDK 1.5+ and also available separately as part of Sun's JDBC RowSet Implementations download (rowset.jar).
Params: - sql – the SQL query to execute
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale
Throws: - DataAccessException – if there is any problem executing the query
See Also: Returns: a SqlRowSet representation (possibly a wrapper around a javax.sql.rowset.CachedRowSet
)
/**
* Query given SQL to create a prepared statement from SQL and a
* list of arguments to bind to the query, expecting a SqlRowSet.
* <p>The results will be mapped to an SqlRowSet which holds the data in a
* disconnected fashion. This wrapper will translate any SQLExceptions thrown.
* <p>Note that, for the default implementation, JDBC RowSet support needs to
* be available at runtime: by default, Sun's {@code com.sun.rowset.CachedRowSetImpl}
* class is used, which is part of JDK 1.5+ and also available separately as part of
* Sun's JDBC RowSet Implementations download (rowset.jar).
* @param sql the SQL query to execute
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @return a SqlRowSet representation (possibly a wrapper around a
* {@code javax.sql.rowset.CachedRowSet})
* @throws DataAccessException if there is any problem executing the query
* @see #queryForRowSet(String)
* @see SqlRowSetResultSetExtractor
* @see javax.sql.rowset.CachedRowSet
*/
SqlRowSet queryForRowSet(String sql, @Nullable Object... args) throws DataAccessException;
Issue a single SQL update operation (such as an insert, update or delete statement)
using a PreparedStatementCreator to provide SQL and any required parameters.
A PreparedStatementCreator can either be implemented directly or
configured through a PreparedStatementCreatorFactory.
Params: - psc – object that provides SQL and any necessary parameters
Throws: - DataAccessException – if there is any problem issuing the update
See Also: Returns: the number of rows affected
/**
* Issue a single SQL update operation (such as an insert, update or delete statement)
* using a PreparedStatementCreator to provide SQL and any required parameters.
* <p>A PreparedStatementCreator can either be implemented directly or
* configured through a PreparedStatementCreatorFactory.
* @param psc object that provides SQL and any necessary parameters
* @return the number of rows affected
* @throws DataAccessException if there is any problem issuing the update
* @see PreparedStatementCreatorFactory
*/
int update(PreparedStatementCreator psc) throws DataAccessException;
Issue an update statement using a PreparedStatementCreator to provide SQL and
any required parameters. Generated keys will be put into the given KeyHolder.
Note that the given PreparedStatementCreator has to create a statement
with activated extraction of generated keys (a JDBC 3.0 feature). This can
either be done directly or through using a PreparedStatementCreatorFactory.
Params: - psc – object that provides SQL and any necessary parameters
- generatedKeyHolder – a KeyHolder that will hold the generated keys
Throws: - DataAccessException – if there is any problem issuing the update
See Also: Returns: the number of rows affected
/**
* Issue an update statement using a PreparedStatementCreator to provide SQL and
* any required parameters. Generated keys will be put into the given KeyHolder.
* <p>Note that the given PreparedStatementCreator has to create a statement
* with activated extraction of generated keys (a JDBC 3.0 feature). This can
* either be done directly or through using a PreparedStatementCreatorFactory.
* @param psc object that provides SQL and any necessary parameters
* @param generatedKeyHolder a KeyHolder that will hold the generated keys
* @return the number of rows affected
* @throws DataAccessException if there is any problem issuing the update
* @see PreparedStatementCreatorFactory
* @see org.springframework.jdbc.support.GeneratedKeyHolder
*/
int update(PreparedStatementCreator psc, KeyHolder generatedKeyHolder) throws DataAccessException;
Issue an update statement using a PreparedStatementSetter to set bind parameters,
with given SQL. Simpler than using a PreparedStatementCreator as this method
will create the PreparedStatement: The PreparedStatementSetter just needs to
set parameters.
Params: - sql – the SQL containing bind parameters
- pss – helper that sets bind parameters. If this is
null
we run an update with static SQL.
Throws: - DataAccessException – if there is any problem issuing the update
Returns: the number of rows affected
/**
* Issue an update statement using a PreparedStatementSetter to set bind parameters,
* with given SQL. Simpler than using a PreparedStatementCreator as this method
* will create the PreparedStatement: The PreparedStatementSetter just needs to
* set parameters.
* @param sql the SQL containing bind parameters
* @param pss helper that sets bind parameters. If this is {@code null}
* we run an update with static SQL.
* @return the number of rows affected
* @throws DataAccessException if there is any problem issuing the update
*/
int update(String sql, @Nullable PreparedStatementSetter pss) throws DataAccessException;
Issue a single SQL update operation (such as an insert, update or delete statement)
via a prepared statement, binding the given arguments.
Params: - sql – the SQL containing bind parameters
- args – arguments to bind to the query
- argTypes – the SQL types of the arguments (constants from
java.sql.Types
)
Throws: - DataAccessException – if there is any problem issuing the update
See Also: Returns: the number of rows affected
/**
* Issue a single SQL update operation (such as an insert, update or delete statement)
* via a prepared statement, binding the given arguments.
* @param sql the SQL containing bind parameters
* @param args arguments to bind to the query
* @param argTypes the SQL types of the arguments
* (constants from {@code java.sql.Types})
* @return the number of rows affected
* @throws DataAccessException if there is any problem issuing the update
* @see java.sql.Types
*/
int update(String sql, Object[] args, int[] argTypes) throws DataAccessException;
Issue a single SQL update operation (such as an insert, update or delete statement)
via a prepared statement, binding the given arguments.
Params: - sql – the SQL containing bind parameters
- args – arguments to bind to the query (leaving it to the PreparedStatement to guess the corresponding SQL type); may also contain
SqlParameterValue
objects which indicate not only the argument value but also the SQL type and optionally the scale
Throws: - DataAccessException – if there is any problem issuing the update
Returns: the number of rows affected
/**
* Issue a single SQL update operation (such as an insert, update or delete statement)
* via a prepared statement, binding the given arguments.
* @param sql the SQL containing bind parameters
* @param args arguments to bind to the query
* (leaving it to the PreparedStatement to guess the corresponding SQL type);
* may also contain {@link SqlParameterValue} objects which indicate not
* only the argument value but also the SQL type and optionally the scale
* @return the number of rows affected
* @throws DataAccessException if there is any problem issuing the update
*/
int update(String sql, @Nullable Object... args) throws DataAccessException;
Issue multiple update statements on a single PreparedStatement,
using batch updates and a BatchPreparedStatementSetter to set values.
Will fall back to separate updates on a single PreparedStatement
if the JDBC driver does not support batch updates.
Params: - sql – defining PreparedStatement that will be reused.
All statements in the batch will use the same SQL.
- pss – object to set parameters on the PreparedStatement
created by this method
Throws: - DataAccessException – if there is any problem issuing the update
Returns: an array of the number of rows affected by each statement
/**
* Issue multiple update statements on a single PreparedStatement,
* using batch updates and a BatchPreparedStatementSetter to set values.
* <p>Will fall back to separate updates on a single PreparedStatement
* if the JDBC driver does not support batch updates.
* @param sql defining PreparedStatement that will be reused.
* All statements in the batch will use the same SQL.
* @param pss object to set parameters on the PreparedStatement
* created by this method
* @return an array of the number of rows affected by each statement
* @throws DataAccessException if there is any problem issuing the update
*/
int[] batchUpdate(String sql, BatchPreparedStatementSetter pss) throws DataAccessException;
Execute a batch using the supplied SQL statement with the batch of supplied arguments.
Params: - sql – the SQL statement to execute
- batchArgs – the List of Object arrays containing the batch of arguments for the query
Returns: an array containing the numbers of rows affected by each update in the batch
/**
* Execute a batch using the supplied SQL statement with the batch of supplied arguments.
* @param sql the SQL statement to execute
* @param batchArgs the List of Object arrays containing the batch of arguments for the query
* @return an array containing the numbers of rows affected by each update in the batch
*/
int[] batchUpdate(String sql, List<Object[]> batchArgs) throws DataAccessException;
Execute a batch using the supplied SQL statement with the batch of supplied arguments.
Params: - sql – the SQL statement to execute.
- batchArgs – the List of Object arrays containing the batch of arguments for the query
- argTypes – the SQL types of the arguments (constants from
java.sql.Types
)
Returns: an array containing the numbers of rows affected by each update in the batch
/**
* Execute a batch using the supplied SQL statement with the batch of supplied arguments.
* @param sql the SQL statement to execute.
* @param batchArgs the List of Object arrays containing the batch of arguments for the query
* @param argTypes the SQL types of the arguments
* (constants from {@code java.sql.Types})
* @return an array containing the numbers of rows affected by each update in the batch
*/
int[] batchUpdate(String sql, List<Object[]> batchArgs, int[] argTypes) throws DataAccessException;
Execute multiple batches using the supplied SQL statement with the collect of supplied arguments.
The arguments' values will be set using the ParameterizedPreparedStatementSetter.
Each batch should be of size indicated in 'batchSize'.
Params: - sql – the SQL statement to execute.
- batchArgs – the List of Object arrays containing the batch of arguments for the query
- batchSize – batch size
- pss – the ParameterizedPreparedStatementSetter to use
Returns: an array containing for each batch another array containing the numbers of rows affected
by each update in the batch Since: 3.1
/**
* Execute multiple batches using the supplied SQL statement with the collect of supplied arguments.
* The arguments' values will be set using the ParameterizedPreparedStatementSetter.
* Each batch should be of size indicated in 'batchSize'.
* @param sql the SQL statement to execute.
* @param batchArgs the List of Object arrays containing the batch of arguments for the query
* @param batchSize batch size
* @param pss the ParameterizedPreparedStatementSetter to use
* @return an array containing for each batch another array containing the numbers of rows affected
* by each update in the batch
* @since 3.1
*/
<T> int[][] batchUpdate(String sql, Collection<T> batchArgs, int batchSize,
ParameterizedPreparedStatementSetter<T> pss) throws DataAccessException;
//-------------------------------------------------------------------------
// Methods dealing with callable statements
//-------------------------------------------------------------------------
Execute a JDBC data access operation, implemented as callback action
working on a JDBC CallableStatement. This allows for implementing arbitrary
data access operations on a single Statement, within Spring's managed
JDBC environment: that is, participating in Spring-managed transactions
and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
The callback action can return a result object, for example a
domain object or a collection of domain objects.
Params: - csc – object that can create a CallableStatement given a Connection
- action – callback object that specifies the action
Throws: - DataAccessException – if there is any problem
Returns: a result object returned by the action, or null
/**
* Execute a JDBC data access operation, implemented as callback action
* working on a JDBC CallableStatement. This allows for implementing arbitrary
* data access operations on a single Statement, within Spring's managed
* JDBC environment: that is, participating in Spring-managed transactions
* and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
* <p>The callback action can return a result object, for example a
* domain object or a collection of domain objects.
* @param csc object that can create a CallableStatement given a Connection
* @param action callback object that specifies the action
* @return a result object returned by the action, or {@code null}
* @throws DataAccessException if there is any problem
*/
@Nullable
<T> T execute(CallableStatementCreator csc, CallableStatementCallback<T> action) throws DataAccessException;
Execute a JDBC data access operation, implemented as callback action
working on a JDBC CallableStatement. This allows for implementing arbitrary
data access operations on a single Statement, within Spring's managed
JDBC environment: that is, participating in Spring-managed transactions
and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
The callback action can return a result object, for example a
domain object or a collection of domain objects.
Params: - callString – the SQL call string to execute
- action – callback object that specifies the action
Throws: - DataAccessException – if there is any problem
Returns: a result object returned by the action, or null
/**
* Execute a JDBC data access operation, implemented as callback action
* working on a JDBC CallableStatement. This allows for implementing arbitrary
* data access operations on a single Statement, within Spring's managed
* JDBC environment: that is, participating in Spring-managed transactions
* and converting JDBC SQLExceptions into Spring's DataAccessException hierarchy.
* <p>The callback action can return a result object, for example a
* domain object or a collection of domain objects.
* @param callString the SQL call string to execute
* @param action callback object that specifies the action
* @return a result object returned by the action, or {@code null}
* @throws DataAccessException if there is any problem
*/
@Nullable
<T> T execute(String callString, CallableStatementCallback<T> action) throws DataAccessException;
Execute a SQL call using a CallableStatementCreator to provide SQL and any
required parameters.
Params: - csc – object that provides SQL and any necessary parameters
- declaredParameters – list of declared SqlParameter objects
Throws: - DataAccessException – if there is any problem issuing the update
Returns: a Map of extracted out parameters
/**
* Execute a SQL call using a CallableStatementCreator to provide SQL and any
* required parameters.
* @param csc object that provides SQL and any necessary parameters
* @param declaredParameters list of declared SqlParameter objects
* @return a Map of extracted out parameters
* @throws DataAccessException if there is any problem issuing the update
*/
Map<String, Object> call(CallableStatementCreator csc, List<SqlParameter> declaredParameters)
throws DataAccessException;
}