Add Java DSL for Camel module and docs (#3937)

* Add Java DSL for Camel module and docs

* Introduce a `LambdaRouteBuilder` option into the `CamelMessageHandler`
to easily provide the Camel route just in-place

* * Fix language in docs

Co-authored-by: Gary Russell <grussell@vmware.com>

Co-authored-by: Gary Russell <grussell@vmware.com>

spring-integration-camel/src/main/java/org/springframework/integration/camel/dsl/Camel.java

@@ -0,0 +1,93 @@
+/*
+ * Copyright 2022 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.camel.dsl;
+
+import org.apache.camel.ExchangePattern;
+import org.apache.camel.ProducerTemplate;
+import org.apache.camel.builder.LambdaRouteBuilder;
+
+import org.springframework.lang.Nullable;
+
+/**
+ * Factory class for Apache Camel components DSL.
+ *
+ * @author Artem Bilan
+ *
+ * @since 6.0
+ */
+public final class Camel {
+
+	/**
+	 * Create an instance of {@link CamelMessageHandlerSpec} in a {@link ExchangePattern#InOnly} mode.
+	 * @return the spec.
+	 */
+	public static CamelMessageHandlerSpec handler() {
+		return camelHandler(null, ExchangePattern.InOnly);
+	}
+
+	/**
+	 * Create an instance of {@link CamelMessageHandlerSpec} for the provided {@link ProducerTemplate}
+	 * in a {@link ExchangePattern#InOnly} mode.
+	 * @param producerTemplate the {@link ProducerTemplate} to use.
+	 * @return the spec.
+	 */
+	public static CamelMessageHandlerSpec handler(ProducerTemplate producerTemplate) {
+		return camelHandler(producerTemplate, ExchangePattern.InOnly);
+	}
+
+	/**
+	 * Create an instance of {@link CamelMessageHandlerSpec} in a {@link ExchangePattern#InOut} mode.
+	 * @return the spec.
+	 */
+	public static CamelMessageHandlerSpec gateway() {
+		return camelHandler(null, ExchangePattern.InOut);
+	}
+
+	/**
+	 * Create an instance of {@link CamelMessageHandlerSpec} for the provided {@link ProducerTemplate}
+	 * in a {@link ExchangePattern#InOut} mode.
+	 * @param producerTemplate the {@link ProducerTemplate} to use.
+	 * @return the spec.
+	 */
+	public static CamelMessageHandlerSpec gateway(ProducerTemplate producerTemplate) {
+		return camelHandler(producerTemplate, ExchangePattern.InOut);
+	}
+
+	/**
+	 * Create an instance of {@link CamelMessageHandlerSpec} for the provided {@link LambdaRouteBuilder}
+	 * in a {@link ExchangePattern#InOut} mode.
+	 * The {@code CamelContext} is fetched as a bean from the application context.
+	 * @param route the {@link LambdaRouteBuilder} to use.
+	 * @return the spec.
+	 */
+	public static CamelMessageHandlerSpec route(LambdaRouteBuilder route) {
+		return camelHandler(null, ExchangePattern.InOut)
+				.route(route);
+	}
+
+	private static CamelMessageHandlerSpec camelHandler(@Nullable ProducerTemplate producerTemplate,
+			ExchangePattern exchangePattern) {
+
+		return new CamelMessageHandlerSpec(producerTemplate)
+				.exchangePattern(exchangePattern);
+	}
+
+
+	private Camel() {
+	}
+
+}

spring-integration-camel/src/main/java/org/springframework/integration/camel/dsl/CamelMessageHandlerSpec.java

@@ -0,0 +1,134 @@
+/*
+ * Copyright 2022 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.camel.dsl;
+
+import java.util.Arrays;
+import java.util.Map;
+import java.util.function.Function;
+
+import org.apache.camel.ExchangePattern;
+import org.apache.camel.ProducerTemplate;
+import org.apache.camel.builder.LambdaRouteBuilder;
+
+import org.springframework.expression.Expression;
+import org.springframework.integration.camel.outbound.CamelMessageHandler;
+import org.springframework.integration.camel.support.CamelHeaderMapper;
+import org.springframework.integration.dsl.MessageHandlerSpec;
+import org.springframework.integration.expression.FunctionExpression;
+import org.springframework.integration.mapping.HeaderMapper;
+import org.springframework.lang.Nullable;
+import org.springframework.messaging.Message;
+import org.springframework.util.Assert;
+
+/**
+ * The {@link MessageHandlerSpec} for {@link CamelMessageHandler}.
+ *
+ * @author Artem Bilan
+ *
+ * @since 6.0
+ */
+public class CamelMessageHandlerSpec extends
+		MessageHandlerSpec<CamelMessageHandlerSpec, CamelMessageHandler> {
+
+	private String[] inboundHeaderNames = { "*" };
+
+	private String[] outboundHeaderNames = { "*" };
+
+	protected CamelMessageHandlerSpec(@Nullable ProducerTemplate producerTemplate) {
+		this.target = producerTemplate == null ? new CamelMessageHandler() : new CamelMessageHandler(producerTemplate);
+	}
+
+	public CamelMessageHandlerSpec endpointUri(String endpointUri) {
+		this.target.setEndpointUri(endpointUri);
+		return this;
+	}
+
+	public CamelMessageHandlerSpec endpointUri(Function<Message<?>, String> endpointUriFunction) {
+		return endpointUriExpression(new FunctionExpression<>(endpointUriFunction));
+	}
+
+	public CamelMessageHandlerSpec endpointUriExpression(String endpointUriExpression) {
+		return endpointUriExpression(PARSER.parseExpression(endpointUriExpression));
+	}
+
+	public CamelMessageHandlerSpec endpointUriExpression(Expression endpointUriExpression) {
+		this.target.setEndpointUriExpression(endpointUriExpression);
+		return this;
+	}
+
+	protected CamelMessageHandlerSpec route(LambdaRouteBuilder route) {
+		this.target.setRoute(route);
+		return this;
+	}
+
+	public CamelMessageHandlerSpec exchangePattern(ExchangePattern exchangePattern) {
+		this.target.setExchangePattern(exchangePattern);
+		return this;
+	}
+
+	public CamelMessageHandlerSpec exchangePattern(Function<Message<?>, ExchangePattern> exchangePatternFunction) {
+		return exchangePatternExpression(new FunctionExpression<>(exchangePatternFunction));
+	}
+
+	public CamelMessageHandlerSpec exchangePatternExpression(String exchangePatternExpression) {
+		return exchangePatternExpression(PARSER.parseExpression(exchangePatternExpression));
+	}
+
+	public CamelMessageHandlerSpec exchangePatternExpression(Expression exchangePatternExpression) {
+		this.target.setExchangePatternExpression(exchangePatternExpression);
+		return this;
+	}
+
+	public CamelMessageHandlerSpec inboundHeaderNames(String... inboundHeaderNames) {
+		Assert.notEmpty(inboundHeaderNames, "'inboundHeaderNames' must not be empty");
+		this.inboundHeaderNames = Arrays.copyOf(inboundHeaderNames, inboundHeaderNames.length);
+		return addCamelHeaderMapper();
+	}
+
+	public CamelMessageHandlerSpec outboundHeaderNames(String... outboundHeaderNames) {
+		Assert.notEmpty(outboundHeaderNames, "'outboundHeaderNames' must not be empty");
+		this.outboundHeaderNames = Arrays.copyOf(outboundHeaderNames, outboundHeaderNames.length);
+		return addCamelHeaderMapper();
+	}
+
+	private CamelMessageHandlerSpec addCamelHeaderMapper() {
+		CamelHeaderMapper headerMapper = new CamelHeaderMapper();
+		headerMapper.setInboundHeaderNames(this.inboundHeaderNames);
+		headerMapper.setOutboundHeaderNames(this.outboundHeaderNames);
+		return headerMapper(headerMapper);
+	}
+
+	public CamelMessageHandlerSpec headerMapper(HeaderMapper<org.apache.camel.Message> headerMapper) {
+		this.target.setHeaderMapper(headerMapper);
+		return this;
+	}
+
+	public CamelMessageHandlerSpec exchangeProperties(Map<String, Object> exchangeProperties) {
+		this.target.setExchangeProperties(exchangeProperties);
+		return this;
+	}
+
+	public CamelMessageHandlerSpec exchangePropertiesExpression(String exchangePropertiesExpression) {
+		return exchangePropertiesExpression(PARSER.parseExpression(exchangePropertiesExpression));
+	}
+
+	public CamelMessageHandlerSpec exchangePropertiesExpression(Expression exchangePropertiesExpression) {
+		this.target.setExchangePropertiesExpression(exchangePropertiesExpression);
+		return this;
+	}
+
+}

spring-integration-camel/src/main/java/org/springframework/integration/camel/dsl/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Provides supporting classes for JavaDSL with Apache Camel components.
+ */
+
+@org.springframework.lang.NonNullApi
+@org.springframework.lang.NonNullFields
+package org.springframework.integration.camel.dsl;

spring-integration-camel/src/main/java/org/springframework/integration/camel/outbound/CamelMessageHandler.java

@@ -19,12 +19,18 @@ package org.springframework.integration.camel.outbound;
 import java.util.Map;
 import java.util.concurrent.CompletableFuture;
 
+import org.apache.camel.CamelContext;
 import org.apache.camel.CamelExecutionException;
 import org.apache.camel.Endpoint;
 import org.apache.camel.Exchange;
 import org.apache.camel.ExchangePattern;
 import org.apache.camel.ProducerTemplate;
+import org.apache.camel.builder.LambdaRouteBuilder;
+import org.apache.camel.builder.RouteBuilder;
+import org.apache.camel.model.RouteDefinition;
 
+import org.springframework.beans.factory.BeanFactory;
+import org.springframework.beans.factory.BeanInitializationException;
 import org.springframework.expression.Expression;
 import org.springframework.expression.common.LiteralExpression;
 import org.springframework.expression.spel.support.StandardEvaluationContext;
@@ -62,13 +68,16 @@ import org.springframework.util.StringUtils;
  */
 public class CamelMessageHandler extends AbstractReplyProducingMessageHandler {
 
-	private final ProducerTemplate producerTemplate;
+	private ProducerTemplate producerTemplate;
 
 	private Expression exchangePatternExpression = new ValueExpression<>(ExchangePattern.InOnly);
 
 	@Nullable
 	private Expression endpointUriExpression;
 
+	@Nullable
+	private LambdaRouteBuilder route;
+
 	private HeaderMapper<org.apache.camel.Message> headerMapper = new CamelHeaderMapper();
 
 	@Nullable
@@ -76,21 +85,47 @@ public class CamelMessageHandler extends AbstractReplyProducingMessageHandler {
 
 	private StandardEvaluationContext evaluationContext;
 
+	public CamelMessageHandler() {
+	}
+
 	public CamelMessageHandler(ProducerTemplate producerTemplate) {
 		Assert.notNull(producerTemplate, "'producerTemplate' must not be null");
 		this.producerTemplate = producerTemplate;
 	}
 
+	/**
+	 * Set Camel route endpoint uri to send a message.
+	 * Mutually exclusive with {@link #setEndpointUriExpression(Expression)} and {@link #setRoute(LambdaRouteBuilder)}.
+	 * @param endpointUri the Camel route endpoint to send a message.
+	 */
 	public void setEndpointUri(String endpointUri) {
 		Assert.hasText(endpointUri, "'endpointUri' must not be empty");
 		setEndpointUriExpression(new LiteralExpression(endpointUri));
 	}
 
+	/**
+	 * Set Camel route endpoint uri to send a message.
+	 * Mutually exclusive with {@link #setEndpointUri(String)} and {@link #setRoute(LambdaRouteBuilder)}.
+	 * @param endpointUriExpression the SpEL expression to determine a Camel route endpoint to send a message.
+	 */
 	public void setEndpointUriExpression(Expression endpointUriExpression) {
 		Assert.notNull(endpointUriExpression, "'endpointUriExpression' must not be null");
 		this.endpointUriExpression = endpointUriExpression;
 	}
 
+	/**
+	 * Set a {@link LambdaRouteBuilder} to add an inline Camel route definition.
+	 * Can be used as a lambda {@code rb -> rb.from("direct:inbound").bean(MyBean.class)}
+	 * or reference to external instance.
+	 * Mutually exclusive with {@link #setEndpointUri(String)} and {@link #setEndpointUriExpression(Expression)}.
+	 * The endpoint to send a message is extracted from the target {@link RouteBuilder}.
+	 * @param route the {@link LambdaRouteBuilder} to use.
+	 */
+	public void setRoute(LambdaRouteBuilder route) {
+		Assert.notNull(route, "'route' must not be null");
+		this.route = route;
+	}
+
 	public void setExchangePattern(ExchangePattern exchangePattern) {
 		Assert.notNull(exchangePattern, "'exchangePattern' must not be null");
 		setExchangePatternExpression(new ValueExpression<>(exchangePattern));
@@ -126,7 +161,38 @@ public class CamelMessageHandler extends AbstractReplyProducingMessageHandler {
 
 	@Override
 	protected final void doInit() {
-		this.evaluationContext = ExpressionUtils.createStandardEvaluationContext(getBeanFactory());
+		Assert.state(this.endpointUriExpression == null || this.route == null,
+				"The 'endpointUri' option is mutually exclusive with 'route'");
+
+		BeanFactory beanFactory = getBeanFactory();
+		if (this.producerTemplate == null) {
+			this.producerTemplate = beanFactory.getBean(CamelContext.class).createProducerTemplate();
+		}
+
+		if (this.route != null) {
+			CamelContext camelContext = this.producerTemplate.getCamelContext();
+			RouteBuilder routeBuilder =
+					new RouteBuilder(camelContext) {
+
+						@Override
+						public void configure() throws Exception {
+							CamelMessageHandler.this.route.accept(this);
+						}
+
+					};
+
+			try {
+				camelContext.addRoutes(routeBuilder);
+			}
+			catch (Exception ex) {
+				throw new BeanInitializationException("Cannot load Camel route", ex);
+			}
+
+			RouteDefinition routeDefinition = routeBuilder.getRouteCollection().getRoutes().get(0);
+			this.endpointUriExpression = new LiteralExpression(routeDefinition.getInput().getEndpointUri());
+		}
+
+		this.evaluationContext = ExpressionUtils.createStandardEvaluationContext(beanFactory);
 	}
 
 	@Override

spring-integration-camel/src/test/java/org/springframework/integration/camel/dsl/CamelDslTests.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2022 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.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.integration.camel.dsl;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.apache.camel.CamelContext;
+import org.apache.camel.builder.RouteBuilder;
+import org.apache.camel.spring.SpringCamelContext;
+import org.junit.jupiter.api.Test;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.event.ContextRefreshedEvent;
+import org.springframework.context.event.EventListener;
+import org.springframework.integration.config.EnableIntegration;
+import org.springframework.integration.core.MessagingTemplate;
+import org.springframework.integration.dsl.IntegrationFlow;
+import org.springframework.messaging.MessageChannel;
+import org.springframework.test.annotation.DirtiesContext;
+import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+
+/**
+ * @author Artem Bilan
+ *
+ * @since 6.0
+ */
+@SpringJUnitConfig
+@DirtiesContext
+public class CamelDslTests {
+
+	@Autowired
+	@Qualifier("camelFlow.input")
+	MessageChannel input;
+
+	@Test
+	void sendAndReceiveCamelRoute() {
+		String result = new MessagingTemplate().convertSendAndReceive(this.input, "apache camel", String.class);
+		assertThat(result).isEqualTo("___APACHE CAMEL___");
+	}
+
+	@Configuration
+	@EnableIntegration
+	public static class Config {
+
+		@Bean
+		CamelContext springCamelContext() {
+			return new SpringCamelContext();
+		}
+
+		@EventListener(ContextRefreshedEvent.class)
+		public void simpleRoute() throws Exception {
+			RouteBuilder.addRoutes(springCamelContext(),
+					rb -> rb.from("direct:simple").bean("camelDslTests.Config", "transformPayload"));
+		}
+
+		@Bean
+		IntegrationFlow camelFlow() {
+			return f -> f
+					.handle(Camel.gateway().endpointUri("direct:simple"))
+					.handle(Camel.route(this::camelRoute));
+		}
+
+		private void camelRoute(RouteBuilder routeBuilder) {
+			routeBuilder.from("direct:inbound").transform(routeBuilder.simple("${body.toUpperCase()}"));
+		}
+
+		public String transformPayload(String payload) {
+			return "___" + payload + "___";
+		}
+
+	}
+
+}

spring-integration-camel/src/test/java/org/springframework/integration/camel/outbound/CamelMessageHandlerTests.java

@@ -183,6 +183,7 @@ public class CamelMessageHandlerTests extends CamelTestSupport {
 			public void configure() {
 				from("direct:simple").to("mock:result");
 			}
+
 		};
 	}