mybatis官网中文文档:/mybatis-3/zh/sqlmap-xml.html
mybatis-spring官方中文文档:/spring/zh/index.html
【1】SqlSessionFactoryBuilder
这个类可以被初始化、使用和丢弃,如果你已经创建好了一个SqlSessionFactory 后就不用再保留它。
因此,SqlSessionFactoryBuilder 的最好作用域是方法体内
比如说定义一个方法变量。你可以重复使用SqlSessionFactoryBuilder 生成多个SqlSessionFactory 实例,但是最好不要强行保留,因为XML 的解析资源要用来做其它更重要的事。
mybatis3.4.1版本中,SqlSessionFactoryBuilder中获取SqlSessionFactory实例如下(每一种都允许你从不同的资源中创建一个 SqlSessionFactory 实例):
SqlSessionFactory build(Reader reader)SqlSessionFactory build(Reader reader, String environment) SqlSessionFactory build(Reader reader, Properties properties) SqlSessionFactory build(Reader reader, String environment, Properties properties)SqlSessionFactory build(InputStream inputStream)SqlSessionFactory build(InputStream inputStream, String environment)SqlSessionFactory build(InputStream inputStream, Properties properties)SqlSessionFactory build(InputStream inputStream, String environment, Properties properties)SqlSessionFactory build(Configuration config)
SqlSessionFactoryBuilder完整源码
package org.apache.ibatis.session;import java.io.IOException;import java.io.InputStream;import java.io.Reader;import java.util.Properties;import org.apache.ibatis.builder.xml.XMLConfigBuilder;import org.apache.ibatis.exceptions.ExceptionFactory;import org.apache.ibatis.executor.ErrorContext;import org.apache.ibatis.session.defaults.DefaultSqlSessionFactory;/*** Builds {@link SqlSession} instances.** @author Clinton Begin*/public class SqlSessionFactoryBuilder {public SqlSessionFactory build(Reader reader) {return build(reader, null, null);}public SqlSessionFactory build(Reader reader, String environment) {return build(reader, environment, null);}public SqlSessionFactory build(Reader reader, Properties properties) {return build(reader, null, properties);}//核心方法一public SqlSessionFactory build(Reader reader, String environment, Properties properties) {try {//这里非常非常重要,会解析mybatis的相关配置,以及XXXMapper.xml中的结点、xxxxMapper.java中的注解XMLConfigBuilder parser = new XMLConfigBuilder(reader, environment, properties);return build(parser.parse());} catch (Exception e) {throw ExceptionFactory.wrapException("Error building SqlSession.", e);} finally {ErrorContext.instance().reset();try {reader.close();} catch (IOException e) {// Intentionally ignore. Prefer previous error.}}}public SqlSessionFactory build(InputStream inputStream) {return build(inputStream, null, null);}public SqlSessionFactory build(InputStream inputStream, String environment) {return build(inputStream, environment, null);}public SqlSessionFactory build(InputStream inputStream, Properties properties) {return build(inputStream, null, properties);}//核心方法二public SqlSessionFactory build(InputStream inputStream, String environment, Properties properties) {try {XMLConfigBuilder parser = new XMLConfigBuilder(inputStream, environment, properties);return build(parser.parse());} catch (Exception e) {throw ExceptionFactory.wrapException("Error building SqlSession.", e);} finally {ErrorContext.instance().reset();try {inputStream.close();} catch (IOException e) {// Intentionally ignore. Prefer previous error.}}}//核心方法三,根据解析到的Configuration 创建一个默认的DefaultSqlSessionFactorypublic SqlSessionFactory build(Configuration config) {return new DefaultSqlSessionFactory(config);}}
上面有两种创建DefaultSqlSessionFactory的核心方法,提供了诸多重载方法,最后调用核心方法三得到一个默认的DefaultSqlSessionFactory实例。
【2】SqlSessionFactory
SqlSessionFactory一旦创建,SqlSessionFactory 就会在整个应用过程中始终存在。所以没有理由去销毁和再创建它,一个应用运行中也不建议多次创建SqlSessionFactory。
因此SqlSessionFactory最好的作用域是Application
。
可以有多种方法实现,最简单的方法是单例模式或者是静态单例模式
。然而这也不是广泛赞成和好用的。反而,使用Google Guice 或Spring 来进行依赖反射会更好。这些框架允许你生成管理器来管理SqlSessionFactory 的单例生命周期。
SqlSessionFactory 接口源码
package org.apache.ibatis.session;import java.sql.Connection;/**根据一个数据库连接或者数据源创建一个sqlsession实例,create..out of 根据/由什么创建* Creates an {@link SqlSession} out of a connection or a DataSource* @author Clinton Begin*/public interface SqlSessionFactory {SqlSession openSession();SqlSession openSession(boolean autoCommit);SqlSession openSession(Connection connection);SqlSession openSession(TransactionIsolationLevel level);SqlSession openSession(ExecutorType execType);SqlSession openSession(ExecutorType execType, boolean autoCommit);SqlSession openSession(ExecutorType execType, TransactionIsolationLevel level);SqlSession openSession(ExecutorType execType, Connection connection);Configuration getConfiguration();}
其默认实现类是DefaultSqlSessionFactory。
SqlSessionFactory 有六个方法创建 SqlSession 实例
SqlSessionFactory 有六个方法创建 SqlSession 实例。通常来说,当你选择其中一个方法时,你需要考虑以下几点:
事务处理:你希望在 session 作用域中使用事务作用域,还是使用自动提交(auto-commit)?(对很多数据库和/或 JDBC 驱动来说,等同于关闭事务支持)数据库连接:你希望 MyBatis 帮你从已配置的数据源获取连接,还是使用自己提供的连接?语句执行:你希望 MyBatis 复用 PreparedStatement 和/或批量更新语句(包括插入语句和删除语句)吗?
基于以上需求,有下列已重载的多个 openSession() 方法供使用。
SqlSession openSession()SqlSession openSession(boolean autoCommit)SqlSession openSession(Connection connection)SqlSession openSession(TransactionIsolationLevel level)SqlSession openSession(ExecutorType execType)SqlSession openSession(ExecutorType execType, boolean autoCommit)SqlSession openSession(ExecutorType execType,TransactionIsolationLevel level)SqlSession openSession(ExecutorType execType, Connection connection)Configuration getConfiguration();
默认的 openSession() 方法没有参数,它会创建具备如下特性的 SqlSession:
事务作用域将会开启(也就是不自动提交)。将由当前环境配置的 DataSource 实例中获取 Connection 对象。事务隔离级别将会使用驱动或数据源的默认设置。预处理语句不会被复用,也不会批量处理更新。
相信你已经能从方法签名中知道这些方法的区别。向autoCommit
可选参数传递 true 值即可开启自动提交功能。若要使用自己的 Connection 实例,传递一个 Connection 实例给 connection 参数即可。注意,我们没有提供同时设置Connection
和autoCommit
的方法,这是因为 MyBatis 会依据传入的Connection
来决定是否启用autoCommit
。对于事务隔离级别,MyBatis 使用了一个 Java 枚举包装器来表示,称为TransactionIsolationLevel
,事务隔离级别支持 JDBC 的五个隔离级别(NONE、READ_UNCOMMITTED、READ_COMMITTED、REPEATABLE_READ 和 SERIALIZABLE
),并且与预期的行为一致。
你可能对 ExecutorType 参数感到陌生。这个枚举类型定义了三个值:
ExecutorType.SIMPLE
:该类型的执行器没有特别的行为。它为每个语句的执行创建一个新的预处理语句。ExecutorType.REUSE
:该类型的执行器会复用预处理语句。ExecutorType.BATCH
:该类型的执行器会批量执行所有更新语句,如果 SELECT 在多个更新中间执行,将在必要时将多条更新语句分隔开来,以方便理解。
批量操作是在
mit()
以后才发送sql语句给数据库进行执行的如果我们想让其提前执行,以方便后续可能的查询操作获取数据,我们可以使用
sqlSession.flushStatements()
方法,让其直接冲刷到数据库进行执行。
提示在SqlSessionFactory
中还有一个方法我们没有提及,就是getConfiguration
()。这个方法会返回一个Configuration
实例,你可以在运行时使用它来检查 MyBatis 的配置。
提示如果你使用过 MyBatis 的旧版本,可能还记得 session、事务和批量操作是相互独立的。在新版本中则不是这样。上述三者都包含在 session 作用域内。你不必分别处理事务或批量操作就能得到想要的全部效果。
默认的openSession() 方法没有参数,它会创建有如下特性的
会开启一个事务(也就是不自动提交)连接对象会从由活动环境配置的数据源实例得到。事务隔离级别将会使用驱动或数据源的默认设置。预处理语句不会被复用,也不会批量处理更新。
【3】非线程安全的SqlSession
使用 MyBatis 的主要 Java 接口就是 SqlSession。你可以通过这个接口来执行命令,获取映射器实例和管理事务。
每个线程都有自己的SqlSession 实例,SqlSession 实例是不能被共享,也不是线程安全的
。因此最好使用request 作用域
或者方法体作用域
。
不要使用类的静态变量来引用一个SqlSession 实例,甚至不要使用类的一个实例变量来引用。否则,会有线程安全问题。
永远不要在一个被管理域中引用SqlSession
比如说在Servlet 中的HttpSession 中。如果你正在使用WEB 框架,应该让SqlSession 跟随HTTP 请求的相似作用域。也就是说,在收到一个HTTP 请求过后,打开SqlSession,等返回一个回应以后,立马关掉这个SqlSession。关闭SqlSession 是非常重要的,你必须要确保SqlSession 在finally 方法体中正常关闭。
SqlSession可以直接调用方法的id进行数据库操作
,但是我们一般还是推荐使用SqlSession获取到Dao接口的代理类,执行代理对象的方法,可以更安全的进行类型检查操作。
如下代码所示,是调用方法ID进行数据库操作:
SqlSessionFactory sqlSessionFactory = getSqlSessionFactory();SqlSession openSession = sqlSessionFactory.openSession();try {Employee employee = openSession.selectOne("com.mybatis.EmployeeMapper.selectEmp", 1);System.out.println(employee);} finally {openSession.close();}
正如之前所提到的,SqlSession 在 MyBatis 中是非常强大的一个类。它包含了所有执行语句、提交或回滚事务以及获取映射器实例的方法。
SqlSession 类的方法超过了 20 个,为了方便理解,我们将它们分成几种组别。
语句执行方法
这些方法被用来执行定义在 SQL 映射 XML 文件中的SELECT、INSERT、UPDATE 和 DELETE
语句。你可以通过名字快速了解它们的作用,每一方法都接受语句的 ID 以及参数对象,参数可以是原始类型(支持自动装箱或包装类)、JavaBean、POJO 或 Map。
<T> T selectOne(String statement, Object parameter)<E> List<E> selectList(String statement, Object parameter)<T> Cursor<T> selectCursor(String statement, Object parameter)<K,V> Map<K,V> selectMap(String statement, Object parameter, String mapKey)int insert(String statement, Object parameter)int update(String statement, Object parameter)int delete(String statement, Object parameter)
selectOne
和selectList
的不同仅仅是selectOne
必须返回一个对象或null
值。如果返回值多于一个,就会抛出异常。如果你不知道返回对象会有多少,请使用selectList
。如果需要查看某个对象是否存在,最好的办法是查询一个 count 值(0 或 1)
。selectMap
稍微特殊一点,它会将返回对象的其中一个属性作为key
值,将对象作为value
值,从而将多个结果集转为 Map 类型值。由于并不是所有语句都需要参数,所以这些方法都具有一个不需要参数的重载形式。
游标(Cursor)与列表(List)返回的结果相同,不同的是,游标借助迭代器实现了数据的惰性加载。
try (Cursor<MyEntity> entities = session.selectCursor(statement, param)) {for (MyEntity entity:entities) {// 处理单个实体}}insert、update 以及 delete 方法返回的值表示受该语句影响的行数。<T> T selectOne(String statement)<E> List<E> selectList(String statement)<T> Cursor<T> selectCursor(String statement)<K,V> Map<K,V> selectMap(String statement, String mapKey)int insert(String statement)int update(String statement)int delete(String statement)
最后,还有 select 方法的三个高级版本,它们允许你限制返回行数的范围,或是提供自定义结果处理逻辑,通常在数据集非常庞大的情形下使用。
<E> List<E> selectList (String statement, Object parameter, RowBounds rowBounds)<T> Cursor<T> selectCursor(String statement, Object parameter, RowBounds rowBounds)<K,V> Map<K,V> selectMap(String statement, Object parameter, String mapKey, RowBounds rowbounds)void select (String statement, Object parameter, ResultHandler<T> handler)void select (String statement, Object parameter, RowBounds rowBounds, ResultHandler<T> handler)
RowBounds
参数会告诉 MyBatis 略过指定数量的记录,并限制返回结果的数量。RowBounds
类的offset 和 limit
值只有在构造函数时才能传入,其它时候是不能修改的。
int offset = 100;int limit = 25;RowBounds rowBounds = new RowBounds(offset, limit);
数据库驱动决定了略过记录时的查询效率。为了获得最佳的性能,建议将ResultSet
类型设置为SCROLL_SENSITIVE
或SCROLL_INSENSITIVE
(换句话说:不要使用 FORWARD_ONLY
)。
ResultHandler
参数允许自定义每行结果的处理过程。你可以将它添加到 List 中、创建 Map 和 Set,甚至丢弃每个返回值,只保留计算后的统计结果。你可以使用 ResultHandler 做很多事,这其实就是 MyBatis 构建 结果列表的内部实现办法。
从版本 3.4.6 开始,ResultHandler
会在存储过程的REFCURSOR
输出参数中传递使用的CALLABLE
语句。
它的接口很简单:
package org.apache.ibatis.session;public interface ResultHandler<T> {void handleResult(ResultContext<? extends T> context);}
ResultContext
参数允许你访问结果对象和当前已被创建的对象数目,另外还提供了一个返回值为Boolean 的 stop
方法,你可以使用此stop
方法来停止 MyBatis 加载更多的结果。
使用ResultHandler
的时候需要注意以下两个限制:
使用带ResultHandler
参数的方法时,收到的数据不会被缓存。当使用高级的结果映射集(resultMap
)时,MyBatis 很可能需要数行结果来构造一个对象。如果你使用了ResultHandler
,你可能会接收到关联(association
)或者集合(collection
)中尚未被完整填充的对象。
立即批量更新方法
当你将ExecutorType
设置为ExecutorType.BATCH
时,可以使用这个方法清除(执行)缓存在 JDBC 驱动类中的批量更新语句。
List<BatchResult> flushStatements()
事务控制方法
有四个方法用来控制事务作用域。当然,如果你已经设置了自动提交或你使用了外部事务管理器,这些方法就没什么作用了。然而,如果你正在使用由 Connection 实例控制的 JDBC 事务管理器,那么这四个方法就会派上用场:
void commit()void commit(boolean force)void rollback()void rollback(boolean force)
默认情况下 MyBatis 不会自动提交事务,除非它侦测到调用了插入、更新或删除方法改变了数据库
。如果你没有使用这些方法提交修改,那么你可以在commit
和rollback
方法参数中传入 true 值,来保证事务被正常提交(注意,在自动提交模式或者使用了外部事务管理器的情况下,设置 force 值对 session 无效)。大部分情况下你无需调用rollback()
,因为MyBatis
会在你没有调用commit
时替你完成回滚操作。不过,当你要在一个可能多次提交或回滚的 session 中详细控制事务,回滚操作就派上用场了。
提示MyBatis-Spring 和 MyBatis-Guice
提供了声明式事务处理,所以如果你在使用 Mybatis 的同时使用了 Spring 或者 Guice,请参考它们的手册以获取更多的内容。
本地缓存
Mybatis 使用到了两种缓存:本地缓存(local cache)和二级缓存(second level cache)
。
每当一个新 session 被创建,MyBatis 就会创建一个与之相关联的本地缓存。任何在 session 执行过的查询结果都会被保存在本地缓存中,所以,当再次执行参数相同的相同查询时,就不需要实际查询数据库了。本地缓存将会在做出修改、事务提交或回滚,以及关闭 session 时清空。
默认情况下,本地缓存数据的生命周期等同于整个 session 的周期
。由于缓存会被用来解决循环引用问题和加快重复嵌套查询的速度,所以无法将其完全禁用。但是你可以通过设置localCacheScope=STATEMENT
来只在语句执行时使用缓存。
注意,如果localCacheScope
被设置为SESSION
,对于某个对象,MyBatis 将返回在本地缓存中唯一对象的引用。对返回的对象(例如 list)做出的任何修改将会影响本地缓存的内容,进而将会影响到在本次session
中从缓存返回的值。因此,不要对 MyBatis 所返回的对象作出更改,以防后患。
你可以随时调用以下方法来清空本地缓存:
void clearCache()
确保 SqlSession 被关闭
void close()
对于你打开的任何session
,你都要保证它们被妥善关闭,这很重要。保证妥善关闭的最佳代码模式是这样的:
SqlSession session = sqlSessionFactory.openSession();try (SqlSession session = sqlSessionFactory.openSession()) {// 假设下面三行代码是你的业务逻辑session.insert(...);session.update(...);session.delete(...);mit();}
提示和SqlSessionFactory
一样,你可以调用当前使用的SqlSession
的getConfiguration
方法来获得Configuration
实例。
Configuration getConfiguration()
使用映射器
<T> T getMapper(Class<T> type)
上述的各个insert、update、delete 和 select
方法都很强大,但也有些繁琐,它们并不符合类型安全,对你的 IDE 和单元测试也不是那么友好。因此,使用映射器类来执行映射语句是更常见的做法。
我们已经在之前的入门章节中见到过一个使用映射器的示例。一个映射器类就是一个仅需声明与 SqlSession 方法相匹配方法的接口。下面的示例展示了一些方法签名以及它们是如何映射到 SqlSession 上的。
public interface AuthorMapper {// (Author) selectOne("selectAuthor",5);Author selectAuthor(int id);// (List<Author>) selectList(“selectAuthors”)List<Author> selectAuthors();// (Map<Integer,Author>) selectMap("selectAuthors", "id")@MapKey("id")Map<Integer, Author> selectAuthors();// insert("insertAuthor", author)int insertAuthor(Author author);// updateAuthor("updateAuthor", author)int updateAuthor(Author author);// delete("deleteAuthor",5)int deleteAuthor(int id);}
总之,每个映射器方法签名应该匹配相关联的 SqlSession 方法,字符串参数 ID 无需匹配。而是由方法名匹配映射语句的 ID
。
此外,返回类型必须匹配期望的结果类型,返回单个值时,返回类型应该是返回值的类,返回多个值时,则为数组或集合类,另外也可以是游标(Cursor)
。所有常用的类型都是支持的,包括:原始类型、Map、POJO 和 JavaBean
。
提示映射器接口不需要去实现任何接口或继承自任何类。只要方法签名可以被用来唯一识别对应的映射语句就可以了。
提示映射器接口可以继承自其他接口。在使用 XML 来绑定映射器接口时,保证语句处于合适的命名空间中即可。唯一的限制是,不能在两个具有继承关系的接口中拥有相同的方法签名(这是潜在的危险做法,不可取)。
你可以传递多个参数给一个映射器方法。在多个参数的情况下,默认它们将会以 param 加上它们在参数列表中的位置来命名,比如:#{param1}、#{param2}
等。如果你想(在有多个参数时)自定义参数的名称,那么你可以在参数上使用@Param("paramName")
注解。
你也可以给方法传递一个RowBounds
实例来限制查询结果。
映射器注解
设计初期的 MyBatis 是一个 XML 驱动的框架。配置信息是基于 XML 的,映射语句也是定义在 XML 中的。而在 MyBatis 3 中,我们提供了其它的配置方式。MyBatis 3 构建在全面且强大的基于 Java 语言的配置 API 之上。它是 XML 和注解配置的基础。注解提供了一种简单且低成本的方式来实现简单的映射语句。
提示不幸的是,Java 注解的表达能力和灵活性十分有限。尽管我们花了很多时间在调查、设计和试验上,但最强大的 MyBatis 映射并不能用注解来构建——我们真没开玩笑。而C#
属性就没有这些限制,因此的配置会比 XML 有更大的选择余地。虽说如此,基于 Java 注解的配置还是有它的好处的。
映射注解示例
这个例子展示了如何使用@SelectKey
注解来在插入前读取数据库序列的值:
@Insert("insert into table3 (id, name) values(#{nameId}, #{name})")@SelectKey(statement="call next value for TestSequence", keyProperty="nameId", before=true, resultType=int.class)int insertTable3(Name name);
这个例子展示了如何使用@SelectKey
注解来在插入后读取数据库自增列的值:
@Insert("insert into table2 (name) values(#{name})")@SelectKey(statement="call identity()", keyProperty="nameId", before=false, resultType=int.class)int insertTable2(Name name);
这个例子展示了如何使用@Flush
注解来调用SqlSession#flushStatements()
:
@FlushList<BatchResult> flush();
这些例子展示了如何通过指定@Result 的 id
属性来命名结果集:
@Results(id = "userResult", value = {@Result(property = "id", column = "uid", id = true),@Result(property = "firstName", column = "first_name"),@Result(property = "lastName", column = "last_name")})@Select("select * from users where id = #{id}")User getUserById(Integer id);@Results(id = "companyResults")@ConstructorArgs({@Arg(column = "cid", javaType = Integer.class, id = true),@Arg(column = "name", javaType = String.class)})@Select("select * from company where id = #{id}")Company getCompanyById(Integer id);
这个例子展示了如何使用单个参数的@SqlProvider
注解:
@SelectProvider(type = UserSqlBuilder.class, method = "buildGetUsersByName")List<User> getUsersByName(String name);class UserSqlBuilder {public static String buildGetUsersByName(final String name) {return new SQL(){{SELECT("*");FROM("users");if (name != null) {WHERE("name like #{value} || '%'");}ORDER_BY("id");}}.toString();}}
这个例子展示了如何使用多个参数的@SqlProvider
注解:
@SelectProvider(type = UserSqlBuilder.class, method = "buildGetUsersByName")List<User> getUsersByName(@Param("name") String name, @Param("orderByColumn") String orderByColumn);class UserSqlBuilder {// 如果不使用 @Param,就应该定义与 mapper 方法相同的参数public static String buildGetUsersByName(final String name, final String orderByColumn) {return new SQL(){{SELECT("*");FROM("users");WHERE("name like #{name} || '%'");ORDER_BY(orderByColumn);}}.toString();}// 如果使用 @Param,就可以只定义需要使用的参数public static String buildGetUsersByName(@Param("orderByColumn") final String orderByColumn) {return new SQL(){{SELECT("*");FROM("users");WHERE("name like #{name} || '%'");ORDER_BY(orderByColumn);}}.toString();}}
以下例子展示了通过使用全局配置Configuration 来实现所有mapper方法共享一个 sql provider 类(3.5.6后可用):
Configuration configuration = new Configuration();configuration.setDefaultSqlProviderType(TemplateFilePathProvider.class);// Specify an sql provider class for sharing on all mapper methods// ...// Can omit the type/value attribute on sql provider annotation// If omit it, the MyBatis apply the class that specified on defaultSqlProviderType.public interface UserMapper {@SelectProvider // Same with @SelectProvider(TemplateFilePathProvider.class)User findUser(int id);@InsertProvider // Same with @InsertProvider(TemplateFilePathProvider.class)void createUser(User user);@UpdateProvider // Same with @UpdateProvider(TemplateFilePathProvider.class)void updateUser(User user);@DeleteProvider // Same with @DeleteProvider(TemplateFilePathProvider.class)void deleteUser(int id);}
以下例子展示了ProviderMethodResolver
(3.5.1 后可用)的默认实现使用方法:
@SelectProvider(UserSqlProvider.class)List<User> getUsersByName(String name);// 在你的 provider 类中实现 ProviderMethodResolver 接口class UserSqlProvider implements ProviderMethodResolver {// 默认实现中,会将映射器方法的调用解析到实现的同名方法上public static String getUsersByName(final String name) {return new SQL(){{SELECT("*");FROM("users");if (name != null) {WHERE("name like #{value} || '%'");}ORDER_BY("id");}}.toString();}}
以下例子展示了如何在注解上使用databaseId (3.5.5后可用):
@Select(value = "SELECT SYS_GUID() FROM dual", databaseId = "oracle") // Use this statement if DatabaseIdProvider provide "oracle"@Select(value = "SELECT uuid_generate_v4()", databaseId = "postgres") // Use this statement if DatabaseIdProvider provide "postgres"@Select("SELECT RANDOM_UUID()") // Use this statement if the DatabaseIdProvider not configured or not matches databaseIdString generateId();
参考博文:
MyBatis中XML映射器使用详解
Mybatis中一级缓存和二级缓存使用详解