Skip to content

Commit 721fd20

Browse files
committed
Document advice precedence in reference manual
This commit documents the precedence for advice declared within the same @aspect class or within the same <aop:aspect> element. See gh-25186
1 parent 0b760c1 commit 721fd20

File tree

1 file changed

+37
-6
lines changed

1 file changed

+37
-6
lines changed

src/docs/asciidoc/core/core-aop.adoc

Lines changed: 37 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1650,12 +1650,23 @@ the aspect class or annotating it with the `@Order` annotation. Given two aspect
16501650
aspect returning the lower value from `Ordered.getValue()` (or the annotation value) has
16511651
the higher precedence.
16521652

1653-
When two pieces of advice defined in the same aspect both need to run at the same
1654-
join point, the ordering is undefined (since there is no way to retrieve the declaration
1655-
order through reflection for javac-compiled classes). Consider collapsing such advice
1656-
methods into one advice method per join point in each aspect class or refactor the
1657-
pieces of advice into separate aspect classes that you can order at the aspect level.
1658-
1653+
[NOTE]
1654+
====
1655+
As of Spring Framework 5.2.7, advice methods defined in the same `@Aspect` class that
1656+
need to run at the same join point are assigned precedence based on their advice type in
1657+
the following order, from highest to lowest precedence: `@Around`, `@Before`, `@After`,
1658+
`@AfterReturning`, `@AfterThrowing`. Note, however, that due to the implementation style
1659+
in Spring's `AspectJAfterAdvice`, an `@After` advice method will effectively be invoked
1660+
after any `@AfterReturning` or `@AfterThrowing` advice methods in the same aspect.
1661+
1662+
When two pieces of the same type of advice (for example, two `@After` advice methods)
1663+
defined in the same `@Aspect` class both need to run at the same join point, the ordering
1664+
is undefined (since there is no way to retrieve the source code declaration order through
1665+
reflection for javac-compiled classes). Consider collapsing such advice methods into one
1666+
advice method per join point in each `@Aspect` class or refactor the pieces of advice
1667+
into separate `@Aspect` classes that you can order at the aspect level via `Ordered` or
1668+
`@Order`.
1669+
====
16591670

16601671

16611672
[[aop-introductions]]
@@ -2555,6 +2566,26 @@ between aspects is determined via the `order` attribute in the `<aop:aspect>` el
25552566
by either adding the `@Order` annotation to the bean that backs the aspect or by having
25562567
the bean implement the `Ordered` interface.
25572568

2569+
[NOTE]
2570+
====
2571+
In contrast to the precedence rules for advice methods defined in the same `@Aspect`
2572+
class, when two pieces of advice defined in the same `<aop:aspect>` element both need to
2573+
run at the same join point, the precedence is determined by the order in which the advice
2574+
elements are declared within the enclosing `<aop:aspect>` element, from highest to lowest
2575+
precedence.
2576+
2577+
For example, given an `around` advice and a `before` advice defined in the same
2578+
`<aop:aspect>` element that apply to the same join point, to ensure that the `around`
2579+
advice has higher precedence than the `before` advice, the `<aop:around>` element must be
2580+
declared before the `<aop:before>` element.
2581+
2582+
As a general rule of thumb, if you find that you have multiple pieces of advice defined
2583+
in the same `<aop:aspect>` element that apply to the same join point, consider collapsing
2584+
such advice methods into one advice method per join point in each `<aop:aspect>` element
2585+
or refactor the pieces of advice into separate `<aop:aspect>` elements that you can order
2586+
at the aspect level.
2587+
====
2588+
25582589

25592590

25602591
[[aop-schema-introductions]]

0 commit comments

Comments
 (0)