<?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 | Sample Code</title>
		<author email="eduardo.macarron@gmail.com">Eduardo Macarron</author>
	</properties>

	<body>
		<section name="Sample Code">

			<p>
				<span class="label important">NOTE</span>
				See <a href="https://github.com/mybatis/jpetstore-6">JPetstore 6 demo</a> to know about how to use Spring with a full web application server.
			</p>

			<p>
				You can check out sample code from the MyBatis-Spring <a href="https://github.com/mybatis/spring/tree/master/src/test/java/org/mybatis/spring/sample">repo</a>:
			</p>
			<p>
				Any of the samples can be run with JUnit 5.
			</p>
			<p>
				The sample code shows a typical design where a transactional service gets domain objects from a data access layer.
			</p>
			<p>
				<code>FooService.java</code> acts as the service:
			</p>
			<source><![CDATA[
@Transactional
public class FooService {

  private final UserMapper userMapper;

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

  public User doSomeBusinessStuff(String userId) {
    return this.userMapper.getUser(userId);
  }

}
]]></source>
			<p>
				It is a transactional bean, so when the method is called, the transaction is started 
				and the transaction is committed when the method ends without throwing an uncaught exception.
				Notice that transactional behaviour is configured with the
				<code>@Transactional</code>
				attribute. This is not required; any other way provided by Spring can be used to demarcate
				your transactions.
			</p>
			<p>
				This service calls a data access layer built with MyBatis. This layer
				consists on a just an interface <code>UserMapper.java</code>
				that will be used with a dynamic proxy built by MyBatis at
				runtime and injected into the service by Spring.
			</p>
			<source><![CDATA[
public interface UserMapper {

  User getUser(String userId);

}
]]></source>			
			<p> 
			    Note that, for the sake of simplicity we used the interface <code>UserMapper.java</code> for the DAO scenario
			    where a DAO is built with an interface and a implementation though in this case it would have been more
			    adequate to use an interface called <code>UserDao.java</code> instead.
			</p>
			<p>
				We will see different ways to find the mapper interface, register it to Spring and inject it into the service bean:
			</p>
			<table>
				<caption>Scenarios</caption>
				<thead>
					<tr>
						<th>Sample test</th>
						<th>Description</th>
					</tr>
				</thead>
				<tbody>
					<tr>
						<td>
							<code>SampleMapperTest.java</code>
						</td>
						<td>
							Shows you the base configuration based on a <code>MapperFactoryBean</code>
							that will dynamically build an implementation for <code>UserMapper</code>
						</td>
					</tr>
					<tr>
						<td>
							<code>SampleScannerTest.java</code>
						</td>
						<td>
							Shows how to use the <code>MapperScannerConfigurer</code> so all the mappers in a project are autodiscovered.
						</td>
					</tr>
					<tr>
						<td>
							<code>SampleSqlSessionTest.java</code>
						</td>
						<td>
							Shows how to hand code a DAO using a Spring managed <code>SqlSession</code>
							and providing your own implementation <code>UserDaoImpl.java</code>.
						</td>
					</tr>
					<tr>
						<td>
							<code>SampleEnableTest</code>
						</td>
						<td>
							Shows how to use Spring's <code>@Configuration</code> with the <code>@MapperScann</code> annotation so
							mappers are autodiscovered.
						</td>
					</tr>
					<tr>
						<td>
							<code>SampleNamespaceTest</code>
						</td>
						<td>
							Shows how to use the custom MyBatis XML namespace. 
						</td>
					</tr>
          <tr>
            <td>
              <code>SampleJavaConfigTest.java</code>
            </td>
            <td>
              Shows how to use Spring's <code>@Configuration</code> to create MyBatis beans manually.
            </td>
          </tr>
          <tr>
            <td>
              <code>SampleJobJavaConfigTest.java</code>
            </td>
            <td>
              Shows how to use <code>ItemReader</code> and <code>ItemWriter</code> on Spring Batch using Java Configuration.
            </td>
          </tr>
          <tr>
            <td>
              <code>SampleJobXmlConfigTest.java</code>
            </td>
            <td>
              Shows how to use <code>ItemReader</code> and <code>ItemWriter</code> on Spring Batch using XML Configuration.
            </td>
          </tr>
				</tbody>
			</table>
			<p>
				Please take a look at the different <code>applicationContext.xml</code> files to see MyBatis-Spring in action.
			</p>

		</section>
	</body>
</document>

