<commit_before><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
    Copyright 2010 The myBatis Team

    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.
-->

<!--
    version: $Id$
-->
<chapter id="templates_support">
  <title>SqlSessionTemplate and SqlSessionDaoSupport</title>

  <section id="templates_support.template">
    <title>SqlSessionTemplate</title>

    <para>
      <literal>SqlSessionTemplate</literal> is the heart of MyBatis-Spring.
      This class is responsible for managing MyBatis
      <literal>SqlSession</literal>s, calling MyBatis SQL methods and
      translating exceptions. It is meant to be a drop-in replacement for
      <literal>SqlSession</literal>. <literal>SqlSessionTemplate</literal>
      should <emphasis>always</emphasis> be used instead of
      <literal>SqlSession</literal> because the base MyBatis session cannot
      participate in Spring transactions. Switching between the two classes in
      the same application can cause data integrity issues.
    </para>

    <para>
      When calling SQL methods, including any method from Mappers returned from
      <literal>getMapper()</literal>,  <literal>SqlSessionTemplate</literal>
      will ensure that the <literal>SqlSession</literal> used is the one
      associated with the current Spring transaction. In addition, it manages
      the session life-cycle, including closing, committing or rolling back as
      necessary.
    </para>

    <para>
      It is usually not necessary to create or use a
      <literal>SqlSessionTemplate</literal> directly. In most cases,
      <literal>MapperFactoryBean</literal>, which uses a template internally,
      will be all that is needed. When access to an
      <literal>SqlSessionTemplate</literal> is needed, it can be created using
      an <literal>SqlSessionFactory</literal> as a constructor argument.

      <programlisting language="java"><![CDATA[SqlSessionTemplate sessionTemplate = new SqlSessionTemplate(sqlSessionFactory);]]></programlisting>
      Similarly, the template could be configured in a Spring XML file.
    </para>

    <para>
      In addition to all the SQL related methods in
      <literal>SqlSession</literal>, <literal>SqlSessionTemplate</literal>
      offers a generic <literal>execute</literal> method. This method takes a
      custom <literal>SqlSessionCallback</literal> as an argument so that you
      can execute more than one SQL method on a <literal>SqlSession</literal>:
      <programlisting language="java"><![CDATA[public void insertUser(final User user) {
  getSqlSessionTemplate().execute(new SqlSessionCallback<Object>() {
    public Object doInSqlSession(SqlSession sqlSession) {
      sqlSession.insert("org.mybatis.spring.sample.mapper.UserMapper.insertUser", user);
      sqlSession.insert("org.mybatis.spring.sample.mapper.UserMapper.insertAccount", user.getAccount());
      return null;
    }
  });
}]]></programlisting>
    </para>

    <para>
      Note that the <literal>execute</literal> method can also accept a
      <literal>ExecutorType</literal> parameter. This can be used if the
      desired execution method differs from the default set for the
      SqlSessionFactory. This will mostly be useful for performing batch SQL
      queries using <literal>ExecutorType.BATCH</literal>. The only caveat to
      this form of the method is that there <emphasis>cannot</emphasis> be an
      existing transaction running with a different ExecutorType when this
      method is called. Either ensure that calls to
      <literal>execute(SqlSessionCallback, ExecutorType)</literal> run in a
      separate transaction, with PROPAGATION_REQUIRES_NEW or with completely
      outside of a transaction.
    </para>
  </section>

  <section id="templates_support.daosupport">
    <title>SqlSessionDaoSupport</title>

    <para>
      <literal>SqlSessionDaoSupport</literal> is an abstract support class that
      builds a <literal>SqlSessionTemplate</literal> for you. Calling
      <literal>getSqlSessionTemplate()</literal> gives you access to the
      template which can then be used to execute SQL methods, like the
      following:

      <programlisting language="java"><![CDATA[public class UserMapperDaoImpl extends SqlSessionDaoSupport implements UserMapper {
  public User getUser(String userId) {
    return (User) getSqlSessionTemplate()
        .selectOne("org.mybatis.spring.sample.mapper.UserMapper.getUser", userId);
  }
}]]></programlisting>

      Usually <literal>MapperFactoryBean</literal> is preferred to this class,
      since it requires no extra code. But, this class is useful if you need
      to do other non-MyBatis work in your DAO and concrete classes are
      required.
    </para>

    <para>
      <literal>SqlSessionDaoSupport</literal> is configured similarly to
      <literal>MapperFactoryBean</literal>. It requires either an
      <literal>sqlSessionFactory</literal> or an
      <literal>sqlSessionTemplate</literal> property to be set. These can be
      set explicitly or autowired by Spring. If both properties are set, the
      SqlSessionFactory is ignored.
    </para>

    <para>
      Assuming a class <literal>UserMapperImpl</literal> that subclasses
      <literal>SqlSessionDaoSupport</literal>, it can be configured in Spring
      like the following:

      <programlisting language="xml"><![CDATA[<bean id="userMapperImpl" class="sample.UserMapperImpl">
  <property name="sqlSessionFactory" ref="sqlSessionFactory" />
</bean>]]></programlisting>
    </para>
  </section>
</chapter><commit_msg>added a snippet from the code sample<commit_after><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
    Copyright 2010 The myBatis Team

    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.
-->

<!--
    version: $Id$
-->
<chapter id="templates_support">
  <title>SqlSessionTemplate and SqlSessionDaoSupport</title>

  <section id="templates_support.template">
    <title>SqlSessionTemplate</title>

    <para>
      <literal>SqlSessionTemplate</literal> is the heart of MyBatis-Spring.
      This class is responsible for managing MyBatis
      <literal>SqlSession</literal>s, calling MyBatis SQL methods and
      translating exceptions. It is meant to be a drop-in replacement for
      <literal>SqlSession</literal>. <literal>SqlSessionTemplate</literal>
      should <emphasis>always</emphasis> be used instead of
      <literal>SqlSession</literal> because the base MyBatis session cannot
      participate in Spring transactions. Switching between the two classes in
      the same application can cause data integrity issues.
    </para>

    <para>
      When calling SQL methods, including any method from Mappers returned from
      <literal>getMapper()</literal>,  <literal>SqlSessionTemplate</literal>
      will ensure that the <literal>SqlSession</literal> used is the one
      associated with the current Spring transaction. In addition, it manages
      the session life-cycle, including closing, committing or rolling back as
      necessary.
    </para>

    <para>
      It is usually not necessary to create or use a
      <literal>SqlSessionTemplate</literal> directly. In most cases,
      <literal>MapperFactoryBean</literal>, which uses a template internally,
      will be all that is needed. When access to an
      <literal>SqlSessionTemplate</literal> is needed, it can be created using
      an <literal>SqlSessionFactory</literal> as a constructor argument.

      <programlisting language="java"><![CDATA[SqlSessionTemplate sessionTemplate = new SqlSessionTemplate(sqlSessionFactory);]]></programlisting>
      Similarly, the template could be configured in a Spring XML file.
    </para>

    <para>
      In addition to all the SQL related methods in
      <literal>SqlSession</literal>, <literal>SqlSessionTemplate</literal>
      offers a generic <literal>execute</literal> method. This method takes a
      custom <literal>SqlSessionCallback</literal> as an argument so that you
      can execute more than one SQL method on a <literal>SqlSession</literal>:
      <programlisting language="java"><![CDATA[public void insertUser(final User user) {
  getSqlSessionTemplate().execute(new SqlSessionCallback<Object>() {
    public Object doInSqlSession(SqlSession sqlSession) {
      sqlSession.insert("org.mybatis.spring.sample.mapper.UserMapper.insertUser", user);
      sqlSession.insert("org.mybatis.spring.sample.mapper.UserMapper.insertAccount", user.getAccount());
      return null;
    }
  });
}]]></programlisting>
    </para>

    <para>
      Note that the <literal>execute</literal> method can also accept a
      <literal>ExecutorType</literal> parameter. This can be used if the
      desired execution method differs from the default set for the
      SqlSessionFactory. This will mostly be useful for performing batch SQL
      queries using <literal>ExecutorType.BATCH</literal>. The only caveat to
      this form of the method is that there <emphasis>cannot</emphasis> be an
      existing transaction running with a different ExecutorType when this
      method is called. Either ensure that calls to
      <literal>execute(SqlSessionCallback, ExecutorType)</literal> run in a
      separate transaction, with PROPAGATION_REQUIRES_NEW or with completely
      outside of a transaction.
    </para>
  </section>

  <section id="templates_support.daosupport">
    <title>SqlSessionDaoSupport</title>

    <para>
      <literal>SqlSessionDaoSupport</literal> is an abstract support class that
      builds a <literal>SqlSessionTemplate</literal> for you. Calling
      <literal>getSqlSessionTemplate()</literal> gives you access to the
      template which can then be used to execute SQL methods, like the
      following:

      <programlisting language="java"><![CDATA[public class UserMapperDaoImpl extends SqlSessionDaoSupport implements UserMapper {
  public User getUser(String userId) {
    return (User) getSqlSessionTemplate()
        .selectOne("org.mybatis.spring.sample.mapper.UserMapper.getUser", userId);
  }
}]]></programlisting>

      Usually <literal>MapperFactoryBean</literal> is preferred to this class,
      since it requires no extra code. But, this class is useful if you need
      to do other non-MyBatis work in your DAO and concrete classes are
      required.
    </para>

    <para>
      <literal>SqlSessionDaoSupport</literal> is configured similarly to
      <literal>MapperFactoryBean</literal>. It requires either an
      <literal>sqlSessionFactory</literal> or an
      <literal>sqlSessionTemplate</literal> property to be set. These can be
      set explicitly or autowired by Spring. If both properties are set, the
      SqlSessionFactory is ignored.
    </para>

    <para>
      Assuming a class <literal>UserMapperImpl</literal> that subclasses
      <literal>SqlSessionDaoSupport</literal>, it can be configured in Spring
      like the following:

      <programlisting language="xml"><![CDATA[<bean id="userMapper" class="org.mybatis.spring.sample.mapper.UserMapperImpl">
  <property name="sqlSessionFactory" ref="sqlSessionFactory" />
</bean>]]></programlisting>
    </para>
  </section>
</chapter>
{'fraction_non_alphanumeric': 0.0881000403388463, 'fraction_numerical': 0.0024203307785397336, 'mean_word_length': 3.743972445464983, 'pattern_counts': {'":': 0, '<': 231, '<?xml version=': 2, '>': 231, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5374103', 'n_tokens_mistral': 3221, 'n_tokens_neox': 3153, 'n_words': 1171}