From 22bb76d32680b138e20352f1c6dfaa41f0def680 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Thu, 2 Mar 2023 15:26:21 +0100 Subject: [PATCH] Revise documentation for @AspectJ argument name resolution algorithm Closes gh-30057 --- src/docs/asciidoc/core/core-aop.adoc | 48 +++++++++++++++------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/src/docs/asciidoc/core/core-aop.adoc b/src/docs/asciidoc/core/core-aop.adoc index 6bab62ae1f..edd4c403be 100644 --- a/src/docs/asciidoc/core/core-aop.adoc +++ b/src/docs/asciidoc/core/core-aop.adoc @@ -1525,31 +1525,33 @@ AspectJ APIs refer to parameter names as argument names. Spring AOP uses the following `ParameterNameDiscoverer` implementations to determine parameter names. Each discoverer will be given a chance to discover parameter names, and the first successful discoverer wins. If none of the registered discoverers is capable -of determining parameter names, an `IllegalArgumentException` is thrown. +of determining parameter names, an exception will be thrown. -`KotlinReflectionParameterNameDiscoverer` :: Uses Kotlin reflection APIs if such APIs are - present on the classpath. Not supported in a GraalVM native image. -`StandardReflectionParameterNameDiscoverer` :: Uses the `java.lang.reflect.Parameter` API - available since Java 8. Requires that code be compiled with the `-parameters` flag for - `javac`. Recommended approach on Java 8+. -`LocalVariableTableParameterNameDiscoverer` :: Analyzes the local variable table available - in the byte code to determine parameter names from debug information. Requires that - code be compiled with debug symbols (`-g:vars` at a minimum). Deprecated as of Spring - Framework 6.0 for removal in Spring Framework 6.1 in favor of compiling code with - `-parameters`. Not supported in a GraalVM native image unless the corresponding class - files are present as resources within the image. -`AspectJAdviceParameterNameDiscoverer` :: Uses parameter names that have been explicitly +`AspectJAnnotationParameterNameDiscoverer` :: Uses parameter names that have been explicitly specified by the user via the `argNames` attribute in the corresponding advice or - pointcut annotation. See the following section for details. + pointcut annotation. See <> for details. +`KotlinReflectionParameterNameDiscoverer` :: Uses Kotlin reflection APIs to determine + parameter names. This discoverer is only used if such APIs are present on the classpath. + Not supported in a GraalVM native image. +`StandardReflectionParameterNameDiscoverer` :: Uses the standard `java.lang.reflect.Parameter` + API to determine parameter names. Requires that code be compiled with the `-parameters` + flag for `javac`. Recommended approach on Java 8+. +`LocalVariableTableParameterNameDiscoverer` :: Analyzes the local variable table available + in the byte code of the advice class to determine parameter names from debug information. + Requires that code be compiled with debug symbols (`-g:vars` at a minimum). Deprecated + as of Spring Framework 6.0 for removal in Spring Framework 6.1 in favor of compiling + code with `-parameters`. Not supported in a GraalVM native image unless the corresponding + class files are present as resources within the image. +`AspectJAdviceParameterNameDiscoverer` :: Deduces parameter names from the pointcut + expression, `returning`, and `throwing` clauses. See the + {api-spring-framework}/aop/aspectj/AspectJAdviceParameterNameDiscoverer.html[javadoc] + for details on the algorithm used. [[aop-ataspectj-advice-params-names-explicit]] ===== Explicit Argument Names @AspectJ advice and pointcut annotations have an optional `argNames` attribute that you -can use to specify the argument names of the annotated method. Note, however, that -explicit `argNames` will only be used by Spring as a fallback if none of the other -`ParameterNameDiscoverer` implementations is able to determine parameter names (see the -previous section for details). +can use to specify the argument names of the annotated method. [TIP] ==== @@ -1608,11 +1610,11 @@ point object, the `argNames` attribute does not need to include it: } ---- -The special treatment given to the first parameter of the `JoinPoint`, -`ProceedingJoinPoint`, and `JoinPoint.StaticPart` types is particularly convenient for -advice instances that do not collect any other join point context. In such situations, -you may omit the `argNames` attribute. For example, the following advice does not need to -declare the `argNames` attribute: +The special treatment given to the first parameter of type `JoinPoint`, +`ProceedingJoinPoint`, or `JoinPoint.StaticPart` is particularly convenient for advice +methods that do not collect any other join point context. In such situations, you may +omit the `argNames` attribute. For example, the following advice does not need to declare +the `argNames` attribute: [source,java,indent=0,subs="verbatim",role="primary"] .Java