BATCH-1531: add docs to user guide and javadocs

spring-batch-core/src/main/java/org/springframework/batch/core/partition/support/PartitionNameProvider.java

@@ -25,6 +25,14 @@ import java.util.Collection;
  * interface if a partitioner extends {@link SimplePartitioner} and re-uses the
  * default partition names.
  * </p>
+ * <p>
+ * If a partitioner does implement this interface, however, on a restart the
+ * {@link Partitioner#partition(int)} method will not be called again, instead
+ * the partitions will be re-used from the last execution, and matched by name
+ * with the results of {@link PartitionNameProvider#getPartitionNames(int)}.
+ * This can be a useful performance optimisation if the partitioning process is
+ * expensive.
+ * </p>
  * 
  * @author Dave Syer
  * 

src/site/docbook/reference/scalability.xml

@@ -340,6 +340,17 @@
       <classname>Job</classname>), and the suffix is just a counter. There is
       a <classname>SimplePartitioner</classname> in the framework that uses
       this convention.</para>
+
+      <para>An optional interface
+      <classname>PartitioneNameProvider</classname> can be used to
+      provide the partition names separately from the partitions
+      themselves.  If a <classname>Partitioner</classname> implements
+      this interface then on a restart only the names will be queried.
+      If partitioning is expensive this can be a useful optimisation.
+      Obviously the names provided by the
+      <classname>PartitioneNameProvider</classname> must match those
+      provided by the <classname>Partitioner</classname>.</para>
+
     </section>
 
     <section id="bindingInputDataToSteps">