Merge pull request #229 from radcortez/master

Documentation to decision and flow projects

Author: radcortez

batch/decision/pom.xml

@@ -10,8 +10,9 @@
 
     <artifactId>decision</artifactId>
     <packaging>war</packaging>
+    <name>Batch Decision</name>
+    <description>Batch DSL - Decision</description>
 
-    <name>${project.artifactId}</name>
 
     <dependencies>
         <dependency>

batch/decision/src/test/java/org/javaee7/batch/decision/BatchDecisionTest.java

@@ -22,10 +22,33 @@
 import static org.junit.Assert.*;
 
 /**
+ * The Batch specification allows you to implement process workflows using a Job Specification Language (JSL). In this
+ * sample, by using the +decision+ element, it's possible to configure a job that follows different paths of execution
+ * based on your own criteria by implementing a +javax.batch.api.Decider+
+ *
+ * The +javax.batch.api.Decider+ just needs to return a meaningful value, to use in the +myJob.xml+ file to be able to
+ * reference the next step that must be executed.
+ *
+ * include::myJob.xml[]
+ *
+ * Three Steps and one Decider are configured in the file +myJob.xml+. We start by executing one +step1+ and
+ * hand over the control to the Decider, which will execute +step2+, since the Decider is always returning the value
+ * +foobar+ which forwards the execution to +step2+.
+ *
  * @author Roberto Cortez
  */
 @RunWith(Arquillian.class)
 public class BatchDecisionTest {
+    /**
+     * 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)
@@ -37,6 +60,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 testBatchDecision() throws Exception {
         JobOperator jobOperator = BatchRuntime.getJobOperator();
@@ -51,9 +81,13 @@ public void testBatchDecision() throws Exception {
             executedSteps.add(stepExecution.getStepName());
         }
 
+        // <1> Make sure that only two steps were executed.
         assertEquals(2, stepExecutions.size());
+        // <2> Make sure that only the expected steps were executed an in order.
         assertArrayEquals(new String[] {"step1", "step3"}, executedSteps.toArray());
+        // <3> Make sure that this step was never executed.
         assertFalse(executedSteps.contains("step2"));
+        // <3> Job should be completed.
         assertEquals(BatchStatus.COMPLETED, jobExecution.getBatchStatus());
     }
 }

batch/flow/pom.xml

@@ -11,8 +11,8 @@
 
     <artifactId>flow</artifactId>
     <packaging>war</packaging>
-
-    <name>${project.artifactId}</name>
+    <name>Batch Flow</name>
+    <description>Batch DSL - Flow</description>
 
     <dependencies>
         <dependency>

batch/flow/src/test/java/org/javaee7/batch/flow/BatchFlowTest.java

@@ -21,10 +21,30 @@
 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 +flow+ element, we define a sequence of elements that execute together as a unit. When the
+ * flow is finished the flow transitions to the next execution element. The execution elements of a flow cannot
+ * transition to elements outside the flow.
+ *
+ * include::myJob.xml[]
+ *
+ * The flow element is usefull to build self contained workflows that you can reference and build as a part of a bigger
+ * workflow.
+ *
  * @author Roberto Cortez
  */
 @RunWith(Arquillian.class)
 public class BatchFlowTest {
+    /**
+     * 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 +56,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 testBatchFlow() throws Exception {
         JobOperator jobOperator = BatchRuntime.getJobOperator();
@@ -58,8 +85,11 @@ public void testBatchFlow() throws Exception {
             }
         }
 
+        // <1> Make sure all the steps were executed.
         assertEquals(3, stepExecutions.size());
+        // <2> Make sure all the steps were executed in order of declaration.
         assertArrayEquals(new String[]{"step1", "step2", "step3"}, executedSteps.toArray());
+        // <3> Job should be completed.
         assertEquals(BatchStatus.COMPLETED, jobExecution.getBatchStatus());
     }
 }