From 1a9f4bc9476b2fbf8a84bf2f382ba018ae1d0623 Mon Sep 17 00:00:00 2001
From: Artem Bilan <abilan@gopivotal.com>
Date: Mon, 9 Dec 2013 13:53:56 +0200
Subject: [PATCH] INT-3219: Document Retry Exception Classification

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

* Upgrade to Spring Retry 1.0.3
* Add a section to Reference Manual about Retry Exception Classification
---
 build.gradle                             |  2 +-
 src/reference/docbook/handler-advice.xml | 28 +++++++++++++++++++++++-
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/build.gradle b/build.gradle
index a2c9119800..6f9f62d2f4 100644
--- a/build.gradle
+++ b/build.gradle
@@ -70,7 +70,7 @@ subprojects { subproject ->
 		springSecurityVersion = '3.1.3.RELEASE'
 		springSocialTwitterVersion = '1.0.5.RELEASE'
 		springWsVersion = '2.1.1.RELEASE'
-		springRetryVersion = '1.0.2.RELEASE'
+		springRetryVersion = '1.0.3.RELEASE'
 	}
 
 	eclipse {
diff --git a/src/reference/docbook/handler-advice.xml b/src/reference/docbook/handler-advice.xml
index 91fb6b1175..8a7a25e383 100644
--- a/src/reference/docbook/handler-advice.xml
+++ b/src/reference/docbook/handler-advice.xml
@@ -78,7 +78,7 @@
 			<para>
 				The retry advice (<classname>o.s.i.handler.advice.RequestHandlerRetryAdvice</classname>)
 				leverages the rich retry mechanisms provided by the
-				<ulink url="https://github.com/SpringSource/spring-retry">spring-retry</ulink> project. The core component
+				<ulink url="https://github.com/SpringSource/spring-retry">Spring Retry</ulink> project. The core component
 				of <emphasis>spring-retry</emphasis> is the <classname>RetryTemplate</classname>, which allows configuration
 				of sophisticated retry scenarios, including <classname>RetryPolicy</classname> and <classname>BackoffPolicy</classname>
 				strategies, with a number of implementations,
@@ -288,6 +288,32 @@ Caused by: java.lang.RuntimeException: foo
 					exception is thrown to the caller on each failure.
 				</para>
 			</section>
+			<para>
+				<emphasis>Exception Classification for Retry</emphasis>
+
+			</para>
+			<para>
+				Spring Retry has a great deal of flexibility for determining which
+				exceptions can invoke retry. The default configuration will retry
+				for all exceptions. Given that, user exceptions may be wrapped in
+				a <classname>MessagingException</classname> in the underlying handler,
+				we need to ensure that the classification examines the exception causes.
+				The default classifier just looks at the top level exception.
+			</para>
+			<para>
+				Since <emphasis>Spring Retry 1.0.3</emphasis>, the
+				<classname>BinaryExceptionClassifier</classname> has a property
+				<code>traverseCauses</code> (default <code>false</code>). When
+				<code>true</code> it will traverse exception causes until it
+				finds a match or there is no cause.
+			</para>
+			<para>
+				To use this classifier for retry, use a <classname>SimpleRetryPolicy</classname>
+				created with the constructor that takes the max attempts, the
+				<interfacename>Map</interfacename> of <classname>Exception</classname>s
+				and the boolean (traverseCauses), and inject this policy into the
+				<classname>RetryTemplate</classname>.
+			</para>
 		</section>
 		<section id="circuit-breaker-advice">
 			<title>Circuit Breaker Advice</title>