Installation

To use the MyBatis you just need to include the mybatis-x.x.x.jar file in the classpath.

If you are using Maven just add the following dependency to your pom.xml:

<dependency>
  <groupId>org.mybatis</groupId>
  <artifactId>mybatis</artifactId>
  <version>x.x.x</version>
</dependency>

从 XML 中构建 SqlSessionFactory

每 一 个 MyBatis 的 应 用 程 序 都 以 一 个 SqlSessionFactory 对 象 的 实 例 为 核 心 。 SqlSessionFactory 对 象 的 实 例 可 以 通 过 SqlSessionFactoryBuilder 对 象 来 获 得 。 SqlSessionFactoryBuilder 对象可以从 XML 配置文件,或从 Configuration 类的习惯准备的实 例中构建 SqlSessionFactory 对象。

从 XML 文件中构建 SqlSessionFactory 的实例非常简单。这里建议你使用类路径下的资 源文件来配置,但是你可以使用任意的 Reader 实例,这个实例包括由文字形式的文件路径 或 URL 形式的文件路径 file://来创建。MyBatis 包含了一些工具类,称作为资源,这些工具 类包含一些方法,这些方法使得从类路径或其他位置加载资源文件更加简单。

String resource = "org/mybatis/example/mybatis-config.xml";
InputStream inputStream = Resources.getResourceAsStream(resource);
sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream);

XML 配置文件包含对 MyBatis 系统的核心设置,包含获取数据库连接实例的数据源和 决定事务范围和控制的事务管理器。关于 XML 配置文件的详细内容可以在文档后面找到, 这里给出一个简单的示例:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE configuration
  PUBLIC "-//mybatis.org//DTD Config 3.0//EN"
  "http://mybatis.org/dtd/mybatis-3-config.dtd">
<configuration>
  <environments default="development">
    <environment id="development">
      <transactionManager type="JDBC"/>
      <dataSource type="POOLED">
        <property name="driver" value="${driver}"/>
        <property name="url" value="${url}"/>
        <property name="username" value="${username}"/>
        <property name="password" value="${password}"/>
      </dataSource>
    </environment>
  </environments>
  <mappers>
    <mapper resource="org/mybatis/example/BlogMapper.xml"/>
  </mappers>
</configuration>

当然, XML 配置文件中还有很多可以配置的, 在 上面的示例指出的则是最关键的部分。 要注意 XML 头部的声明,需要用来验证 XML 文档正确性。environment 元素体中包含对事 务管理和连接池的环境配置。 mappers 元素是包含所有 mapper 映射器) ( 的列表, 这些 mapper 的 XML 文件包含 SQL 代码和映射定义信息。

不使用 XML 构建 SqlSessionFactory

如果你喜欢从 Java 程序而不是 XML 文件中直接创建配置实例, 或创建你自己的配置构 建器,MyBatis 也提供完整的配置类,提供所有从 XML 文件中加载配置信息的选项。

DataSource dataSource = BlogDataSourceFactory.getBlogDataSource();
TransactionFactory transactionFactory = new JdbcTransactionFactory();
Environment environment = new Environment("development", transactionFactory, dataSource);
Configuration configuration = new Configuration(environment);
configuration.addMapper(BlogMapper.class);
SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(configuration);

注意这种情况下配置是添加映射类。映射类是 Java 类,这些类包含 SQL 映射语句的注 解从而避免了 XML 文件的依赖, XML 映射仍然在大多数高级映射 (比如: 嵌套 Join 映射) 时需要。出于这样的原因,如果存在 XML 配置文件的话,MyBatis 将会自动查找和加载一 个对等的 XML 文件(这种情况下,基于类路径下的 BlogMapper.class 类的类名,那么 BlogMapper.xml 将会被加载)。后面我们会了解更多。

从 SqlSessionFactory 中获取 SqlSession

现在,我们已经知道如何获取 SqlSessionFactory 对象了,基于同样的启示,我们就可以 获得 SqlSession 的实例了。 SqlSession 对象完全包含以数据库为背景的所有执行 SQL 操作的 方法。你可以用 SqlSession 实例来直接执行已映射的 SQL 语句。例如:

SqlSession session = sqlSessionFactory.openSession();
try {
  Blog blog = (Blog) session.selectOne("org.mybatis.example.BlogMapper.selectBlog", 101);
} finally {
  session.close();
}

这种方法起到的作用, 和我们使用之前的 MyBatis 版本是相似的, 现在有一种更简洁的 方法。使用合理描述参数和 SQL 语句返回值的接口(比如 BlogMapper.class) ,这样现在就 可以至此那个更简单,更安全的代码,没有容易发生的字符串文字和转换的错误。

例如:

SqlSession session = sqlSessionFactory.openSession();
try {
  BlogMapper mapper = session.getMapper(BlogMapper.class);
  Blog blog = mapper.selectBlog(101);
} finally {
  session.close();
}

现在我们来探究一下这里到底执行了什么。

探究已映射的 SQL 语句

这里你也许想知道通过 SqlSession 和 Mapper 对象到底执行了什么操作。已映射的 SQL 语句是一个很大的主题, 而且这个主题会贯穿本文档的大部分内容。 为了给出一个宏观的概 念,这里有一些示例。 上面提到的任何一个示例,语句是通过 XML 或注解定义的。我们先来看看 XML。使 用基于 XML 的映射语言,在过去的几年中使得 MyBatis 非常流行,他为 MyBatis 提供所有 的特性设置。如果你以前用过 MyBatis,这个概念应该很熟悉了,但是 XML 映射文件也有 很多的改进,后面我们会详细来说。这里给出一个基于 XML 映射语句的示例,这些语句应 该可以满足上述示例中 SqlSession 对象的调用。

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE mapper
  PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
  "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="org.mybatis.example.BlogMapper">
  <select id="selectBlog" parameterType="int" resultType="Blog">
    select * from Blog where id = #{id}
  </select>
</mapper>

这个简单的例子中看起来有很多额外的东西, 但是也相当简洁了。 你可以在一个单独的 XML 映射文件中定义很多的映射语句,除 XML 头部和文档类型声明之外,你可以得到很 多 方 便 之 处 。 在 文 件 的 剩 余 部 分 是 很 好 的 自 我 解 释 。 在 命 名 空 间 “com.mybatis.example.BlogMapper”中,它定义了一个名为“selectBlog”的映射语句,这 样它允许你使用完全限定名 “org.mybatis.example.BlogMapper.selectBlog” 来调用映射语句, 我们下面示例中所有的写法也是这样的。

Blog blog = (Blog) session.selectOne("org.mybatis.example.BlogMapper.selectBlog", 101);

要注意这个使用完全限定名调用 Java 对象的方法是相似的,这样做是有原因的。这个 命名可以直接给相同命名空间下的的映射类, 使用一个名称, 参数和返回值和已映射的查询 语句都一样的方法即可。 这就允许你非常容易地调用映射器接口中的方法, 这和你前面看到 的是一样的,下面这个示例中它又出现了。

BlogMapper mapper = session.getMapper(BlogMapper.class);
Blog blog = mapper.selectBlog(101);

第二种方式有很多有点,首先它不是基于文字的,那就更安全了。第二,如果你的 IDE 有代码补全功能,那么你可以利用它来操纵已映射的 SQL 语句。第三,不需要强制类型转 换,同时 BlogMapper 接口可以保持简洁,返回值类型很安全(参数类型也很安全) 。

重要 命名空间的一点注释

命名空间 在之前版本的 MyBatis 中是可选项,非常混乱也没有帮助。现在,命名空间 是必须的,而且有一个目的,它使用更长的完全限定名来隔离语句。

命名空间使得接口绑定成为可能,就像你看到的那样,如果之前不了解,那么现在你 就会使用它们了,你应该按照下面给出示例的来练习,以免改变自己的想法。使用命名空 间,并将它放在合适的 Java 包空间之下,将会使你的代码变得简洁,在很长的时间内提高 MyBatis 的作用。

命名解析: 为了减少输入量,MyBatis 对所有的命名配置元素使用如下的命名解析规 则,包括语句,结果映射,缓存等。

• 直接查找完全限定名(比如“com.mypackage.MyMapper.selectAllThings”,如果 ) 发现就使用。
• 短名称(比如“selectAllThings” )可以用来引用任意含糊的对象。而如果有两个 或两个以上的(比如“com.foo.selectAllThings ”和“com.bar.selectAllThings” ), 那么就会得到错误报告,说短名称是含糊的,因此就必须使用完全限定名。

如 BlogMapper 这样的映射器类来说,还有一个妙招。它们中间映射的语句可以不需要 在 XML 中来写,而可以使用 Java 注解来替换。比如,上面的 XML 示例可以如下来替换:

package org.mybatis.example;
public interface BlogMapper {
  @Select("SELECT * FROM blog WHERE id = #{id}")
  Blog selectBlog(int id);
}

对于简单语句来说,使用注解代码会更加清晰,然而 Java 注解对于复杂语句来说就会 混乱, 应该限制使用。 因此, 如果你不得不做复杂的事情, 那么最好使用 XML 来映射语句。

当然这也取决于你和你的项目团队的决定, 看哪种更适合你来使用, 还有以长久方式来 使用映射语句的重要性。也就是说,不要将自己局限在一种方式中。你可以轻松地将注解换 成 XML 映射语句,反之亦然。

范围和生命周期

理解我们目前已经讨论过的不同范围和生命周期类是很重要的。 不正确的使用它们会导 致严重的并发问题。

SqlSession session = sqlSessionFactory.openSession();
try {
  // do work
} finally {
  session.close();
}

SqlSession session = sqlSessionFactory.openSession();
try {
  BlogMapper mapper = session.getMapper(BlogMapper.class);
  // do work
} finally {
  session.close();
}