Clean up and improve Java DSL for JDBC

Follow up for: #10081

* Rename `StoredProcExecutorConfigurer` to `StoredProcExecutorSpec`
* Add `Jdbc.storedProcExecutorSpec()` factory
* Improve logic of `StoredProcExecutor`-based Java DSL classes to handle an external `StoredProcExecutor` as well
* Add `package-info.java` into the `jdbc/dsl` package
* Add `/jdbc/dsl.adoc` and respective `What's New` entry

Author: artembilan

spring-integration-jdbc/src/main/java/org/springframework/integration/jdbc/dsl/Jdbc.java

@@ -26,6 +26,7 @@
  * Factory class for JDBC components.
  *
  * @author Jiandong Ma
+ * @author Artem Bilan
  *
  * @since 7.0
  */
@@ -109,7 +110,9 @@ public static JdbcOutboundGatewaySpec outboundGateway(JdbcOperations jdbcOperati
 	 * @param selectQuery the select query to build on
 	 * @return the {@link JdbcOutboundGatewaySpec} instance
 	 */
-	public static JdbcOutboundGatewaySpec outboundGateway(JdbcOperations jdbcOperations, String updateQuery, String selectQuery) {
+	public static JdbcOutboundGatewaySpec outboundGateway(JdbcOperations jdbcOperations, String updateQuery,
+			String selectQuery) {
+
 		return new JdbcOutboundGatewaySpec(jdbcOperations, updateQuery, selectQuery);
 	}
 
@@ -119,7 +122,18 @@ public static JdbcOutboundGatewaySpec outboundGateway(JdbcOperations jdbcOperati
 	 * @return the {@link JdbcStoredProcInboundChannelAdapterSpec} instance
 	 */
 	public static JdbcStoredProcInboundChannelAdapterSpec storedProcInboundAdapter(DataSource dataSource) {
-		return new JdbcStoredProcInboundChannelAdapterSpec(new StoredProcExecutor(dataSource));
+		return new JdbcStoredProcInboundChannelAdapterSpec(storedProcExecutorSpec(dataSource));
+	}
+
+	/**
+	 * The factory to produce a {@link JdbcStoredProcInboundChannelAdapterSpec}.
+	 * @param storedProcExecutor the {@link StoredProcExecutor} to use
+	 * @return the {@link JdbcStoredProcInboundChannelAdapterSpec} instance
+	 */
+	public static JdbcStoredProcInboundChannelAdapterSpec storedProcInboundAdapter(
+			StoredProcExecutor storedProcExecutor) {
+
+		return new JdbcStoredProcInboundChannelAdapterSpec(storedProcExecutor);
 	}
 
 	/**
@@ -128,7 +142,18 @@ public static JdbcStoredProcInboundChannelAdapterSpec storedProcInboundAdapter(D
 	 * @return the {@link JdbcStoredProcOutboundChannelAdapterSpec} instance
 	 */
 	public static JdbcStoredProcOutboundChannelAdapterSpec storedProcOutboundAdapter(DataSource dataSource) {
-		return new JdbcStoredProcOutboundChannelAdapterSpec(new StoredProcExecutor(dataSource));
+		return new JdbcStoredProcOutboundChannelAdapterSpec(storedProcExecutorSpec(dataSource));
+	}
+
+	/**
+	 * The factory to produce a {@link JdbcStoredProcOutboundChannelAdapterSpec}.
+	 * @param storedProcExecutor the {@link StoredProcExecutor} to use
+	 * @return the {@link JdbcStoredProcOutboundChannelAdapterSpec} instance
+	 */
+	public static JdbcStoredProcOutboundChannelAdapterSpec storedProcOutboundAdapter(
+			StoredProcExecutor storedProcExecutor) {
+
+		return new JdbcStoredProcOutboundChannelAdapterSpec(storedProcExecutor);
 	}
 
 	/**
@@ -137,7 +162,25 @@ public static JdbcStoredProcOutboundChannelAdapterSpec storedProcOutboundAdapter
 	 * @return the {@link JdbcStoredProcOutboundGatewaySpec} instance
 	 */
 	public static JdbcStoredProcOutboundGatewaySpec storedProcOutboundGateway(DataSource dataSource) {
-		return new JdbcStoredProcOutboundGatewaySpec(new StoredProcExecutor(dataSource));
+		return new JdbcStoredProcOutboundGatewaySpec(storedProcExecutorSpec(dataSource));
+	}
+
+	/**
+	 * The factory to produce a {@link JdbcStoredProcOutboundGatewaySpec}.
+	 * @param storedProcExecutor the {@link StoredProcExecutor} to use
+	 * @return the {@link JdbcStoredProcOutboundGatewaySpec} instance
+	 */
+	public static JdbcStoredProcOutboundGatewaySpec storedProcOutboundGateway(StoredProcExecutor storedProcExecutor) {
+		return new JdbcStoredProcOutboundGatewaySpec(storedProcExecutor);
+	}
+
+	/**
+	 * The factory to produce a {@link StoredProcExecutorSpec}.
+	 * @param dataSource the {@link DataSource} to build on
+	 * @return the {@link StoredProcExecutorSpec} instance
+	 */
+	public static StoredProcExecutorSpec storedProcExecutorSpec(DataSource dataSource) {
+		return new StoredProcExecutorSpec(dataSource);
 	}
 
 	private Jdbc() {

spring-integration-jdbc/src/main/java/org/springframework/integration/jdbc/dsl/JdbcInboundChannelAdapterSpec.java

@@ -27,10 +27,12 @@
  * A {@link MessageSourceSpec} for a {@link JdbcInboundChannelAdapterSpec}.
  *
  * @author Jiandong Ma
+ * @author Artem Bilan
  *
  * @since 7.0
  */
-public class JdbcInboundChannelAdapterSpec extends MessageSourceSpec<JdbcInboundChannelAdapterSpec, JdbcPollingChannelAdapter> {
+public class JdbcInboundChannelAdapterSpec
+		extends MessageSourceSpec<JdbcInboundChannelAdapterSpec, JdbcPollingChannelAdapter> {
 
 	protected JdbcInboundChannelAdapterSpec(JdbcOperations jdbcOperations, String selectQuery) {
 		this.target = new JdbcPollingChannelAdapter(jdbcOperations, selectQuery);
@@ -43,7 +45,7 @@ protected JdbcInboundChannelAdapterSpec(JdbcOperations jdbcOperations, String se
 	 */
 	public JdbcInboundChannelAdapterSpec rowMapper(RowMapper<?> rowMapper) {
 		this.target.setRowMapper(rowMapper);
-		return _this();
+		return this;
 	}
 
 	/**
@@ -53,7 +55,7 @@ public JdbcInboundChannelAdapterSpec rowMapper(RowMapper<?> rowMapper) {
 	 */
 	public JdbcInboundChannelAdapterSpec updateSql(String updateSql) {
 		this.target.setUpdateSql(updateSql);
-		return _this();
+		return this;
 	}
 
 	/**
@@ -63,17 +65,19 @@ public JdbcInboundChannelAdapterSpec updateSql(String updateSql) {
 	 */
 	public JdbcInboundChannelAdapterSpec updatePerRow(boolean updatePerRow) {
 		this.target.setUpdatePerRow(updatePerRow);
-		return _this();
+		return this;
 	}
 
 	/**
 	 * @param sqlParameterSourceFactory the sqlParameterSourceFactory
 	 * @return the spec
 	 * @see JdbcPollingChannelAdapter#setUpdateSqlParameterSourceFactory(SqlParameterSourceFactory)
 	 */
-	public JdbcInboundChannelAdapterSpec updateSqlParameterSourceFactory(SqlParameterSourceFactory sqlParameterSourceFactory) {
+	public JdbcInboundChannelAdapterSpec updateSqlParameterSourceFactory(
+			SqlParameterSourceFactory sqlParameterSourceFactory) {
+
 		this.target.setUpdateSqlParameterSourceFactory(sqlParameterSourceFactory);
-		return _this();
+		return this;
 	}
 
 	/**
@@ -83,7 +87,7 @@ public JdbcInboundChannelAdapterSpec updateSqlParameterSourceFactory(SqlParamete
 	 */
 	public JdbcInboundChannelAdapterSpec selectSqlParameterSource(SqlParameterSource sqlQueryParameterSource) {
 		this.target.setSelectSqlParameterSource(sqlQueryParameterSource);
-		return _this();
+		return this;
 	}
 
 	/**
@@ -93,7 +97,7 @@ public JdbcInboundChannelAdapterSpec selectSqlParameterSource(SqlParameterSource
 	 */
 	public JdbcInboundChannelAdapterSpec maxRows(int maxRows) {
 		this.target.setMaxRows(maxRows);
-		return _this();
+		return this;
 	}
 
 }

spring-integration-jdbc/src/main/java/org/springframework/integration/jdbc/dsl/JdbcOutboundChannelAdapterSpec.java

@@ -26,10 +26,12 @@
  * A {@link MessageHandlerSpec} for a {@link JdbcOutboundChannelAdapterSpec}.
  *
  * @author Jiandong Ma
+ * @author Artem Bilan
  *
  * @since 7.0
  */
-public class JdbcOutboundChannelAdapterSpec extends MessageHandlerSpec<JdbcOutboundChannelAdapterSpec, JdbcMessageHandler> {
+public class JdbcOutboundChannelAdapterSpec
+		extends MessageHandlerSpec<JdbcOutboundChannelAdapterSpec, JdbcMessageHandler> {
 
 	protected JdbcOutboundChannelAdapterSpec(JdbcOperations jdbcOperations, String updateQuery) {
 		this.target = new JdbcMessageHandler(jdbcOperations, updateQuery);
@@ -42,17 +44,19 @@ protected JdbcOutboundChannelAdapterSpec(JdbcOperations jdbcOperations, String u
 	 */
 	public JdbcOutboundChannelAdapterSpec keysGenerated(boolean keysGenerated) {
 		this.target.setKeysGenerated(keysGenerated);
-		return _this();
+		return this;
 	}
 
 	/**
 	 * @param sqlParameterSourceFactory the sqlParameterSourceFactory
 	 * @return the spec
 	 * @see JdbcMessageHandler#setSqlParameterSourceFactory(SqlParameterSourceFactory)
 	 */
-	public JdbcOutboundChannelAdapterSpec sqlParameterSourceFactory(SqlParameterSourceFactory sqlParameterSourceFactory) {
+	public JdbcOutboundChannelAdapterSpec sqlParameterSourceFactory(
+			SqlParameterSourceFactory sqlParameterSourceFactory) {
+
 		this.target.setSqlParameterSourceFactory(sqlParameterSourceFactory);
-		return _this();
+		return this;
 	}
 
 	/**
@@ -62,17 +66,19 @@ public JdbcOutboundChannelAdapterSpec sqlParameterSourceFactory(SqlParameterSour
 	 */
 	public JdbcOutboundChannelAdapterSpec usePayloadAsParameterSource(boolean usePayloadAsParameterSource) {
 		this.target.setUsePayloadAsParameterSource(usePayloadAsParameterSource);
-		return _this();
+		return this;
 	}
 
 	/**
 	 * @param preparedStatementSetter the preparedStatementSetter
 	 * @return the spec
 	 * @see JdbcMessageHandler#setPreparedStatementSetter(MessagePreparedStatementSetter)
 	 */
-	public JdbcOutboundChannelAdapterSpec preparedStatementSetter(MessagePreparedStatementSetter preparedStatementSetter) {
+	public JdbcOutboundChannelAdapterSpec preparedStatementSetter(
+			MessagePreparedStatementSetter preparedStatementSetter) {
+
 		this.target.setPreparedStatementSetter(preparedStatementSetter);
-		return _this();
+		return this;
 	}
 
 }

spring-integration-jdbc/src/main/java/org/springframework/integration/jdbc/dsl/JdbcOutboundGatewaySpec.java

@@ -27,6 +27,7 @@
  * A {@link MessageHandlerSpec} for a {@link JdbcOutboundGatewaySpec}.
  *
  * @author Jiandong Ma
+ * @author Artem Bilan
  *
  * @since 7.0
  */
@@ -43,7 +44,7 @@ protected JdbcOutboundGatewaySpec(JdbcOperations jdbcOperations, String updateQu
 	 */
 	public JdbcOutboundGatewaySpec maxRows(Integer maxRows) {
 		this.target.setMaxRows(maxRows);
-		return _this();
+		return this;
 	}
 
 	/**
@@ -53,27 +54,31 @@ public JdbcOutboundGatewaySpec maxRows(Integer maxRows) {
 	 */
 	public JdbcOutboundGatewaySpec keysGenerated(boolean keysGenerated) {
 		this.target.setKeysGenerated(keysGenerated);
-		return _this();
+		return this;
 	}
 
 	/**
 	 * @param sqlParameterSourceFactory the sqlParameterSourceFactory
 	 * @return the spec
 	 * @see JdbcOutboundGateway#setRequestSqlParameterSourceFactory(SqlParameterSourceFactory)
 	 */
-	public JdbcOutboundGatewaySpec requestSqlParameterSourceFactory(SqlParameterSourceFactory sqlParameterSourceFactory) {
+	public JdbcOutboundGatewaySpec requestSqlParameterSourceFactory(
+			SqlParameterSourceFactory sqlParameterSourceFactory) {
+
 		this.target.setRequestSqlParameterSourceFactory(sqlParameterSourceFactory);
-		return _this();
+		return this;
 	}
 
 	/**
 	 * @param preparedStatementSetter the preparedStatementSetter
 	 * @return the spec
 	 * @see JdbcOutboundGateway#setRequestPreparedStatementSetter(MessagePreparedStatementSetter)
 	 */
-	public JdbcOutboundGatewaySpec requestPreparedStatementSetter(MessagePreparedStatementSetter preparedStatementSetter) {
+	public JdbcOutboundGatewaySpec requestPreparedStatementSetter(
+			MessagePreparedStatementSetter preparedStatementSetter) {
+
 		this.target.setRequestPreparedStatementSetter(preparedStatementSetter);
-		return _this();
+		return this;
 	}
 
 	/**
@@ -83,7 +88,7 @@ public JdbcOutboundGatewaySpec requestPreparedStatementSetter(MessagePreparedSta
 	 */
 	public JdbcOutboundGatewaySpec replySqlParameterSourceFactory(SqlParameterSourceFactory sqlParameterSourceFactory) {
 		this.target.setReplySqlParameterSourceFactory(sqlParameterSourceFactory);
-		return _this();
+		return this;
 	}
 
 	/**
@@ -93,7 +98,7 @@ public JdbcOutboundGatewaySpec replySqlParameterSourceFactory(SqlParameterSource
 	 */
 	public JdbcOutboundGatewaySpec rowMapper(RowMapper<?> rowMapper) {
 		this.target.setRowMapper(rowMapper);
-		return _this();
+		return this;
 	}
 
 }

spring-integration-jdbc/src/main/java/org/springframework/integration/jdbc/dsl/JdbcStoredProcInboundChannelAdapterSpec.java

@@ -20,6 +20,8 @@
 import java.util.Map;
 import java.util.function.Consumer;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.integration.dsl.ComponentsRegistration;
 import org.springframework.integration.dsl.MessageSourceSpec;
 import org.springframework.integration.jdbc.StoredProcExecutor;
@@ -30,6 +32,7 @@
  * A {@link MessageSourceSpec} for a {@link JdbcStoredProcInboundChannelAdapterSpec}.
  *
  * @author Jiandong Ma
+ * @author Artem Bilan
  *
  * @since 7.0
  */
@@ -39,11 +42,16 @@ public class JdbcStoredProcInboundChannelAdapterSpec
 
 	private final StoredProcExecutor storedProcExecutor;
 
-	private final StoredProcExecutorConfigurer storedProcExecutorConfigurer;
+	private @Nullable StoredProcExecutorSpec storedProcExecutorSpec;
+
+	protected JdbcStoredProcInboundChannelAdapterSpec(StoredProcExecutorSpec storedProcExecutorSpec) {
+		this(storedProcExecutorSpec.getObject());
+		this.storedProcExecutorSpec = storedProcExecutorSpec;
+	}
 
 	protected JdbcStoredProcInboundChannelAdapterSpec(StoredProcExecutor storedProcExecutor) {
 		this.storedProcExecutor = storedProcExecutor;
-		this.storedProcExecutorConfigurer = new StoredProcExecutorConfigurer(this.storedProcExecutor);
+		this.storedProcExecutorSpec = null;
 		this.target = new StoredProcPollingChannelAdapter(this.storedProcExecutor);
 	}
 
@@ -52,10 +60,14 @@ protected JdbcStoredProcInboundChannelAdapterSpec(StoredProcExecutor storedProcE
 	 * @param configurer the configurer.
 	 * @return the spec
 	 */
-	public JdbcStoredProcInboundChannelAdapterSpec configurerStoredProcExecutor(Consumer<StoredProcExecutorConfigurer> configurer) {
+	public JdbcStoredProcInboundChannelAdapterSpec configurerStoredProcExecutor(
+			Consumer<StoredProcExecutorSpec> configurer) {
+
 		Assert.notNull(configurer, "'configurer' must not be null");
-		configurer.accept(this.storedProcExecutorConfigurer);
-		return _this();
+		Assert.notNull(this.storedProcExecutorSpec,
+				"The externally provided 'StoredProcExecutor' cannot be mutated in this spec");
+		configurer.accept(this.storedProcExecutorSpec);
+		return this;
 	}
 
 	/**
@@ -65,11 +77,12 @@ public JdbcStoredProcInboundChannelAdapterSpec configurerStoredProcExecutor(Cons
 	 */
 	public JdbcStoredProcInboundChannelAdapterSpec expectSingleResult(boolean expectSingleResult) {
 		this.target.setExpectSingleResult(expectSingleResult);
-		return _this();
+		return this;
 	}
 
 	@Override
 	public Map<Object, String> getComponentsToRegister() {
 		return Collections.singletonMap(this.storedProcExecutor, null);
 	}
+
 }