<?xml version="1.0" encoding="UTF-8"?>
<!--

    Copyright ${license.git.copyrightYears} the original author or authors.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

-->
<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

  <properties>
    <title>MyBatis-Spring | 入门</title>
    <author email="hpresnall@gmail.com">Hunter Presnall</author>
    <author email="eduardo.macarron@gmail.com">Eduardo Macarron</author>
    <author email="nanlei1987@gmail.com">Nan Lei</author>
  </properties>

  <body>
    <section name="入门">
      <p>
      本章将会以简略的步骤告诉你如何安装和配置 MyBatis-Spring，并构建一个简单的具备事务管理功能的数据访问应用程序。
      </p>

    <subsection name="安装">
      <p>
      要使用 MyBatis-Spring 模块，只需要在类路径下包含 <code>mybatis-spring-${project.version}.jar</code> 文件和相关依赖即可。
      </p>
      <p>
      如果使用 Maven 作为构建工具，仅需要在 pom.xml 中加入以下代码即可：
      </p>
        <source><![CDATA[
<dependency>
  <groupId>org.mybatis</groupId>
  <artifactId>mybatis-spring</artifactId>
  <version>${project.version}</version>
</dependency>]]></source>
    </subsection>

    <subsection name="快速上手">
      <p>
      要和 Spring 一起使用 MyBatis，需要在 Spring 应用上下文中定义至少两样东西：一个 <code>SqlSessionFactory</code> 和至少一个数据映射器类。
      </p>

      <p>
      在 MyBatis-Spring 中，可使用 <code>SqlSessionFactoryBean</code>来创建 <code>SqlSessionFactory</code>。
      要配置这个工厂 bean，只需要把下面代码放在 Spring 的 XML 配置文件中：
      </p>

        <source><![CDATA[
<bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean">
  <property name="dataSource" ref="dataSource" />
</bean>]]></source>

      <source><![CDATA[
@Bean
public SqlSessionFactory sqlSessionFactory() throws Exception {
  SqlSessionFactoryBean factoryBean = new SqlSessionFactoryBean();
  factoryBean.setDataSource(dataSource());
  return factoryBean.getObject();
}]]></source>

      <p>
      注意：<code>SqlSessionFactory</code> 需要一个 <code>DataSource</code>（数据源）。
      这可以是任意的 <code>DataSource</code>，只需要和配置其它 Spring 数据库连接一样配置它就可以了。
      </p>

      <p>
      假设你定义了一个如下的 mapper 接口：
      </p>
        <source><![CDATA[public interface UserMapper {
  @Select("SELECT * FROM users WHERE id = #{userId}")
  User getUser(@Param("userId") String userId);
} ]]></source>

      <p>
      那么可以通过 <code>MapperFactoryBean</code> 将接口加入到 Spring 中:
      </p>

        <source><![CDATA[
<bean id="userMapper" class="org.mybatis.spring.mapper.MapperFactoryBean">
  <property name="mapperInterface" value="org.mybatis.spring.sample.mapper.UserMapper" />
  <property name="sqlSessionFactory" ref="sqlSessionFactory" />
</bean>]]></source>

      <p>
      需要注意的是：所指定的映射器类<b>必须</b>是一个接口，而不是具体的实现类。在这个示例中，通过注解来指定 SQL 语句，但是也可以使用 MyBatis 映射器的 XML 配置文件。
      </p>

      <p>
      配置好之后，你就可以像 Spring 中普通的 bean 注入方法那样，将映射器注入到你的业务或服务对象中。<code>MapperFactoryBean</code> 将会负责 <code>SqlSession</code> 的创建和关闭。如果使用了 Spring 的事务功能，那么当事务完成时，session 将会被提交或回滚。最终任何异常都会被转换成 Spring 的 <code>DataAccessException</code> 异常。
      </p>

      <p>
      使用 Java 代码来配置的方式如下：
      </p>
       <source><![CDATA[
@Bean
public UserMapper userMapper() throws Exception {
  SqlSessionTemplate sqlSessionTemplate = new SqlSessionTemplate(sqlSessionFactory());
  return sqlSessionTemplate.getMapper(UserMapper.class);
}]]></source>

      <p>
      要调用 MyBatis 的数据方法，只需一行代码：
      </p>
      <source><![CDATA[
public class FooServiceImpl implements FooService {

  private final UserMapper userMapper;

  public FooServiceImpl(UserMapper userMapper) {
    this.userMapper = userMapper;
  }

  public User doSomeBusinessStuff(String userId) {
    return this.userMapper.getUser(userId);
  }
}]]></source>
      </subsection>
    </section>
  </body>
</document>
