diff --git a/src/docs/asciidoc/core/core-aop.adoc b/src/docs/asciidoc/core/core-aop.adoc index a2e30c53c3fb..c78716536cc6 100644 --- a/src/docs/asciidoc/core/core-aop.adoc +++ b/src/docs/asciidoc/core/core-aop.adoc @@ -1650,12 +1650,23 @@ the aspect class or annotating it with the `@Order` annotation. Given two aspect aspect returning the lower value from `Ordered.getValue()` (or the annotation value) has the higher precedence. -When two pieces of advice defined in the same aspect both need to run at the same -join point, the ordering is undefined (since there is no way to retrieve the declaration -order through reflection for javac-compiled classes). Consider collapsing such advice -methods into one advice method per join point in each aspect class or refactor the -pieces of advice into separate aspect classes that you can order at the aspect level. - +[NOTE] +==== +As of Spring Framework 5.2.7, advice methods defined in the same `@Aspect` class that +need to run at the same join point are assigned precedence based on their advice type in +the following order, from highest to lowest precedence: `@Around`, `@Before`, `@After`, +`@AfterReturning`, `@AfterThrowing`. Note, however, that due to the implementation style +in Spring's `AspectJAfterAdvice`, an `@After` advice method will effectively be invoked +after any `@AfterReturning` or `@AfterThrowing` advice methods in the same aspect. + +When two pieces of the same type of advice (for example, two `@After` advice methods) +defined in the same `@Aspect` class both need to run at the same join point, the ordering +is undefined (since there is no way to retrieve the source code declaration order through +reflection for javac-compiled classes). Consider collapsing such advice methods into one +advice method per join point in each `@Aspect` class or refactor the pieces of advice +into separate `@Aspect` classes that you can order at the aspect level via `Ordered` or +`@Order`. +==== [[aop-introductions]] @@ -2555,6 +2566,26 @@ between aspects is determined via the `order` attribute in the `` el by either adding the `@Order` annotation to the bean that backs the aspect or by having the bean implement the `Ordered` interface. +[NOTE] +==== +In contrast to the precedence rules for advice methods defined in the same `@Aspect` +class, when two pieces of advice defined in the same `` element both need to +run at the same join point, the precedence is determined by the order in which the advice +elements are declared within the enclosing `` element, from highest to lowest +precedence. + +For example, given an `around` advice and a `before` advice defined in the same +`` element that apply to the same join point, to ensure that the `around` +advice has higher precedence than the `before` advice, the `` element must be +declared before the `` element. + +As a general rule of thumb, if you find that you have multiple pieces of advice defined +in the same `` element that apply to the same join point, consider collapsing +such advice methods into one advice method per join point in each `` element +or refactor the pieces of advice into separate `` elements that you can order +at the aspect level. +==== + [[aop-schema-introductions]]