[mybatis-spring] minor docbook updates

Author: hpresnall

src/docbkx/getting_started.xml

@@ -24,7 +24,7 @@
 
   <para>
     This chapter will show you in a few steps how to install and setup MyBatis-Spring and how to build
-    a simple data access transactional application. 
+    a simple transactional application. 
   </para>
 
   <section id="getting_started.installation">
@@ -37,13 +37,11 @@
     <para>
       If you are using Maven just add the following dependency
       to your pom.xml:
-      <programlisting language="xml"><![CDATA[
-<dependency>
+      <programlisting language="xml"><![CDATA[<dependency>
   <groupId>org.mybatis</groupId>
   <artifactId>mybatis-spring</artifactId>
   <version>]]><?eval ${project.version}?><![CDATA[</version>
-</dependency>]]>
-      </programlisting>
+</dependency>]]></programlisting>
     </para>
   </section>
 
@@ -105,8 +103,7 @@
 
      <para>
        Calling MyBatis data methods is now only one line of code:
-       <programlisting language="java"><![CDATA[
-public class FooServiceImpl implements FooService {
+       <programlisting language="java"><![CDATA[public class FooServiceImpl implements FooService {
 
   private UserMapper userMapper;
 
@@ -117,9 +114,7 @@ public class FooServiceImpl implements FooService {
   public User doSomeBusinessStuff(String userId) {
     return this.userMapper.getUser(userId);
   }
-}
-       ]]></programlisting>
+}]]></programlisting>
      </para>
-
   </section>
 </chapter>

src/docbkx/introduction.xml

@@ -30,18 +30,18 @@
       Spring. Using the classes in this library, Spring will load the necessary
       MyBatis factory and session classes for you. This library also provides
       an easy way to inject MyBatis data mappers and <literal>SqlSession</literal>s
-      into your service beans. It will also handle transactions and translate MyBatis 
-      exceptions into Spring <literal>DataAccessException</literal>s. 
-      And Finally, it will let you build your application code free of 
+      into your service beans. It will also handle transactions and translate MyBatis
+      exceptions into Spring <literal>DataAccessException</literal>s.
+      Finally, it will let you build your application code free of 
       dependencies on MyBatis, Spring or MyBatis-Spring.
     </para>
   </section>
 
   <section id="introduction.motivation">
     <title>Motivation</title>
     <para>
-      As of version 2, Spring 3.0 only supports iBATIS version 2. An attempt 
-      was made to add MyBatis 3 support into Spring 3.0 (see the Spring Jira 
+      Spring version 2 only supports iBATIS version 2. An attempt was made to
+      add MyBatis 3 support into Spring 3.0 (see the Spring Jira 
       <ulink url="https://jira.springsource.org/browse/SPR-5991">issue</ulink>).
       Unfortunately, Spring 3.0 development ended before MyBatis 3.0 was
       officially released. Because the Spring team did not want to release with
@@ -77,5 +77,4 @@
       this project wouldn't exist.
     </para>
   </section>
-
 </chapter>

src/docbkx/mappers.xml

@@ -38,7 +38,7 @@
     MyBatis, Spring or MyBatis-Spring. The proxy that
     <literal>MapperFactoryBean</literal> creates handles opening and closing
     the session as well as translating any exceptions into Spring
-    <literal>DataAccessExceptions</literal>. In addition, the proxy will start
+    <literal>DataAccessException</literal>s. In addition, the proxy will start
     a new Spring transaction if required or participate in an existing one if
     it a transaction is active. 
   </para>
@@ -73,11 +73,11 @@
     </para>
 
     <para>
-      Note that while <literal>MapperFactoryBean</literal> requires either an
+      Note that <literal>MapperFactoryBean</literal> requires either an
       <literal>SqlSessionFactory</literal> or an
       <literal>SqlSessionTemplate</literal>. These can be set through the
-      respective <literal>sqlSessionFactory</literal> or 
-      <literal>sqlSessionTemplate</literal> properties or they can
+      respective <literal>sqlSessionFactory</literal> and 
+      <literal>sqlSessionTemplate</literal> properties, or they can
       be autowired by Spring. If both properties are set, the 
       <literal>SqlSessionFactory</literal> is ignored. Since the 
       <literal>SqlSessionTemplate</literal> is required to have a session
@@ -120,7 +120,7 @@
       There is no need to register all your mappers in the Spring XML file.
       Instead, you can use a <literal>MapperScannerConfigurer</literal> that
       will search the classpath for your mappers and set them up
-      automatically as <literal>MapperFactoryBeans</literal>.
+      automatically as <literal>MapperFactoryBean</literal>s.
     </para>
 
     <para>
@@ -141,7 +141,7 @@
       <literal>SqlSessionFactory</literal> or <literal>SqlSessionTemplate</literal>
       because the <literal>MapperScannerConfigurer</literal> will autowire 
       <literal>MapperFactoryBeans</literal>. But, if you are using more than
-      one <literal>DataSource</literal>, (thus, more than one
+      one <literal>DataSource</literal> (thus, more than one
       SqlSessionFactory), autowiring will not  work. In this case you can use
       the <literal>sqlSessionFactory</literal> or 
       <literal>sqlSessionTemplate</literal> properties to set the right
@@ -158,20 +158,18 @@
      By default, these two properties are null, so all interfaces in the given
      base package(s) will be loaded as mappers.
     </para>
-    
+
     <para>
      Discovered mappers will be named using Spring default naming strategy for
-     autodetected components (see Spring manual 3.14.4). 
+     autodetected components (see section 3.14.4 of the Spring manual). 
      That is, if no annotation is found, it will use the uncapitalized non-qualified class 
      name of the mapper. But if either a @Component or a JSR-330 @Named annotation is 
-     found it will get the name from it.
+     found it will get the name from the annotation.
      Notice that you can set the <literal>annotationClass</literal> property
      to <literal>org.springframework.stereotype.Component</literal>,  
      <literal>javax.inject.Named</literal> (if you have JSE 6) or to your own annotation
      (that must be itself annotated) so the annotation will work both as a marker 
      and as a name provider.
     </para>
-    
    </section>
-
 </chapter>

src/docbkx/sample.xml

@@ -51,7 +51,7 @@
 		The service is composed by an interface <literal>FooService.java</literal>
 		and an implementation <literal>FooServiceImpl.java</literal>. This service is transactional
 		so a transaction is started when any of its methods is called and committed when
-		the method ends without throwing a unchecked exception.
+		the method ends without throwing an unchecked exception.
 		<programlisting language="java"><![CDATA[@Transactional
 public interface FooService {
   User doSomeBusinessStuff(String userId);
@@ -131,7 +131,7 @@ public interface FooService {
 				</tr>
 			</tbody>
 		</table>
-		Please have a look at the different <literal>applicationContext.xml</literal>
+		Please take a look at the different <literal>applicationContext.xml</literal>
 		files to see MyBatis-Spring in action.
 	</para>
 </chapter>

src/docbkx/templates_support.xml

@@ -34,8 +34,8 @@
   </para>  
 
   <para>
-    Note that is usually not necessary to use a <literal>SqlSession</literal> directly. 
-    In most cases a <literal>MapperFactoryBean</literal>, that will inject mappers
+    Note that it is usually not necessary to use a <literal>SqlSession</literal> directly. 
+    In most cases a <literal>MapperFactoryBean</literal> that will inject mappers
     into your beans, will be all that is needed. The 
     <link linkend="mappers.mapperfactorybean"><literal>MapperFactoryBean</literal></link> 
     will be explained in detail in the next chapter. 
@@ -63,23 +63,19 @@
 
     <para>
       <literal>SqlSessionTemplate</literal> implements <literal>SqlSession</literal> 
-      and is meant to be a drop-in replacement for MyBatis <literal>SqlSession</literal>.
-    </para>
-
-    <para>
-      <literal>SqlSessionTemplate</literal> should <emphasis>always</emphasis>
+      and is meant to be a drop-in replacement for any existing use of <literal>SqlSession</literal>
+      in your code. <literal>SqlSessionTemplate</literal> should <emphasis>always</emphasis>
       be used instead of default MyBatis implementation <literal>DefaultSqlSession</literal> 
-      because it cannot participate in Spring transactions and it cannot be 
-      injected because it is not thread safe. 
-      Switching between the two classes in the same application can cause data integrity issues.
+      because the template can participate in Spring transactions and is thread safe for use by
+      multiple injected mapper classes. Switching between the two classes in the
+      same application can cause data integrity issues.
     </para>
 
     <para>
       A <literal>SqlSessionTemplate</literal> can be constructed 
       using an <literal>SqlSessionFactory</literal> as a constructor argument.
 
-      <programlisting language="xml"><![CDATA[
-<bean id="sqlSession" class="org.mybatis.spring.SqlSessionTemplate">
+      <programlisting language="xml"><![CDATA[<bean id="sqlSession" class="org.mybatis.spring.SqlSessionTemplate">
   <constructor-arg index="0" ref="sqlSessionFactory" />
 </bean>]]></programlisting>	      
     </para>
@@ -88,8 +84,7 @@
       This bean can now be injected directly in your DAO beans. You need a
       <literal>SqlSession</literal> property in your bean like the following
 
-      <programlisting language="java"><![CDATA[      
-public class UserDaoImpl implements UserDao {
+      <programlisting language="java"><![CDATA[public class UserDaoImpl implements UserDao {
     
   private SqlSession sqlSession;
 
@@ -104,31 +99,28 @@ public class UserDaoImpl implements UserDao {
 
       And inject the <literal>SqlSessionTemplate</literal> as follows
 
-      <programlisting language="java"><![CDATA[
-<bean id="userDao" class="org.mybatis.spring.sample.dao.UserDaoImpl">
+      <programlisting language="java"><![CDATA[<bean id="userDao" class="org.mybatis.spring.sample.dao.UserDaoImpl">
   <property name="sqlSession" ref="sqlSession" />
 </bean>]]></programlisting>	      
     </para>
 
     <para>
       <literal>SqlSessionTemplate</literal> has also a constructor that takes
       an <literal>ExecutorType</literal> as an argument. This allows you to
-      construct, for example, a batch <literal>SqlSession</literal> but using
+      construct, for example, a batch <literal>SqlSession</literal> by using
 	  the following in Spring's configuration xml:  
-      <programlisting language="xml"><![CDATA[
-<bean id="sqlSession" class="org.mybatis.spring.SqlSessionTemplate">
+      <programlisting language="xml"><![CDATA[<bean id="sqlSession" class="org.mybatis.spring.SqlSessionTemplate">
   <constructor-arg index="0" ref="sqlSessionFactory" />
   <constructor-arg index="1" value="BATCH" />
 </bean>]]></programlisting>
 
       Now all your statements will be batched so the following could be coded
       in a DAO
-      <programlisting language="java"><![CDATA[
- public void insertUsers(User[] users) {
+      <programlisting language="java"><![CDATA[public void insertUsers(User[] users) {
    for (User user : users) {
    	sqlSession.insert("org.mybatis.spring.sample.mapper.UserMapper.insertUser", user);
    }
- }]]></programlisting>       
+ }]]></programlisting> 
     </para>
 
     <para>
@@ -142,7 +134,7 @@ public class UserDaoImpl implements UserDao {
       there <emphasis>cannot</emphasis> be an existing transaction running with
       a different ExecutorType when this method is called. Either ensure that
       calls to <literal>SqlSessionTemplate</literal>s with different executor
-      types run in a separate transaction, with PROPAGATION_REQUIRES_NEW or
+      types run in a separate transaction (e.g. with PROPAGATION_REQUIRES_NEW) or
       completely outside of a transaction.
     </para>
   </section>
@@ -156,8 +148,7 @@ public class UserDaoImpl implements UserDao {
       <literal>getSqlSession()</literal> you will get a <literal>SqlSessionTemplate</literal>
       which can then be used to execute SQL methods, like the following:
 
-      <programlisting language="java"><![CDATA[
-public class UserDaoImpl extends SqlSessionDaoSupport implements UserDao {
+      <programlisting language="java"><![CDATA[public class UserDaoImpl extends SqlSessionDaoSupport implements UserDao {
   public User getUser(String userId) {
     return (User) getSqlSession()
         .selectOne("org.mybatis.spring.sample.mapper.UserMapper.getUser", userId);
@@ -182,11 +173,9 @@ public class UserDaoImpl extends SqlSessionDaoSupport implements UserDao {
       <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.UserDaoImpl">
+      <programlisting language="xml"><![CDATA[<bean id="userMapper" class="org.mybatis.spring.sample.mapper.UserDaoImpl">
   <property name="sqlSessionFactory" ref="sqlSessionFactory" />
 </bean>]]></programlisting>
     </para>
   </section>
-
 </chapter>

src/docbkx/transactions.xml

@@ -30,9 +30,9 @@
   </para>
 
   <para>
-    Once a Spring PlatformTransactionManager is configured, you can configure
+    Once a Spring transaction manager is configured, you can configure
     transactions in Spring as you normally would. Both
-    <literal>@Transactional</literal> annotations as well as AOP style
+    <literal>@Transactional</literal> annotations and AOP style
     configurations are supported. A single <literal>SqlSession</literal>
     object will be created and used for the duration of the transaction. This
     session will be committed or rolled back as appropriate when then
@@ -99,8 +99,7 @@
       also configure the <literal>SqlSessionFactoryBean</literal> to use the base 
       MyBatis <literal>ManagedTransactionFactory</literal>:
 
-      <programlisting language="xml"><![CDATA[
-<bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean"> 
+      <programlisting language="xml"><![CDATA[<bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean"> 
   <property name="dataSource" ref="dataSource" />
   <property name="transactionFactory">
     <bean class="org.apache.ibatis.transaction.managed.ManagedTransactionFactory" />
@@ -110,7 +109,7 @@
   </section>
 
   <section id="transactions.programmatic">
-    <title>Programmatic transaction management</title>
+    <title>Programmatic Transaction Management</title>
     <para>
       MyBatis <literal>SqlSession</literal> provides you with specific methods to handle
       transactions programmatically. But when using MyBatis-Spring your beans will be 
@@ -121,20 +120,18 @@
       You cannot call <literal>SqlSession.commit()</literal>, <literal>SqlSession.rollback()</literal>  
       or <literal>SqlSession.close()</literal> over a Spring managed <literal>SqlSession</literal>.
       If you try to do so, a <literal>UnsupportedOperationException</literal> exception 
-      will be thrown. In case you are using injected mappers you won't even have access 
-      to those methods.
+      will be thrown. Note these methods are not exposed in injected mapper classes.
     </para>
     <para>
-      Regardless your connection's autocommit is set or not, any execution of a 
+      Regardless of your JDBC connection's autocommit setting, any execution of a 
       <literal>SqlSession</literal> data method or any call to a mapper 
-      method outside a Spring transaction will be automatically committed. 
+      method outside a Spring transaction will be automatically committed.
     </para>
     <para>
       If you want to control your transactions programmatically please refer to chapter 10.6 of 
       the Spring reference manual. This code shows how to handle a transaction manually 
       using the <literal>PlatformTransactionManager</literal> described in section 10.6.2. 
-      <programlisting language="java"><![CDATA[
-DefaultTransactionDefinition def = new DefaultTransactionDefinition();
+      <programlisting language="java"><![CDATA[DefaultTransactionDefinition def = new DefaultTransactionDefinition();
 def.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRED);
 
 TransactionStatus status = txManager.getTransaction(def);
@@ -145,9 +142,9 @@ catch (MyException ex) {
   txManager.rollback(status);
   throw ex;
 }
-txManager.commit(status);
-      ]]></programlisting>
-      Notice that this code shows a mapper but it will also work with a <literal>SqlSession</literal>.
+txManager.commit(status);]]></programlisting>
+
+      Notice that this code uses a mapper, but it will also work with a <literal>SqlSession</literal>.
     </para>
   </section>
 </chapter>

src/docbkx/using_api.xml

@@ -49,8 +49,8 @@
   </para>
 
   <para>
-    Use this option <emphasis>with care</emphasis> because wrong usage may produce runtime errors or,
-	much worse, data integrity problems. These are the caveats:
+    Use this option <emphasis>with care</emphasis> because wrong usage may produce runtime errors or
+	worse, data integrity problems. Be aware of the following caveats with direct API usage:
 	<itemizedlist>
 		<listitem>
 			<para>
@@ -66,20 +66,20 @@
 		</listitem>
 		<listitem>
 			<para>
-				MyBatis default <literal>SqlSession</literal> is not thread safe. If you
+				MyBatis' <literal>DefaultSqlSession</literal> is not thread safe. If you
 				inject it in your beans you <emphasis>will</emphasis> get errors.
 			</para>
 		</listitem>
 		<listitem>
 			<para>
-				Mappers got from MyBatis default <literal>SqlSession</literal> are not thread safe either. 
+				Mappers created using <literal>DefaultSqlSession</literal> are not thread safe either. 
 				If you inject them it in your beans you <emphasis>will</emphasis> get errors.
 			</para>
 		</listitem>
 		<listitem>
 			<para>
 				You must make sure that your <literal>SqlSession</literal>s 
-				are <emphasis>always</emphasis> closed.
+				are <emphasis>always</emphasis> closed in a finally block.
 			</para>
 		</listitem>
 	</itemizedlist>