Added documentation to chunk-csv-database project.

Author: radcortez

batch/chunk-csv-database/pom.xml

@@ -11,6 +11,8 @@
 
     <artifactId>chunk-csv-database</artifactId>
     <packaging>war</packaging>
+    <name>Batch Chunk CSV Database</name>
+    <description>Chunk Processing - Read, Process, Write to a Database</description>
 
     <dependencies>
         <dependency>

batch/chunk-csv-database/src/main/resources/META-INF/persistence.xml

@@ -11,7 +11,6 @@
             <property name="javax.persistence.schema-generation.drop-source" value="script"/> 
             <property name="javax.persistence.schema-generation.create-script-source" value="META-INF/create.sql"/> 
             <property name="javax.persistence.schema-generation.drop-script-source" value="META-INF/drop.sql"/> 
-            <property name="eclipselink.logging.level" value="FINE"/> 
         </properties>
     </persistence-unit>
 </persistence>

batch/chunk-csv-database/src/test/java/org/javaee7/batch/chunk/csv/database/BatchCSVDatabaseTest.java

@@ -22,13 +22,50 @@
 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 a writer.
+ *
+ * This job will read a file from the system in CSV format:
+ * include::MyItemReader#open[]
+ * include::MyItemReader#readItem[]
+ *
+ * Process the data by transforming it into a +Person+ object:
+ * include::MyItemProcessor#processItem[]
+ *
+ * Finally write the data using JPA to a database:
+ * include::MyItemWriter#writeItems[]
+ *
  * @author Roberto Cortez
  */
 @RunWith(Arquillian.class)
 public class BatchCSVDatabaseTest {
     @PersistenceContext
     private EntityManager entityManager;
 
+    /**
+     * 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
+     * /META-INF/persistence.xml
+     * /META-INF/create.sql
+     * /META-INF/drop-sql
+     * /META-INF/mydata.csv
+     * ----
+     *
+     * * The +myjob.xml+ file is needed for running the batch definition.
+     * * The +persistence.xml+ file is needed for JPA configuration, create schema, load-data and drop schema.
+     * * The +create.sql+ file has the necessary database schema for the data.
+     * * The +drop.sql+ file has the required commands to drop the database schema created.
+     * * The +mydata.csv+ file has the data to load into the database.
+     */
     @Deployment
     public static WebArchive createDeployment() {
         WebArchive war = ShrinkWrap.create(WebArchive.class)
@@ -44,7 +81,17 @@ public static WebArchive createDeployment() {
         return war;
     }
 
+    @SuppressWarnings("unchecked")
     @Test
+    /**
+     * 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 write 7 elements of type +Person+. Commits are executed after 3 elements
+     * are read.
+     *
+     * @throws Exception an exception if the batch could not complete successfully.
+     */
     public void testBatchCSVDatabase() throws Exception {
         JobOperator jobOperator = BatchRuntime.getJobOperator();
         Long executionId = jobOperator.start("myJob", new Properties());
@@ -57,17 +104,21 @@ public void testBatchCSVDatabase() throws Exception {
             if (stepExecution.getStepName().equals("myStep")) {
                 Map<Metric.MetricType, Long> metricsMap = BatchTestHelper.getMetricsMap(stepExecution.getMetrics());
 
+                // <1> The read count should be 7 elements. Check +MyItemReader+.
                 assertEquals(7L, metricsMap.get(Metric.MetricType.READ_COUNT).longValue());
+                // <2> The write count should be same 7 read elements.
                 assertEquals(7L, metricsMap.get(Metric.MetricType.WRITE_COUNT).longValue());
+                // <3> The commit count should be 4. Checkpoint is on every 3rd read, 4 commits for read elements.
                 assertEquals(3L, metricsMap.get(Metric.MetricType.COMMIT_COUNT).longValue());
             }
         }
 
         Query query = entityManager.createNamedQuery("Person.findAll");
-        @SuppressWarnings("unchecked")
         List<Person> persons = query.getResultList();
 
+        // <4> Confirm that the elements were actually persisted into the database.
         assertEquals(7L, persons.size());
+        // <5> Job should be completed.
         assertEquals(jobExecution.getBatchStatus(), BatchStatus.COMPLETED);
     }
-}
+}