INT-4284: INFO about overriding readOnly headers

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

Add `INFO` into the `MessageBuilder#copyHeadersIfAbsent()` when end-user
tries to populate headers which are `readOnly`

We can't throw exception on the matter since can modify `readOnlyHeaders`
and that would force end-user to add `header-filter` logic to the application.

* Document `readOnly` headers in the `message.adoc`

**Cherry-pick 4.3.x**

spring-integration-core/src/test/java/org/springframework/integration/gateway/GatewayInterfaceTests.java

@@ -39,6 +39,7 @@ import java.lang.reflect.Method;
 import java.util.Collection;
 import java.util.Collections;
 import java.util.Map;
+import java.util.Properties;
 import java.util.concurrent.CountDownLatch;
 import java.util.concurrent.Future;
 import java.util.concurrent.TimeUnit;
@@ -48,6 +49,7 @@ import java.util.concurrent.atomic.AtomicReference;
 import org.hamcrest.Matchers;
 import org.junit.Test;
 import org.junit.runner.RunWith;
+import org.mockito.ArgumentCaptor;
 import org.mockito.Mockito;
 
 import org.springframework.beans.factory.annotation.Autowired;
@@ -71,6 +73,8 @@ import org.springframework.integration.annotation.MessagingGateway;
 import org.springframework.integration.annotation.ServiceActivator;
 import org.springframework.integration.channel.DirectChannel;
 import org.springframework.integration.config.EnableIntegration;
+import org.springframework.integration.context.IntegrationContextUtils;
+import org.springframework.integration.context.IntegrationProperties;
 import org.springframework.integration.handler.BridgeHandler;
 import org.springframework.integration.support.MessageBuilder;
 import org.springframework.integration.test.util.TestUtils;
@@ -79,6 +83,7 @@ import org.springframework.messaging.MessageChannel;
 import org.springframework.messaging.MessageHandler;
 import org.springframework.messaging.MessagingException;
 import org.springframework.messaging.PollableChannel;
+import org.springframework.messaging.SubscribableChannel;
 import org.springframework.messaging.handler.annotation.Header;
 import org.springframework.messaging.handler.annotation.Payload;
 import org.springframework.messaging.support.ChannelInterceptorAdapter;
@@ -102,6 +107,8 @@ import org.springframework.util.concurrent.ListenableFutureCallback;
 @DirtiesContext
 public class GatewayInterfaceTests {
 
+	private static final String IGNORE_HEADER = "ignoreHeader";
+
 	@Autowired
 	private Int2634Gateway int2634Gateway;
 
@@ -141,6 +148,9 @@ public class GatewayInterfaceTests {
 	@Autowired
 	private MessageChannel errorChannel;
 
+	@Autowired
+	private IgnoredHeaderGateway ignoredHeaderGateway;
+
 	@Test
 	public void testWithServiceSuperclassAnnotatedMethod() throws Exception {
 		ConfigurableApplicationContext ac = new ClassPathXmlApplicationContext("GatewayInterfaceTests-context.xml", this.getClass());
@@ -453,6 +463,25 @@ public class GatewayInterfaceTests {
 		assertEquals("baz", ((LiteralExpression) barHeaderExpression).getValue());
 	}
 
+	@Test
+	@SuppressWarnings("unchecked")
+	public void testIgnoredHeader() {
+		MessageHandler messageHandler = mock(MessageHandler.class);
+
+		((SubscribableChannel) this.errorChannel).subscribe(messageHandler);
+		this.ignoredHeaderGateway.service("foo", "theHeaderValue");
+
+		ArgumentCaptor<Message<?>> messageArgumentCaptor = ArgumentCaptor.forClass(Message.class);
+
+		verify(messageHandler).handleMessage(messageArgumentCaptor.capture());
+
+		Message<?> message = messageArgumentCaptor.getValue();
+
+		assertFalse(message.getHeaders().containsKey(IGNORE_HEADER));
+
+		((SubscribableChannel) this.errorChannel).unsubscribe(messageHandler);
+	}
+
 
 	public interface Foo {
 
@@ -513,6 +542,13 @@ public class GatewayInterfaceTests {
 	@EnableIntegration
 	public static class TestConfig {
 
+		@Bean(name = IntegrationContextUtils.INTEGRATION_GLOBAL_PROPERTIES_BEAN_NAME)
+		public Properties integrationProperties() {
+			Properties properties = new Properties();
+			properties.setProperty(IntegrationProperties.READ_ONLY_HEADERS, IGNORE_HEADER);
+			return properties;
+		}
+
 		@Bean
 		@BridgeTo
 		public MessageChannel gatewayChannel() {
@@ -616,6 +652,14 @@ public class GatewayInterfaceTests {
 
 	}
 
+	@MessagingGateway(defaultRequestChannel = "errorChannel")
+	@TestMessagingGateway
+	public interface IgnoredHeaderGateway {
+
+		void service(String payload, @Header(IGNORE_HEADER) String myHeader);
+
+	}
+
 	@MessagingGateway(
 			defaultRequestChannel = "${gateway.channel:gatewayChannel}",
 			defaultReplyChannel = "${gateway.channel:gatewayChannel}",