From f002ebd9762669a269ccad52c685d47a1c4827db Mon Sep 17 00:00:00 2001
From: Juergen Hoeller <jhoeller@pivotal.io>
Date: Mon, 5 Nov 2018 19:32:34 +0100
Subject: [PATCH] Explicit notes on class/method-level semantics in class
 hierarchies

Issue: SPR-17445

(cherry picked from commit ea3250c8d618bf638b69f1917b2cbacfe26b9225)
---
 .../transaction/annotation/Transactional.java              | 7 ++++++-
 src/asciidoc/data-access.adoc                              | 7 +++++++
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/spring-tx/src/main/java/org/springframework/transaction/annotation/Transactional.java b/spring-tx/src/main/java/org/springframework/transaction/annotation/Transactional.java
index eeccff5c53e9..68f7df3f2030 100644
--- a/spring-tx/src/main/java/org/springframework/transaction/annotation/Transactional.java
+++ b/spring-tx/src/main/java/org/springframework/transaction/annotation/Transactional.java
@@ -27,7 +27,12 @@
 import org.springframework.transaction.TransactionDefinition;
 
 /**
- * Describes transaction attributes on a method or class.
+ * Describes a transaction attribute on an individual method or on a class.
+ *
+ * <p>At the class level, this annotation applies as a default to all methods of
+ * the declaring class and its subclasses. Note that it does not apply to ancestor
+ * classes up the class hierarchy; methods need to be locally redeclared in order
+ * to participate in a subclass-level annotation.
  *
  * <p>This annotation type is generally directly comparable to Spring's
  * {@link org.springframework.transaction.interceptor.RuleBasedTransactionAttribute}
diff --git a/src/asciidoc/data-access.adoc b/src/asciidoc/data-access.adoc
index df35df15e3ca..95d30375c6ac 100644
--- a/src/asciidoc/data-access.adoc
+++ b/src/asciidoc/data-access.adoc
@@ -1090,6 +1090,12 @@ following class definition:
 	}
 ----
 
+Used at the class level as above, the annotation indicates a default for all methods
+of the declaring class (as well as its subclasses). Alternatively, each method can
+get annotated individually. Note that a class-level annotation does not apply to
+ancestor classes up the class hierarchy; in such a scenario, methods need to be
+locally redeclared in order to participate in a subclass-level annotation.
+
 When the above POJO is defined as a bean in a Spring IoC container, the bean instance
 can be made transactional by adding merely __one__ line of XML configuration:
 
@@ -1115,6 +1121,7 @@ can be made transactional by adding merely __one__ line of XML configuration:
 
 		<!-- enable the configuration of transactional behavior based on annotations -->
 		__<tx:annotation-driven transaction-manager="txManager"/>__<!-- a PlatformTransactionManager is still required -->
+
 		<bean id="txManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
 			<!-- (this dependency is defined somewhere else) -->
 			<property name="dataSource" ref="dataSource"/>