From 56de7149c304fa051c8fc421bd5fdc0a7f7f1ee0 Mon Sep 17 00:00:00 2001
From: Gary Russell <grussell@pivotal.io>
Date: Mon, 30 Oct 2017 14:29:30 -0400
Subject: [PATCH] INT-4314: MutableMessageBuilder Javadocs

JIRA: https://jira.spring.io/browse/INT-4314
---
 .../integration/support/MutableMessage.java     | 17 ++++++++++++-----
 .../support/MutableMessageBuilder.java          | 10 ++++++++++
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/spring-integration-core/src/main/java/org/springframework/integration/support/MutableMessage.java b/spring-integration-core/src/main/java/org/springframework/integration/support/MutableMessage.java
index f86b7ee545..b5de8ba803 100644
--- a/spring-integration-core/src/main/java/org/springframework/integration/support/MutableMessage.java
+++ b/spring-integration-core/src/main/java/org/springframework/integration/support/MutableMessage.java
@@ -27,11 +27,18 @@ import org.springframework.util.ObjectUtils;
 
 /**
  * An implementation of {@link Message} with a generic payload. Unlike
- * {@link GenericMessage}, this message (or its headers) can be modified
- * after creation. Great care must be taken, when mutating messages, that
- * some other element/thread is not concurrently using the message. Also note
- * that any in-memory stores (such as {@link SimpleMessageStore}) may have
- * a reference to the message and changes will be reflected there too.
+ * {@link GenericMessage}, this message (or its headers) can be modified after creation.
+ * Great care must be taken, when mutating messages, that some other element/thread is not
+ * concurrently using the message. Also note that any in-memory stores (such as
+ * {@link SimpleMessageStore}) may have a reference to the message and changes will be
+ * reflected there too.
+ *
+ * <p>
+ * <b>IMPORTANT: Mutable messages may share state (such as message headers); such messages
+ * should never be exposed to other components or undesirable side-effects may result.</b>
+ * <p>
+ * <b>It is generally recommended that messages transferred between components should
+ * always be immutable unless great care is taken with their use.</b>
  *
  * @author Gary Russell
  * @author Artem Bilan
diff --git a/spring-integration-core/src/main/java/org/springframework/integration/support/MutableMessageBuilder.java b/spring-integration-core/src/main/java/org/springframework/integration/support/MutableMessageBuilder.java
index e8197b5fce..ed4ad51349 100644
--- a/spring-integration-core/src/main/java/org/springframework/integration/support/MutableMessageBuilder.java
+++ b/spring-integration-core/src/main/java/org/springframework/integration/support/MutableMessageBuilder.java
@@ -30,6 +30,16 @@ import org.springframework.util.StringUtils;
 
 
 /**
+ * Specialized message builder that can be used within a component to avoid the overhead
+ * of having to build multiple messages for mutations within that component.
+ *
+ * <p>
+ * <b>IMPORTANT: Mutable messages may share state (such as message headers); such messages
+ * should never be exposed to other components or undesirable side-effects may result.</b>
+ * <p>
+ * <b>It is generally recommended that messages transferred between components should
+ * always be immutable unless great care is taken with their use.</b>
+ *
  * @author Gary Russell
  * @author Artem Bilan
  * @since 4.0