扩展 iBatis 以透明支持多种数据库

iBatis 是一个开源的对象关系映射框架，着重于 POJO 与 SQL 之间的映射关系。和其它 ORM 框架不同，iBatis 开发者需要自己编写和维护 SQL 语句。为了得到更好的执行性能，在实际开发中免不了会使用一些数据库方言。随之而来的一个问题是，如何在增加对新的数据库支持的同时尽可能避免对已有应用程序代码的修改？本文提供了一个简单有效的方法，通过扩展 iBatis 来透明地支持多数据库方言。


iBatis 简介

iBatis 是一个开源的对象关系映射程序，着重于 POJO 与 SQL 之间的映射关系。使用时，开发者提供一个被称为 SQL 映射的 XML 文件，定义程序对象与 SQL 语句间的映射关系， iBatis 会根据 SQL 映射文件的定义，运行时自动完成 SQL 调用参数的绑定以及 JDBC ResultSet 到 Java POJO 之间的转换。下面是一个简单的例子，相比其它 ORM 工具，iBatis 相对简单，更容易上手。

清单 1. POJO 对象

               
public class BlogData implements Serializable {
  protected String id;
  protected String name;
  protected int rating = 0;
  public String getId() {
    return id;
  }
  public String getName() {
    return name;
  }
  public int getRating() {
    return rating;
  }
  public void setId(String id) {
    this.id = id;
  }
  public void setName(String name) {
    this.name = name;
  }
  public void setRating(int rating) {
    this.rating = rating;
  }
}



清单 2. SQL 映射文件—— SQLMAP.XML

               
<sqlMap namespace="blog">
  <resultMap id="blog" class="BlogData">
  <result property="id" column="id" />
  <result property="name" column="name" />
  <result property="rating" column="rating" />
</resultMap>
<insert id="SAVEBLOG" parameterClass="BlogData">
  insert into blogs(id, name, rating) values(#id#, #name#, #rating#)
</insert>
<update id="UPDATEBLOG" parameterClass="BlogData">
  update blogs set name = #name#, rating = #rating# where id = #id#
</update>
<delete id="REMOVEBLOG" parameterClass="string">
  delete from blogs where id = #id#
</delete>
<select id="GETMOSTPOPULARBLOG" parameterClass="map" resultMap="blog">
  select * from blogs order by rating desc fetch first $size$ rows only
</select>
</sqlMap>



清单 3. iBatis 配置文件—— SQLMAPCONFIG.XML

               
<sqlMapConfig>
  <settings useStatementNamespaces="true" />
  <transactionManager type="JDBC" commitRequired="true">
    <dataSource type="JNDI">
      <property name="DataSource" value="java:comp/env/jdbc/db" />
    </dataSource>
  </transactionManager>
  //SQL 映射声明
  <sqlMap resource="SQLMAP.XML" />
</sqlMapConfig>



清单 4. SQL 访问示例

               
String cfg = "SQLMAPCONFIG.XML";
Reader r = Resources.getResourceAsReader(cfg);
SqlMapClient client = new SqlMapConfigParser().parse(r);
...
// 插入
BlogData o = new BlogData();
o.setId("id");
o.setName("test");
client.insert("SAVEBLOG", o);
...
// 更新
o.setRating(10);
client.update("UPDATEBLOG", o);
...
// 删除
client.delete("REMOVEBLOG", "id");
...
// 查询
Map params = new HashMap();
params.put(size, 5);
List l = client. queryForList("GETMOSTPOPULARBLOG", params, 0, 5);
...






回页首


iBatis 应用中的多数据库支持

在 iBatis 应用中，开发者仍需自己编写具体的 SQL 语句，iBatis 只是隐藏和简化了 JDBC 的相关调用。

实际开发中，我们不免需要就 SQL 语句针对各种特定的数据库进行特殊优化，以期获取更好的执行性能，随之而来的一个问题是，如何应对新的数据库平台支持的需求。

一般的做法是，修改 SQL 映射文件，提供一些新的针对新数据库平台的 SQL 语句版本，然后修改程序代码，添加相应调用。继续上面的例子。上面的例子中，对于 SQL 语句 GETMOSTPOPULARBLOG 的定义，我们使用了 DB2 特有的 SQL 方言“FETCH FIRST n ROWS ONLY”，对于这样的程序，如果希望增加对 MYSQL 的支持，按照一般的做法，需要：

1．修改 SQLMAP.XML，增加语句定义“GETMOSTPOPULARBLOG_MYSQL”。

清单 5. 增加语句定义

               
......
<select id="GETMOSTPOPULARBLOG" parameterClass="map" resultMap="blog">
select * from blogs order by rating desc fetch first $size$ rows only
</select>
<select id=" GETMOSTPOPULARBLOG_MYSQL" parameterClass="map" resultMap="blog">
select * from blogs order by rating desc limit 0, $size$
</select>
......


2．搜索程序代码，在每一个调用 iBatis “GETMOSTPOPULARBLOG”的地方，增加检测 MYSQL 数据库引擎的代码，并添加对“GETMOSTPOPULARBLOG_MYSQL”的 iBatis 调用。

清单 6. 增加检测数据库引擎的代码

               
......
SqlMapClient client = ...;
......
// 查询
Map params = new HashMap();
params.put(size, 5);
List l = null;
Connection conn = client.getCurrentConnection();
String prodName = conn.getMetaData().getDatabaseProductName().toLowerCase();
if (prodName.indexOf("mysql") > - 1) {
  //Microsoft SQL Server
  l = client. queryForList("GETMOSTPOPULARBLOG_MYSQL", params);
} else {
  l = client. queryForList("GETMOSTPOPULARBLOG", params);
}

......


每增加一个新的数据库支持，增加了一些新的针对新数据库平台的 SQL 语句版本，我们就不得不搜索源代码，找出所有受到影响的 iBatis 调用，修改并增加针对新数据库的特殊调用。代码维护时，每次涉及使用数据库方言的 SQL 语句，我们也都必须记住小心谨慎地处理所有相关的数据库特化调用。这样的工作乏味且容易出错。

本文，我们试图在分析 iBatis 源码的基础上，通过适当扩展 iBatis，提供一个高效方便的解决方案。




回页首


扩展 SqlMapConfigParser

在 iBatis 应用中，SqlMapConfigParser 负责解析 iBatis 配置文件，加载所有的 SQL 映射文件，生成 SqlMapClient 实例，这是持久化调用的入口。

SqlMapConfigParser 的实现并不复杂。成员函数 parser 将传入的配置文件 XML 输入流交给一个 XML 解析器。XML 解析器解析 XML 输入，并针对每一个 XML Fragment 调用合适的处理器处理。所有的处理器都在 SqlMapConfigParser 类实例初始化时预先被注册到 XML 解析器上，其中，对于 iBatis 配置中的 SQL 映射声明，只是简单地调用类 SqlMapParser 中的 parser 方法，解析并加载相应的 SQL 映射定义文件。

清单 7. SqlMapConfigParser 实现

               
public class SqlMapConfigParser {
  //XML 解析器
  protected final NodeletParser parser = new NodeletParser();

  public SqlMapConfigParser() {
    ......

    // 注册 XML 处理器
    addSqlMapNodelets();
    ...... // more
  }

  public SqlMapClient parse(Reader reader) {
    ......
    // 调用 XML 解析器解析传入的配置文件 XML 输入流
    parser.parse(reader);
    return vars.client;
  }

  protected void addSqlMapNodelets() {
    //XML 处理器，处理 XPath:"/sqlMapConfig/sqlMap"，即 SQL 映射声明
    parser.addNodelet("/sqlMapConfig/sqlMap", new Nodelet() {
      public void process(Node node)throws Exception {
        Properties attributes = NodeletUtils.parseAttributes(node);
        String resource = attributes.getProperty("resource");
        Reader reader = Resources.getResourceAsReader(resource);
        new SqlMapParser(vars).parse(reader); // 调用 SqlMapParser.parser 方法
        // 解析并加载 SQL 映射文件
        ......
      }
    }
    );
  }
  ......
}


我们继承 iBatis 原有的配置文件解析器实现 SqlMapConfigParser，重写其中对 SQL 映射声明的处理。

首先，我们重写 SqlMapConfigParser 的成员函数 addSqlMapNodelets。对于从 XML 解析器传入的 SQL 映射声明节点，我们并不立即进行解析处理，而只是将它们记录下来。

清单 8. 重写 addSqlMapNodelets 方法

               
public class SqlMapConfigParserEx extends SqlMapConfigParser {
List sqlMapNodeList = new ArrayList();
  .......
  protected void addSqlMapNodelets() {
  //XML 处理器，处理 XPath:”/sqlMapConfig/sqlMap”，即 SQL 映射声明
    parser.addNodelet("/sqlMapConfig/sqlMap", new Nodelet() {
      public void process(Node node)throws Exception {
        sqlMapNodeList.addNode(node);
      }
    }
   );
  }
  ......
}


这些 SQL 映射声明被放到最后处理，此时 SqlMapClient 实例已经基本构造完毕，至少，我们可以安全地调用它的相关方法，打开数据库连接，查询数据库引擎相关信息。对于每个 SQL 映射声明，SqlMapConfigParserEx 调用其成员函数方法 handleSqlMapNode 进行相应的 SQL 映射文件解析和加载处理，数据库引擎支持的 SQL 方言版本信息作为参数被一并传入。

清单 9. 重写 parse 方法

               
public interface DialectMapping {
  public String getDialect(String productName);
  // 返回数据库平台支持的 SQL 方言信息
}

public class SqlMapConfigParserEx extends SqlMapConfigParser {
  List sqlMapNodeList = new ArrayList();
  DialectMapping dialectMapping = ...;
  .......
  public SqlMapClient parse(Reader reader) {
    ......
    super.parse(reader);
    String sqlDialect = null;
    SqlMapClient client = vars.client;
    Connection conn = client.getDataSource().getConnection();
    DatabaseMetaData dbMetaData = conn.getMetaData();
    String productName = dbMetaData.getDatabaseProductName();
    sqlDialect = dialectMapping.getDialect(productName);
    conn.close();

    for (Iterator iter = sqlMapNodeList.iterator(); iter.hasNext();) {
      handleSqlMapNode((Node)iter.next(), sqlDialect);
    }

    return client;
  }
  ......
}


对于传入的 SQL 映射声明，除了解析并加载 SQL 映射声明中指定的 SQL 映射文件，handleSqlMapNode 还根据传入的 SQL 方言版本信息，以一定的路径规则，寻找针对该 SQL 方言的 SQL 映射文件定制版本，将它们一并解析加载。

清单 10. handleSqlMapNode 方法

               
public interface SqlMapStreamMerger {
  public void addInput(InputStream input);
  public InputStream merge();
  ......
}

public class SqlMapConfigParserEx extends SqlMapConfigParser {
  SqlMapStreamMerger sqlMapStreamMerger = ...;
  .......
 
  public void handleSqlMapNode(Node node, String sqlDialect) {
    Properties attributes = NodeletUtils.parseAttributes(node);
    String resource = attributes.getProperty("resource");
    // 读取 SQL 映射声明指定的 SQL 映射文件
    InputStream is = Resources.getResourceAsStream(resource);
    sqlMapStreamMerger.addInput(is);
    // 寻找并试图读取针对 SQL 方言 sqlDialect 的 SQL 映射文件定制版本
    int idx = resource.lastIndexOf('/');
    resource = resource.substring(0, idx) + "/" + sqlDialect +
      resource.substring(idx);
    is = Resources.getResourceAsStream(resource);
    if (is != null) {
      sqlMapStreamMerger.addInput(is);
    }
    // 将读取到的 SQL 映射文件，包括基本的 SQL 映射文件，以及为特定数据库的定制版本，
    // 合成一个 SQL 映射文件 XML 数据流交给 SqlMapParser 解析处理
    Reader reader = new InputStreamReader(sqlMapStreamMerger.merge());
    new SqlMapParser(vars).parse(reader);
  }
 
  ......
}


成员函数 handleSqlMapNode 将找到的 SQL 映射文件，包括 SQL 映射声明中指定的基本的 SQL 映射文件，以及以一定路径规则找到的针对特定数据库的 SQL 映射文件定制版本，通过 SqlMapStreamMerge 对象整合成一个 SQL 映射文件，才递交给 SqlMapParser 解析处理。SqlMapStreamMerge 确保：

   1. 结果 SQL 映射文件中不存在重复 ID 的 SQL 映射配置块（statement、insert、update、delete、sql、resultMap 等）。如果基本的 SQL 映射文件与针对特定数据库的 SQL 映射文件定制版本之间存在重复 ID 的 SQL 映射配置块定义，SqlMapStreamMerge 保留后者覆盖前者；
   2. 结果 SQL 映射文件中的配置块按引用依赖顺序有序排列。即所有的 resultMap 声明都位于引用它们的 statement 声明之前，被继承的 resultMap 声明都位于继承的 resultMap 声明之前等。

先 Merge 再解析，这是必要的，因为 SqlMapParser 本身并不支持 SQL 映射定义的方法重写。




回页首


使用

使用扩展的 SqlMapConfigParser 实现 —— SqlMapConfigParserEx，可以大大简化应用程序中多数据库支持问题的解决。

还是之前那个例子。

首先，我们使用 SqlMapConfigParserEx 替换程序中的 SqlMapConfigParser 使用。

清单 11. 在应用代码中使用扩展的 SqlMapConfigParserEx

               
String cfg = "SQLMAPCONFIG.XML";
Reader r = Resources.getResourceAsReader(cfg);

// old code
// SqlMapClient client = new SqlMapConfigParser().parse(r);

// new code
SqlMapClient client = new SqlMapConfigParserEx().parse(r);
...


现在，要增加对 MySQL 的支持，只需建立一个新的 SQL 映射文件 /mysql/SQLMAP.XML，重写 SQLMAP.XML 中 GETMOSTPOPULARBLOG 的 SQL 定义。Java 代码可以继续保持数据库平台透明性，无需作出任何修改。

清单 12. 针对 MySQL 的配置文件 /mysql/SQLMAP.XML

               
<!-- /mysql/SQLMAP.XML -->
<sqlMap namespace="blog">
<select id="GETMOSTPOPULARBLOG" parameterClass="map" resultMap="blog">
select * from blogs order by rating desc limit 0, $size$
</select>
</sqlMap>


运行时，SqlMapConfigParserEx 会自动检测数据库引擎版本信息，读取文件 /mysql/SQLMAP.XML，使用其中的（针对 MYSQL 定制的）GETMOSTPOPULARBLOG 定义覆盖 SQLMAP.XML 中的 DB2 方言版本，从而确保程序行为的正确性。

我们支持，针对新的数据库平台，对 SQL 映射文件中的任意配置进行定制 / 重写，甚至包括 <parameterMap>、<resultMap>、<cacheModel> 等，尽管在实际应用中，这样的需求并不常见。




回页首


关于 iBatis 2.1.5

上述分析只适合 iBatis 2.2.0 之后的版本。在 iBatis 2.1.5 中，addSqlMapNodelets 是 SqlMapConfigParser 的私有成员函数，无法在子类中重写。附件中，我们给出了针对 iBatis 2.1.5 的 SqlMapConfigParserEx 实现，大致思想类似，这里就不再详述。




回页首


结束语

iBatis 作为一个 ORM 框架，以其简单易用，支持更为灵活的数据库 / 系统设计，正在得到越来越多的关注。iBatis 应用中，开发者需要自己编写具体的 SQL 语句，针对特定的数据库进行 SQL 优化，处理跨数据库平台移植问题等。本文，针对 iBatis 应用中的多数据库支持问题，通过扩展 iBatis 的现有实现，给出了一个较为简单高效的解决方法。