Revised documentation on AUTO_ACKNOWLEDGE behavior

Issue: SPR-12705

Author: jhoeller

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -60,8 +60,13 @@
  * <p>The listener container offers the following message acknowledgment options:
  * <ul>
  * <li>"sessionAcknowledgeMode" set to "AUTO_ACKNOWLEDGE" (default):
- * Automatic message acknowledgment <i>before</i> listener execution;
- * no redelivery in case of exception thrown.
+ * This mode is container-dependent: For {@link DefaultMessageListenerContainer},
+ * it means automatic message acknowledgment <i>before</i> listener execution, with
+ * no redelivery in case of an exception. For {@link SimpleMessageListenerContainer},
+ * it means automatic message acknowledgment <i>after</i> listener execution, with
+ * redelivery in case of an exception thrown, as defined by the JMS specification.
+ * In order to consistently achieve the latter behavior with any container variant,
+ * consider setting "sessionTransacted" to "true" instead.
  * <li>"sessionAcknowledgeMode" set to "CLIENT_ACKNOWLEDGE":
  * Automatic message acknowledgment <i>after</i> successful listener execution;
  * no redelivery in case of exception thrown.

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -107,9 +107,11 @@
  * <p><b>It is strongly recommended to either set {@link #setSessionTransacted
  * "sessionTransacted"} to "true" or specify an external {@link #setTransactionManager
  * "transactionManager"}.</b> See the {@link AbstractMessageListenerContainer}
- * javadoc for details on acknowledge modes and native transaction options,
- * as well as the {@link AbstractPollingMessageListenerContainer} javadoc
- * for details on configuring an external transaction manager.
+ * javadoc for details on acknowledge modes and native transaction options, as
+ * well as the {@link AbstractPollingMessageListenerContainer} javadoc for details
+ * on configuring an external transaction manager. Note that for the default
+ * "AUTO_ACKNOWLEDGE" mode, this container applies automatic message acknowledgment
+ * before listener execution, with no redelivery in case of an exception.
  *
  * @author Juergen Hoeller
  * @since 2.0

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -44,7 +44,10 @@
  * on the JMS provider: Not even the ServerSessionPool facility is required.
  *
  * <p>See the {@link AbstractMessageListenerContainer} javadoc for details
- * on acknowledge modes and transaction options.
+ * on acknowledge modes and transaction options. Note that this container
+ * exposes standard JMS behavior for the default "AUTO_ACKNOWLEDGE" mode:
+ * that is, automatic message acknowledgment after listener execution,
+ * with redelivery in case of an exception thrown.
  *
  * <p>For a different style of MessageListener handling, through looped
  * {@code MessageConsumer.receive()} calls that also allow for