|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.springframework.jdbc.support.JdbcAccessor
org.springframework.jdbc.core.JdbcTemplate
This is the central class in the JDBC core package. It simplifies the use of JDBC and helps to avoid common errors. It executes core JDBC workflow, leaving application code to provide SQL and extract results. This class executes SQL queries or updates, initiating iteration over ResultSets and catching JDBC exceptions and translating them to the generic, more informative exception hierarchy defined in the org.springframework.dao package.
Code using this class need only implement callback interfaces, giving them a clearly defined contract. The PreparedStatementCreator callback interface creates a prepared statement given a Connection provided by this class, providing SQL and any necessary parameters. The RowCallbackHandler interface extracts values from each row of a ResultSet.
Can be used within a service implementation via direct instantiation with a DataSource reference, or get prepared in an application context and given to services as bean reference. Note: The DataSource should always be configured as a bean in the application context, in the first case given to the service directly, in the second case to the prepared template.
The motivation and design of this class is discussed in detail in Expert One-On-One J2EE Design and Development by Rod Johnson (Wrox, 2002).
Because this class is parameterizable by the callback interfaces and the SQLExceptionTranslator interface, it isn't necessary to subclass it. All SQL issued by this class is logged.
org.springframework.dao
,
org.springframework.jdbc.datasource
,
org.springframework.jdbc.object
Nested Class Summary | |
protected static class |
JdbcTemplate.ListResultSetExtractor
ResultSetExtractor implementation that returns an ArrayList of HashMaps. |
protected static class |
JdbcTemplate.ObjectResultSetExtractor
ResultSetExtractor implementation that returns single result object. |
protected static class |
JdbcTemplate.RowCallbackHandlerResultSetExtractor
Adapter to enable use of a RowCallbackHandler inside a ResultSetExtractor. |
protected static class |
JdbcTemplate.SimpleCallableStatementCreator
Simple adapter for CallableStatementCreator, allowing to use a plain SQL statement. |
protected static class |
JdbcTemplate.SimplePreparedStatementCreator
Simple adapter for PreparedStatementCreator, allowing to use a plain SQL statement. |
Field Summary | |
protected org.apache.commons.logging.Log |
logger
|
Constructor Summary | |
JdbcTemplate()
Construct a new JdbcTemplate for bean usage. |
|
JdbcTemplate(javax.sql.DataSource dataSource)
Construct a new JdbcTemplate, given a DataSource to obtain connections from. |
Method Summary | |
int[] |
batchUpdate(java.lang.String sql,
BatchPreparedStatementSetter pss)
Issue multiple updates on a single PreparedStatement, using JDBC 2.0 batch updates and a BatchPreparedStatementSetter to set values. |
java.util.Map |
call(CallableStatementCreator csc,
java.util.List declaredParameters)
Execute a SQL call using a CallableStatementCreator to provide SQL and any required parameters. |
java.lang.Object |
execute(CallableStatementCreator csc,
CallableStatementCallback action)
Execute the action specified by the given action object within a JDBC CallableStatement. |
java.lang.Object |
execute(PreparedStatementCreator psc,
PreparedStatementCallback action)
Execute the action specified by the given action object within a JDBC PreparedStatement. |
java.lang.Object |
execute(StatementCallback action)
Execute the action specified by the given action object within a JDBC Statement. |
void |
execute(java.lang.String sql)
Issue a single SQL execute, typically a DDL statement. |
java.lang.Object |
execute(java.lang.String callString,
CallableStatementCallback action)
Execute the action specified by the given action object within a JDBC CallableStatement. |
java.lang.Object |
execute(java.lang.String sql,
PreparedStatementCallback action)
Execute the action specified by the given action object within a JDBC PreparedStatement. |
protected java.util.Map |
extractOutputParameters(java.sql.CallableStatement cs,
java.util.List parameters)
Extract output parameters from the completed stored procedure. |
protected java.util.Map |
extractReturnedResultSets(java.sql.CallableStatement cs,
java.util.List parameters)
Extract returned resultsets from the completed stored procedure. |
boolean |
getIgnoreWarnings()
Return whether or not we ignore SQLWarnings. |
NativeJdbcExtractor |
getNativeJdbcExtractor()
Return the current NativeJdbcExtractor implementation. |
protected java.lang.String |
getSql(java.lang.Object sqlProvider)
Determine SQL from potential provider object. |
protected java.lang.Object |
query(PreparedStatementCreator psc,
PreparedStatementSetter pss,
ResultSetExtractor rse)
Query using a prepared statement, allowing for a PreparedStatementCreator and a PreparedStatementSetter. |
java.lang.Object |
query(PreparedStatementCreator psc,
ResultSetExtractor rse)
Query using a prepared statement. |
java.util.List |
query(PreparedStatementCreator psc,
RowCallbackHandler rch)
Query using a prepared statement, reading the ResultSet on a per-row basis with a RowCallbackHandler (potentially implementing the ResultReader sub-interface that provides a result List). |
java.util.List |
query(java.lang.String sql,
java.lang.Object[] args,
int[] argTypes,
RowCallbackHandler rch)
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 (potentially implementing the ResultReader sub-interface that provides a result List). |
java.util.List |
query(java.lang.String sql,
java.lang.Object[] args,
RowCallbackHandler rch)
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 (potentially implementing the ResultReader sub-interface that provides a result List). |
java.lang.Object |
query(java.lang.String sql,
PreparedStatementSetter pss,
ResultSetExtractor rse)
Query using a prepared statement, reading the ResultSet with a ResultSetExtractor. |
java.util.List |
query(java.lang.String sql,
PreparedStatementSetter pss,
RowCallbackHandler rch)
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 (potentially implementing the ResultReader sub-interface that provides a result List). |
java.lang.Object |
query(java.lang.String sql,
ResultSetExtractor rse)
Execute a query given static SQL, reading the ResultSet with a ResultSetExtractor. |
java.util.List |
query(java.lang.String sql,
RowCallbackHandler rch)
Execute a query given static SQL, reading the ResultSet on a per-row basis with a RowCallbackHandler (potentially implementing the ResultReader sub-interface that provides a result List). |
int |
queryForInt(java.lang.String sql)
Execute a query that results in an int value, given static SQL. |
int |
queryForInt(java.lang.String sql,
java.lang.Object[] args)
Query given SQL to create a prepared statement from SQL and a list of arguments to bind to the query, resulting in an int value. |
java.util.List |
queryForList(java.lang.String sql)
Execute a query for a result list, given static SQL. |
java.util.List |
queryForList(java.lang.String sql,
java.lang.Object[] args)
Query given SQL to create a prepared statement from SQL and a list of arguments to bind to the query, expecting a result list. |
long |
queryForLong(java.lang.String sql)
Execute a query that results in a long value, given static SQL. |
long |
queryForLong(java.lang.String sql,
java.lang.Object[] args)
Query given SQL to create a prepared statement from SQL and a list of arguments to bind to the query, resulting in a long value. |
java.lang.Object |
queryForObject(java.lang.String sql,
java.lang.Class requiredType)
Execute a query for a result object, given static SQL. |
java.lang.Object |
queryForObject(java.lang.String sql,
java.lang.Object[] args,
java.lang.Class requiredType)
Query given SQL to create a prepared statement from SQL and a list of arguments to bind to the query, expecting a result object. |
void |
setIgnoreWarnings(boolean ignoreWarnings)
Set whether or not we want to ignore SQLWarnings. |
void |
setNativeJdbcExtractor(NativeJdbcExtractor extractor)
Set a NativeJdbcExtractor to extract native JDBC objects from wrapped handles. |
protected void |
throwExceptionOnWarningIfNotIgnoringWarnings(java.sql.SQLWarning warning)
Throw an SQLWarningException if we're not ignoring warnings. |
int |
update(PreparedStatementCreator psc)
Issue an update using a PreparedStatementCreator to provide SQL and any required parameters. |
protected int |
update(PreparedStatementCreator psc,
PreparedStatementSetter pss)
|
int |
update(java.lang.String sql)
Issue a single SQL update. |
int |
update(java.lang.String sql,
java.lang.Object[] args)
Issue an update via a prepared statement, binding the given arguments. |
int |
update(java.lang.String sql,
java.lang.Object[] args,
int[] argTypes)
Issue an update via a prepared statement, binding the given arguments. |
int |
update(java.lang.String sql,
PreparedStatementSetter pss)
Issue an update using a PreparedStatementSetter to set bind parameters, with given SQL. |
Methods inherited from class org.springframework.jdbc.support.JdbcAccessor |
afterPropertiesSet, getDataSource, getExceptionTranslator, setDataSource, setExceptionTranslator |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Methods inherited from interface org.springframework.beans.factory.InitializingBean |
afterPropertiesSet |
Field Detail |
protected final org.apache.commons.logging.Log logger
Constructor Detail |
public JdbcTemplate()
JdbcAccessor.setDataSource(javax.sql.DataSource)
public JdbcTemplate(javax.sql.DataSource dataSource)
dataSource
- JDBC DataSource to obtain connections fromMethod Detail |
public void setNativeJdbcExtractor(NativeJdbcExtractor extractor)
public NativeJdbcExtractor getNativeJdbcExtractor()
public void setIgnoreWarnings(boolean ignoreWarnings)
public boolean getIgnoreWarnings()
public java.lang.Object execute(StatementCallback action)
JdbcOperations
execute
in interface JdbcOperations
action
- callback object that specifies the action
public void execute(java.lang.String sql) throws DataAccessException
JdbcOperations
execute
in interface JdbcOperations
sql
- static SQL to execute
DataAccessException
- if there is any problempublic java.lang.Object query(java.lang.String sql, ResultSetExtractor rse) throws DataAccessException
JdbcOperations
Uses a JDBC Statement, not a PreparedStatement. If you want to execute a static query with a PreparedStatement, use the overloaded query method with a null PreparedStatementSetter as a parameter.
query
in interface JdbcOperations
sql
- SQL query to executerse
- object that will extract all rows of results
DataAccessException
- if there is any problem executing the queryJdbcOperations.query(String, PreparedStatementSetter, ResultSetExtractor)
public java.util.List query(java.lang.String sql, RowCallbackHandler rch) throws DataAccessException
JdbcOperations
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 PreparedStatementSetter argument.
query
in interface JdbcOperations
sql
- SQL query to executerch
- object that will extract results
DataAccessException
- if there is any problem executing the queryJdbcOperations.query(String, PreparedStatementSetter, RowCallbackHandler)
public java.util.List queryForList(java.lang.String sql) throws DataAccessException
JdbcOperations
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.
This method is useful for running static SQL with a known outcome. The results will be mapped to an ArrayList (one entry for each row) of HashMaps (one entry for each column using the column name as the key).
queryForList
in interface JdbcOperations
sql
- SQL query to execute
DataAccessException
- if there is any problem executing the queryJdbcOperations.queryForList(String, Object[])
public java.lang.Object queryForObject(java.lang.String sql, java.lang.Class requiredType) throws DataAccessException
JdbcOperations
Uses a JDBC Statement, not a PreparedStatement. If you want to execute a static query with a PreparedStatement, use the overloaded queryForObject 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.
queryForObject
in interface JdbcOperations
sql
- SQL query to executerequiredType
- the type that the result object is expected to match
DataAccessException
- if there is any problem executing the queryJdbcOperations.queryForObject(String, Object[], Class)
public long queryForLong(java.lang.String sql) throws DataAccessException
JdbcOperations
Uses a JDBC Statement, not a PreparedStatement. If you want to execute a static query with a PreparedStatement, use the overloaded queryForLong 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 that results in a long value.
queryForLong
in interface JdbcOperations
sql
- SQL query to execute
DataAccessException
- if there is any problem executing the queryJdbcOperations.queryForLong(String, Object[])
public int queryForInt(java.lang.String sql) throws DataAccessException
JdbcOperations
Uses a JDBC Statement, not a PreparedStatement. If you want to execute a static query with a PreparedStatement, use the overloaded queryForInt 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 that results in an int value.
queryForInt
in interface JdbcOperations
sql
- SQL query to execute
DataAccessException
- if there is any problem executing the queryJdbcOperations.queryForInt(String, Object[])
public int update(java.lang.String sql) throws DataAccessException
JdbcOperations
update
in interface JdbcOperations
sql
- static SQL to execute
DataAccessException
- if there is any problem.public java.lang.Object execute(PreparedStatementCreator psc, PreparedStatementCallback action)
JdbcOperations
execute
in interface JdbcOperations
psc
- object that can create a PreparedStatement given a Connectionaction
- callback object that specifies the action
public java.lang.Object execute(java.lang.String sql, PreparedStatementCallback action)
JdbcOperations
execute
in interface JdbcOperations
sql
- SQL to executeaction
- callback object that specifies the action
protected java.lang.Object query(PreparedStatementCreator psc, PreparedStatementSetter pss, ResultSetExtractor rse) throws DataAccessException
psc
- Callback handler that can create a PreparedStatement given a
Connectionpss
- 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.rse
- object that will extract results.
DataAccessException
- if there is any problempublic java.lang.Object query(PreparedStatementCreator psc, ResultSetExtractor rse)
JdbcOperations
query
in interface JdbcOperations
psc
- object that can create a PreparedStatement given a Connectionrse
- object that will extract results
public java.lang.Object query(java.lang.String sql, PreparedStatementSetter pss, ResultSetExtractor rse) throws DataAccessException
JdbcOperations
query
in interface JdbcOperations
sql
- SQL to executepss
- 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.
DataAccessException
- if there is any problempublic java.util.List query(PreparedStatementCreator psc, RowCallbackHandler rch) throws DataAccessException
JdbcOperations
query
in interface JdbcOperations
psc
- object that can create a PreparedStatement given a Connectionrch
- object that will extract results,
one row at a time
DataAccessException
- if there is any problempublic java.util.List query(java.lang.String sql, PreparedStatementSetter pss, RowCallbackHandler rch) throws DataAccessException
JdbcOperations
query
in interface JdbcOperations
sql
- SQL to executepss
- 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
DataAccessException
- if the query failspublic java.util.List query(java.lang.String sql, java.lang.Object[] args, int[] argTypes, RowCallbackHandler rch) throws DataAccessException
JdbcOperations
query
in interface JdbcOperations
sql
- SQL to executeargs
- arguments to bind to the queryargTypes
- SQL types of the arguments (constants from java.sql.Types)rch
- object that will extract results
DataAccessException
- if the query failsTypes
public java.util.List query(java.lang.String sql, java.lang.Object[] args, RowCallbackHandler rch) throws DataAccessException
JdbcOperations
query
in interface JdbcOperations
sql
- SQL to executeargs
- arguments to bind to the query
(leaving it to the PreparedStatement to guess the respective SQL type)rch
- object that will extract results
DataAccessException
- if the query failspublic java.util.List queryForList(java.lang.String sql, java.lang.Object[] args) throws DataAccessException
JdbcOperations
This method is useful for running static SQL with a known outcome. The results will be mapped to an ArrayList (one entry for each row) of HashMaps (one entry for each column using the column name as the key).
queryForList
in interface JdbcOperations
sql
- SQL to executeargs
- arguments to bind to the query
(leaving it to the PreparedStatement to guess the respective SQL type)
DataAccessException
- if the query failsJdbcOperations.queryForList(String)
public java.lang.Object queryForObject(java.lang.String sql, java.lang.Object[] args, java.lang.Class requiredType) throws DataAccessException
JdbcOperations
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.
queryForObject
in interface JdbcOperations
sql
- SQL to executeargs
- arguments to bind to the query
(leaving it to the PreparedStatement to guess the respective SQL type)requiredType
- the type that the result object is expected to match
DataAccessException
- if the query failsJdbcOperations.queryForObject(String, Class)
public long queryForLong(java.lang.String sql, java.lang.Object[] args) throws DataAccessException
JdbcOperations
This method is useful for running static SQL with a known outcome. The query is expected to be a single row/single column query that results in a long value.
queryForLong
in interface JdbcOperations
sql
- SQL to executeargs
- arguments to bind to the query
(leaving it to the PreparedStatement to guess the respective SQL type)
DataAccessException
- if the query failsJdbcOperations.queryForLong(String)
public int queryForInt(java.lang.String sql, java.lang.Object[] args) throws DataAccessException
JdbcOperations
This method is useful for running static SQL with a known outcome. The query is expected to be a single row/single column query that results in an int value.
queryForInt
in interface JdbcOperations
sql
- SQL to executeargs
- arguments to bind to the query
(leaving it to the PreparedStatement to guess the respective SQL type)
DataAccessException
- if the query failsJdbcOperations.queryForInt(String)
protected int update(PreparedStatementCreator psc, PreparedStatementSetter pss) throws DataAccessException
DataAccessException
public int update(PreparedStatementCreator psc) throws DataAccessException
JdbcOperations
update
in interface JdbcOperations
psc
- object that provides SQL and any necessary parameters
DataAccessException
- if there is any problem issuing the updatepublic int update(java.lang.String sql, PreparedStatementSetter pss) throws DataAccessException
JdbcOperations
update
in interface JdbcOperations
sql
- SQL, containing bind parameterspss
- helper that sets bind parameters. If this is null
we run an update with static SQL.
DataAccessException
- if there is any problem issuing the updatepublic int update(java.lang.String sql, java.lang.Object[] args, int[] argTypes) throws DataAccessException
JdbcOperations
update
in interface JdbcOperations
sql
- SQL, containing bind parametersargs
- arguments to bind to the queryargTypes
- SQL types of the arguments (constants from java.sql.Types)
DataAccessException
- if there is any problem issuing the updatepublic int update(java.lang.String sql, java.lang.Object[] args) throws DataAccessException
JdbcOperations
update
in interface JdbcOperations
sql
- SQL, containing bind parametersargs
- arguments to bind to the query
(leaving it to the PreparedStatement to guess the respective SQL type)
DataAccessException
- if there is any problem issuing the updatepublic int[] batchUpdate(java.lang.String sql, BatchPreparedStatementSetter pss) throws DataAccessException
JdbcOperations
Will fall back to separate updates on a single PreparedStatement if the JDBC driver does not support batch updates.
batchUpdate
in interface JdbcOperations
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
DataAccessException
- if there is any problem issuing the updatepublic java.lang.Object execute(CallableStatementCreator csc, CallableStatementCallback action)
JdbcOperations
execute
in interface JdbcOperations
csc
- object that can create a CallableStatement given a Connectionaction
- callback object that specifies the action
public java.lang.Object execute(java.lang.String callString, CallableStatementCallback action)
JdbcOperations
execute
in interface JdbcOperations
callString
- the SQL call string to executeaction
- callback object that specifies the action
public java.util.Map call(CallableStatementCreator csc, java.util.List declaredParameters) throws DataAccessException
JdbcOperations
call
in interface JdbcOperations
csc
- object that provides SQL and any necessary parameters
DataAccessException
- if there is any problem issuing the updateprotected java.util.Map extractOutputParameters(java.sql.CallableStatement cs, java.util.List parameters) throws java.sql.SQLException
cs
- JDBC wrapper for the stored procedureparameters
- parameter list for the stored procedure
java.sql.SQLException
protected java.util.Map extractReturnedResultSets(java.sql.CallableStatement cs, java.util.List parameters) throws java.sql.SQLException
cs
- JDBC wrapper for the stored procedureparameters
- Parameter list for the stored procedure
java.sql.SQLException
protected void throwExceptionOnWarningIfNotIgnoringWarnings(java.sql.SQLWarning warning) throws SQLWarningException
warning
- warning from current statement. May be null,
in which case this method does nothing.
SQLWarningException
protected java.lang.String getSql(java.lang.Object sqlProvider)
sqlProvider
- object that's potentially a SqlProvider
SqlProvider
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |