BATCH-1346: added test and extra Javadocs to clarify

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

@@ -26,21 +26,42 @@ import java.util.HashMap;
 import com.ibatis.sqlmap.client.SqlMapClient;
 
 /**
- * {@link org.springframework.batch.item.ItemReader} for reading database records using iBATIS in a paging
- * fashion.
- *
- * It executes the query specified as the {@link #setQueryId(String)} to retrieve requested data.
- * The query is executed using paged requests of a size specified in {@link #setPageSize(int)}.
- * Additional pages are requested when needed as {@link #read()} method is called, returning an
- * object corresponding to current position.
- *
+ * <p>
+ * {@link org.springframework.batch.item.ItemReader} for reading database
+ * records using iBATIS in a paging fashion.
+ * </p>
+ * 
+ * <p>
+ * It executes the query specified as the {@link #setQueryId(String)} to
+ * retrieve requested data. The query is executed using paged requests of a size
+ * specified in {@link #setPageSize(int)}. Additional pages are requested when
+ * needed as {@link #read()} method is called, returning an object corresponding
+ * to current position. Some standard query parameters are provided by the
+ * reader and the SQL in the named query must use some or all of these parameters
+ * (depending on the SQL variant) to construct a result set of the required
+ * size. The parameters are:
+ * <ul>
+ * <li><code>_page</code>: the page number to be read (starting at 0)</li>
+ * <li><code>_pagesize</code>: the size of the pages, i.e. the number of rows to
+ * return</li>
+ * <li><code>_skiprows</code>: the product of <code>_page</code> and
+ * <code>_pagesize</code></li>
+ * </ul>
+ * Failure to write the correct platform-specific SQL often results in an
+ * infinite loop in the reader because it keeps asking for the next page and
+ * gets the same result set over and over.
+ * </p>
+ * 
+ * <p>
  * The performance of the paging depends on the iBATIS implementation.
- *
- * Setting a fairly large page size and using a commit interval that matches the page size should provide
- * better performance.
- *
+ * Setting a fairly large page size and using a commit interval that matches the
+ * page size should provide better performance.
+ * </p>
+ * 
+ * <p>
  * The implementation is *not* thread-safe.
- *
+ * </p>
+ * 
  * @author Thomas Risberg
  * @since 2.0
  */
@@ -68,14 +89,14 @@ public class IbatisPagingItemReader<T> extends AbstractPagingItemReader<T> {
 
 	/**
 	 * The parameter values to be used for the query execution.
-	 *
-	 * @param parameterValues the values keyed by the parameter named used in the query string.
+	 * 
+	 * @param parameterValues the values keyed by the parameter named used in
+	 * the query string.
 	 */
 	public void setParameterValues(Map<String, Object> parameterValues) {
 		this.parameterValues = parameterValues;
 	}
 
-
 	/**
 	 * Check mandatory properties.
 	 * @see org.springframework.beans.factory.InitializingBean#afterPropertiesSet()

spring-batch-infrastructure/src/test/java/org/springframework/batch/item/database/AbstractDatabaseItemStreamItemReaderTests.java

@@ -5,7 +5,9 @@ import static org.junit.Assert.assertEquals;
 import javax.sql.DataSource;
 
 import org.springframework.batch.item.AbstractItemStreamItemReaderTests;
+import org.springframework.batch.item.ExecutionContext;
 import org.springframework.batch.item.ItemReader;
+import org.springframework.batch.item.ItemStream;
 import org.springframework.batch.item.sample.Foo;
 import org.springframework.context.support.ClassPathXmlApplicationContext;
 import org.junit.Before;
@@ -31,13 +33,14 @@ public abstract class AbstractDatabaseItemStreamItemReaderTests extends Abstract
 	@Test
 	public void testReadToExhaustion() throws Exception {
 		ItemReader<Foo> reader = getItemReader();
-		pointToEmptyInput(reader);
+		((ItemStream) reader).open(new ExecutionContext());
+		// pointToEmptyInput(reader);
 		int count = 0;
 		Foo item = new Foo();
 		while (count++<100 && item!=null) {
 			item = reader.read();
 		}
-		assertEquals(2, count);
+		assertEquals(7, count);
 	}
 
 	protected DataSource getDataSource() {

spring-batch-infrastructure/src/test/java/org/springframework/batch/item/database/IbatisPagingItemReaderCommonTests.java

@@ -23,6 +23,7 @@ public class IbatisPagingItemReaderCommonTests extends AbstractDatabaseItemStrea
 
 		IbatisPagingItemReader reader = new IbatisPagingItemReader();
 		reader.setQueryId("getPagedFoos");
+		reader.setPageSize(2);
 		reader.setSqlMapClient(sqlMapClient);
 		reader.setSaveState(true);