BATCH-605:Added an extra section about archiving and some misc. changes from review with Wayne.

docs/src/site/docbook/reference/schema-appendix.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
 <appendix>
   <title>Meta-Data Schema</title>
 
@@ -13,25 +13,29 @@
     BATCH_JOB_INSTANCE, BATCH_JOB_EXECUTION, BATCH_JOB_PARAMS,
     BATCH_STEP_EXECUTION, BATCH_STEP_EXECUTION_CONTEXT, respectively. The
     <classname>JobRepository</classname> is responsible for saving and storing
-    each of java object into it's correct table. The following appendix
-    describes the meta-data tables in detail, along with many of the design
-    decisions that were made when creating them. When viewing the various
-    table creation statements below, it is important to realize that the
-    datatypes used are as generic as possible. Spring Batch provides many
-    schemas as examples, which all have varying datatypes due to quirks in
-    individual database vendors' handling of data types. Below is an ERD model
-    of all 5 tables and their relationships to one another:</para>
+    each Java object into it's correct table. The following appendix describes
+    the meta-data tables in detail, along with many of the design decisions
+    that were made when creating them. When viewing the various table creation
+    statements below, it is important to realize that the data types used are
+    as generic as possible. Spring Batch provides many schemas as examples,
+    which all have varying data types due to variations in individual database
+    vendors' handling of data types. Below is an ERD model of all 5 tables and
+    their relationships to one another:</para>
 
     <mediaobject>
-      <imageobject>
-        <imagedata fileref="images/meta-data-erd.png" />
+      <imageobject role="html">
+        <imagedata align="center" fileref="images/meta-data-erd.png" />
+      </imageobject>
+
+      <imageobject role="html">
+        <imagedata fileref="src/site/resources/reference/images/meta-data-erd.png" />
       </imageobject>
     </mediaobject>
 
     <section>
       <title>Version</title>
 
-      <para>Many of the databse tables discussed in this appendix contain a
+      <para>Many of the database tables discussed in this appendix contain a
       version column. This column is important because Spring Batch employs an
       optimistic locking strategy when dealing with updates to the database.
       This means that each time a record is 'touched' (updated) the value in
@@ -39,7 +43,7 @@
       to try and save the value, if the version number has change it will
       throw <classname>OptimisticLockingFailureException</classname>,
       indicating there has been an error with concurrent access. This check is
-      very necessary, since even though different batch jobs may be running in
+      necessary, since even though different batch jobs may be running in
       different machines, they are all using the same database tables.</para>
     </section>
 
@@ -51,7 +55,7 @@
       respective tables. However, they are not database generated keys, but
       rather are generated by separate sequences. This is necessary because
       after inserting one of the domain objects into the database, the key it
-      is given need to be set on the actual object, so that they can be
+      is given needs to be set on the actual object, so that they can be
       uniquely identified in Java. Newer database drivers (Jdbc 3.0 and up)
       support this feature with database generated keys, but rather than
       requiring it, sequences were used. Each variation of the schema will
@@ -61,8 +65,8 @@
 CREATE SEQUENCE BATCH_JOB_EXECUTION_SEQ;
 CREATE SEQUENCE BATCH_JOB_SEQ;</programlisting>
 
-      <para>Many database vendors don't official support sequences. In these
-      cases, work arounds are used, such as the following for mySQL:</para>
+      <para>Many database vendors don't support sequences. In these cases,
+      work arounds are used, such as the following for mySQL:</para>
 
       <programlisting>CREATE TABLE BATCH_STEP_EXECUTION_SEQ (ID BIGINT NOT NULL) type=MYISAM;
 INSERT INTO BATCH_STEP_EXECUTION_SEQ values(0);
@@ -73,7 +77,7 @@ INSERT INTO BATCH_JOB_SEQ values(0);</programlisting>
 
       <para>In the above case, a table is used in place of each sequence. The
       Spring core class <classname>MySQLMaxValueIncrementer</classname> will
-      then increment hte one column in this sequence in order to give similar
+      then increment the one column in this sequence in order to give similar
       functionality.</para>
     </section>
   </section>
@@ -83,7 +87,7 @@ INSERT INTO BATCH_JOB_SEQ values(0);</programlisting>
 
     <para>The BATCH_JOB_INSTANCE table holds all information relevant to a
     <classname>JobInstance</classname>, and serves as the top of the overall
-    heirarchy. The following generic DDL statement is used to create
+    hierarchy. The following generic DDL statement is used to create
     it:</para>
 
     <programlisting>CREATE TABLE BATCH_JOB_INSTANCE  (
@@ -156,12 +160,12 @@ INSERT INTO BATCH_JOB_SEQ values(0);</programlisting>
 
       <listitem>
         <para>TYPE_CD: String representation of the type of value stored,
-        which can be either a character string, date, long, or double. Because
-        the type must be known, it cannot be null.</para>
+        which can be either a string, date, long, or double. Because the type
+        must be known, it cannot be null.</para>
       </listitem>
 
       <listitem>
-        <para>KEY_NAME: The Parameter key.</para>
+        <para>KEY_NAME: The parameter key.</para>
       </listitem>
 
       <listitem>
@@ -177,7 +181,7 @@ INSERT INTO BATCH_JOB_SEQ values(0);</programlisting>
       </listitem>
 
       <listitem>
-        <para>DOUBLE_VAL: Paramter value, if the type is double.</para>
+        <para>DOUBLE_VAL: Parameter value, if the type is double.</para>
       </listitem>
     </itemizedlist>
 
@@ -214,8 +218,8 @@ INSERT INTO BATCH_JOB_SEQ values(0);</programlisting>
     <itemizedlist>
       <listitem>
         <para>JOB_EXECUTION_ID: Primary key that uniquely identifies this
-        execution. The value of this column should be obtainable by calling
-        the <methodname>getId</methodname> method of the
+        execution. The value of this column is obtainable by calling the
+        <methodname>getId</methodname> method of the
         <classname>JobExecution</classname> object.</para>
       </listitem>
 
@@ -347,7 +351,7 @@ INSERT INTO BATCH_JOB_SEQ values(0);</programlisting>
       </listitem>
 
       <listitem>
-        <para>ITEM_COUNT: The number of items that have been writtne out
+        <para>ITEM_COUNT: The number of items that have been written out
         during this execution.</para>
       </listitem>
 
@@ -378,10 +382,10 @@ INSERT INTO BATCH_JOB_SEQ values(0);</programlisting>
     one <classname>ExecutionContext</classname> per
     <classname>StepExecution</classname>, and it contains all user defined
     key/value pairs that need to persisted for a particular job run. This data
-    is usually state information that must be retrieved back after a failure
-    so that a JobInstance can 'start from where it left off'. As with the
-    BATCH_JOB_PARAMS table, this table has been denormalized and uses a column
-    to determine the type:</para>
+    is typically state that must be retrieved back after a failure so that a
+    <classname>JobInstance</classname> can 'start from where it left off'. As
+    with the BATCH_JOB_PARAMS table, this table has been denormalized and uses
+    a column to determine the type:</para>
 
     <programlisting>CREATE TABLE BATCH_STEP_EXECUTION_CONTEXT  (
   STEP_EXECUTION_ID BIGINT NOT NULL ,
@@ -429,7 +433,7 @@ INSERT INTO BATCH_JOB_SEQ values(0);</programlisting>
       </listitem>
 
       <listitem>
-        <para>DOUBLE_VAL: Paramter value, if the type is double.</para>
+        <para>DOUBLE_VAL: Parameter value, if the type is double.</para>
       </listitem>
 
       <listitem>
@@ -445,4 +449,31 @@ INSERT INTO BATCH_JOB_SEQ values(0);</programlisting>
     it. If a user so chooses, one may be added with a database generated key,
     without causing any issues to the framework itself.</para>
   </section>
+
+  <section>
+    <title>Archiving</title>
+
+    <para>Because there are entries in multiple tables everytime a batch job
+    is run, it is common to create an archive strategy for the meta-data
+    tables. The tables themselves are designed to show a record of what
+    happened in the past, and generally won't affect the run of any job, with
+    a couple of notable exceptions:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Restart: Because the ExecutionContext is persisted, removing any
+        entries from this table of jobs that haven't completed successfully,
+        will prevent them from starting at the correct point if run again.
+        Furthermore, if an entry for a JobInstance is removed without having
+        completed successfully, the framework will think that the job is new,
+        rather than a restart.</para>
+      </listitem>
+
+      <listitem>
+        <para>Determining if an instance has been run: The framework will use
+        the meta-data tables to determine if a particular JobInstance has been
+        run before, and if it has an exception will be thrown.</para>
+      </listitem>
+    </itemizedlist>
+  </section>
 </appendix>