<?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 | Getting Started</title>
    <author email="hpresnall@gmail.com">Hunter Presnall</author>
    <author email="eduardo.macarron@gmail.com">Eduardo Macarron</author>
  </properties>

  <body>
    <section name="Getting Started">
      <p>
        This chapter will show you in a few steps how to install and setup
        MyBatis-Spring and how to build
        a simple transactional application.
      </p>

    <subsection name="Installation">
      <p>
        To use the MyBatis-Spring module, you just need to include the
        <code>mybatis-spring-${project.version}.jar</code>
        file and its dependencies in the classpath.
      </p>
      <p>
        If you are using Maven just add the following dependency
        to your
        pom.xml:
      </p>
        <source><![CDATA[
<dependency>
  <groupId>org.mybatis</groupId>
  <artifactId>mybatis-spring</artifactId>
  <version>${project.version}</version>
</dependency>]]></source>
    </subsection>

    <subsection name="Quick Setup">
      <p>
        To use MyBatis with Spring you need at least two things defined in
        the
        Spring application context: an
        <code>SqlSessionFactory</code>
        and
        at least one mapper interface.
      </p>

      <p>
        In MyBatis-Spring, an
        <code>SqlSessionFactoryBean</code>
        is used to
        create an
        <code>SqlSessionFactory</code>
        . To configure the
        factory bean, put the following in the Spring
        configuration file:
      </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>
        Notice that the
        <code>SqlSessionFactory</code>
        requires a
        <code>DataSource</code>
        . This can be any
        <code>DataSource</code>
        and should be configured just like any other Spring database
        connection.
      </p>

      <p>
        Assume you have a mapper interface defined like the following:
      </p>
        <source><![CDATA[public interface UserMapper {
  @Select("SELECT * FROM users WHERE id = #{userId}")
  User getUser(@Param("userId") String userId);
} ]]></source>

      <p>
        This interface is added to Spring using a
        <code>MapperFactoryBean</code>
        like the following:
      </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>
        Note that the mapper class specified
        <strong>must</strong>
        be an
        interface, not an actual implementation class. In this example,
        annotations are used to specify the SQL, but a MyBatis mapper XML
        file
        could also be used.
      </p>

      <p>
        Once configured, you can inject mappers directly into your
        business/service objects in the same way you inject any other Spring
        bean. The <code>MapperFactoryBean</code>
        handles creating an <code>SqlSession</code>
        as well as closing it. If there is a Spring transaction in
        progress,
        the session will also be committed or rolled back when the
        transaction completes. Finally, any exceptions will be translated
        into Spring <code>DataAccessException</code>s.
      </p>

      <p>
        If you use the Java Configuration:
      </p>

      <source><![CDATA[
@Bean
public UserMapper userMapper() throws Exception {
  SqlSessionTemplate sqlSessionTemplate = new SqlSessionTemplate(sqlSessionFactory());
  return sqlSessionTemplate.getMapper(UserMapper.class);
}]]></source>

      <p>
        Calling MyBatis data methods is now only one line of code:
      </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>
