From 1c10861a92d7118d3879bb314d9349a25e8c5d0f Mon Sep 17 00:00:00 2001
From: Juergen Hoeller <jhoeller@pivotal.io>
Date: Fri, 27 Feb 2015 22:28:18 +0100
Subject: [PATCH] Revised documentation on AUTO_ACKNOWLEDGE behavior

Issue: SPR-12705
(cherry picked from commit 91c47a9)
---
 .../listener/AbstractMessageListenerContainer.java    | 11 ++++++++---
 .../jms/listener/DefaultMessageListenerContainer.java | 10 ++++++----
 .../jms/listener/SimpleMessageListenerContainer.java  |  7 +++++--
 3 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/spring-jms/src/main/java/org/springframework/jms/listener/AbstractMessageListenerContainer.java b/spring-jms/src/main/java/org/springframework/jms/listener/AbstractMessageListenerContainer.java
index e19285dc90..bf1feab5dd 100644
--- a/spring-jms/src/main/java/org/springframework/jms/listener/AbstractMessageListenerContainer.java
+++ b/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.
@@ -54,8 +54,13 @@ import org.springframework.util.ErrorHandler;
  * <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.
diff --git a/spring-jms/src/main/java/org/springframework/jms/listener/DefaultMessageListenerContainer.java b/spring-jms/src/main/java/org/springframework/jms/listener/DefaultMessageListenerContainer.java
index d33f1fef29..103555490d 100644
--- a/spring-jms/src/main/java/org/springframework/jms/listener/DefaultMessageListenerContainer.java
+++ b/spring-jms/src/main/java/org/springframework/jms/listener/DefaultMessageListenerContainer.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 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.
@@ -104,9 +104,11 @@ import org.springframework.util.ClassUtils;
  * <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
diff --git a/spring-jms/src/main/java/org/springframework/jms/listener/SimpleMessageListenerContainer.java b/spring-jms/src/main/java/org/springframework/jms/listener/SimpleMessageListenerContainer.java
index c3f0f22e59..7743208745 100644
--- a/spring-jms/src/main/java/org/springframework/jms/listener/SimpleMessageListenerContainer.java
+++ b/spring-jms/src/main/java/org/springframework/jms/listener/SimpleMessageListenerContainer.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 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.
@@ -45,7 +45,10 @@ import org.springframework.util.Assert;
  * 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