Added documentation to split project.

Author: radcortez

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());
     }
 }