开发指南 iBATIS SQL Maps Page 1 of 62
iBATIS SQL Maps
开发指南
Version 2.0
2004 年 6 月 17 日
Clinton Begin 著
刘 涛 译
http://www.ibatis.com Clinton Begin 著 刘涛(toleu@21cn.com) 译
开发指南 iBATIS SQL Maps Page 2 of 62
目 录
简介 ..................................................................................................................................................4
关于本文...................................................................................................................................4
SQL Maps (com.ibatis.sqlmap.*)......................................................................................................5
SQL Map 的概念......................................................................................................................5
SQL Map 如何工作？..............................................................................................................5
安装 SQL Maps ........................................................................................................................6
JAR 文件和依赖性...................................................................................................................6
从 1.x 版本升级........................................................................................................................7
是否应该升级...................................................................................................................7
转换 XML 配置文件（从 1.x 到 2.0）...........................................................................7
使用新的 JAR 文件..........................................................................................................8
SQL Map XML 配置文件..............................................................................................................10
<properties>元素....................................................................................................................11
<setting>元素 .........................................................................................................................11
<typeAlias>元素.....................................................................................................................13
<transactionManager>元素 ....................................................................................................13
<datasource>元素...........................................................................................................14
<sqlMap>元素........................................................................................................................15
SQL Map XML 映射文件..............................................................................................................17
Mapped Statements.................................................................................................................18
Statement 的类型............................................................................................................18
SQL 语句 .......................................................................................................................19
自动生成的主键.............................................................................................................20
存储过程.........................................................................................................................20
parameterClass................................................................................................................21
parameterMap .................................................................................................................21
Inline Parameter 简介.....................................................................................................22
resultClass.......................................................................................................................22
resultMap ........................................................................................................................23
cacheModel.....................................................................................................................23
xmlResultName...............................................................................................................24
Parameter Map 和 Inline Parameter......................................................................................24
<parameter>元素............................................................................................................25
Inline Parameter Map......................................................................................................26
基本类型输入参数.........................................................................................................27
Map 类型输入参数 ........................................................................................................28
Result Map..............................................................................................................................28
隐式的 Result Map .........................................................................................................30
基本类型的 Result（即 String，Integer，Boolean） ..................................................31
http://www.ibatis.com Clinton Begin 著 刘涛(toleu@21cn.com) 译
开发指南 iBATIS SQL Maps Page 3 of 62
Map 类型的 Result .........................................................................................................31
复杂类型属性（即自定义类型的属性）.............................................................................32
避免 N＋1 Select（1:1）.......................................................................................................33
延迟加载 VS 联合查询（1:1）...................................................................................33
复杂类型集合的属性.............................................................................................................34
避免 N＋1 Select（1:M 和 M:N）........................................................................................34
组合键值或多个复杂参数属性.............................................................................................35
支持 Parameter Map 和 Result Map 的数据类型..................................................................36
缓存 Mapped Statement 结果集.............................................................................................36
只读 VS 可读写............................................................................................................37
Serializable 可读写缓存.................................................................................................37
缓存类型.........................................................................................................................38
动态 Mapped Statement..........................................................................................................41
二元条件元素.................................................................................................................42
一元条件元素.................................................................................................................43
其他元素.........................................................................................................................43
简单的动态 SQL 元素 ...................................................................................................44
使用 SQL Map API 编程................................................................................................................46
配置 SQL Map........................................................................................................................46
事务处理.................................................................................................................................46
自动的事务处理.............................................................................................................47
全局（分布式）事务.....................................................................................................48
批处理.....................................................................................................................................49
用 SqlMapClient 执行 SQL 语句...........................................................................................49
代码例子.................................................................................................................................52
例子 1：执行 update（insert，update，delete）.........................................................52
例子 2：查询成对象（select）.....................................................................................52
例子 3：用预赋值的结果对象查询成对象（select）.................................................52
例子 4：查询成对象 List（select）..............................................................................52
例子 5：自动提交..........................................................................................................53
例子 6：用结果集边界查询成对象 List（select）......................................................53
例子 7：用 RowHandler 执行查询（select） ..............................................................53
例子 8：查询成 Paginated List（select）.....................................................................53
例子 9：查询成 Map（select） ....................................................................................53
用 Jakarta Commons Logging 记录 SQL Map 日志......................................................................54
配置日志服务.........................................................................................................................54
Java Bean 简易教程 .......................................................................................................................56
Resources（com.ibatis.common.resource.*） ...............................................................................58
SimpleDataSource（com.ibatis.common.jdbc.*） ........................................................................60
ScriptRunner (com.ibatis.common.jdbc.*) .....................................................................................62
http://www.ibatis.com Clinton Begin 著 刘涛(toleu@21cn.com) 译
开发指南 iBATIS SQL Maps Page 4 of 62
简介
使用 SQL Map，能够大大减少访问关系数据库的代码。SQL Map 使用简单的 XML 配
置文件将 Java Bean 映射成 SQL 语句，对比其他的数据库持续层和 ORM 框架（如 JDO 的
实现，Hibernate 等），SQL Map 最大的优点在于它简单易学。要使用 SQL Map，只要熟悉
Java Bean，XML 和 SQL，就能使您充分发挥 SQL 语句的能力。
关于本文
本文讨论了 iBATIS SQL Map 最重要的特性。本文中没有提及的其他特性，可能以后
不再支持或不久将会修改，并且修改时不作通告，因此最好不要使用它们。本文将随着 iBatis
SQL Map 的修改而变更。如果您发现其中的错误，或是觉得某些地方难以理解，请发 email
至 clinton.begin@ibatis.com
。
本文是《iBatis SQL Maps Developer Guide》的中文版，仅供读者参考，最权威的应以
Clinton Begin 的官方文档为准。如果中文翻译有错误，请通知译者（email：toleu@21cn.com
，
Blog：http://starrynight.blogdriver.com/
）。
http://www.ibatis.com Clinton Begin 著 刘涛(toleu@21cn.com) 译
开发指南 iBATIS SQL Maps Page 5 of 62
SQL Maps (com.ibatis.sqlmap.*)
SQL Map 的概念
SQL Map API 让开发人员可以轻易地将 Java Bean 映射成 PreparedStatement 的输入参数
和 ResultSet 结果集。开发 SQL Map 的想法很简单：提供一个简洁的架构，能够用 20％的代
码实现 80％JDBC 的功能。
SQL Map 如何工作？
SQL Map 提供了一个简洁的框架，使用简单的 XML 描述文件将 Java Bean，Map 实现
和基本数据类型的包装类（String，Integer 等）映射成 JDBC 的 PreparedStatement。以下流
程描述了 SQL Maps 的高层生命周期：
将一个对象作为参数（对象可以是 Java Bean，Map 实现和基本类型的包装类），参数对
象将为 SQL 修改语句和查询语句设定参数值。
1) 执行 mapped statement。这是 SQL Maps 最重要的步骤。SQL Map 框架将创建一个
PreparedStatement 实例，用参数对象为 PreparedStatement 实例设定参数，执行
PreparedStatement 并从 ResultSet 中创建结果对象。
2) 执行 SQL 的更新数据语句时，返回受影响的数据行数。执行查询语句时，将返回
一个结果对象或对象的集合。和参数对象一样，结果对象可以是 Java Bean，Map
实现和基本数据类型的包装类。
下图描述了以上的执行流程。
http://www.ibatis.com Clinton Begin 著 刘涛(toleu@21cn.com) 译
