INT-2260: JdbcPollingChA: rename prop to maxRows

JIRA: https://jira.spring.io/browse/INT-2260

Having a feedback about confusing with the `max-rows-per-poll` property
name and its responsibility it would be better do not mention `per-poll`
at all

* Deprecate `max-rows-per-poll` in favor of new `max-rows`
* Some code style polishing, tests improvements
* Docs polishing on the matter

* Add `What's New` bullet

* Optimize `maxRows` logic
* Document vendor-specific native SELECT limiting options
* Raise warning in the parsers about deprecated `max-rows-per-poll`

Doc polishing

Author: artembilan

spring-integration-jdbc/src/main/java/org/springframework/integration/jdbc/JdbcOutboundGateway.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-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.
@@ -44,14 +44,13 @@ public class JdbcOutboundGateway extends AbstractReplyProducingMessageHandler im
 
 	private final JdbcPollingChannelAdapter poller;
 
-	private volatile SqlParameterSourceFactory sqlParameterSourceFactory =
-			new ExpressionEvaluatingSqlParameterSourceFactory();
+	private SqlParameterSourceFactory sqlParameterSourceFactory = new ExpressionEvaluatingSqlParameterSourceFactory();
 
-	private volatile boolean sqlParameterSourceFactorySet;
+	private boolean sqlParameterSourceFactorySet;
 
-	private volatile boolean keysGenerated;
+	private boolean keysGenerated;
 
-	private volatile Integer maxRowsPerPoll;
+	private Integer maxRows;
 
 	public JdbcOutboundGateway(DataSource dataSource, String updateQuery) {
 		this(new JdbcTemplate(dataSource), updateQuery, null);
@@ -66,16 +65,16 @@ public JdbcOutboundGateway(JdbcOperations jdbcOperations, String updateQuery) {
 	}
 
 	public JdbcOutboundGateway(JdbcOperations jdbcOperations, String updateQuery, String selectQuery) {
-
 		Assert.notNull(jdbcOperations, "'jdbcOperations' must not be null.");
 
 		if (!StringUtils.hasText(updateQuery) && !StringUtils.hasText(selectQuery)) {
-			throw new IllegalArgumentException("The 'updateQuery' and the 'selectQuery' must not both be null or empty.");
+			throw new IllegalArgumentException(
+					"The 'updateQuery' and the 'selectQuery' must not both be null or empty.");
 		}
 
 		if (StringUtils.hasText(selectQuery)) {
 			this.poller = new JdbcPollingChannelAdapter(jdbcOperations, selectQuery);
-			this.poller.setMaxRowsPerPoll(1);
+			this.poller.setMaxRows(1);
 		}
 		else {
 			this.poller = null;
@@ -98,10 +97,54 @@ public JdbcOutboundGateway(JdbcOperations jdbcOperations, String updateQuery, St
 	 * This parameter is only applicable if a selectQuery was provided. Null values
 	 * are not permitted.
 	 * @param maxRowsPerPoll the number of rows to select. Must not be null.
+	 * @deprecated since 5.1 in favor of {@link #setMaxRows(Integer)}
 	 */
+	@Deprecated
 	public void setMaxRowsPerPoll(Integer maxRowsPerPoll) {
-		Assert.notNull(maxRowsPerPoll, "MaxRowsPerPoll must not be null.");
-		this.maxRowsPerPoll = maxRowsPerPoll;
+		setMaxRows(maxRowsPerPoll);
+	}
+
+	/**
+	 * The maximum number of rows to query.
+	 * The value is ultimately set on the underlying {@link JdbcPollingChannelAdapter}.
+	 * If not specified this value will default to {@code 1}.
+	 * This parameter is only applicable if a selectQuery was provided. Null values
+	 * are not permitted.
+	 * @param maxRows the number of rows to select. Must not be null.
+	 * @since 5.1
+	 * @see JdbcPollingChannelAdapter#setMaxRows(int)
+	 */
+	public void setMaxRows(Integer maxRows) {
+		Assert.notNull(maxRows, "'maxRows' must not be null.");
+		this.maxRows = maxRows;
+	}
+
+	/**
+	 * Flag to indicate that the update query is an insert with auto-generated keys,
+	 * which will be logged at debug level.
+	 * @param keysGenerated the flag value to set
+	 */
+	public void setKeysGenerated(boolean keysGenerated) {
+		this.keysGenerated = keysGenerated;
+	}
+
+	public void setRequestSqlParameterSourceFactory(SqlParameterSourceFactory sqlParameterSourceFactory) {
+		Assert.notNull(this.handler, "'handler' cannot be null");
+		this.handler.setSqlParameterSourceFactory(sqlParameterSourceFactory);
+	}
+
+	public void setRequestPreparedStatementSetter(MessagePreparedStatementSetter requestPreparedStatementSetter) {
+		Assert.notNull(this.handler, "'handler' cannot be null");
+		this.handler.setPreparedStatementSetter(requestPreparedStatementSetter);
+	}
+
+	public void setReplySqlParameterSourceFactory(SqlParameterSourceFactory sqlParameterSourceFactory) {
+		this.sqlParameterSourceFactory = sqlParameterSourceFactory;
+		this.sqlParameterSourceFactorySet = true;
+	}
+
+	public void setRowMapper(RowMapper<?> rowMapper) {
+		this.poller.setRowMapper(rowMapper);
 	}
 
 	@Override
@@ -111,9 +154,9 @@ public String getComponentType() {
 
 	@Override
 	protected void doInit() {
-		if (this.maxRowsPerPoll != null) {
-			Assert.notNull(this.poller, "If you want to set 'maxRowsPerPoll', then you must provide a 'selectQuery'.");
-			this.poller.setMaxRowsPerPoll(this.maxRowsPerPoll);
+		if (this.maxRows != null) {
+			Assert.notNull(this.poller, "If you want to set 'maxRows', then you must provide a 'selectQuery'.");
+			this.poller.setMaxRows(this.maxRows);
 		}
 
 		if (this.handler != null) {
@@ -167,31 +210,4 @@ protected Object handleRequestMessage(Message<?> requestMessage) {
 		return payload;
 	}
 
-	/**
-	 * Flag to indicate that the update query is an insert with auto-generated keys, which will be logged at debug level.
-	 * @param keysGenerated the flag value to set
-	 */
-	public void setKeysGenerated(boolean keysGenerated) {
-		this.keysGenerated = keysGenerated;
-	}
-
-	public void setRequestSqlParameterSourceFactory(SqlParameterSourceFactory sqlParameterSourceFactory) {
-		Assert.notNull(this.handler, "'handler' cannot be null");
-		this.handler.setSqlParameterSourceFactory(sqlParameterSourceFactory);
-	}
-
-	public void setRequestPreparedStatementSetter(MessagePreparedStatementSetter requestPreparedStatementSetter) {
-		Assert.notNull(this.handler, "'handler' cannot be null");
-		this.handler.setPreparedStatementSetter(requestPreparedStatementSetter);
-	}
-
-	public void setReplySqlParameterSourceFactory(SqlParameterSourceFactory sqlParameterSourceFactory) {
-		this.sqlParameterSourceFactory = sqlParameterSourceFactory;
-		this.sqlParameterSourceFactorySet = true;
-	}
-
-	public void setRowMapper(RowMapper<?> rowMapper) {
-		this.poller.setRowMapper(rowMapper);
-	}
-
 }

spring-integration-jdbc/src/main/java/org/springframework/integration/jdbc/JdbcPollingChannelAdapter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-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.
@@ -16,22 +16,25 @@
 
 package org.springframework.integration.jdbc;
 
-import java.util.ArrayList;
+import java.sql.PreparedStatement;
 import java.util.List;
+import java.util.function.Consumer;
 
 import javax.sql.DataSource;
 
 import org.springframework.integration.context.IntegrationObjectSupport;
 import org.springframework.integration.core.MessageSource;
 import org.springframework.jdbc.core.ColumnMapRowMapper;
 import org.springframework.jdbc.core.JdbcOperations;
-import org.springframework.jdbc.core.ResultSetExtractor;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.core.PreparedStatementCreator;
+import org.springframework.jdbc.core.PreparedStatementCreatorFactory;
 import org.springframework.jdbc.core.RowMapper;
-import org.springframework.jdbc.core.RowMapperResultSetExtractor;
 import org.springframework.jdbc.core.namedparam.NamedParameterJdbcOperations;
 import org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate;
 import org.springframework.jdbc.core.namedparam.SqlParameterSource;
 import org.springframework.messaging.Message;
+import org.springframework.util.Assert;
 
 /**
  * A polling channel adapter that creates messages from the payload returned by
@@ -50,42 +53,55 @@ public class JdbcPollingChannelAdapter extends IntegrationObjectSupport implemen
 
 	private final String selectQuery;
 
-	private volatile RowMapper<?> rowMapper;
+	private RowMapper<?> rowMapper;
 
-	private volatile SqlParameterSource sqlQueryParameterSource;
+	private SqlParameterSource sqlQueryParameterSource;
 
-	private volatile boolean updatePerRow = false;
+	private boolean updatePerRow = false;
 
-	private volatile String updateSql;
+	private String updateSql;
 
-	private volatile SqlParameterSourceFactory sqlParameterSourceFactory =
-			new ExpressionEvaluatingSqlParameterSourceFactory();
+	private SqlParameterSourceFactory sqlParameterSourceFactory = new ExpressionEvaluatingSqlParameterSourceFactory();
 
-	private volatile boolean sqlParameterSourceFactorySet;
+	private boolean sqlParameterSourceFactorySet;
 
-	private volatile int maxRowsPerPoll = 0;
+	private int maxRows = 0;
 
 	/**
 	 * Constructor taking {@link DataSource} from which the DB Connection can be
 	 * obtained and the select query to execute to retrieve new rows.
-	 *
 	 * @param dataSource Must not be null
 	 * @param selectQuery query to execute
 	 */
 	public JdbcPollingChannelAdapter(DataSource dataSource, String selectQuery) {
-		this.jdbcOperations = new NamedParameterJdbcTemplate(dataSource);
-		this.selectQuery = selectQuery;
+		this(new JdbcTemplate(dataSource), selectQuery);
 	}
 
 	/**
 	 * Constructor taking {@link JdbcOperations} instance to use for query
 	 * execution and the select query to execute to retrieve new rows.
-	 *
 	 * @param jdbcOperations instance to use for query execution
 	 * @param selectQuery query to execute
 	 */
 	public JdbcPollingChannelAdapter(JdbcOperations jdbcOperations, String selectQuery) {
-		this.jdbcOperations = new NamedParameterJdbcTemplate(jdbcOperations);
+		Assert.hasText(selectQuery, "'selectQuery' must be specified.");
+		this.jdbcOperations = new NamedParameterJdbcTemplate(jdbcOperations) {
+
+			@Override
+			protected PreparedStatementCreator getPreparedStatementCreator(String sql,
+					SqlParameterSource paramSource, Consumer<PreparedStatementCreatorFactory> customizer) {
+
+				PreparedStatementCreator preparedStatementCreator =
+						super.getPreparedStatementCreator(sql, paramSource, customizer);
+
+				return con -> {
+					PreparedStatement preparedStatement = preparedStatementCreator.createPreparedStatement(con);
+					preparedStatement.setMaxRows(JdbcPollingChannelAdapter.this.maxRows);
+					return preparedStatement;
+				};
+			}
+		};
+
 		this.selectQuery = selectQuery;
 	}
 
@@ -108,7 +124,6 @@ public void setUpdateSqlParameterSourceFactory(SqlParameterSourceFactory sqlPara
 
 	/**
 	 * A source of parameters for the select query used for polling.
-	 *
 	 * @param sqlQueryParameterSource the sql query parameter source to set
 	 */
 	public void setSelectSqlParameterSource(SqlParameterSource sqlQueryParameterSource) {
@@ -119,22 +134,37 @@ public void setSelectSqlParameterSource(SqlParameterSource sqlQueryParameterSour
 	 * The maximum number of rows to pull out of the query results per poll (if
 	 * greater than zero, otherwise all rows will be packed into the outgoing
 	 * message). Default is zero.
-	 *
 	 * @param maxRows the max rows to set
+	 * @deprecated since 5.1 in favor of {@link #setMaxRows(int)}
 	 */
+	@Deprecated
 	public void setMaxRowsPerPoll(int maxRows) {
-		this.maxRowsPerPoll = maxRows;
+		setMaxRows(maxRows);
+	}
+
+	/**
+	 * The maximum number of rows to query. Default is zero - select all records.
+	 * @param maxRows the max rows to set
+	 * @since 5.1
+	 */
+	public void setMaxRows(int maxRows) {
+		this.maxRows = maxRows;
 	}
 
 	@Override
 	protected void onInit() throws Exception {
 		super.onInit();
-		if (!this.sqlParameterSourceFactorySet && this.getBeanFactory() != null) {
+		if (!this.sqlParameterSourceFactorySet && getBeanFactory() != null) {
 			((ExpressionEvaluatingSqlParameterSourceFactory) this.sqlParameterSourceFactory)
-					.setBeanFactory(this.getBeanFactory());
+					.setBeanFactory(getBeanFactory());
 		}
 	}
 
+	@Override
+	public String getComponentType() {
+		return "jdbc:inbound-channel-adapter";
+	}
+
 	/**
 	 * Execute the query. If a query result set contains one or more rows, the
 	 * Message payload will contain either a List of Maps for each row or, if a
@@ -148,7 +178,9 @@ public Message<Object> receive() {
 		if (payload == null) {
 			return null;
 		}
-		return this.getMessageBuilderFactory().withPayload(payload).build();
+		return getMessageBuilderFactory()
+				.withPayload(payload)
+				.build();
 	}
 
 	/**
@@ -174,43 +206,20 @@ private Object poll() {
 		return payload;
 	}
 
-	private void executeUpdateQuery(Object obj) {
-		SqlParameterSource updateParameterSource = this.sqlParameterSourceFactory.createParameterSource(obj);
-		this.jdbcOperations.update(this.updateSql, updateParameterSource);
-	}
-
 	protected List<?> doPoll(SqlParameterSource sqlQueryParameterSource) {
 		final RowMapper<?> rowMapper = this.rowMapper == null ? new ColumnMapRowMapper() : this.rowMapper;
-		ResultSetExtractor<List<Object>> resultSetExtractor;
-
-		if (this.maxRowsPerPoll > 0) {
-			resultSetExtractor = rs -> {
-				List<Object> results = new ArrayList<Object>(JdbcPollingChannelAdapter.this.maxRowsPerPoll);
-				int rowNum = 0;
-				while (rs.next() && rowNum < JdbcPollingChannelAdapter.this.maxRowsPerPoll) {
-					results.add(rowMapper.mapRow(rs, rowNum++));
-				}
-				return results;
-			};
-		}
-		else {
-			@SuppressWarnings("unchecked")
-			ResultSetExtractor<List<Object>> temp =
-					new RowMapperResultSetExtractor<Object>((RowMapper<Object>) rowMapper);
-			resultSetExtractor = temp;
-		}
 
 		if (sqlQueryParameterSource != null) {
-			return this.jdbcOperations.query(this.selectQuery, sqlQueryParameterSource, resultSetExtractor);
+			return this.jdbcOperations.query(this.selectQuery, sqlQueryParameterSource, rowMapper);
 		}
 		else {
-			return this.jdbcOperations.getJdbcOperations().query(this.selectQuery, resultSetExtractor);
+			return this.jdbcOperations.query(this.selectQuery, rowMapper);
 		}
 	}
 
-	@Override
-	public String getComponentType() {
-		return "jdbc:inbound-channel-adapter";
+	private void executeUpdateQuery(Object obj) {
+		SqlParameterSource updateParameterSource = this.sqlParameterSourceFactory.createParameterSource(obj);
+		this.jdbcOperations.update(this.updateSql, updateParameterSource);
 	}
 
 }