GH-8626: Provide cleaner transform() DSL (#8653)

* GH-8626: Provide cleaner `transform()` DSL

Fixes #8626

* Add missed `transform(String beanName, @nullable String methodName)` API
* Introduce a `TransformerSpec` to expose a strict API to configure
transformer variants.
* Introduce `transformWith(Consumer<TransformerSpec>)` as a single point
of all possible transformer and its endpoint options
* Deprecate those `IntegrationFlowDefinition.transform()` variants
which are harder to configure as several lambda arguments

This change will make Kotlin & Groovy DSL more readable and straightforward

* * Use new `transformWith()` in tests where a deprecated API still used
* Add JavaDocs to `TransformerSpec`
* Fix generic types for `BaseIntegrationFlowDefinition.transformWith()` -
they make sense exactly on the `TransformerSpec.transformer()` only
* Apply `transformWith()` for Groovy DSL
* Introduce a new `ClassUtils.isLambda(Object candidate)`
and add a check for Groovy `Closure`
* Fix `GroovyIntegrationFlowDefinition.createConfigurerIfAny()` to propagate a `Consumer` argument
down to the `Closure`

* * Rename `TransformerSpec -> TransformerEndpointSpec` for better context
meaning of the class
* Introduce `KotlinTransformerEndpointSpec` as an extension of the `TransformerEndpointSpec`
to have an `inline fun <reified P> transformer(crossinline function: (P) -> Any)`
for Kotlin style
* Add `KotlinIntegrationFlowDefinition.transformWith(KotlinTransformerEndpointSpec)`
* Deprecate Kotlin methods which are covered by the mentioned `transformWith()`
* Fix tests to use new API
* Mentioned the change in the doc

Author: artembilan

spring-integration-core/src/main/java/org/springframework/integration/dsl/BaseIntegrationFlowDefinition.java

@@ -538,12 +538,18 @@ public B controlBus(@Nullable Consumer<GenericEndpointSpec<ServiceActivatingHand
 	/**
 	 * Populate the {@code Transformer} EI Pattern specific {@link MessageHandler} implementation
 	 * for the SpEL {@link Expression}.
+	 * Shortcut for:
+	 * <pre class="code">
+	 * {@code
+	 *  .transformWith((transformerSpec) -> transformerSpec.expression(expression))
+	 * }
+	 * </pre>
 	 * @param expression the {@code Transformer} {@link Expression}.
 	 * @return the current {@link BaseIntegrationFlowDefinition}.
 	 * @see ExpressionEvaluatingTransformer
 	 */
 	public B transform(String expression) {
-		return transform(expression, (Consumer<GenericEndpointSpec<MessageTransformingHandler>>) null);
+		return transformWith((transformerSpec) -> transformerSpec.expression(expression));
 	}
 
 	/**
@@ -552,8 +558,10 @@ public B transform(String expression) {
 	 * @param expression the {@code Transformer} {@link Expression}.
 	 * @param endpointConfigurer the {@link Consumer} to provide integration endpoint options.
 	 * @return the current {@link BaseIntegrationFlowDefinition}.
+	 * @deprecated since 6.2 in favor of {@link #transformWith(Consumer)}.
 	 * @see ExpressionEvaluatingTransformer
 	 */
+	@Deprecated(since = "6.2", forRemoval = true)
 	public B transform(String expression,
 			@Nullable Consumer<GenericEndpointSpec<MessageTransformingHandler>> endpointConfigurer) {
 
@@ -566,9 +574,15 @@ public B transform(String expression,
 	/**
 	 * Populate the {@code MessageTransformingHandler} for the {@link MethodInvokingTransformer}
 	 * to invoke the discovered service method at runtime.
+	 * Shortcut for:
+	 * <pre class="code">
+	 * {@code
+	 *  .transformWith((transformerSpec) -> transformerSpec.ref(service))
+	 * }
+	 * </pre>
 	 * @param service the service to use.
 	 * @return the current {@link BaseIntegrationFlowDefinition}.
-	 * @see ExpressionEvaluatingTransformer
+	 * @see MethodInvokingTransformer
 	 */
 	public B transform(Object service) {
 		return transform(service, null);
@@ -577,13 +591,36 @@ public B transform(Object service) {
 	/**
 	 * Populate the {@code MessageTransformingHandler} for the {@link MethodInvokingTransformer}
 	 * to invoke the service method at runtime.
+	 * <pre class="code">
+	 * {@code
+	 *  .transformWith((transformerSpec) -> transformerSpec.ref(service).method(methodName))
+	 * }
+	 * </pre>
 	 * @param service the service to use.
 	 * @param methodName the method to invoke.
 	 * @return the current {@link BaseIntegrationFlowDefinition}.
 	 * @see MethodInvokingTransformer
 	 */
 	public B transform(Object service, @Nullable String methodName) {
-		return transform(service, methodName, null);
+		return transformWith((transformerSpec) -> transformerSpec.ref(service).method(methodName));
+	}
+
+	/**
+	 * Populate the {@code MessageTransformingHandler} for the {@link MethodInvokingTransformer}
+	 * to invoke the bean method at runtime.
+	 * <pre class="code">
+	 * {@code
+	 *  .transformWith((transformerSpec) -> transformerSpec.refName(beanName).method(methodName))
+	 * }
+	 * </pre>
+	 * @param beanName the name for bean to resolve lazily.
+	 * @param methodName the method to invoke.
+	 * @return the current {@link BaseIntegrationFlowDefinition}.
+	 * @since 6.2
+	 * @see MethodInvokingTransformer
+	 */
+	public B transform(String beanName, @Nullable String methodName) {
+		return transformWith((transformerSpec) -> transformerSpec.refName(beanName).method(methodName));
 	}
 
 	/**
@@ -593,8 +630,10 @@ public B transform(Object service, @Nullable String methodName) {
 	 * @param methodName the method to invoke.
 	 * @param endpointConfigurer the {@link Consumer} to provide integration endpoint options.
 	 * @return the current {@link BaseIntegrationFlowDefinition}.
-	 * @see ExpressionEvaluatingTransformer
+	 * @deprecated since 6.2 in favor of {@link #transformWith(Consumer)}.
+	 * @see MethodInvokingTransformer
 	 */
+	@Deprecated(since = "6.2", forRemoval = true)
 	public B transform(Object service, @Nullable String methodName,
 			@Nullable Consumer<GenericEndpointSpec<MessageTransformingHandler>> endpointConfigurer) {
 
@@ -617,12 +656,18 @@ public B transform(Object service, @Nullable String methodName,
 	 *  .transform(Scripts.script("classpath:myScript.py").variable("foo", bar()))
 	 * }
 	 * </pre>
+	 * Shortcut for:
+	 * <pre class="code">
+	 * {@code
+	 *  .transformWith((transformerSpec) -> transformerSpec.processor(messageProcessorSpec))
+	 * }
+	 * </pre>
 	 * @param messageProcessorSpec the {@link MessageProcessorSpec} to use.
 	 * @return the current {@link BaseIntegrationFlowDefinition}.
 	 * @see MethodInvokingTransformer
 	 */
 	public B transform(MessageProcessorSpec<?> messageProcessorSpec) {
-		return transform(messageProcessorSpec, (Consumer<GenericEndpointSpec<MessageTransformingHandler>>) null);
+		return transformWith((transformerSpec) -> transformerSpec.processor(messageProcessorSpec));
 	}
 
 	/**
@@ -638,8 +683,10 @@ public B transform(MessageProcessorSpec<?> messageProcessorSpec) {
 	 * @param messageProcessorSpec the {@link MessageProcessorSpec} to use.
 	 * @param endpointConfigurer the {@link Consumer} to provide integration endpoint options.
 	 * @return the current {@link BaseIntegrationFlowDefinition}.
+	 * @deprecated since 6.2 in favor of {@link #transformWith(Consumer)}.
 	 * @see MethodInvokingTransformer
 	 */
+	@Deprecated(since = "6.2", forRemoval = true)
 	public B transform(MessageProcessorSpec<?> messageProcessorSpec,
 			@Nullable Consumer<GenericEndpointSpec<MessageTransformingHandler>> endpointConfigurer) {
 
@@ -679,7 +726,8 @@ public <P> B convert(Class<P> payloadType) {
 	 * @see LambdaMessageProcessor
 	 */
 	public <P, T> B transform(@Nullable Class<P> expectedType, GenericTransformer<P, T> genericTransformer) {
-		return transform(expectedType, genericTransformer, null);
+		return transformWith((transformerSpec) ->
+				transformerSpec.transformer(genericTransformer).expectedType(expectedType));
 	}
 
 	/**
@@ -714,10 +762,12 @@ public <P> B convert(Class<P> payloadType,
 	 * @param <P> the payload type - 'transform from', or {@code Message.class}.
 	 * @param <T> the target type - 'transform to'.
 	 * @return the current {@link BaseIntegrationFlowDefinition}.
+	 * @deprecated since 6.2 in favor of {@link #transformWith(Consumer)}
 	 * @see MethodInvokingTransformer
 	 * @see LambdaMessageProcessor
 	 * @see GenericEndpointSpec
 	 */
+	@Deprecated(since = "6.2", forRemoval = true)
 	public <P, T> B transform(@Nullable Class<P> expectedType, GenericTransformer<P, T> genericTransformer,
 			@Nullable Consumer<GenericEndpointSpec<MessageTransformingHandler>> endpointConfigurer) {
 
@@ -730,6 +780,16 @@ public <P, T> B transform(@Nullable Class<P> expectedType, GenericTransformer<P,
 				.handle(new MessageTransformingHandler(transformer), endpointConfigurer);
 	}
 
+	/**
+	 * Populate a {@link MessageTransformingHandler} into the endpoint with provided {@link TransformerEndpointSpec} options.
+	 * One of the 'expression', 'ref', 'refName', 'processor' or 'function' must be provided.
+	 * @return the current {@link BaseIntegrationFlowDefinition}.
+	 * @since 6.2
+	 */
+	public B transformWith(Consumer<TransformerEndpointSpec> transformerConfigurer) {
+		return register(new TransformerEndpointSpec(), transformerConfigurer);
+	}
+
 	/**
 	 * Populate a {@link MessageFilter} with {@link MessageSelector} for the provided SpEL expression.
 	 * @param expression the SpEL expression.
@@ -2787,7 +2847,7 @@ protected <T> Publisher<Message<T>> toReactivePublisher(boolean autoStartOnSubsc
 	}
 
 	protected <S extends ConsumerEndpointSpec<? super S, ? extends MessageHandler>> B register(S endpointSpec,
-			@Nullable Consumer<S> endpointConfigurer) {
+			@Nullable Consumer<? super S> endpointConfigurer) {
 
 		if (endpointConfigurer != null) {
 			endpointConfigurer.accept(endpointSpec);

spring-integration-core/src/main/java/org/springframework/integration/dsl/IntegrationFlowDefinition.java

@@ -50,6 +50,12 @@ public abstract class IntegrationFlowDefinition<B extends IntegrationFlowDefinit
 	 * Populate the {@link MessageTransformingHandler} instance for the provided
 	 * {@link GenericTransformer}. Use {@link #transform(Class, GenericTransformer)} if
 	 * you need to access the entire message.
+	 * Shortcut for:
+	 * <pre class="code">
+	 * {@code
+	 *  .transformWith((transformerSpec) -> transformerSpec.function(genericTransformer))
+	 * }
+	 * </pre>
 	 * @param genericTransformer the {@link GenericTransformer} to populate.
 	 * @param <S> the source type - 'transform from'.
 	 * @param <T> the target type - 'transform to'.
@@ -58,26 +64,29 @@ public abstract class IntegrationFlowDefinition<B extends IntegrationFlowDefinit
 	 * @see org.springframework.integration.handler.LambdaMessageProcessor
 	 */
 	public <S, T> B transform(GenericTransformer<S, T> genericTransformer) {
-		return transform(null, genericTransformer);
+		return transformWith((transformerSpec) -> transformerSpec.transformer(genericTransformer));
 	}
 
 
 	/**
 	 * Populate the {@link MessageTransformingHandler} instance for the provided
 	 * {@link GenericTransformer}. In addition, accept options for the integration endpoint
 	 * using {@link GenericEndpointSpec}. Use
-	 * {@link #transform(Class, GenericTransformer, Consumer)} if you need to access the
-	 * entire message.
+	 * {@code .transform((transformerSpec) -> transformerSpec.function(genericTransformer).expectedType(Message.class))}
+	 * if you need to access the entire message.
 	 * @param genericTransformer the {@link GenericTransformer} to populate.
 	 * @param endpointConfigurer the {@link Consumer} to provide integration endpoint
 	 * options.
 	 * @param <S> the source type - 'transform from'.
 	 * @param <T> the target type - 'transform to'.
 	 * @return the current {@link IntegrationFlowDefinition}.
+	 * @deprecated since 6.2 in favor of {@link #transformWith(Consumer)}
 	 * @see org.springframework.integration.transformer.MethodInvokingTransformer
 	 * @see org.springframework.integration.handler.LambdaMessageProcessor
 	 * @see GenericEndpointSpec
 	 */
+	@Deprecated(since = "6.2", forRemoval = true)
+	@SuppressWarnings("removal")
 	public <S, T> B transform(GenericTransformer<S, T> genericTransformer,
 			Consumer<GenericEndpointSpec<MessageTransformingHandler>> endpointConfigurer) {
 
@@ -108,7 +117,7 @@ public <P> B filter(GenericSelector<P> genericSelector) {
 	 * Populate a {@link org.springframework.integration.filter.MessageFilter}
 	 * with {@link org.springframework.integration.filter.MethodInvokingSelector}
 	 * for the provided {@link GenericSelector}.
-	 * In addition accept options for the integration endpoint using {@link FilterEndpointSpec}.
+	 * In addition, accept options for the integration endpoint using {@link FilterEndpointSpec}.
 	 * Typically used with a Java 8 Lambda expression:
 	 * <pre class="code">
 	 * {@code
@@ -152,7 +161,7 @@ public <P> B handle(GenericHandler<P> handler) {
 	 * Populate a {@link ServiceActivatingHandler} for the
 	 * {@link org.springframework.integration.handler.MethodInvokingMessageProcessor}
 	 * to invoke the provided {@link GenericHandler} at runtime.
-	 * In addition accept options for the integration endpoint using {@link GenericEndpointSpec}.
+	 * In addition, accept options for the integration endpoint using {@link GenericEndpointSpec}.
 	 * Typically used with a Java 8 Lambda expression:
 	 * <pre class="code">
 	 * {@code
@@ -177,7 +186,7 @@ public <P> B handle(GenericHandler<P> handler,
 	/**
 	 * Populate the {@link MethodInvokingSplitter} to evaluate the provided
 	 * {@link Function} at runtime.
-	 * In addition accept options for the integration endpoint using {@link GenericEndpointSpec}.
+	 * In addition, accept options for the integration endpoint using {@link GenericEndpointSpec}.
 	 * Typically used with a Java 8 Lambda expression:
 	 * <pre class="code">
 	 * {@code