From c7100f771cea9e6982d84ac2665deb42b1aa3995 Mon Sep 17 00:00:00 2001 From: Juergen Hoeller Date: Sun, 22 Oct 2017 20:34:34 +0200 Subject: [PATCH] Explicit notes on advice mode proxy vs aspectj Issue: SPR-16092 --- .../cache/annotation/EnableCaching.java | 31 ++++++++++++------- .../scheduling/annotation/EnableAsync.java | 30 +++++++++++------- .../EnableTransactionManagement.java | 29 +++++++++++------ src/docs/asciidoc/data-access.adoc | 8 +++++ src/docs/asciidoc/integration.adoc | 20 ++++++++++-- 5 files changed, 84 insertions(+), 34 deletions(-) diff --git a/spring-context/src/main/java/org/springframework/cache/annotation/EnableCaching.java b/spring-context/src/main/java/org/springframework/cache/annotation/EnableCaching.java index 0ec602b9ea..c05b44ce1b 100644 --- a/spring-context/src/main/java/org/springframework/cache/annotation/EnableCaching.java +++ b/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 @@ import org.springframework.core.Ordered; * can be useful if you do not need to customize everything. See {@link CachingConfigurer} * Javadoc for further details. * - *

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. + *

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. * - *

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. + *

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. + *

The default is {@link AdviceMode#PROXY}. + * 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}. + *

The default is {@link Ordered#LOWEST_PRECEDENCE}. */ int order() default Ordered.LOWEST_PRECEDENCE; diff --git a/spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java b/spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java index 8b7eb4c026..a06ed0cb57 100644 --- a/spring-context/src/main/java/org/springframework/scheduling/annotation/EnableAsync.java +++ b/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 @@ import org.springframework.core.Ordered; * } * } * - *

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. - * - *

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. - * *

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. * + *

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. + * + *

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. - *

The default is {@link AdviceMode#PROXY}. - * @see AdviceMode + *

The default is {@link AdviceMode#PROXY}. + * 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; diff --git a/spring-tx/src/main/java/org/springframework/transaction/annotation/EnableTransactionManagement.java b/spring-tx/src/main/java/org/springframework/transaction/annotation/EnableTransactionManagement.java index f0d8d733f7..8d500e8d03 100644 --- a/spring-tx/src/main/java/org/springframework/transaction/annotation/EnableTransactionManagement.java +++ b/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 @@ import org.springframework.core.Ordered; * {@code @Transactional} methods. See {@link TransactionManagementConfigurer} Javadoc * for further details. * - *

The {@link #mode()} attribute controls how advice is applied; if the mode is + *

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. * - *

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. + *

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. + *

The default is {@link AdviceMode#PROXY}. + * 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}. + *

The default is {@link Ordered#LOWEST_PRECEDENCE}. */ int order() default Ordered.LOWEST_PRECEDENCE; diff --git a/src/docs/asciidoc/data-access.adoc b/src/docs/asciidoc/data-access.adoc index c190cd9324..e5bff0f814 100644 --- a/src/docs/asciidoc/data-access.adoc +++ b/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 diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index 80d8796871..05908c20bf 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/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]. ==== -- GitLab