Explicit notes on advice mode proxy vs aspectj

Issue: SPR-16092

Author: jhoeller

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

@@ -1,5 +1,5 @@
 /*
- * 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 @@
  * 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 @@
 	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

@@ -1,5 +1,5 @@
 /*
- * 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 @@
  *     }
  * }</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 @@
  * 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 @@
 
 	/**
 	 * 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

@@ -1,5 +1,5 @@
 /*
- * 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 @@
  * {@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 @@
 	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;