Clarify the use of sessionTransacted

This commit clarifies the role of the external transactionManager for
a DMLC and the relationship with the sessionTransacted flag

Issue: SPR-9200

Author: snicoll

spring-jms/src/main/java/org/springframework/jms/listener/AbstractMessageListenerContainer.java

@@ -104,15 +104,13 @@
  * runtime processing overhead.
  * </ul>
  *
- * <p>Note that it is also possible to specify a
- * {@link org.springframework.jms.connection.JmsTransactionManager} as external
- * "transactionManager", providing fully synchronized Spring transactions based
- * on local JMS transactions. The effect is similar to "sessionTransacted" set
- * to "true", the difference being that this external transaction management
- * will also affect independent JMS access code within the service layer
- * (e.g. based on {@link org.springframework.jms.core.JmsTemplate} or
- * {@link org.springframework.jms.connection.TransactionAwareConnectionFactoryProxy}),
- * not just direct JMS Session usage in a {@link SessionAwareMessageListener}.
+ * <p>Note that even if
+ * {@link org.springframework.jms.connection.JmsTransactionManager} used to
+ * only provide fully synchronized Spring transactions based
+ * on local JMS transactions, "sessionTransacted" offers now the same feature and
+ * is the recommended option when transactions are not managed externally. In
+ * other words, set the transaction manager only if you are using JTA , or
+ * synchronizing transactions.
  *
  * @author Juergen Hoeller
  * @author Stephane Nicoll

spring-jms/src/main/java/org/springframework/jms/listener/AbstractPollingMessageListenerContainer.java

@@ -132,11 +132,13 @@ protected boolean isPubSubNoLocal() {
 	 * Simply switch the {@link #setSessionTransacted "sessionTransacted"} flag
 	 * to "true" in order to use a locally transacted JMS Session for the entire
 	 * receive processing, including any Session operations performed by a
-	 * {@link SessionAwareMessageListener} (e.g. sending a response message).
-	 * Alternatively, a {@link org.springframework.jms.connection.JmsTransactionManager}
-	 * may be used for fully synchronized Spring transactions based on local JMS
-	 * transactions. Check {@link AbstractMessageListenerContainer}'s javadoc for
+	 * {@link SessionAwareMessageListener} (e.g. sending a response message). This
+	 * allows for fully synchronized Spring transactions based on local JMS
+	 * transactions, similar to what
+	 * {@link org.springframework.jms.connection.JmsTransactionManager} provides. Check
+	 * {@link AbstractMessageListenerContainer}'s javadoc for
 	 * a discussion of transaction choices and message redelivery scenarios.
+	 * @see #setSessionTransacted(boolean)
 	 * @see org.springframework.transaction.jta.JtaTransactionManager
 	 * @see org.springframework.jms.connection.JmsTransactionManager
 	 */

spring-jms/src/main/java/org/springframework/jms/listener/DefaultMessageListenerContainer.java

@@ -262,12 +262,13 @@ public void setCacheLevelName(String constantName) throws IllegalArgumentExcepti
 	 * <p>Default is {@link #CACHE_NONE} if an external transaction manager has been specified
 	 * (to reobtain all resources freshly within the scope of the external transaction),
 	 * and {@link #CACHE_CONSUMER} otherwise (operating with local JMS resources).
-	 * <p>Some J2EE servers only register their JMS resources with an ongoing XA
+	 * <p>Some JavaEE servers only register their JMS resources with an ongoing XA
 	 * transaction in case of a freshly obtained JMS {@code Connection} and {@code Session},
 	 * which is why this listener container by default does not cache any of those.
-	 * However, if you want to optimize for a specific server, consider switching
-	 * this setting to at least {@link #CACHE_CONNECTION} or {@link #CACHE_SESSION}
-	 * even in conjunction with an external transaction manager.
+	 * However, depending on how smart your JavaEE server is with respect to the caching
+	 * of transactional resource, consider switching this setting to at least
+	 * {@link #CACHE_CONNECTION} or {@link #CACHE_SESSION} even in conjunction with an
+	 * external transaction manager.
 	 * @see #CACHE_NONE
 	 * @see #CACHE_CONNECTION
 	 * @see #CACHE_SESSION

spring-jms/src/main/java/org/springframework/jms/support/JmsAccessor.java

@@ -86,7 +86,7 @@ public ConnectionFactory getConnectionFactory() {
 	 * <p>Setting this flag to "true" will use a short local JMS transaction
 	 * when running outside of a managed transaction, and a synchronized local
 	 * JMS transaction in case of a managed transaction (other than an XA
-	 * transaction) being present. The latter has the effect of a local JMS
+	 * transaction) being present. This has the effect of a local JMS
 	 * transaction being managed alongside the main transaction (which might
 	 * be a native JDBC transaction), with the JMS transaction committing
 	 * right after the main transaction.