Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Revise documentation for @AspectJ argument name resolution algorithm

Browse Source 
Closes gh-30057
This commit is contained in:
Sam Brannen
2023-03-02 15:26:21 +01:00
parent 4dc45d551c
commit 22bb76d326
1 changed files with 25 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
src/docs/asciidoc/core/core-aop.adoc
View File

@@ -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 <<aop-ataspectj-advice-params-names-explicit>> 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