INT-3288 JMS 'session-transacted' Attribute

JIRA: https://jira.springsource.org/browse/INT-3288

Previously, if you wanted to have a JMS outbound-channel-adapter
participate in an upstream JMS transaction (or use transactions
at all), you had to inject a `JmsTemplate` with `sessionTransacted`
set to `true`.

The `session-transacted` attribute has been added to the adapter,
allowing transactions to be used with the default `JmsTemplate`,
avoiding the need to inject a separate template.

Also, the inbound (polled) channel adapter incorrectly allowed
the `acknowledge` attribute to be set to `transacted` which is invalid and,
again, you had to inject an appropriately configured JmsTemplate
for transactions.

The inbound-channel-adapter now supports `session-transacted` as
well, and `acknowledge` can no longer be set to `transacted`.

There are no changes to the `message-driven-channel-adapter`, you
enable transactions with it by setting `acknowledge="transacted"`
as before.

INT-3288 Doc Polishing; Integration Tests

src/reference/docbook/jms.xml

@@ -75,6 +75,28 @@
     <int:poller fixed-rate="30000"/>
 </int-jms:inbound-channel-adapter>]]></programlisting>
     </para>
+	<section id="jms-ib-transactions">
+		<title>Transactions</title>
+		<para>
+			Starting with <emphasis>version 4.0</emphasis>, the inbound channel adapter supports the
+			<code>session-transacted</code> attribute. In earlier versions, you had to inject a
+			<classname>JmsTemplate</classname> with <code>sessionTransacted</code> set to <code>true</code>.
+			(The adapter did allow the <code>acknowledge</code> attribute to be set to
+			<code>transacted</code> but this was incorrect and did not work).
+		</para>
+		<para>
+			Note, however, that setting <code>session-transacted</code> to <code>true</code> has
+			little value because the transaction is committed immediately after the <code>receive()</code>
+			and before the message is sent to the <code>channel</code>,
+		</para>
+		<para>
+			If you want the entire flow to be transactional (for example if there is a downstream
+			outbound channel adapter), you must use a <code>transactional</code> poller, with a
+			<classname>JmsTransactionManager</classname>. Or, consider using a
+			<code>jms-message-driven-channel-adapter</code> with <code>acknowledge</code>
+			set to <code>transacted</code>.
+		</para>
+	</section>
   </section>
 
   <section id="jms-message-driven-channel-adapter">
@@ -151,6 +173,18 @@
         those cases, it's the JMS properties mapping <emphasis>to</emphasis> Spring Integration MessageHeaders).
       </note>
     </para>
+    <section id="jms-ob-transactions">
+		<title>Transactions</title>
+		<para>
+			Starting with <emphasis>version 4.0</emphasis>, the outbound channel adapter supports the
+		<code>session-transacted</code> attribute. In earlier versions, you had to inject a
+		<classname>JmsTemplate</classname> with <code>sessionTransacted</code> set to <code>true</code>.
+			The attribute now sets the property on the built-in default <classname>JmsTemplate</classname>.
+			If a transaction exists (perhaps from an upstream <code>message-driven-channel-adapter</code>)
+			the send will be performed within the same transaction. Otherwise a new transaction will
+			be started.
+		</para>
+	</section>
   </section>
 
   <section id="jms-inbound-gateway">

src/reference/docbook/whats-new.xml

@@ -107,6 +107,24 @@
 				considered for outbound messages. For more information see <xref linkend="jms-header-mapping"/>.
 			</para>
 		</section>
+		<section id="4.0-jms-ob">
+			<title>JMS Outbound Channel Adapter</title>
+			<para>
+				The JMS outbound channel adapter now supports the <code>session-transacted</code> attribute
+				(default false). Previously, you had to inject a customized <classname>JmsTemplate</classname>
+				to use transactions. See <xref linkend="jms-outbound-channel-adapter"/>.
+			</para>
+		</section>
+		<section id="4.0-jms-ib">
+			<title>JMS Inbound Channel Adapter</title>
+			<para>
+				The JMS inbound channel adapter now supports the <code>session-transacted</code> attribute
+				(default false). Previously, you had to inject a customized <classname>JmsTemplate</classname>
+				to use transactions (the adapter allowed 'transacted' in the acknowledgeMode which was
+				incorrect, and didn't work; this value is no longer allowed). See
+				<xref linkend="jms-inbound-channel-adapter"/>.
+			</para>
+		</section>
 		<section id="4.0-datatype-channel">
 			<title>Datatype Channels</title>
 			<para>