Explicit notes on advice mode proxy vs aspectj

Issue: SPR-16092

spring-context/src/main/java/org/springframework/cache/annotation/EnableCaching.java

 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -148,15 +148,19 @@ import org.springframework.core.Ordered;
  * can be useful if you do not need to customize everything. See {@link CachingConfigurer}
  * Javadoc for further details.
  *
- * <p>The {@link #mode()} attribute controls how advice is applied; if the mode is
- * {@link AdviceMode#PROXY} (the default), then the other attributes such as
- * {@link #proxyTargetClass()} control the behavior of the proxying.
+ * <p>The {@link #mode} attribute controls how advice is applied: If the mode is
+ * {@link AdviceMode#PROXY} (the default), then the other attributes control the behavior
+ * of the proxying. Please note that proxy mode allows for interception of calls through
+ * the proxy only; local calls within the same class cannot get intercepted that way.
  *
- * <p>If the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then the
- * {@link #proxyTargetClass()} attribute is obsolete. Note also that in this case the
- * {@code spring-aspects} module JAR must be present on the classpath.
+ * <p>Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then the
+ * value of the {@link #proxyTargetClass} attribute will be ignored. Note also that in
+ * this case the {@code spring-aspects} module JAR must be present on the classpath, with
+ * compile-time weaving or load-time weaving applying the aspect to the affected classes.
+ * There is no proxy involved in such a scenario; local calls will be intercepted as well.
  *
  * @author Chris Beams
+ * @author Juergen Hoeller
  * @since 3.1
  * @see CachingConfigurer
  * @see CachingConfigurationSelector
@@ -183,16 +187,21 @@ public @interface EnableCaching {
 	boolean proxyTargetClass() default false;
 
 	/**
-	 * Indicate how caching advice should be applied. The default is
-	 * {@link AdviceMode#PROXY}.
-	 * @see AdviceMode
+	 * Indicate how caching advice should be applied.
+	 * <p><b>The default is {@link AdviceMode#PROXY}.</b>
+	 * Please note that proxy mode allows for interception of calls through the proxy
+	 * only. Local calls within the same class cannot get intercepted that way;
+	 * a caching annotation on such a method within a local call will be ignored
+	 * since Spring's interceptor does not even kick in for such a runtime scenario.
+	 * For a more advanced mode of interception, consider switching this to
+	 * {@link AdviceMode#ASPECTJ}.
 	 */
 	AdviceMode mode() default AdviceMode.PROXY;
 
 	/**
 	 * Indicate the ordering of the execution of the caching advisor
 	 * when multiple advices are applied at a specific joinpoint.
-	 * The default is {@link Ordered#LOWEST_PRECEDENCE}.
+	 * <p>The default is {@link Ordered#LOWEST_PRECEDENCE}.
 	 */
 	int order() default Ordered.LOWEST_PRECEDENCE;
 

spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java

 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -58,14 +58,6 @@ import org.springframework.core.Ordered;
  *     }
  * }</pre>
  *
- * <p>The {@link #mode} attribute controls how advice is applied; if the mode is
- * {@link AdviceMode#PROXY} (the default), then the other attributes control the behavior
- * of the proxying.
- *
- * <p>Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then the
- * value of the {@link #proxyTargetClass} attribute will be ignored. Note also that in
- * this case the {@code spring-aspects} module JAR must be present on the classpath.
- *
  * <p>By default, Spring will be searching for an associated thread pool definition:
  * either a unique {@link org.springframework.core.task.TaskExecutor} bean in the context,
  * or an {@link java.util.concurrent.Executor} bean named "taskExecutor" otherwise. If
@@ -140,6 +132,17 @@ import org.springframework.core.Ordered;
  * demonstrates how the JavaConfig-based approach allows for maximum configurability
  * through direct access to actual componentry.
  *
+ * <p>The {@link #mode} attribute controls how advice is applied: If the mode is
+ * {@link AdviceMode#PROXY} (the default), then the other attributes control the behavior
+ * of the proxying. Please note that proxy mode allows for interception of calls through
+ * the proxy only; local calls within the same class cannot get intercepted that way.
+ *
+ * <p>Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then the
+ * value of the {@link #proxyTargetClass} attribute will be ignored. Note also that in
+ * this case the {@code spring-aspects} module JAR must be present on the classpath, with
+ * compile-time weaving or load-time weaving applying the aspect to the affected classes.
+ * There is no proxy involved in such a scenario; local calls will be intercepted as well.
+ *
  * @author Chris Beams
  * @author Juergen Hoeller
  * @author Stephane Nicoll
@@ -182,8 +185,13 @@ public @interface EnableAsync {
 
 	/**
 	 * Indicate how async advice should be applied.
-	 * <p>The default is {@link AdviceMode#PROXY}.
-	 * @see AdviceMode
+	 * <p><b>The default is {@link AdviceMode#PROXY}.</b>
+	 * Please note that proxy mode allows for interception of calls through the proxy
+	 * only. Local calls within the same class cannot get intercepted that way; an
+	 * {@link Async} annotation on such a method within a local call will be ignored
+	 * since Spring's interceptor does not even kick in for such a runtime scenario.
+	 * For a more advanced mode of interception, consider switching this to
+	 * {@link AdviceMode#ASPECTJ}.
 	 */
 	AdviceMode mode() default AdviceMode.PROXY;
 

spring-tx/src/main/java/org/springframework/transaction/annotation/EnableTransactionManagement.java

 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -131,15 +131,19 @@ import org.springframework.core.Ordered;
  * {@code @Transactional} methods. See {@link TransactionManagementConfigurer} Javadoc
  * for further details.
  *
- * <p>The {@link #mode()} attribute controls how advice is applied; if the mode is
+ * <p>The {@link #mode} attribute controls how advice is applied: If the mode is
  * {@link AdviceMode#PROXY} (the default), then the other attributes control the behavior
- * of the proxying.
+ * of the proxying. Please note that proxy mode allows for interception of calls through
+ * the proxy only; local calls within the same class cannot get intercepted that way.
  *
- * <p>If the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then the
- * {@link #proxyTargetClass()} attribute is obsolete. Note also that in this case the
- * {@code spring-aspects} module JAR must be present on the classpath.
+ * <p>Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then the
+ * value of the {@link #proxyTargetClass} attribute will be ignored. Note also that in
+ * this case the {@code spring-aspects} module JAR must be present on the classpath, with
+ * compile-time weaving or load-time weaving applying the aspect to the affected classes.
+ * There is no proxy involved in such a scenario; local calls will be intercepted as well.
  *
  * @author Chris Beams
+ * @author Juergen Hoeller
  * @since 3.1
  * @see TransactionManagementConfigurer
  * @see TransactionManagementConfigurationSelector
@@ -167,16 +171,21 @@ public @interface EnableTransactionManagement {
 	boolean proxyTargetClass() default false;
 
 	/**
-	 * Indicate how transactional advice should be applied. The default is
-	 * {@link AdviceMode#PROXY}.
-	 * @see AdviceMode
+	 * Indicate how transactional advice should be applied.
+	 * <p><b>The default is {@link AdviceMode#PROXY}.</b>
+	 * Please note that proxy mode allows for interception of calls through the proxy
+	 * only. Local calls within the same class cannot get intercepted that way; an
+	 * {@link Transactional} annotation on such a method within a local call will be
+	 * ignored since Spring's interceptor does not even kick in for such a runtime
+	 * scenario. For a more advanced mode of interception, consider switching this to
+	 * {@link AdviceMode#ASPECTJ}.
 	 */
 	AdviceMode mode() default AdviceMode.PROXY;
 
 	/**
 	 * Indicate the ordering of the execution of the transaction advisor
 	 * when multiple advices are applied at a specific joinpoint.
-	 * The default is {@link Ordered#LOWEST_PRECEDENCE}.
+	 * <p>The default is {@link Ordered#LOWEST_PRECEDENCE}.
 	 */
 	int order() default Ordered.LOWEST_PRECEDENCE;
 

src/docs/asciidoc/data-access.adoc

@@ -1225,6 +1225,14 @@ any kind of method.
   No specified ordering means that the AOP subsystem determines the order of the advice.
 |===
 
+[NOTE]
+====
+The default advice mode for processing `@Transactional` annotations is "proxy" which
+allows for interception of calls through the proxy only; local calls within the same
+class cannot get intercepted that way. For a more advanced mode of interception,
+consider switching to "aspectj" mode in combination with compile/load-time weaving.
+====
+
 [NOTE]
 ====
 The `proxy-target-class` attribute controls what type of transactional proxies are

src/docs/asciidoc/integration.adoc

@@ -6250,6 +6250,14 @@ Notice with the above XML that an executor reference is provided for handling th
 tasks that correspond to methods with the `@Async` annotation, and the scheduler
 reference is provided for managing those methods annotated with `@Scheduled`.
 
+[NOTE]
+====
+The default advice mode for processing `@Async` annotations is "proxy" which allows
+for interception of calls through the proxy only; local calls within the same class
+cannot get intercepted that way. For a more advanced mode of interception, consider
+switching to "aspectj" mode in combination with compile-time or load-time weaving.
+====
+
 
 [[scheduling-annotation-support-scheduled]]
 ==== The @Scheduled annotation
@@ -8313,8 +8321,16 @@ application through AOP. The configuration is intentionally similar with that of
 
 [NOTE]
 ====
-Advanced customizations using Java config require to implement `CachingConfigurer`, refer
-to {api-spring-framework}/cache/annotation/CachingConfigurer.html[the
+The default advice mode for processing caching annotations is "proxy" which allows
+for interception of calls through the proxy only; local calls within the same class
+cannot get intercepted that way. For a more advanced mode of interception, consider
+switching to "aspectj" mode in combination with compile-time or load-time weaving.
+====
+
+[NOTE]
+====
+Advanced customizations using Java config require to implement `CachingConfigurer`:
+Please refer to {api-spring-framework}/cache/annotation/CachingConfigurer.html[the
 javadoc for more details].
 ====