INT-3772: Add MessagePreparedStatementCallback

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

INT-3722: Polishing

PR Comments and conflicts fixes

src/reference/asciidoc/jdbc.adoc

@@ -181,6 +181,49 @@ The following example uses a `ExpressionEvaluatingSqlParameterSourceFactory` to
 
 For further information, please also see <<sp-defining-parameter-sources>>
 
+_PreparedStatement Callback_
+
+There are some cases when the flexibility and loose-coupling of `SqlParameterSourceFactory` isn't enough for the target
+`PreparedStatement` or we need to do some low-level JDBC work.
+The Spring JDBC module provides APIs to configure the execution environment (e.g. `ConnectionCallback`
+or `PreparedStatementCreator`) and manipulation of parameter values (e.g. `SqlParameterSource`).
+Or even APIs for low level operations, for example `StatementCallback`.
+
+Starting with _Spring Integration 4.2_, the `MessagePreparedStatementSetter` is available to allow
+the specification of parameters on the `PreparedStatement` manually, in the `requestMessage` context.
+This class plays exactly the same role as `PreparedStatementSetter` in the standard Spring JDBC API.
+Actually it is invoked directly from an inline `PreparedStatementSetter` implementation, when the `JdbcMessageHandler`
+performs invokes `execute` on the `JdbcTemplate`.
+
+This functional interface option is mutually exclusive with `sqlParameterSourceFactory` and can be used as a more
+powerful alternative to populate parameters of the `PreparedStatement` from the `requestMessage`.
+For example it is useful when we need to store `File` data to the DataBase `BLOB` column in a stream manner:
+
+[source,java]
+----
+@Bean
+@ServiceActivator(inputChannel = "storeFileChannel")
+public MessageHandler jdbcMessageHandler(DataSource dataSource) {
+    JdbcMessageHandler jdbcMessageHandler = new JdbcMessageHandler(dataSource,
+    		"INSERT INTO imagedb (image_name, content, description) VALUES (?, ?, ?)");
+    jdbcMessageHandler.setPreparedStatementSetter((ps, m) -> {
+    	ps.setString(1, m.getHeaders().get(FileHeaders.FILENAME));
+    	try (FileInputStream inputStream = new FileInputStream((File) m.getPayload())) {
+    		ps.setBlob(2, inputStream);
+    	}
+    	catch (Exception e) {
+    		throw new MessageHandlingException(m, e);
+    	}
+    	ps.setClob(3, new StringReader(m.getHeaders().get("description", String.class)));
+    });
+    return jdbcMessageHandler;
+}
+----
+
+From the XML configuration perspective, the `prepared-statement-setter` attribute is available on the
+`<int-jdbc:outbound-channel-adapter>` component, to specify a  `MessagePreparedStatementSetter`
+bean reference.
+
 [[jdbc-outbound-gateway]]
 === Outbound Gateway
 
@@ -239,11 +282,19 @@ If keys-generated="true" then the root of the expression is the generated keys (
 The outbound gateway requires a reference to either a DataSource or a JdbcTemplate.
 It can also have a `SqlParameterSourceFactory` injected to control the binding of the incoming message to the query.
 
+Starting with the _version 4.2_ the `request-prepared-statement-setter` attribute is available on the
+`<int-jdbc:outbound-gateway>` as an alternative to the `request-sql-parameter-source-factory`.
+It allows you to specify a `MessagePreparedStatementSetter` bean reference, which implements more sophisticated
+`PreparedStatement` preparation before its execution.
+
+See <<jdbc-outbound-channel-adapter>> for more information about `MessagePreparedStatementSetter`.
+
 [[jdbc-message-store]]
 === JDBC Message Store
 
-Spring Integration provides 2 JDBC specifc Message Store implementations.
-The first one, is the `JdbcMessageStore` which is suitable to be used in conjunction with _Aggregators_ and the _Claimcheck_ pattern.
+Spring Integration provides 2 JDBC specific Message Store implementations.
+The first one, is the `JdbcMessageStore` which is suitable to be used in conjunction with _Aggregators_ and the
+_Claim-Check_ pattern.
 While it can be used for backing _Message Channels_ as well, you may want to consider using the `JdbcChannelMessageStore` implementation instead, as it provides a more targeted and scalable implementation.
 
 [[jdbc-message-store-generic]]

src/reference/asciidoc/whats-new.adoc

@@ -76,6 +76,14 @@ Codec-based transformers and message converters are also provided.
 
 See <<codec>> for more information.
 
+[[x4.2-prepared-statement-setter]]
+==== Message PreparedStatement Setter
+
+A new `MessagePreparedStatementSetter` functional interface callback is available for the `JdbcMessageHandler`
+(`<int-jdbc:outbound-gateway>` and `<int-jdbc:outbound-channel-adapter>`) as an alternative to the
+`SqlParameterSourceFactory` to populate parameters on the `PreparedStatement` with the `requestMessage` context.
+
+See <<jdbc-outbound-channel-adapter>> for more information.
 
 [[x4.2-general]]
 === General Changes