iBATIS SQL Maps User Manual

开发指南 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) 译

开发指南 iBATIS SQL Maps 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 SQL Maps Page 7 of 62

仅仅依赖于 Jakarta Commons Logging 框架。可选的 JAR 文件放在发布版的/lib/optional 目录

下。它们根据功能来分类。下面列表总结了何时需要使用可选 JAR 类库。

描述何时使用目录

1.4 以前 JDK 版本支持如果您使用的 JDK 版本低于

1.4，并且您的应用服务器不

提供这些 JAR 文件，您将需要这些可选的 JAR 文件

IBATIS 的向后兼容如果您使用旧的IBATIS（1.x）

DAO 框架，或旧的 SQL Maps

（1.x）

运行时字节码增强如果您需要使用CGLIB2.0 字

节码增强来提高 lazy loading 和 reflection 的性能

DataSource 实现如果您使用 Jakarta DBCP 连

接池

分布式缓存如果您使用 OSCache 来支持

集中或分布式缓存

Log4J 日志如果您需要使用 Log4J

/lib/optional/jdbc /lib/optional/jta /lib/optional/xml

/lib/optional/compatibility

/lib/optional/enhancement

/lib/optional/dbcp

/lib/optional/caching

/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 SQL Maps 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">

</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 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

ibatis-common.jar（必需） ibatis-sqlmap.jar（必需） ibatis-dao.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 SQL Maps 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 SQL Maps 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">

<settings

cacheModelsEnabled="true" enhancementEnabled="true" lazyLoadingEnabled="true" maxRequests="32" maxSessions="10" maxTransactions="5"

useStatementNamespaces="false" />

http://www.ibatis.com Clinton Begin 著刘涛(toleu@21cn.com) 译

开发指南 iBATIS SQL Maps Page 11 of 62

</dataSource> </transactionManager>

</sqlMapConfig>

以下详细讨论

SQL Map

配置文件的各组成部分。

<properties>元素

SQL Map 配置文件拥有唯一的<properties>元素，用于在配置文件中使用标准的 Java 属

性文件（name＝value）。这样做后，在属性文件中定义的属性可以作为变量在 SQL Map 配

置文件及其包含的所有 SQL Map 映射文件中引用。例如，如果属性文件中包含属性：

driver=org.hsqldb.jdbcDriver

SQL Map 配置文件及其每个映射文件都可以使用占位符${driver} 来代表值

org.hsqldb.jdbcDriver。例如：

这个元素在开发，测试和部署各阶段都很有用。它可以使在多个不同的环境中重新配置

应用和使用自动生成工具（如 ANT）变得容易。属性文件可以从类路径中加载（使用 resource

熟悉），也可以从合法的 URL 中加载（使用 url 属性）。例如，要加载固定路径的属性文件，

使用：

<setting>元素

<setting>元素用于配置和优化 SqlMapClient 实例的各选项。<setting>元素本身及其所有

的属性都是可选的。下表列出了<setting>元素支持的属性及其功能：

maxRequests

http://www.ibatis.com Clinton Begin 著刘涛(toleu@21cn.com) 译

同时执行 SQL 语句的最大线程数。大于这个值的线

开发指南 iBATIS SQL Maps 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 SQL Maps Page 13 of 62

queryForObject(“sqlMapName.statementName”);

例如：useStatementNamespaces=“false” 缺省值：false（禁用）

<typeAlias>元素

<typeAlias>元素让您为一个通常较长的、全限定类名指定一个较短的别名。例如：

在 SQL Map 配置文件预定义了几个别名。它们是：

事务管理器别名

JDBC JTA EXTERNAL

Data Source Factory 别名

SIMPLE DBCP JNDI

com.ibatis.sqlmap.engine.transaction.jdbc.JdbcTransactionConfig com.ibatis.sqlmap.engine.transaction.jta.JtaTransactionConfig com.ibatis.sqlmap.engine.transaction.external.ExternalTransactionConfig

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。

 JDBC：通过常用的 Connection commit()和 rollback()方法，让 JDBC 管理事务。

 JTA：本事务管理器使用一个 JTA 全局事务，使 SQL Map 的事务包括在更大的事

务范围内，这个更大的事务范围可能包括了其他的数据库和事务资源。这个配置需

要一个UserTransaction属性，以便从JNDI 获得一个 UserTransaction。

数据源的例子。

参见以下

 EXTERNAL：这个配置可以让您自己管理事务。您仍然可以配置一个数据源，但

JNDI

事务不再作为框架生命周期的一部分被提交或回退。这意味着 SQL Map 外部应用

的一部分必须自己管理事务。这个配置也可以用于没有事务管理的数据库（例如只

http://www.ibatis.com Clinton Begin 著刘涛(toleu@21cn.com) 译

开发指南 iBATIS SQL Maps Page 14 of 62

读数据库）。

<datasource>元素

<datasource>是<transactionManager>的一部分，为 SQL Map 数据源设置了一系列参数。

目前 SQL Map 架构只提供三个 DataSource Factory，但您也可以添加自己的实现。下面详细

地讨论 DataSourceFactory 的三个实现及其例子。

SimpleDataSourceFactory

SimpleDataSourceFactory 为 DataSource 提供了一个基本的实现，适用于在没有 J2EE 容

器提供 DataSource 的情况。它基于 iBatis 的 SimpleDataSource 连接池实现。

</dataSource>

</transactionManager>

DbcpDataSourceFactory

DbcpDataSourceFactory 实现使用 Jakarta DBCP（Database Connection Pool）的 DataSource

API 提供连接池服务。适用于应用/Web 容器不提供 DataSource 服务的情况，或执行一个单

独的应用。DbcpDataSourceFactory 中必须要配置的参数例子如下：

http://www.ibatis.com Clinton Begin 著刘涛(toleu@21cn.com) 译

开发指南 iBATIS SQL Maps Page 15 of 62

</datasource>

</transactionManager>

JndiDataSourceFactory

JndiDataSourceFactory 在应用容器内部从 JNDI Context 中查找 DataSource 实现。当使用

应用服务器，并且服务器提供了容器管理的连接池和相关 DataSource 实现的情况下，可以

使用 JndiDataSourceFactory。使用 JDBC DataSource 的标准方法是通过 JNDI 来查找。

JndiDataSourceFactory 必须要配置的属性如下：

</transactionManager>

以上配置使用了常用的 JDBC 事务管理。但对于容器管理的资源，您可能需要象下面的

例子一样配置，让它能和全局事务一起工作：

</transactionManager>

注意，UserTransaction 属性指向 UserTransaction 实例所在的 JNDI 位置。JTA 事务管理

需要它，以使 SQL Map 能够参与涉及其他数据库和事务资源的范围更大的事务。

<sqlMap>元素

<sqlMap>元素用于包括 SQL Map 映射文件和其他的 SQL Map 配置文件。每个

SqlMapClient 对象使用的所有 SQL Map 映射文件都要在此声明。映射文件作为 stream

resource 从类路径或 URL 读入。您必须在这里指定所有的 SQL Map 文件。例子如下：

http://www.ibatis.com Clinton Begin 著刘涛(toleu@21cn.com) 译

开发指南 iBATIS SQL Maps Page 16 of 62

以下几个章节详细讨论

SQL Map XML

映射文件的结构。

http://www.ibatis.com Clinton Begin 著刘涛(toleu@21cn.com) 译

开发指南 iBATIS SQL Maps Page 17 of 62

SQL Map XML 映射文件

在上面的例子中，只使用了 SQL Map 最简单的形式。SQL Map 的结构中还有其他更多

的选项。这里是一个 mapped statement 较复杂的例子，使用了更多的特性。

select * from PRODUCT where PRD_ID = ? </select>

</sqlMap>

太麻烦？虽然框架为您做了很多工作，为了完成一个简单的查询操作，依然需要做很多。

别担心，下面是一个简洁版本。

<select id=”getProduct” parameterClass=” com.ibatis.example.Product”

resultClass=”com.ibatis.example.Product”> select PRD_ID as id, PRD_DESCRIPTION as description from PRODUCT where PRD_ID = #id#

</select>

</sqlMap>

但是简洁版本的行为和前一个声明的行为不太一样。首先，简洁版本没有定义缓存，因

此每一个请求都要读取数据库。其次，简洁版本使用了框架的自动映射特性，这将带来一些

副作用。但是，这两者在 Java 代码中的执行方式完全一致，因此您开始可以先使用一个简

http://www.ibatis.com Clinton Begin 著刘涛(toleu@21cn.com) 译

开发指南 iBATIS SQL Maps Page 18 of 62

单的方案，等将来需要时再换成更好的版本。首先应用最简单的方案，是很多现代方法学的

最佳实践。

注意！一个 SQL Map XML映射文件可以包含任意多个 Mapped Statement，Parameter Map

和 Result Map。按照它们之间的逻辑关系，为您的应用合理地组织 Mapped Statement，

Parameter Map 和 Result Map。

注意！SQL Map 的名称是全局性的，在所有的 SQL Map 文件中名称必须是唯一的。

Mapped Statements

SQL Map 的核心概念是 Mapped Statement。Mapped Statement 可以使用任意的 SQL 语

句，并拥有 parameter map（输入）和 result map（输出）。如果是简单情况，Mapped Statement

可以使用 Java 类来作为 parameter 和 result。Mapped Statement 也可以使用缓存模型，在内存

中缓存常用的数据。Mapped Statement 的结构如下所示：

<statement id=”statementName”

[parameterClass=”some.class.Name”] [resultClass=”some.class.Name”] [parameterMap=”nameOfParameterMap”] [resultMap=”nameOfResultMap”] [cacheModel=”nameOfCache”]

select * from PRODUCT where PRD_ID = [?|#propertyName#] order by [$simpleDynamic$]

</statement>

在上面的表达式中，括号[]里的部分时可选的属性，并且在某些情况下只有特定的组合

才是合法的。因此下面这个简单的例子也是正确的：

insert into PRODUCT (PRD_ID, PRD_DESCRIPTION) values (1, “Shih Tzu”)

</statement>

上面的例子不太可能出现，但如果只是简单地想用 SQL Map 架构来执行任意地的 SQL

语句，这种写法就派上用场了。但常见的用法还是通过 Parameter Map 和 Result Map，来实

现 Java Bean 映射的特性，这是 SQL Map 真正有价值的地方。

Statement的类型

<statement>元素是个通用声明，可以用于任何类型的 SQL 语句。通常，使用具体的

statement 类型是个好主意。具体 statement 类型提供了更直观的 XML DTD，并拥有某些

http://www.ibatis.com Clinton Begin 著刘涛(toleu@21cn.com) 译

开发指南 iBATIS SQL Maps Page 19 of 62

<statement>元素没有的特性。下表总结了 statement 类型及其属性和特性：

Statement 类型属性子元素方法

<statement> id

parameterClass resultClass parameterMap

所有的动态元素 insert

update delete

所有的查询方法 resultMap cacheModel xmlResultName

<insert> id

parameterClass parameterMap

<update> id

parameterClass parameterMap

<delete> id

parameterClass parameterMap

<select> id

所有的动态元素 <selectKey>

insert

update

delete

所有的动态元素 insert

update

delete

所有的动态元素 insert

update

delete

所有的动态元素所有的查询方法 parameterClass resultClass parameterMap resultMap cacheModel

<procedure> id

parameterClass resultClass parameterMap

所有的动态元素 insert

update delete

所有的查询方法 resultMap xmlResultName

SQL 语句

SQL 显然是 mapped statement 中最重要的部分，可以使用对于数据库和 JDBC Driver 合

法的任意 SQL 语句。只要 JDBC Driver 支持，可以使用任意的函数，甚至是多条语句。因

为 SQL 语句是嵌在 XML 文档中的，因此有些特殊的字符不能直接使用，例如大于号和小

于号（<>）。幸运的是，解决的办法很简单，只需将包含特殊字符的 SQL 语句放在 XML 的

CDATA 区里面就可以了。例如：

<statement id="getPersonsByAge" parameterClass=”int”

resultClass="examples.domain.Person">

<![CDATA[

http://www.ibatis.com Clinton Begin 著刘涛(toleu@21cn.com) 译

+ 43 hidden pages

iBATIS SQL Maps User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

关于本文

SQL Maps (com.ibatis.sqlmap.*)

SQL Map 的概念

SQL Map 如何工作？

安装 SQL Maps

JAR 文件和依赖性

从 1.x 版本升级

是否应该升级

转换XML配置文件（从1.x到2.0）

使用新的JAR文件

SQL Map XML 配置文件

<properties>元素

<setting>元素

<typeAlias>元素

<transactionManager>元素

<datasource>元素

SimpleDataSourceFactory

DbcpDataSourceFactory

JndiDataSourceFactory

<sqlMap>元素

SQL Map XML 映射文件

Mapped Statements

Statement的类型

SQL 语句