INT-4298: Add Interface HeaderPropagationAware

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

Used to indicate components that can propagate headers; allows suppression.

Move Interface to AbstractMessageProducingHandler

Add Docs

* Fix typo in doc

spring-integration-core/src/main/java/org/springframework/integration/handler/AbstractMessageProducingHandler.java

@@ -62,7 +62,7 @@ import reactor.core.publisher.Mono;
  * since 4.1
  */
 public abstract class AbstractMessageProducingHandler extends AbstractMessageHandler
-		implements MessageProducer {
+		implements MessageProducer, HeaderPropagationAware {
 
 	private final Set<String> notPropagatedHeaders = new HashSet<String>();
 
@@ -120,6 +120,7 @@ public abstract class AbstractMessageProducingHandler extends AbstractMessageHan
 	 * @param headers the headers to not propagate from the inbound message.
 	 * @since 4.3.10
 	 */
+	@Override
 	public void setNotPropagatedHeaders(String... headers) {
 		updateNotPropagatedHeaders(headers, false);
 	}
@@ -137,24 +138,25 @@ public abstract class AbstractMessageProducingHandler extends AbstractMessageHan
 
 	/**
 	 * Get the header names this handler doesn't propagate.
-	 * @return an immutable {@link java.util.Collection} of headers that will
+	 * @return an immutable {@link java.util.Collection} of headers that will not be
-	 *         not be copied from the inbound message if
+	 * copied from the inbound message if {@link #shouldCopyRequestHeaders()} is true.
-	 *         {@link #shouldCopyRequestHeaders()} is true.
 	 * @since 4.3.10
 	 * @see #setNotPropagatedHeaders(String...)
 	 */
+	@Override
 	public Collection<String> getNotPropagatedHeaders() {
 		return Collections.unmodifiableSet(this.notPropagatedHeaders);
 	}
 
 	/**
 	 * Add headers that will NOT be copied from the inbound message if
-	 * {@link #shouldCopyRequestHeaders()} is true, instead of overwriting
+	 * {@link #shouldCopyRequestHeaders()} is true, instead of overwriting the existing
-	 * the existing set.
+	 * set.
 	 * @param headers the headers to not propagate from the inbound message.
 	 * @since 4.3.10
 	 * @see #setNotPropagatedHeaders(String...)
 	 */
+	@Override
 	public void addNotPropagatedHeaders(String... headers) {
 		updateNotPropagatedHeaders(headers, true);
 	}

spring-integration-core/src/main/java/org/springframework/integration/handler/HeaderPropagationAware.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2017 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.handler;
+
+import java.util.Collection;
+
+/**
+ * MessageHandlers implementing this interface can propagate headers from
+ * an input message to an output message.
+ *
+ * @author Gary Russell
+ * @since 4.3.11
+ *
+ */
+public interface HeaderPropagationAware {
+
+	/**
+	 * Set headers that will NOT be copied from the inbound message if
+	 * the handler is configured to copy headers.
+	 * @param headers the headers to not propagate from the inbound message.
+	 */
+	void setNotPropagatedHeaders(String... headers);
+
+	/**
+	 * Get the header names this handler doesn't propagate.
+	 * @return an immutable {@link java.util.Collection} of headers that will not be
+	 * copied from the inbound message if the handler is configured to copy headers.
+	 * @see #setNotPropagatedHeaders(String...)
+	 */
+	Collection<String> getNotPropagatedHeaders();
+
+	/**
+	 * Add headers that will NOT be copied from the inbound message if
+	 * the handler is configured to copy headers, instead of overwriting
+	 * the existing set.
+	 * @param headers the headers to not propagate from the inbound message.
+	 * @see #setNotPropagatedHeaders(String...)
+	 */
+	void addNotPropagatedHeaders(String... headers);
+
+}

src/reference/asciidoc/message.adoc

@@ -384,6 +384,21 @@ When you try to build a new message using `MessageBuilder`, this kind of headers
 
 Starting with _version 5.0_, <<gateway,Messaging Gateway>>, <<header-enricher,Header Enricher>>, <<payload-enricher,Content Enricher>> and <<header-filter, Header Filter>> don't allow to configure `MessageHeaders.ID` and `MessageHeaders.TIMESTAMP` header names when `DefaultMessageBuilderFactory` is used and they throw `BeanInitializationException`.
 
+[[header-propagation]]
+===== Header Propagation
+
+When messages are processed (and modified) by message-producing endpoints (such as a <<service-activator, service activator>>), in general, inbound headers are propagated to the outbound message.
+One exception to this is a <<transformer, transformer>>, when a complete message is returned to the framework; in that case, the user code is responsible for the entire outbound message.
+When a transformer just returns the payload; the inbound headers **are** propagated.
+Also, a header is only propagated if it does not already exist in the outbound message, allowing user code to change header values as needed.
+
+Starting with _version 4.3.10_, you can configure message handlers (that modify messages and produce output) to suppress the propagation of specific headers.
+Call the `setNotPropagatedHeaders()` or `addNotPropagatedHeaders()` methods on the `MessageProducingMessageHandler` abstract class, to configure the header(s) you don't want to be copied.
+You can also globally suppress propagation of specific message headers by setting the `readOnlyHeaders` property in `META-INF/spring.integration.properties` to a comma-delimited list of headers.
+
+IMPORTANT: Header propagation suppression does not apply to those endpoints that don't modify the message, e.g. <<bridge, bridges>> and <<router, routers>>
+
+
 [[message-implementations]]
 ==== Message Implementations