INT-2853 ObjectToStringTransformer Improvements

* Convert byte[] and char[] to String rather than simply using toString().
* Allow the charset to be configured for byte[] payloads.
* Add tests.
* Add reference documentation updates.

src/reference/docbook/transformer.xml

@@ -113,6 +113,22 @@
       When debugging, this transformer is not typically necessary since the 'logging-channel-adapter' is capable
       of logging the Message payload. Refer to <xref linkend="channel-wiretap"/> for more detail.
     </tip>
+    <note>
+      <para>
+        The <emphasis>object-to-string-transformer</emphasis> is very simple; it invokes <code>toString()</code>
+        on the inbound payload. There are two exceptions to this (since 3.0): if the payload is a <code>char[]</code>,
+        it invokes <code>new String(payload)</code>; if the payload is a <code>byte[]</code>, it invokes
+        <code>new String(payload, charset)</code>, where <code>charset</code> is "UTF-8" by default. The
+        <code>charset</code> can be modified by supplying the <emphasis>charset</emphasis> attribute on
+        the transformer.
+      </para>
+      <para>
+        For more sophistication (such as selection of the charset dynamically, at runtime), you can use
+        a SpEL expression-based transformer instead; for example:
+      </para>
+      <programlisting language="xml"><![CDATA[<int:transformer input-channel="in" output-channel="out"
+		 expression="new java.lang.String(payload, headers['myCharset']" />]]></programlisting>
+    </note>
   </para>
   <para>
     If you need to serialize an Object to a byte array or deserialize a byte array back into an Object,

src/reference/docbook/whats-new.xml

@@ -26,6 +26,13 @@
 					for at least this number of milliseconds. For more information see <xref linkend="aggregator-config"/>.
 				</para>
 		</section>
+		<section id="3.0-o-t-s-t">
+			<title>ObjectToStringTransformer Improvements</title>
+			<para>
+				This transformer now correctly transforms <code>byte[]</code> and <code>char[]</code>
+				payloads to <classname>String</classname>. For more information see <xref linkend="transformer"/>.
+			</para>
+		</section>
 
 	</section>