diff --git a/framework-docs/src/docs/asciidoc/core/core-aop.adoc b/framework-docs/src/docs/asciidoc/core/core-aop.adoc index 467072a52fa2..2ab57095200c 100644 --- a/framework-docs/src/docs/asciidoc/core/core-aop.adoc +++ b/framework-docs/src/docs/asciidoc/core/core-aop.adoc @@ -1535,31 +1535,31 @@ 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. -`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. -`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. +`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. +`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] ==== @@ -1579,26 +1579,28 @@ The following example shows how to use the `argNames` attribute: ---- @Before( value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> - argNames = "bean,auditable") + argNames = "bean,auditable") // <2> public void audit(Object bean, Auditable auditable) { AuditCode code = auditable.value(); // ... use code and bean } ---- <1> References the `publicMethod` named pointcut defined in <>. +<2> Declares `bean` and `auditable` as the argument names. [source,kotlin,indent=0,subs="verbatim",role="secondary"] .Kotlin ---- @Before( value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> - argNames = "bean,auditable") + argNames = "bean,auditable") // <2> fun audit(bean: Any, auditable: Auditable) { val code = auditable.value() // ... use code and bean } ---- <1> References the `publicMethod` named pointcut defined in <>. +<2> Declares `bean` and `auditable` as the argument names. If the first parameter is of type `JoinPoint`, `ProceedingJoinPoint`, or `JoinPoint.StaticPart`, you can omit the name of the parameter from the value of the @@ -1610,32 +1612,34 @@ point object, the `argNames` attribute does not need to include it: ---- @Before( value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> - argNames = "bean,auditable") + argNames = "bean,auditable") // <2> public void audit(JoinPoint jp, Object bean, Auditable auditable) { AuditCode code = auditable.value(); // ... use code, bean, and jp } ---- <1> References the `publicMethod` named pointcut defined in <>. +<2> Declares `bean` and `auditable` as the argument names. [source,kotlin,indent=0,subs="verbatim",role="secondary"] .Kotlin ---- @Before( value = "com.xyz.Pointcuts.publicMethod() && target(bean) && @annotation(auditable)", // <1> - argNames = "bean,auditable") + argNames = "bean,auditable") // <2> fun audit(jp: JoinPoint, bean: Any, auditable: Auditable) { val code = auditable.value() // ... use code, bean, and jp } ---- <1> References the `publicMethod` named pointcut defined in <>. +<2> Declares `bean` and `auditable` as the argument names. -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