Added documentation to chunk-checkpoint project.

Author: radcortez

batch/chunk-checkpoint/pom.xml

@@ -11,6 +11,8 @@
 
     <artifactId>chunk-checkpoint</artifactId>
     <packaging>war</packaging>
+    <name>Batch Chunk Checkpoint</name>
+    <description>Chunk Checkpoint - Custom Checkpoint Policy</description>
 
     <dependencies>
         <dependency>

batch/chunk-checkpoint/src/main/resources/META-INF/batch-jobs/myJob.xml

@@ -42,7 +42,7 @@
 
 <job id="myJob" xmlns="http://xmlns.jcp.org/xml/ns/javaee" version="1.0">
     <step id="myStep" >
-        <chunk item-count="3" checkpoint-policy="custom">
+        <chunk checkpoint-policy="custom">
             <reader ref="myItemReader"/>
             <processor ref="myItemProcessor"/>
             <writer ref="myItemWriter"/>

batch/chunk-checkpoint/src/test/java/org/javaee7/batch/chunk/checkpoint/BatchChunkCheckpointTest.java

@@ -21,10 +21,42 @@
 import static org.junit.Assert.assertTrue;
 
 /**
+ * The Batch specification provides a Chunk Oriented processing style. This style is defined by enclosing into a
+ * transaction a set of reads, process and write operations via +javax.batch.api.chunk.ItemReader+,
+ * +javax.batch.api.chunk.ItemProcessor+ and +javax.batch.api.chunk.ItemWriter+. Items are read one at a time, processed
+ * and aggregated. The transaction is then committed when the defined +checkpoint-policy+ is triggered.
+ *
+ * The +checkpoint-policy+ can be defined as +item+ or +custom+. The +item+ policy means the chunk is checkpointed after
+ * a specified number of items are processed. The +custom+ policy means the chunk is checkpointed according to a
+ * checkpoint algorithm implementation. To use the +custom+ policy you also need to define a +checkpoint-algorithm+
+ * element.
+ *
+ * include::myJob.xml[]
+ *
+ * A very simple job is defined in the +myJob.xml+ file. Just a single step with a reader, processor and writer. For
+ * this sample, a custom checkpoint policy is going to be used. The custom policy needs to implement
+ * +javax.batch.api.chunk.CheckpointAlgorithm+ or in alternative extend
+ * +javax.batch.api.chunk.AbstractCheckpointAlgorithm+ that already provides empty implementations for all methods.
+ *
+ * include::MyCheckpointAlgorithm[]
+ *
+ * Note that the behaviour of this custom checkpoint algorithm could also be achieved by using the +item+ policy and
+ * defining the +item-count+ element at the +chunk+ level.
+ *
  * @author Roberto Cortez
  */
 @RunWith(Arquillian.class)
 public class BatchChunkCheckpointTest {
+  /**
+   * We're just going to deploy the application as a +web archive+. Note the inclusion of the following files:
+   *
+   * [source,file]
+   * ----
+   * /META-INF/batch-jobs/myjob.xml
+   * ----
+   *
+   * The +myjob.xml+ file is needed for running the batch definition.
+   */
     @Deployment
     public static WebArchive createDeployment() {
         WebArchive war = ShrinkWrap.create(WebArchive.class)
@@ -36,6 +68,15 @@ public static WebArchive createDeployment() {
         return war;
     }
 
+  /**
+   * In the test, we're just going to invoke the batch execution and wait for completion. To validate the test
+   * expected behaviour we need to query the +Metric[]+ object available in the step execution.
+   *
+   * The batch process itself will read and process 10 elements from numbers  1 to 10, but only write the odd
+   * elements. Commits are executed after 5 elements are read by the custom checkpoint algorithm.
+   *
+   * @throws Exception an exception if the batch could not complete successfully.
+   */
     @Test
     public void testBatchChunkCheckpoint() throws Exception {
         JobOperator jobOperator = BatchRuntime.getJobOperator();
@@ -49,12 +90,16 @@ public void testBatchChunkCheckpoint() throws Exception {
             if (stepExecution.getStepName().equals("myStep")) {
                 Map<Metric.MetricType, Long> metricsMap = BatchTestHelper.getMetricsMap(stepExecution.getMetrics());
 
+                // <1> The read count should be 10 elements. Check +MyItemReader+.
                 assertEquals(10L, metricsMap.get(Metric.MetricType.READ_COUNT).longValue());
+                // <2> The write count should be 5. The 10 elements are read and the checkpoint is on every 5th read.
                 assertEquals(10L / 2L, metricsMap.get(Metric.MetricType.WRITE_COUNT).longValue());
+                // <3> The commit count is equals to the write count plus 1. An empty read is executed after all reads.
                 assertEquals(10L / 5L + 1, metricsMap.get(Metric.MetricType.COMMIT_COUNT).longValue());
             }
         }
 
+        // <4> The checkpoint algorithm should be checked 10 times. One for each element read.
         assertTrue(MyCheckpointAlgorithm.checkpointCountDownLatch.await(0, TimeUnit.SECONDS));
         assertEquals(jobExecution.getBatchStatus(), BatchStatus.COMPLETED);
     }