Documentation for Spring Batch support

Author: jeffgbutler

src/site/markdown/docs/springBatch.md

@@ -0,0 +1,61 @@
+# Spring Batch Support
+This library provides some utilities to make it easier to interact with the MyBatis Spring Batch support.
+
+## The Problem
+
+MyBatis Spring support provides utility classes for interacting with Spring Batch (see [http://www.mybatis.org/spring/batch.html](http://www.mybatis.org/spring/batch.html)). These classes are specialized implementations of Spring Batch's `ItemReader` and `ItemWriter` interfaces that have support for MyBatis mappers.
+
+The `ItemWriter` implementations work with SQL generated by MyBatis Dynamic SQL with no modification needed.
+
+The `ItemReader` implementations need special care. Those classes assume that all query parameters will be placed in a Map (as per usual when using multiple parameters in a query). MyBatis Dynamic SQL, by default, builds a parameter object that should be the only parameter in a query and will not work when placed in a Map of parameters.
+
+## The Solution
+
+The solution involves these steps:
+
+1. The SQL must be rendered such that the parameter markers are aware of the enclosing parameter Map in the `ItemReader`
+1. The `SelectStatamentProvider` must be placed in the `ItemReader` parameter Map with a known key.
+1. The `@SelectProvider` must be configured to be aware of the enclosing parameter Map
+
+MyBatis Dynamic SQL provides utilities for each of these requirements. Each utility uses a shared Map key for consistency.
+
+### Specialized Rendering
+
+MyBatis Dynamic SQL provides a specialized rendering strategy for queries used with the MyBatis Spring `ItemReader` implementations. Queries should be rendered as follows:
+
+```java
+        SelectStatementProvider selectStatement =  SelectDSL.select(person.allColumns())
+                .from(person)
+                .where(lastName, isEqualTo("flintstone"))
+                .build()
+                .render(SpringBatchUtility.SPRING_BATCH_READER_RENDERING_STRATEGY);
+```
+
+### Creating the Parameter Map
+
+The `SpringBatchUtility` provides a method to create the parameter values Map needed by the MyBatis Spring `ItemReader`. It can be used as follows:
+
+```java
+        MyBatisCursorItemReader<Person> reader = new MyBatisCursorItemReader<>();
+        reader.setQueryId(PersonMapper.class.getName() + ".selectMany");
+        reader.setSqlSessionFactory(sqlSessionFactory);
+        reader.setParameterValues(SpringBatchUtility.toParameterValues(selectStatement));
+```
+
+### Specialized @SelectProvider Adapter
+
+MyBatis mappers should be configured to use the specialized `@SelectProvider` adapter as follows:
+
+```java
+    @SelectProvider(type=SpringBatchProviderAdapter.class, method="select")
+    @Results({
+        @Result(column="id", property="id", id=true),
+        @Result(column="first_name", property="firstName"),
+        @Result(column="last_name", property="lastName")
+    })
+    List<Person> selectMany(Map<String, Object> parameterValues);
+```
+
+## Complete Example
+
+The unit tests for MyBatis Dynamic SQL include a complete example of using MyBatis Spring Batch support using both a reader and writer. You can see the full example here: [https://github.com/mybatis/mybatis-dynamic-sql/tree/master/src/test/java/examples/springbatch](https://github.com/mybatis/mybatis-dynamic-sql/tree/master/src/test/java/examples/springbatch)

src/site/site.xml

@@ -45,6 +45,7 @@
       <item href="docs/update.html" name="UPDATE Statements" />
       <item href="docs/mybatis3.html" name="MyBatis3 Support" />
       <item href="docs/spring.html" name="Spring Support" />
+      <item href="docs/springBatch.html" name="Spring Batch Support" />
       <item href="docs/howItWorks.html" name="How it Works" />
       <item href="docs/extending.html" name="Extending the Library" />
       <item href="docs/codingStandards.html" name="Coding Standards" />

src/test/java/examples/springbatch/PersonMapper.java

@@ -16,6 +16,7 @@
 package examples.springbatch;
 
 import java.util.List;
+import java.util.Map;
 
 import org.apache.ibatis.annotations.Result;
 import org.apache.ibatis.annotations.Results;
@@ -35,7 +36,7 @@ public interface PersonMapper {
         @Result(column="first_name", property="firstName"),
         @Result(column="last_name", property="lastName")
     })
-    List<Person> selectMany(SelectStatementProvider selectStatement);
+    List<Person> selectMany(Map<String, Object> parameterValues);
 
     @UpdateProvider(type=SqlProviderAdapter.class, method="update")
     int update(UpdateStatementProvider updateStatement);