org.springframework.orm.ibatis
Class SqlMapClientTemplate

java.lang.Object
  extended by org.springframework.jdbc.support.JdbcAccessor
      extended by org.springframework.orm.ibatis.SqlMapClientTemplate
All Implemented Interfaces:
InitializingBean, SqlMapClientOperations

public class SqlMapClientTemplate
extends JdbcAccessor
implements SqlMapClientOperations

Helper class that simplifies data access via the SqlMapClient API of iBATIS SQL Maps, and converts checked SQLExceptions into unchecked DataAccessExceptions, following the org.springframework.dao exception hierarchy. Uses the same SQLExceptionTranslator mechanism as JdbcTemplate.

The main method of this class executes a callback that implements a data access action. Furthermore, this class provides numerous convenience methods that mirror SqlMapExecutor's execution methods. See the SqlMapExecutor javadocs for details on those methods.

It is generally recommended to use the convenience methods on this template for plain query/insert/update/delete operations. However, for more complex operations like batch updates, a custom SqlMapClientCallback must be implemented, usually as anonymous inner class. For example:

 getSqlMapClientTemplate().execute(new SqlMapClientCallback() {
         public Object doInSqlMapClient(SqlMapExecutor executor) throws SQLException {
                 executor.startBatch();
                 executor.update("insertSomething", "myParamValue");
                 executor.update("insertSomethingElse", "myOtherParamValue");
                 executor.executeBatch();
                 return null;
         }
 });
The template needs a SqlMapClient to work on, passed in via the "sqlMapClient" property. Can additionally be configured with a DataSource for fetching Connections, although this is not necessary if a DataSource is specified for the SqlMapClient itself.

NOTE: The SqlMapClient/SqlMapSession API is the API of iBATIS SQL Maps 2. With SQL Maps 1.x, the SqlMap/MappedStatement API has to be used.

Since:
24.02.2004
Author:
Juergen Hoeller
See Also:
execute(org.springframework.orm.ibatis.SqlMapClientCallback), setSqlMapClient(com.ibatis.sqlmap.client.SqlMapClient), JdbcAccessor.setDataSource(javax.sql.DataSource), JdbcAccessor.setExceptionTranslator(org.springframework.jdbc.support.SQLExceptionTranslator), SqlMapClientFactoryBean.setDataSource(javax.sql.DataSource), SqlMapTransactionManager.getDataSource(), SqlMapSession, SqlMapExecutor

Field Summary
 
Fields inherited from class org.springframework.jdbc.support.JdbcAccessor
logger
 
Constructor Summary
SqlMapClientTemplate()
          Create a new SqlMapClientTemplate.
SqlMapClientTemplate(DataSource dataSource, com.ibatis.sqlmap.client.SqlMapClient sqlMapClient)
          Create a new SqlMapTemplate.
SqlMapClientTemplate(com.ibatis.sqlmap.client.SqlMapClient sqlMapClient)
          Create a new SqlMapTemplate.
 
Method Summary
 void afterPropertiesSet()
          Eagerly initialize the exception translator, creating a default one for the specified DataSource if none set.
 int delete(String statementName, Object parameterObject)
           
 void delete(String statementName, Object parameterObject, int requiredRowsAffected)
          Convenience method provided by Spring: execute a delete operation with an automatic check that the delete affected the given required number of rows.
 Object execute(SqlMapClientCallback action)
          Execute the given data access action on a SqlMapSession.
 List executeWithListResult(SqlMapClientCallback action)
          Execute the given data access action on a SqlMapSession, expecting a List result.
 Map executeWithMapResult(SqlMapClientCallback action)
          Execute the given data access action on a SqlMapSession, expecting a Map result.
 DataSource getDataSource()
          If no DataSource specified, use SqlMapClient's DataSource.
 com.ibatis.sqlmap.client.SqlMapClient getSqlMapClient()
          Return the iBATIS Database Layer SqlMapClient that this template works with.
 Object insert(String statementName, Object parameterObject)
           
 List queryForList(String statementName, Object parameterObject)
           
 List queryForList(String statementName, Object parameterObject, int skipResults, int maxResults)
           
 Map queryForMap(String statementName, Object parameterObject, String keyProperty)
           
 Map queryForMap(String statementName, Object parameterObject, String keyProperty, String valueProperty)
           
 Object queryForObject(String statementName, Object parameterObject)
           
 Object queryForObject(String statementName, Object parameterObject, Object resultObject)
           
 com.ibatis.common.util.PaginatedList queryForPaginatedList(String statementName, Object parameterObject, int pageSize)
           
 void queryWithRowHandler(String statementName, Object parameterObject, com.ibatis.sqlmap.client.event.RowHandler rowHandler)
           
 void setSqlMapClient(com.ibatis.sqlmap.client.SqlMapClient sqlMapClient)
          Set the iBATIS Database Layer SqlMapClient that defines the mapped statements.
 int update(String statementName, Object parameterObject)
           
 void update(String statementName, Object parameterObject, int requiredRowsAffected)
          Convenience method provided by Spring: execute an update operation with an automatic check that the update affected the given required number of rows.
 
Methods inherited from class org.springframework.jdbc.support.JdbcAccessor
getExceptionTranslator, isLazyInit, setDatabaseProductName, setDataSource, setExceptionTranslator, setLazyInit
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SqlMapClientTemplate

public SqlMapClientTemplate()
Create a new SqlMapClientTemplate.


SqlMapClientTemplate

public SqlMapClientTemplate(com.ibatis.sqlmap.client.SqlMapClient sqlMapClient)
Create a new SqlMapTemplate.

Parameters:
sqlMapClient - iBATIS SqlMapClient that defines the mapped statements

SqlMapClientTemplate

public SqlMapClientTemplate(DataSource dataSource,
                            com.ibatis.sqlmap.client.SqlMapClient sqlMapClient)
Create a new SqlMapTemplate.

Parameters:
dataSource - JDBC DataSource to obtain connections from
sqlMapClient - iBATIS SqlMapClient that defines the mapped statements
Method Detail

setSqlMapClient

public void setSqlMapClient(com.ibatis.sqlmap.client.SqlMapClient sqlMapClient)
Set the iBATIS Database Layer SqlMapClient that defines the mapped statements.


getSqlMapClient

public com.ibatis.sqlmap.client.SqlMapClient getSqlMapClient()
Return the iBATIS Database Layer SqlMapClient that this template works with.


getDataSource

public DataSource getDataSource()
If no DataSource specified, use SqlMapClient's DataSource.

Overrides:
getDataSource in class JdbcAccessor
See Also:
SqlMapTransactionManager.getDataSource()

afterPropertiesSet

public void afterPropertiesSet()
Description copied from class: JdbcAccessor
Eagerly initialize the exception translator, creating a default one for the specified DataSource if none set.

Specified by:
afterPropertiesSet in interface InitializingBean
Overrides:
afterPropertiesSet in class JdbcAccessor

execute

public Object execute(SqlMapClientCallback action)
               throws DataAccessException
Execute the given data access action on a SqlMapSession.

Parameters:
action - callback object that specifies the data access action
Returns:
a result object returned by the action, or null
Throws:
DataAccessException - in case of SQL Maps errors

executeWithListResult

public List executeWithListResult(SqlMapClientCallback action)
                           throws DataAccessException
Execute the given data access action on a SqlMapSession, expecting a List result.

Parameters:
action - callback object that specifies the data access action
Returns:
the List result
Throws:
DataAccessException - in case of SQL Maps errors

executeWithMapResult

public Map executeWithMapResult(SqlMapClientCallback action)
                         throws DataAccessException
Execute the given data access action on a SqlMapSession, expecting a Map result.

Parameters:
action - callback object that specifies the data access action
Returns:
the Map result
Throws:
DataAccessException - in case of SQL Maps errors

queryForObject

public Object queryForObject(String statementName,
                             Object parameterObject)
                      throws DataAccessException
Specified by:
queryForObject in interface SqlMapClientOperations
Throws:
DataAccessException - in case of errors
See Also:
SqlMapExecutor.queryForObject(String, Object)

queryForObject

public Object queryForObject(String statementName,
                             Object parameterObject,
                             Object resultObject)
                      throws DataAccessException
Specified by:
queryForObject in interface SqlMapClientOperations
Throws:
DataAccessException - in case of errors
See Also:
SqlMapExecutor.queryForObject(String, Object, Object)

queryForList

public List queryForList(String statementName,
                         Object parameterObject)
                  throws DataAccessException
Specified by:
queryForList in interface SqlMapClientOperations
Throws:
DataAccessException - in case of errors
See Also:
SqlMapExecutor.queryForList(String, Object)

queryForList

public List queryForList(String statementName,
                         Object parameterObject,
                         int skipResults,
                         int maxResults)
                  throws DataAccessException
Specified by:
queryForList in interface SqlMapClientOperations
Throws:
DataAccessException - in case of errors
See Also:
SqlMapExecutor.queryForList(String, Object, int, int)

queryWithRowHandler

public void queryWithRowHandler(String statementName,
                                Object parameterObject,
                                com.ibatis.sqlmap.client.event.RowHandler rowHandler)
                         throws DataAccessException
Specified by:
queryWithRowHandler in interface SqlMapClientOperations
Throws:
DataAccessException - in case of errors
See Also:
SqlMapExecutor.queryWithRowHandler(String, Object, RowHandler)

queryForPaginatedList

public com.ibatis.common.util.PaginatedList queryForPaginatedList(String statementName,
                                                                  Object parameterObject,
                                                                  int pageSize)
                                                           throws DataAccessException
Specified by:
queryForPaginatedList in interface SqlMapClientOperations
Throws:
DataAccessException - in case of errors
See Also:
SqlMapExecutor.queryForPaginatedList(String, Object, int)

queryForMap

public Map queryForMap(String statementName,
                       Object parameterObject,
                       String keyProperty)
                throws DataAccessException
Specified by:
queryForMap in interface SqlMapClientOperations
Throws:
DataAccessException - in case of errors
See Also:
SqlMapExecutor.queryForMap(String, Object, String)

queryForMap

public Map queryForMap(String statementName,
                       Object parameterObject,
                       String keyProperty,
                       String valueProperty)
                throws DataAccessException
Specified by:
queryForMap in interface SqlMapClientOperations
Throws:
DataAccessException - in case of errors
See Also:
SqlMapExecutor.queryForMap(String, Object, String, String)

insert

public Object insert(String statementName,
                     Object parameterObject)
              throws DataAccessException
Specified by:
insert in interface SqlMapClientOperations
Throws:
DataAccessException - in case of errors
See Also:
SqlMapExecutor.insert(String, Object)

update

public int update(String statementName,
                  Object parameterObject)
           throws DataAccessException
Specified by:
update in interface SqlMapClientOperations
Throws:
DataAccessException - in case of errors
See Also:
SqlMapExecutor.update(String, Object)

delete

public int delete(String statementName,
                  Object parameterObject)
           throws DataAccessException
Specified by:
delete in interface SqlMapClientOperations
Throws:
DataAccessException - in case of errors
See Also:
SqlMapExecutor.delete(String, Object)

update

public void update(String statementName,
                   Object parameterObject,
                   int requiredRowsAffected)
            throws DataAccessException
Description copied from interface: SqlMapClientOperations
Convenience method provided by Spring: execute an update operation with an automatic check that the update affected the given required number of rows.

Specified by:
update in interface SqlMapClientOperations
Parameters:
statementName - the name of the mapped statement
parameterObject - the parameter object
requiredRowsAffected - the number of rows that the update is required to affect
Throws:
DataAccessException - in case of errors

delete

public void delete(String statementName,
                   Object parameterObject,
                   int requiredRowsAffected)
            throws DataAccessException
Description copied from interface: SqlMapClientOperations
Convenience method provided by Spring: execute a delete operation with an automatic check that the delete affected the given required number of rows.

Specified by:
delete in interface SqlMapClientOperations
Parameters:
statementName - the name of the mapped statement
parameterObject - the parameter object
requiredRowsAffected - the number of rows that the delete is required to affect
Throws:
DataAccessException - in case of errors


Copyright (c) 2002-2006 The Spring Framework Project.