Added documentation to chunk-simple project.

Author: radcortez

batch/chunk-simple/pom.xml

@@ -10,13 +10,9 @@
     </parent>
 
     <artifactId>chunk-simple</artifactId>
-    <version>1.0-SNAPSHOT</version>
     <packaging>war</packaging>
-
-    <name>${project.artifactId}</name>
-    <properties>
-        <netbeans.hint.deploy.server>gfv3ee6</netbeans.hint.deploy.server>
-    </properties>
+    <name>Batch Chunk Simple</name>
+    <description>Chunk Processing - Read, Process, Write</description>
 
     <dependencies>
         <dependency>

batch/chunk-simple/src/test/java/org/javaee7/batch/chunk/simple/ChunkSimpleTest.java

@@ -19,10 +19,29 @@
 import static org.junit.Assert.assertEquals;
 
 /**
+ * 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.
+ *
+ * include::myJob.xml[]
+ *
+ * A very simple job is defined in the +myJob.xml+ file. Just a single step with a reader, a processor and writer.
+ *
  * @author Roberto Cortez
  */
 @RunWith(Arquillian.class)
 public class ChunkSimpleTest {
+    /**
+     * 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)
@@ -34,6 +53,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 3 elements are read.
+   *
+   * @throws Exception an exception if the batch could not complete successfully.
+   */
     @Test
     public void testChunkSimple() throws Exception {
         JobOperator jobOperator = BatchRuntime.getJobOperator();
@@ -46,12 +74,18 @@ public void testChunkSimple() throws Exception {
         for (StepExecution stepExecution : stepExecutions) {
             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. Only half of the elements read are processed to be written.
                 assertEquals(10L / 2L, metricsMap.get(Metric.MetricType.WRITE_COUNT).longValue());
-                assertEquals(10L / 3 + (10L % 3 > 0 ? 1 : 0), metricsMap.get(Metric.MetricType.COMMIT_COUNT).longValue());
+                // <3> The commit count should be 4. Checkpoint is on every 3rd read, 4 commits for read elements.
+                assertEquals(10L / 3 + (10L % 3 > 0 ? 1 : 0),
+                             metricsMap.get(Metric.MetricType.COMMIT_COUNT).longValue());
             }
         }
 
+        // <4> Job should be completed.
         assertEquals(jobExecution.getBatchStatus(), BatchStatus.COMPLETED);
     }
 }