com.ibatis.sqlmap.client

Interface SqlMapClient

All Superinterfaces:

EntityManager, SqlMapExecutor, SqlMapExecutor2, SqlMapTransactionManager

All Known Subinterfaces:

SqlMapClient

public interface SqlMapClient
extends SqlMapExecutor, SqlMapTransactionManager

A thread safe client for working with your SQL Maps (Start Here). This interface inherits transaction control and execution methods from the SqlMapTransactionManager and SqlMapExecutor interfaces.

The SqlMapClient is the central class for working with SQL Maps. This class will allow you to run mapped statements (select, insert, update, delete etc.), and also demarcate transactions and work with batches. Once you have an SqlMapClient instance, everything you need to work with SQL Maps is easily available.

The SqlMapClient can either be worked with directly as a multi-threaded client (internal session management), or you can get a single threaded session and work with that. There may be a slight performance increase if you explicitly get a session (using the openSession() method), as it saves the SqlMapClient from having to manage threads contexts. But for most cases it won't make much of a difference, so choose whichever paradigm suits your needs or preferences.

An SqlMapClient instance can be safely made static or applied as a Singleton. Generally it's a good idea to make a simple configuration class that will configure the instance (using SqlMapClientBuilder) and provide access to it.

The following example will demonstrate the use of SqlMapClient.

 
 //
 // autocommit simple query --these are just examples...not patterns
 //
 
 Employee emp = (Employee) sqlMap.queryForObject("getEmployee", new Integer(1));
 
 //
 // transaction --these are just examples...not patterns
 //
 
 try {
   sqlMap.startTransaction()
   Employee emp2 = new Employee();
   // ...set emp2 data
   Integer generatedKey = (Integer) sqlMap.insert ("insertEmployee", emp2);
   emp2.setFavouriteColour ("green");
   sqlMap.update("updateEmployee", emp2);
   sqlMap.commitTransaction();
 } finally {
   sqlMap.endTransaction();
 }
 
 //
 // session --these are just examples...not patterns
 //
 
 try {
   SqlMapSession session = sqlMap.openSession()
   session.startTransaction()
   Employee emp2 = new Employee();
   // ...set emp2 data
   Integer generatedKey = (Integer) session.insert ("insertEmployee", emp2);
   emp2.setFavouriteColour ("green");
   session.update("updateEmployee", emp2);
   session.commitTransaction();
 } finally {
   try {
     session.endTransaction();
   } finally {
     session.close();
   }
   // Generally your session scope would be in a wider context and therefore the
   // ugly nested finally block above would not be there.  Realize that sessions
   // MUST be closed if explicitly opened (via openSession()).
 }
 
 //
 // batch --these are just examples...not patterns
 //
 
 try {
   sqlMap.startTransaction()
   List list = (Employee) sqlMap.queryForList("getFiredEmployees", null);
   sqlMap.startBatch ();
   for (int i=0, n=list.size(); i < n; i++) {
     sqlMap.delete ("deleteEmployee", list.get(i));
   }
   sqlMap.executeBatch();
   sqlMap.commitTransaction();
 } finally {
   sqlMap.endTransaction();
 }
 

See Also:

SqlMapSession, SqlMapExecutor

Method Summary

Modifier and Type	Method and Description
void	flushDataCache() Flushes all data caches.
void	flushDataCache(String cacheId) Flushes the data cache that matches the cache model ID provided.
void	flushEntityCache(Class<?> entityClass) Flushes the data cache of the entity class.
SqlMapSession	openSession() Returns a single threaded SqlMapSession implementation for use by one user.
SqlMapSession	openSession(Connection conn) Returns a single threaded SqlMapSession implementation for use by one user.

Methods inherited from interface com.ibatis.sqlmap.client.SqlMapExecutor

delete, delete, executeBatch, executeBatchDetailed, insert, insert, queryForList, queryForList, queryForList, queryForList, queryForMap, queryForMap, queryForMap, queryForObject, queryForObject, queryForObject, queryForPage, queryForPage, queryWithRowHandler, queryWithRowHandler, startBatch, startBatch, update, update

Methods inherited from interface org.ibatis.client.SqlMapExecutor2

deleteArgs, insertArgs, queryForFirst, queryForFirst, queryForFirstArgs, queryForListArgs, queryForListArgs, queryForMapArgs, queryForMapArgs, queryForMapArgs, queryForObjectArgs, queryForPageArgs, queryForResultSet, queryForResultSet, queryForResultSetArgs, queryWithRowHandlerArgs, updateArgs

Methods inherited from interface org.ibatis.persist.EntityManager

deleteEntity, executeDelete, executeQuery, executeQuery, executeQueryObject, executeQueryPage, executeUpdate, findEntity, getCriteriaBuilder, initEntityClass, insertEntity, updateEntity

Methods inherited from interface com.ibatis.sqlmap.client.SqlMapTransactionManager

commitTransaction, endTransaction, getCurrentConnection, getDataSource, setUserConnection, startTransaction, startTransaction

Method Detail

openSession

SqlMapSession openSession()

Returns a single threaded SqlMapSession implementation for use by one user. Remember though, that SqlMapClient itself is a thread safe SqlMapSession implementation, so you can also just work directly with it. If you do get a session explicitly using this method be sure to close it! You can close a session using the sqlMapSession.close() method.

Returns:

An SqlMapSession instance.

openSession

SqlMapSession openSession(Connection conn)

Returns a single threaded SqlMapSession implementation for use by one user. Remember though, that SqlMapClient itself is a thread safe SqlMapSession implementation, so you can also just work directly with it. If you do get a session explicitly using this method be sure to close it! You can close a session using the SqlMapSession.close() method.

This particular implementation takes a user provided connection as a parameter. This connection will be used for executing statements, and therefore overrides any configured datasources. Using this approach allows the developer to easily use an externally supplied connection for executing statements.

Important: Using a user supplied connection basically sidesteps the datasource so you are responsible for appropriately handling your connection lifecycle (i.e. closing). Here's a (very) simple example (throws SQLException):

 try {
     Connection connection = dataSource.getConnection();
     SqlMapSession session = sqlMap.openSession(connection);
     // do work
     connection.commit();
 } catch (SQLException e) {
     try {
         if (connection != null)
             commit.rollback();
     } catch (SQLException ignored) {
         // generally ignored
     }
     throw e; // rethrow the exception
 } finally {
     try {
         if (connection != null)
             connection.close();
     } catch (SQLException ignored) {
         // generally ignored
     }
 }
 

Parameters:

conn - - the connection to use for the session

Returns:

An SqlMapSession instance.

flushDataCache

void flushDataCache()

Flushes all data caches.

flushDataCache

void flushDataCache(String cacheId)

Flushes the data cache that matches the cache model ID provided. cacheId should include the namespace, even when useStatementNamespaces="false".

Parameters:

cacheId - The cache model to flush

flushEntityCache

void flushEntityCache(Class<?> entityClass)

Flushes the data cache of the entity class.

Parameters:

entityClass - The entity class object to flush cache