1

开发指南 iBATIS SQLMaps 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 SQLMaps 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 SQLMaps 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 SQLMaps 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 SQLMaps 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) 译
开发指南 iBATIS SQLMaps Page 6 of 62
安装SQL Maps
安装SQL Maps很简单，只要把相关的JAR文件复制到类路径下即可。类路径或者是JVM启动是指定的类路径（java命令参数），或者是Web应用中的/WEB-INF/lib目录。Java类路径的详尽讨论超出了本文的范围，如果您是Java的初学者，请参考以下的资源：
http://java.sun.com/j2se/1.4/docs/tooldocs/win32/classpath.html
http://java.sun.com/j2se/1.4.2/docs/api/java/lang/ClassLoader.html
http://java.sun.com/j2se/1.4.2/docs/
安装iBatis需要在类路径下放置以下JAR文件：
文件名
描述
是否必需
ibatis-common.jar
IBATIS公用的工具类
是
ibatis-sqlmap.jar
IBATIS SQL Maps框架
是
ibatis-dao.jar
IBATIS DAO 框架
否
JAR文件和依赖性
如果一个框架依赖于太多的JAR文件，就很难与其他的应用和框架集成。IBATIS 2.0的一个主要的关注点是管理并降低JAR文件的依赖性。因此，如果您用的是JDK1.4，IBATIS
http://www.ibatis.com Clinton Begin 著 刘涛(toleu@21cn.com) 译
开发指南 iBATIS SQLMaps Page 7 of 62
仅仅依赖于Jakarta Commons Logging框架。可选的JAR文件放在发布版的/lib/optional目录下。它们根据功能来分类。下面列表总结了何时需要使用可选JAR类库。
描述
何时使用
目录
1.4以前JDK版本支持
如果您使用的JDK版本低于1.4，并且您的应用服务器不提供这些JAR文件，您将需要这些可选的JAR文件
/lib/optional/jdbc
/lib/optional/jta
/lib/optional/xml
IBATIS的向后兼容
如果您使用旧的IBATIS（1.x）DAO框架，或旧的SQL Maps（1.x）
/lib/optional/compatibility
运行时字节码增强
如果您需要使用CGLIB2.0字节码增强来提高lazy loading和reflection的性能
/lib/optional/enhancement
DataSource实现
如果您使用Jakarta DBCP连接池
/lib/optional/dbcp
分布式缓存
如果您使用OSCache来支持集中或分布式缓存
/lib/optional/caching
Log4J日志
如果您需要使用Log4J
/lib/optional/logging
从1.x版本升级
是否应该升级
判断您是否需要升级的最好办法是尝试它。下面是几种升级的方法。
1. 版本2.0几乎完全保持和1.x版本的向后兼容，因此某些情况下只需用新的JAR文件替代旧的即可。这个升级方法带来的好处最少，但最简单。您无需修改XML文件或Java代码，但会存在某些不兼容的问题。
2. 第二种方法是把1.x的XML文件转换成2.0规范，但仍使用1.x的Java API。除了XML映射文件存在着细微的不兼容之处外，这是个安全的方法。SQL Map框架包括了用来转换XML映射文件的ANT Task（参见下节）。
3. 第三种方法是转换XML文件（和第二种方法相同）和Java代码。因为没有转换Java代码的工具，必须手工进行。
4. 第四种方法是不必升级。如果您升级有困难，可以让应用继续使用1.x版本。让旧应用继续使用1.x版，在新应用中使用2.0版是个不错的主意。
转换XML配置文件（从1.x到2.0）
框架的2.0版本包含了一个可以在ANT构建环境中使用的XML文件转换器。虽然转换
http://www.ibatis.com Clinton Begin 著 刘涛(toleu@21cn.com) 译
开发指南 iBATIS SQLMaps Page 8 of 62
XML配置文件是可选的，但将1.x的配置文件转换成2.0仍然是个好主意。你几乎不会遇到不兼容的文件，并且还可以使用2.0版本新的特性（即使您继续使用1.x的Java API）。
XML配置文件转换器在build.xml文件中的例子如下：
<taskdef name="convertSqlMaps"
classname="com.ibatis.db.sqlmap.upgrade.ConvertTask"
classpathref="classpath"/>
<target name="convert">
<convertSqlMaps todir="D:/targetDirectory/" overwrite="true">
<fileset dir="D/sourceDirectory/">
<include name="**/maps/*.xml"/>
</fileset>
</convertSqlMaps>
</target>
就像您看到的一样，它和Ant的copy task很相似。事实上它就是Ant的copy task类的子类，因此您可以用这个task完成任何copy task的功能（详细信息请参考Ant的Copy task文档）
使用新的JAR文件
要升级到2.0，最好删除iBatis原有旧的JAR文件及其依赖JAR类库，并用新的JAR文件替代。但要主要不要删除其他组件或框架还需要的文件。请参考上节关于JAR类库及其依赖性的讨论。
下表总结了旧文件及其相应的新文件。
旧文件
新文件
ibatis-db.jar
1.2.9b以后的版本，这个文件被分拆成一下3个文件
ibatis-common.jar
ibatis-dao.jar
ibatis-sqlmap.jar
ibatis-common.jar（必需）
ibatis-sqlmap.jar（必需）
ibatis-dao.jar（可选）
commons-logging.jar
commons-logging-api.jar
commons-collection.jar
commons-dbcp.jar
commons-pool.jar
oscache.jar
jta.jar
jdbc2_0-stdext.jar
xercesImpl.jar
xmlParserAPIs.jar
commons-logging-1-0-3.jar（必需）
commons-collection-2-1.jar（可选）
commons-dbcp-1-1.jar（可选）
commons-pool-1-1.jar（可选）
oscache-2-0-1.jar（可选）
jta-1-0-1a.jar（可选）
jdbc2_0-stdext.jar（可选）
xercesImpl-2-4-0.jar（可选）
xmlParserAPIs-2-4-0.jar（可选）
xalan-2-5-2.jar（可选）
http://www.ibatis.com Clinton Begin 著 刘涛(toleu@21cn.com) 译
开发指南 iBATIS SQLMaps Page 9 of 62
jdom.jar
log4j-1.2.8.jar（可选）
cglib-full-2-0-rc2.jar（可选）
本文余下部分将介绍如何使用SQL Maps框架。
http://www.ibatis.com Clinton Begin 著 刘涛(toleu@21cn.com) 译
开发指南 iBATIS SQLMaps Page 10 of 62
SQL Map XML配置文件
SQL Map使用XML配置文件统一配置不同的属性，包括DataSource的详细配置信息，SQL Map和其他可选属性，如线程管理等。以下是SQL Map配置文件的一个例子：
SqlMapConfig.xml
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE sqlMapConfig
PUBLIC "-//iBATIS.com//DTD SQL Map Config 2.0//EN"
"http://www.ibatis.com/dtd/sql-map-config-2.dtd">
<!-- Always ensure to use the correct XML header as above! -->
<sqlMapConfig>
<!-- The properties (name=value) in the file specified here can be used placeholders in this config file (e.g. “${driver}”. The file is relative to the classpath and is completely optional. -->
<properties resource=" examples/sqlmap/maps/SqlMapConfigExample.properties " />
<!-- These settings control SqlMapClient configuration details, primarily to do with transaction
management. They are all optional (more detail later in this document). -->
<settings
cacheModelsEnabled="true"
enhancementEnabled="true"
lazyLoadingEnabled="true"
maxRequests="32"
maxSessions="10"
maxTransactions="5"
useStatementNamespaces="false"
/>
<!-- Type aliases allow you to use a shorter name for long fully qualified class names. -->
<typeAlias alias="order" type="testdomain.Order"/>
<!-- Configure a datasource to use with this SQL Map using SimpleDataSource.
Notice the use of the properties from the above resource -->
<transactionManager type="JDBC" >
<dataSource type="SIMPLE">
<property name="JDBC.Driver" value="${driver}"/>
<property name="JDBC.ConnectionURL" value="${url}"/>
<property name="JDBC.Username" value="${username}"/>
<property name="JDBC.Password" value="${password}"/>
<property name="JDBC.DefaultAutoCommit" value="true" />
<property name="Pool.MaximumActiveConnections" value="10"/>
http://www.ibatis.com Clinton Begin 著 刘涛(toleu@21cn.com) 译
开发指南 iBATIS SQLMaps Page 11 of 62
<property name="Pool.MaximumIdleConnections" value="5"/>
<property name="Pool.MaximumCheckoutTime" value="120000"/>
<property name="Pool.TimeToWait" value="500"/>
<property name="Pool.PingQuery" value="select 1 from ACCOUNT"/>
<property name="Pool.PingEnabled" value="false"/>
<property name="Pool.PingConnectionsOlderThan" value="1"/>
<property name="Pool.PingConnectionsNotUsedFor" value="1"/>
</dataSource>
</transactionManager>
<!-- Identify all SQL Map XML files to be loaded by this SQL map. Notice the paths
are relative to the classpath. For now, we only have one… -->
<sqlMap resource="examples/sqlmap/maps/Person.xml" />
</sqlMapConfig>
以下详细讨论SQL Map配置文件的各组成部分。
<properties>元素
SQL Map配置文件拥有唯一的<properties>元素，用于在配置文件中使用标准的Java属性文件（name＝value）。这样做后，在属性文件中定义的属性可以作为变量在SQL Map配置文件及其包含的所有SQL Map映射文件中引用。例如，如果属性文件中包含属性：
driver=org.hsqldb.jdbcDriver
SQL Map配置文件及其每个映射文件都可以使用占位符${driver}来代表值org.hsqldb.jdbcDriver。例如：
<property name="JDBC.Driver" value="${driver}"/>
这个元素在开发，测试和部署各阶段都很有用。它可以使在多个不同的环境中重新配置应用和使用自动生成工具（如ANT）变得容易。属性文件可以从类路径中加载（使用resource熟悉），也可以从合法的URL中加载（使用url属性）。例如，要加载固定路径的属性文件，使用：
<properties url=”file:///c:/config/my.properties” />
<setting>元素
<setting>元素用于配置和优化SqlMapClient实例的各选项。<setting>元素本身及其所有的属性都是可选的。下表列出了<setting>元素支持的属性及其功能：
maxRequests
同时执行SQL语句的最大线程数。大于这个值的线
http://www.ibatis.com Clinton Begin 著 刘涛(toleu@21cn.com) 译
开发指南 iBATIS SQLMaps Page 12 of 62
程将阻塞直到另一个线程执行完成。不同的DBMS有不同的限制值，但任何数据库都有这些限制。通常这个值应该至少是maxTransactions（参见以下）的10倍，并且总是大于maxSessions和maxTranactions。减小这个参数值通常能提高性能。
例如：maxRequests=“256”
缺省值：512
maxSessions
同一时间内活动的最大session数。一个session可以是代码请求的显式session，也可以是当线程使用SqlMapClient实例（即执行一条语句）自动获得的session。它应该总是大于或等于maxTransactions并小于maxRequests。减小这个参数值通常能减少内存使用。
例如：maxSessions=“64”
缺省值：128
maxTransactions
同时进入SqlMapClient.startTransaction()的最大线程数。大于这个值的线程将阻塞直到另一个线程退出。不同的DBMS有不同的限制值，但任何数据库都有这些限制。这个参数值应该总是小于或等于maxSessions并总是远远小于maxRequests。减小这个参数值通常能提高性能。
例如：maxTransactions=“16”
缺省值：32
cacheModelsEnabled
全局性地启用或禁用SqlMapClient的所有缓存model。调试程序时使用。
例如：cacheModelsEnabled=“true”
缺省值：true（启用）
lazyLoadingEnabled
全局性地启用或禁用SqlMapClient的所有延迟加载。调试程序时使用。
例子：lazyLoadingEnabled=“true”
缺省值：true（启用）
enhancementEnabled
全局性地启用或禁用运行时字节码增强，以优化访问Java Bean属性的性能，同时优化延迟加载的性能。
例子：enhancementEnabled=“true”
缺省值：false（禁用）
useStatementNamespaces
如果启用本属性，必须使用全限定名来引用mapped statement。Mapped statement的全限定名由sql-map的名称和mapped-statement的名称合成。例如：
http://www.ibatis.com Clinton Begin 著 刘涛(toleu@21cn.com) 译
开发指南 iBATIS SQLMaps Page 13 of 62
queryForObject(“sqlMapName.statementName”);
例如：useStatementNamespaces=“false”
缺省值：false（禁用）
<typeAlias>元素
<typeAlias>元素让您为一个通常较长的、全限定类名指定一个较短的别名。例如：
<typeAlias alias="shortname" type="com.long.class.path.Class"/>
在SQL Map配置文件预定义了几个别名。它们是：
事务管理器别名
JDBC
JTA
EXTERNAL
com.ibatis.sqlmap.engine.transaction.jdbc.JdbcTransactionConfig
com.ibatis.sqlmap.engine.transaction.jta.JtaTransactionConfig
com.ibatis.sqlmap.engine.transaction.external.ExternalTransactionConfig
Data Source Factory别名
SIMPLE
DBCP
JNDI
com.ibatis.sqlmap.engine.datasource.SimpleDataSourceFactory
com.ibatis.sqlmap.engine.datasource.DbcpDataSourceFactory
com.ibatis.sqlmap.engine.datasource.JndiDataSourceFactory
<transactionManager>元素
1.0转换注意事项：SQL Map 1.0允许配置多个数据源。这引起了一些不好的实践。因此，2.0版本只允许一个数据源。要使用多个部署/配置参数，您最好使用多个属性文件，不同的系统使用不同的属性文件，或在创建SQL Map时传入不同的属性文件（参见下面的Java API）。
<transationManager>元素让您为SQL Map配置事务管理服务。属性type指定所使用的事务管理器类型。这个属性值可以是一个类名，也可以是一个别名。包含在框架的三个事务管理器分别是：JDBC，JTA和EXTERNAL。