Advice Ordering
When several advices apply to the same function, AspectK orders them with two rules, applied by priority.
| Priority | Rule | Order |
|---|---|---|
| 1 | Kind | @Before, then @Around, then the body, then @After |
| 2 | Target annotation | The order the annotations are written on the function |
"First" means runs first for @Before and @After, and outermost for @Around: the first
@Around is entered first and returns last.
The order advices are declared in inside an @Aspect is not part of the rules. See
What Is Not Guaranteed.
1. Kind
Whatever annotations the advices target, and wherever they are declared, the kinds always layer the same way:
@Aspect
object TransferAspect {
@After(target = [Transfer::class])
fun audit(joinPoint: JoinPoint) = println("audit")
@Around(target = [Transfer::class])
fun transaction(pjp: ProceedingJoinPoint): Any? {
println("begin")
return pjp.proceed().also { println("commit") }
}
@Before(target = [Transfer::class])
fun checkPermission(joinPoint: JoinPoint) = println("check")
}
@Transfer
fun transfer(amount: Int) = println("transfer $amount")
Two things follow from where each kind sits:
@Beforeis outside every@Around. It runs exactly once per call, sees the original arguments, and runs even if an@Aroundnever callsproceed().@Afteris inside every@Around, wrapped around the body only. It runs once perproceed(): not at all if an@Aroundskipsproceed(), twice if one calls it twice. It sees the arguments the body actually received, including ones replaced throughproceed(newArgs). If the body throws,@Afterruns first and the exception then reaches the@Aroundadvices.
2. Target Annotation
When a function carries several target annotations, the advices of the annotation written first come first. Reorder the annotations on the function to reorder the advices.
@Aspect
object Aspects {
@Around(target = [Cached::class])
fun cache(pjp: ProceedingJoinPoint): Any? { /* return the cached value or proceed() */ }
@Around(target = [Timed::class])
fun time(pjp: ProceedingJoinPoint): Any? { /* measure proceed() */ }
}
@Timed
@Cached
fun timedThenCached(x: Int): Int = x * 2 // time( cache( body ) ): a cache hit is timed too
@Cached
@Timed
fun cachedThenTimed(x: Int): Int = x * 2 // cache( time( body ) ): only real computations are timed
The same holds for @Before and @After: with @Logged @Timed on the function, the Logged
advice of each kind runs ahead of the Timed one.
Rule 1 still wins over this one. With @Logged @Timed, a @Before targeting Timed runs
ahead of an @Around targeting Logged.
One advice listing several targets
An advice applies once for each of its target annotations that the function carries.
@Aspect
object TraceAspect {
@Around(target = [Logged::class, Timed::class])
fun trace(pjp: ProceedingJoinPoint): Any? {
println("enter")
return pjp.proceed().also { println("exit") }
}
}
@Logged
fun one() = println("body")
@Logged
@Timed
fun both() = println("body")
one() carries one of the two targets, so the advice applies once:
both() carries both, so the advice applies twice, nested inside itself:
The same goes for @Before and @After: on both() they would run twice in a row. If the
advice should run once however many of its targets are present, give it a single target
annotation and put that annotation on the function.
Inherited annotations
An override that receives advice through inherits = true uses the order the annotations
are written in on the overridden declaration.
What Is Not Guaranteed
Two orders are left unspecified. Don't rely on what you observe for them: it can change between builds and versions.
Several advices on one target annotation. When advices of the same kind target the same
annotation, the order between them is not guaranteed. It does not follow the order they are
declared in, inside one @Aspect or across several.
@Aspect
object Aspects {
@Around(target = [Logged::class]) fun first(pjp: ProceedingJoinPoint): Any? { /* ... */ }
@Around(target = [Logged::class]) fun second(pjp: ProceedingJoinPoint): Any? { /* ... */ }
}
@Logged
fun work() { /* ... */ } // which of the two is outermost is unspecified
When the order matters, give each advice its own target annotation and order the annotations on the function (rule 2).
Annotations inherited from another module. Rule 2 holds for inherited annotations only when the overridden declaration is compiled in the same module. Otherwise, repeat the annotations on the override.