Merge pull request #226 from radcortez/master

Documentation to split and multiple-steps

Author: radcortez

batch/multiple-steps/pom.xml

@@ -11,8 +11,8 @@
 
     <artifactId>multiple-steps</artifactId>
     <packaging>war</packaging>
-
-    <name>${project.artifactId}</name>
+    <name>Batch Multiple Steps</name>
+    <description>Batch JSL - Executing Multiple Steps</description>
 
     <dependencies>
         <dependency>

batch/multiple-steps/src/test/java/org/javaee7/batch/multiple/steps/BatchMultipleStepsTest.java

@@ -21,10 +21,26 @@
 import static org.junit.Assert.assertEquals;
 
 /**
+ * The Batch specification allows you to implement process workflows using a Job Specification Language (JSL). In this
+ * sample, by using the +step+ element, it's possible to configure a job that runs multiple steps.
+ *
+ * One Chunk oriented Step and a Batchlet are configured in the file +myJob.xml+. They both execute in order of
+ * declaration. First the Chunk oriented Step and finally the Batchlet Step.
+ *
  * @author Roberto Cortez
  */
 @RunWith(Arquillian.class)
 public class BatchMultipleStepsTest {
+    /**
+     * 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 +52,13 @@ 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 +JobOperator#getStepExecutions+ and the +Metric[]+ object available in the
+     * step execution.
+     *
+     * @throws Exception an exception if the batch could not complete successfully.
+     */
     @Test
     public void testBatchMultipleSteps() throws Exception {
         JobOperator jobOperator = BatchRuntime.getJobOperator();
@@ -51,14 +74,17 @@ public void testBatchMultipleSteps() throws Exception {
 
             if (stepExecution.getStepName().equals("step1")) {
                 Map<Metric.MetricType, Long> metricsMap = BatchTestHelper.getMetricsMap(stepExecution.getMetrics());
-                System.out.println(metricsMap);
                 assertEquals(10L, metricsMap.get(Metric.MetricType.READ_COUNT).longValue());
                 assertEquals(10L / 2, metricsMap.get(Metric.MetricType.WRITE_COUNT).longValue());
                 assertEquals(10L / 3 + (10L % 3 > 0 ? 1 : 0), metricsMap.get(Metric.MetricType.COMMIT_COUNT).longValue());
             }
         }
+
+        // <1> Make sure all the steps were executed.
         assertEquals(2, stepExecutions.size());
+        // <2> Make sure all the steps were executed in order of declaration.
         assertArrayEquals(new String[]{"step1", "step2"}, executedSteps.toArray());
+        // <3> Job should be completed.
         assertEquals(BatchStatus.COMPLETED, jobExecution.getBatchStatus());
     }
 }

batch/split/pom.xml

@@ -11,8 +11,8 @@
 
     <artifactId>split</artifactId>
     <packaging>war</packaging>
-
-    <name>${project.artifactId}</name>
+    <name>Batch Split</name>
+    <description>Batch JSL - Splitting Steps</description>
 
     <dependencies>
         <dependency>

batch/split/src/test/java/org/javaee7/batch/split/BatchSplitTest.java

@@ -23,10 +23,29 @@
 import static org.junit.Assert.assertTrue;
 
 /**
+ * The Batch specification allows you to implement process workflows using a Job Specification Language (JSL). In this
+ * sample, by using the +split+ element, it's possible to configure a job that runs parallel flows. A +split+ can only
+ * contain +flow+ elements. These +flow+ elements can be used to implement separate executions to be processed by the
+ * job.
+ *
+ * Three simple Batchlet's are configured in the file +myjob.xml+. +MyBatchlet1+ and +MyBatchlet2+ are setted up to
+ * execute in parallel by using the +split+ and +flow+ elements. +MyBatchlet3+ is only going to execute after
+ * +MyBatchlet1+ and +MyBatchlet2+ are both done with their job.
+ *
  * @author Roberto Cortez
  */
 @RunWith(Arquillian.class)
 public class BatchSplitTest {
+    /**
+     * 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)
@@ -38,6 +57,12 @@ 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 +JobOperator#getStepExecutions+.
+     *
+     * @throws Exception an exception if the batch could not complete successfully.
+     */
     @Test
     public void testBatchSplit() throws Exception {
         JobOperator jobOperator = BatchRuntime.getJobOperator();
@@ -52,13 +77,19 @@ public void testBatchSplit() throws Exception {
             executedSteps.add(stepExecution.getStepName());
         }
 
+        // <1> Make sure all the steps were executed.
         assertEquals(3, stepExecutions.size());
         assertTrue(executedSteps.contains("step1"));
         assertTrue(executedSteps.contains("step2"));
         assertTrue(executedSteps.contains("step3"));
+
+        // <2> Steps 'step1' and 'step2' can appear in any order, since they were executed in parallel.
         assertTrue(executedSteps.get(0).equals("step1") || executedSteps.get(0).equals("step2"));
         assertTrue(executedSteps.get(1).equals("step1") || executedSteps.get(1).equals("step2"));
+        // <3> Step 'step3' is always the last to be executed.
         assertTrue(executedSteps.get(2).equals("step3"));
+
+        // <4> Job should be completed.
         assertEquals(BatchStatus.COMPLETED, jobExecution.getBatchStatus());
     }
 }