BATCH-2465: add note about the importance to have a unique key

constraint on the sortKey

This PR is for BATCH-2465.

It updates the reference documentation and the Javadoc to mention
explicitly the importance to have a unique key constraint on the sortKey
when using paging item readers.

I deliberately used "It is important" and not "It is required" (or
mandatory) because in the end this is not required but in that case
there is no guarantee to not lose data between executions.

Please let me know if the wording should be updated.

Author: mminella

spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/JdbcPagingItemReader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2013 the original author or authors.
+ * Copyright 2006-2018 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -51,7 +51,8 @@
  * needed as {@link #read()} method is called, returning an object corresponding
  * to current position. On restart it uses the last sort key value to locate the
  * first page to read (so it doesn't matter if the successfully processed items
- * have been removed or modified).
+ * have been removed or modified).  It is important to have a unique key constraint on the
+ * sort key to guarantee that no data is lost between executions.
  * </p>
  * 
  * <p>

spring-batch-infrastructure/src/main/java/org/springframework/batch/item/database/support/AbstractSqlPagingQueryProvider.java

@@ -16,19 +16,19 @@
 
 package org.springframework.batch.item.database.support;
 
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import javax.sql.DataSource;
+
 import org.springframework.batch.item.database.JdbcParameterUtils;
 import org.springframework.batch.item.database.Order;
 import org.springframework.batch.item.database.PagingQueryProvider;
 import org.springframework.dao.InvalidDataAccessApiUsageException;
 import org.springframework.util.Assert;
 import org.springframework.util.StringUtils;
 
-import javax.sql.DataSource;
-import java.util.ArrayList;
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
-
 /**
  * Abstract SQL Paging Query Provider to serve as a base class for all provided
  * SQL paging query providers.
@@ -42,7 +42,9 @@
  * Provides properties and preparation for the mandatory "selectClause" and
  * "fromClause" as well as for the optional "whereClause". Also provides
  * property for the mandatory "sortKeys".  <b>Note:</b> The columns that make up 
- * the sort key must be a true key and not just a column to order by.
+ * the sort key must be a true key and not just a column to order by.  It is important
+ * to have a unique key constraint on the sort key to guarantee that no data is lost
+ * between executions.
  * 
  * @author Thomas Risberg
  * @author Dave Syer

src/site/docbook/reference/readersAndWriters.xml

@@ -2192,6 +2192,9 @@ itemReader.close(executionContext);</programlisting>
         also provide an optional where clause. These clauses will be used to
         build an SQL statement combined with the required sortKey.</para>
 
+        <note>It is important to have a unique key constraint on the `sortKey` to
+          guarantee that no data is lost between executions.</note>
+
         <para>After the reader has been opened, it will pass back one item per
         call to <methodname>read</methodname> in the same basic fashion as any
         other <classname>ItemReader</classname>. The paging happens behind the