INT-3500: Consider to add "error-channel" to the <enricher>

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

* add 'error-channel' to the <enricher> component
* delegate errorChannel to the internal gateway in ContentEnricher
* added tests for xml based and java based enrichers with error channels

INT-3500: Consider to add "error-channel" to the <enricher>

* Fixed typos and comments
* Reworked xml integration test to use the outputChannel and increased timeout
* Added overview in whats-new doc

INT-3500: Consider to add "error-channel" to the <enricher>

* Ensure requestChannel is set if an errorChannel is set
* Increased timeout to fix unit test
* Added details to content-enricher ref doc

Polishing

Author: krisjacyna

spring-integration-core/src/main/java/org/springframework/integration/config/xml/EnricherParser.java

@@ -41,6 +41,7 @@
  * @author Mark Fisher
  * @author Artem Bilan
  * @author Liujiong
+ * @author Kris Jacyna
  * @since 2.1
  */
 public class EnricherParser extends AbstractConsumerEndpointParser {
@@ -51,6 +52,7 @@ protected BeanDefinitionBuilder parseHandler(Element element, ParserContext pars
 
 		IntegrationNamespaceUtils.setReferenceIfAttributeDefined(builder, element, "request-channel");
 		IntegrationNamespaceUtils.setReferenceIfAttributeDefined(builder, element, "reply-channel");
+		IntegrationNamespaceUtils.setReferenceIfAttributeDefined(builder, element, "error-channel");
 		IntegrationNamespaceUtils.setValueIfAttributeDefined(builder, element, "request-timeout");
 		IntegrationNamespaceUtils.setValueIfAttributeDefined(builder, element, "reply-timeout");
 		IntegrationNamespaceUtils.setValueIfAttributeDefined(builder, element, "requires-reply");
@@ -69,19 +71,21 @@ protected BeanDefinitionBuilder parseHandler(Element element, ParserContext pars
 				boolean hasAttributeExpression = StringUtils.hasText(expression);
 				boolean hasAttributeNullResultExpression = StringUtils.hasText(nullResultExpression);
 
-				if (hasAttributeValue && hasAttributeExpression){
+				if (hasAttributeValue && hasAttributeExpression) {
 					parserContext.getReaderContext().error("Only one of 'value' or 'expression' is allowed", element);
 				}
 
-				if (!hasAttributeValue && !hasAttributeExpression && !hasAttributeNullResultExpression){
-					parserContext.getReaderContext().error("One of 'value' or 'expression' or 'null-result-expression' is required", element);
+				if (!hasAttributeValue && !hasAttributeExpression && !hasAttributeNullResultExpression) {
+					parserContext.getReaderContext()
+							.error("One of 'value' or 'expression' or 'null-result-expression' is required", element);
 				}
 
 				BeanDefinition expressionDef = null;
 				BeanDefinition nullResultExpressionExpressionDef;
 
 				if (hasAttributeValue) {
-					BeanDefinitionBuilder expressionBuilder = BeanDefinitionBuilder.genericBeanDefinition(ValueExpression.class);
+					BeanDefinitionBuilder expressionBuilder =
+							BeanDefinitionBuilder.genericBeanDefinition(ValueExpression.class);
 					if (StringUtils.hasText(type)) {
 						expressionBuilder.addConstructorArgValue(new TypedStringValue(value, type));
 					}
@@ -93,19 +97,20 @@ protected BeanDefinitionBuilder parseHandler(Element element, ParserContext pars
 				else if (hasAttributeExpression) {
 					if (StringUtils.hasText(type)) {
 						parserContext.getReaderContext().error("The 'type' attribute for '<property>' of '<enricher>' " +
-										"is not allowed with an 'expression' attribute.", element);
+								"is not allowed with an 'expression' attribute.", element);
 					}
 					expressionDef = BeanDefinitionBuilder
 							.genericBeanDefinition(ExpressionFactoryBean.class)
 							.addConstructorArgValue(expression)
 							.getBeanDefinition();
 				}
-				if (expressionDef != null){
+				if (expressionDef != null) {
 					expressions.put(name, expressionDef);
 				}
 				if (hasAttributeNullResultExpression) {
-					nullResultExpressionExpressionDef = BeanDefinitionBuilder.genericBeanDefinition(ExpressionFactoryBean.class)
-							.addConstructorArgValue(nullResultExpression).getBeanDefinition();
+					nullResultExpressionExpressionDef =
+							BeanDefinitionBuilder.genericBeanDefinition(ExpressionFactoryBean.class)
+									.addConstructorArgValue(nullResultExpression).getBeanDefinition();
 					nullResultExpressions.put(name, nullResultExpressionExpressionDef);
 				}
 			}
@@ -129,21 +134,23 @@ else if (hasAttributeExpression) {
 				boolean hasAttributeValue = StringUtils.hasText(valueElementValue);
 				boolean hasAttributeExpression = StringUtils.hasText(expressionElementValue);
 				boolean hasAttributeNullResultExpression = StringUtils.hasText(nullResultHeaderExpression);
-				if (hasAttributeValue && hasAttributeExpression){
+				if (hasAttributeValue && hasAttributeExpression) {
 					parserContext.getReaderContext().error("Only one of '" + "value" + "' or '"
-								+ "expression" + "' is allowed", subElement);
+							+ "expression" + "' is allowed", subElement);
 				}
 
-				if (!hasAttributeValue && !hasAttributeExpression && !hasAttributeNullResultExpression){
-					parserContext.getReaderContext().error("One of 'value' or 'expression' or 'null-result-expression' is required", subElement);
+				if (!hasAttributeValue && !hasAttributeExpression && !hasAttributeNullResultExpression) {
+					parserContext.getReaderContext()
+							.error("One of 'value' or 'expression' or 'null-result-expression' is required", subElement);
 				}
 				BeanDefinition expressionDef = null;
 				if (hasAttributeValue) {
 					expressionDef = new RootBeanDefinition(LiteralExpression.class);
 					expressionDef.getConstructorArgumentValues().addGenericArgumentValue(valueElementValue);
 				}
 				else if (hasAttributeExpression) {
-					expressionDef = IntegrationNamespaceUtils.createExpressionDefIfAttributeDefined("expression", subElement);
+					expressionDef =
+							IntegrationNamespaceUtils.createExpressionDefIfAttributeDefined("expression", subElement);
 				}
 
 				if (StringUtils.hasText(subElement.getAttribute("expression"))
@@ -167,7 +174,8 @@ else if (hasAttributeExpression) {
 							.genericBeanDefinition(ExpressionEvaluatingHeaderValueMessageProcessor.class)
 							.addConstructorArgValue(nullResultExpressionDefinition)
 							.addConstructorArgValue(subElement.getAttribute("type"));
-					IntegrationNamespaceUtils.setValueIfAttributeDefined(nullResultValueProcessorBuilder, subElement, "overwrite");
+					IntegrationNamespaceUtils.setValueIfAttributeDefined(nullResultValueProcessorBuilder, subElement,
+							"overwrite");
 					nullResultHeaderExpressions.put(name, nullResultValueProcessorBuilder.getBeanDefinition());
 				}
 			}
@@ -184,8 +192,9 @@ else if (hasAttributeExpression) {
 		String requestPayloadExpression = element.getAttribute("request-payload-expression");
 
 		if (StringUtils.hasText(requestPayloadExpression)) {
-			BeanDefinitionBuilder expressionBuilder = BeanDefinitionBuilder.genericBeanDefinition(ExpressionFactoryBean.class);
-			expressionBuilder.addConstructorArgValue(requestPayloadExpression);
+			BeanDefinitionBuilder expressionBuilder =
+					BeanDefinitionBuilder.genericBeanDefinition(ExpressionFactoryBean.class)
+							.addConstructorArgValue(requestPayloadExpression);
 			builder.addPropertyValue("requestPayloadExpression", expressionBuilder.getBeanDefinition());
 		}
 

spring-integration-core/src/main/java/org/springframework/integration/transformer/ContentEnricher.java

@@ -49,6 +49,7 @@
  * @author Gary Russell
  * @author Artem Bilan
  * @author Liujiong
+ * @author Kris Jacyna
  * @since 2.1
  */
 public class ContentEnricher extends AbstractReplyProducingMessageHandler
@@ -82,6 +83,10 @@ public class ContentEnricher extends AbstractReplyProducingMessageHandler
 
 	private volatile String replyChannelName;
 
+	private volatile MessageChannel errorChannel;
+
+	private volatile String errorChannelName;
+
 	private volatile Gateway gateway = null;
 
 	private volatile Long requestTimeout;
@@ -167,6 +172,22 @@ public void setReplyChannelName(String replyChannelName) {
 		this.replyChannelName = replyChannelName;
 	}
 
+	/**
+	 * Set the content enricher's error channel to allow the error handling flow to return
+	 * of an alternative object to use for enrichment if exceptions occur in the
+	 * downstream flow.
+	 * @param errorChannel The error channel.
+	 * @since 4.1
+	 */
+	public void setErrorChannel(MessageChannel errorChannel) {
+		this.errorChannel = errorChannel;
+	}
+
+	public void setErrorChannelName(String errorChannelName) {
+		Assert.hasText(errorChannelName, "'errorChannelName' must not be empty");
+		this.errorChannelName = errorChannelName;
+	}
+
 	/**
 	 * Set the timeout value for sending request messages. If not explicitly configured,
 	 * the default is one second.
@@ -246,10 +267,17 @@ protected void doInit() {
 		Assert.state(!(this.replyChannelName != null && this.replyChannel != null),
 				"'replyChannelName' and 'replyChannel' are mutually exclusive.");
 
+		Assert.state(!(this.errorChannelName != null && this.errorChannel != null),
+				"'errorChannelName' and 'errorChannel' are mutually exclusive.");
+
 		if (this.replyChannel != null || this.replyChannelName != null) {
 			Assert.state(this.requestChannel != null || this.requestChannelName != null,
 					"If the replyChannel is set, then the requestChannel must not be null");
 		}
+		if (this.errorChannel != null || this.errorChannelName != null) {
+			Assert.state(this.requestChannel != null || this.requestChannelName != null,
+					"If the errorChannel is set, then the requestChannel must not be null");
+		}
 		if (this.requestChannel != null || this.requestChannelName != null) {
 			this.gateway = new Gateway();
 			this.gateway.setRequestChannel(this.requestChannel);
@@ -269,6 +297,11 @@ protected void doInit() {
 				this.gateway.setReplyChannelName(this.replyChannelName);
 			}
 
+			this.gateway.setErrorChannel(errorChannel);
+			if (this.errorChannelName != null) {
+				this.gateway.setErrorChannelName(this.errorChannelName);
+			}
+
 			if (this.getBeanFactory() != null) {
 				this.gateway.setBeanFactory(this.getBeanFactory());
 			}

spring-integration-core/src/main/resources/org/springframework/integration/config/xml/spring-integration-4.1.xsd

@@ -1387,6 +1387,21 @@
 				</xsd:appinfo>
 			</xsd:annotation>
 		</xsd:attribute>
+		<xsd:attribute name="error-channel" type="xsd:string" use="optional">
+			<xsd:annotation>
+				<xsd:documentation>
+					Used when exceptions occur in a downstream flow and allows the error
+					handling flow to return an alternative object to use for enrichment.
+					If no "error-channel" reference is provided,
+					this enricher will propagate Exceptions to the caller.
+				</xsd:documentation>
+				<xsd:appinfo>
+					<tool:annotation kind="ref">
+						<tool:expected-type type="org.springframework.messaging.MessageChannel"/>
+					</tool:annotation>
+				</xsd:appinfo>
+			</xsd:annotation>
+		</xsd:attribute>
         <xsd:attribute name="request-timeout" type="xsd:string">
             <xsd:annotation>
                 <xsd:documentation><![CDATA[

spring-integration-core/src/test/java/org/springframework/integration/config/xml/EnricherParserTests5-context.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<beans:beans xmlns="http://www.springframework.org/schema/integration"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xmlns:beans="http://www.springframework.org/schema/beans"
+	xsi:schemaLocation="http://www.springframework.org/schema/beans
+			http://www.springframework.org/schema/beans/spring-beans.xsd
+			http://www.springframework.org/schema/integration
+			http://www.springframework.org/schema/integration/spring-integration.xsd">
+
+	<channel id="inputChannel"/>
+
+	<channel id="requestChannel"/>
+
+	<channel id="errChannel"/>
+
+	<channel id="outputChannel">
+		<queue />
+	</channel>
+
+	<enricher id="enricher" 
+			input-channel="inputChannel" request-channel="requestChannel" 
+			output-channel="outputChannel" error-channel="errChannel">
+		<property name="name" expression="'Mr. ' + payload.name"/>
+	</enricher>
+
+</beans:beans>

spring-integration-core/src/test/java/org/springframework/integration/config/xml/EnricherParserTests5.java

@@ -0,0 +1,97 @@
+/*
+ * Copyright 2014 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
+ *
+ *      http://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.config.xml;
+
+import static org.junit.Assert.assertEquals;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.ApplicationContext;
+import org.springframework.integration.channel.DirectChannel;
+import org.springframework.integration.handler.AbstractReplyProducingMessageHandler;
+import org.springframework.integration.support.MessageBuilder;
+import org.springframework.messaging.Message;
+import org.springframework.messaging.PollableChannel;
+import org.springframework.test.context.ContextConfiguration;
+import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
+
+/**
+ * Tests the error-channel in an enricher to produce
+ * a default object in case of downstream failure.
+ *
+ * @author Kris Jacyna
+ * @since 4.1
+ */
+@RunWith(SpringJUnit4ClassRunner.class)
+@ContextConfiguration
+public class EnricherParserTests5 {
+
+	@Autowired
+	private ApplicationContext context;
+
+
+	@Test
+	public void errorChannelTest() {
+
+		class ErrorThrower extends AbstractReplyProducingMessageHandler {
+			@Override
+			protected Object handleRequestMessage(Message<?> requestMessage) {
+				throw new RuntimeException();
+			}
+		}
+
+		class DefaultTargetProducer extends AbstractReplyProducingMessageHandler {
+			@Override
+			protected Object handleRequestMessage(Message<?> requestMessage) {
+				final Target defaultTarget = new Target();
+				defaultTarget.setName("Default");
+				return defaultTarget;
+			}
+		}
+
+		context.getBean("requestChannel", DirectChannel.class).subscribe(new ErrorThrower());
+		context.getBean("errChannel", DirectChannel.class).subscribe(new DefaultTargetProducer());
+
+		Target original = new Target();
+		original.setName("John");
+		Message<?> request = MessageBuilder.withPayload(original).build();
+
+		context.getBean("inputChannel", DirectChannel.class).send(request);
+
+		Message<?> reply = context.getBean("outputChannel", PollableChannel.class).receive(10000);
+		Target enriched = (Target) reply.getPayload();
+		assertEquals("Mr. Default", enriched.getName());
+	}
+
+
+	public static class Target {
+
+		private volatile String name;
+
+		public String getName() {
+			return name;
+		}
+
+		public void setName(String name) {
+			this.name = name;
+		}
+
+	}
+
+}