SQL Map API 力求简洁。它为程序员提供 4 种功能：配置一个 SQL Map，执行 SQL update操作，执行查询语句以取得一个对象，以及执行查询语句以取得一个对象的 List。

• 配置 SQL Map

一旦您创建了 SQL Map XML 定义文件和 SQL Map 配置文件，配置 SQL Map 就是一件 极其简单的事情。SQL Map 使用 XmlSqlMapClientBuilder 来创建。这个类有一个静态方法 叫 buildSqlMap。方法 buildSqlMap 简单地用一个 Reader 对象为参数，读入 sqlMap-config.xml 文件（不必是这个文件名）的内容。

 String resource = “com/ibatis/example/sqlMap-config.xml”;

 Reader reader = Resources.getResourceAsReader (resource);

 SqlMapClient sqlMap = SqlMapClientBuilder.buildSqlMap(reader);

• 事务处理

  缺省情况下 ，调用 SqlMapClient  对象的任 意 executeXxxx() 方法将 缺省地自 动 COMMIT/ROLLBACK。这意味着每次调用 executeXxxx()方法都是一个独立的事务。这确实 很简单，但对于需要在同一个事务中执行多个语句的情况（即只能同时成功或失败），并不 适用。这正是事务处理要关心的事情。

  如果您在使用 Global Transaction（在 SQL Map 配置文件中设置），您可以使用自动提交 并且可以得到在同一事务中执行的效果。但为了提高性能，最好是明确地划分事务的范围， 因为这样做可以减少连接池的通讯流量和数据库连接的初始化。

  SqlMapClient 对象拥有让您定义事务范围的方法。使用下面 SqlMapClient 类的方法，可 以开始、提交和/或回退事务：

   public void startTransaction () throws SQLException 
  　public void commitTransaction () throws SQLException
    public void endTransaction () throws SQLException

  开始一个事务，意味着您从连接池中得到一个连接，打开它并执行查询和更新 SQL 操 作。使用事务处理的例子如下：

   private Reader reader = new Resources.getResourceAsReader( "com/ibatis/example/sqlMapconfig.xml");
  
   private SqlMapClient sqlMap = XmlSqlMapBuilder.buildSqlMap(reader);
  
   public updateItemDescription (String itemId, String newDescription) throws SQLException {
  
   try {
  
   sqlMap.startTransaction ();
  
   Item item = (Item) sqlMap.queryForObject ("getItem", itemId);
  
   item.setDescription (newDescription); sqlMap.update ("updateItem", item); sqlMap.commitTransaction ();
  
   } finally {
  
   sqlMap.endTransaction ();
  
   }
  
   }

  注意！事务不能嵌套。在调用 commit（）或 rollback（）之前，从同     一线程多次调用.startTransaction，将引起抛出例外。换句话说，对于每个 SqlMap 实例，每个线程最多只能打开一个事务。

  注意！SqlMapClient 事务处理使用 Java 的 ThreadLocal 保存事务对象。这意味着在处理 事务时，每个调用 startTransaction（）的线程，将得到一个唯一的 Connection 对象。将一个 Connection  对象返回数据源（或关闭连接）唯一的方法是调用 commitTransaction（）或 rollbackTransaction（）方法。否则，会用光连接池中的连接并导致死锁。

• 自动的事务处理

  虽然极力推荐使用明确划分的事务范围，在简单需求（通常使只读）的情况下，可以使 用简化的语法。如果您没有使用 startTransaction（），commitTransation（）和 rollbackTransaction（）方法来明确地划分事务范围，事务将会自动执行。例如：

   private Reader reader = new Resources.getResourceAsReader
  
   ("com/ibatis/example/sqlMapconfig.xml");
  
   private SqlMapClient sqlMap = XmlSqlMapBuilder.buildSqlMap(reader);
  
   public updateItemDescription (String itemId, String newDescription) throws SQLException {
  
   try {
  
   Item item = (Item) sqlMap.queryForObject ("getItem", itemId);
  
   item.setDescription (“TX1”);
  
   //No transaction demarcated, so transaction will be automatic (implied)
  
   sqlMap.update ("updateItem", item); item.setDescription (newDescription); item.setDescription (“TX2”);
  
   //No transaction demarcated, so transaction will be automatic (implied)
  
   sqlMap.update("updateItem", item);
  
   } catch (SQLException e) {
  
   throw (SQLException) e.fillInStackTrace();
  
   }
  
   }

  注意！使用自动事务处理要非常小心。虽然看起来很有吸引力，但如果有多个数据更新操作要在同一事务中处理时，您会遇到麻烦。在上面的例子中，如果第二个“updateItem”操作失败，第一个“updateItem”操作仍然会执行，description 会更新成“TX1”。

• 全局（分布式）事务

  SQL Map 框架支持全局事务。全局事务也叫分布式事务，它可以允许您在同一事务中 更新多个数据库（或其他符合 JTA 规范的资源），即同时成功或失败。

  * External/Programmatic Global  事务

  您可以选择外部管理或手工编程管理全局事务，或实现一个象 EJB 一样的架构。使用 EJB，您可以通过使用 EJB 的描述文件定义事务范围。要支 持外部管理或手工编程管理全局事务，必须在 SQL Map 配置文件中(参见前面章节的内容) 设定<transactionManager>的 type 属性为 EXTERNAL。使用外部管理的全局事务，SQL Map 事务控制方法变得有的多余，因为事务的开始、提交和回退都由外部的事务管理器来控制。 但是，使用 SqlMapClient 的 startTransaction（），commitTransaction（）或 rollbackTransaction（）来划分事务范围（相对于自动的事务处理），还是对提高性能有帮助。继续使用这些方 法，可以保持编程规范的一致性。另一个好处是，在某些情况下，您可能需要改变关闭资源 的顺序（不幸的是，不同的应用服务器和事务管理器具有不同的规则）。除了这些考虑，要 使用全局事务，不需要改变您的 SQL Map 代码。

  * 受管理的（Managed）全局事务

  SQL Map 框架也可以为您管理全局事务。要支持受管理的全局事务，必须在 SQL Map 配置文件中设定<transactionManager>的 type 属性为 JTA，并设定“UserTransaction”属性为 JNDI 的全名，以使 SqlMapClient 实例能找到 UserTransaction 对象。

  使用全局事务编程，代码没有多大的不同，但有几个小小的地方要注意。例如：

   try {
  
   orderSqlMap.startTransaction(); storeSqlMap.startTransaction(); orderSqlMap.insertOrder(…); orderSqlMap.updateQuantity(…);
  
   storeSqlMap.commitTransaction();
  
   orderSqlMap.commitTransaction();
  
   } finally {
  
   try {
  
   storeSqlMap.endTransaction()
  
   } finally {
  
   orderSqlMap.endTransaction()
  
   }
  
   }

  上面的例子中，假设我们通过两个 SqlMapClient 来使用两个不同的数据库。第一个开始事务的 SqlMapClient（orderSqlMap）同时也开始了一个全局事务。在这之后，所有其他的操作将被看作是这个全局事务的一部分，直到同一个 SqlMapClient（orderSqlMap）调用 commitTransaction（）或 rollbackTransaction（），届时全局事务被提交并完成其他所有的操 作。

  警告！虽然这些看起来很简单，但记住不要滥用全局（分布式）事务，这点很重要。这 样做既有性能方面的考虑，同时也是因为全局事务会让应用服务器和数据库驱动程序的设置 变得更复杂。虽然看起来简单，您可能还是会遇到一些困难。

• 批处理

  如果要执行很多非查询（insert/update/delete）的语句，您可能喜欢将它们作为一个批处 理来执行，以减少网络通讯流量，并让 JDBC Driver 进行优化（例如压缩）。SQL Map API 使用批处理很简单，可以使用两个简单的方法划分批处理的边界：

   sqlMap.startBatch();
  
   //…execute statements in between
  
   sqlMap.executeBatch();

  当调用 endBatch（）方法时，所有的批处理语句将通过 JDBC Driver 来执行。