Target Annotations
An advice names one or more annotation classes, and AspectK weaves it into every function of your module that carries one of them. This page covers which annotations can be named and what counts as a function.
Annotations You Did Not Declare
A target annotation does not have to be your own. Any annotation class the aspect can reference works, including one from the standard library, from a third-party library, or written in Java:
@Aspect
object ThreadCheckAspect {
@Before(WorkerThread::class) // androidx.annotation.WorkerThread
fun check(joinPoint: JoinPoint) {
check(Looper.myLooper() != Looper.getMainLooper()) {
"${joinPoint.signature.methodName} must not run on the main thread"
}
}
}
class UserRepository {
@WorkerThread
fun load(id: Int): User = dao.find(id) // the check now runs first
}
Code that already carries such annotations gets the advice without being edited.
Note
The advice is woven into functions compiled in your module. A function inside the library that declares the annotation is not changed.
Lambdas and Anonymous Functions
Kotlin applies an annotation written in front of a lambda to the function the lambda compiles to, so a lambda can be a target:
button.setOnClickListener(@Logged { submit() }) // as an argument
executor.execute @Logged { refresh() } // as a trailing lambda
val handler: (String) -> Unit = @Logged { name -> greet(name) }
register(@Logged fun() { submit() }) // anonymous function
- The advice runs each time the lambda is invoked, not when it is created.
joinPoint.argsholds the arguments the lambda was invoked with.@Before,@Afterand@Aroundall apply. A lambda under@Aroundcan still capture variables from the enclosing function.
Lambdas Passed to Inline Functions
forEach, let, run, map, getOrElse, onFailure and most other standard-library
functions that take a lambda are inline. Their lambda never becomes a function, so Kotlin
rejects an annotation it would have to store:
Declare the target annotation with SOURCE retention and Kotlin accepts it. AspectK weaves the
advice into the lambda body before the lambda is inlined:
@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.SOURCE)
annotation class LogFailure
@Aspect
object FailureAspect {
@Before(LogFailure::class)
fun log(joinPoint: JoinPoint) {
println("failed: ${joinPoint.args.first()}")
}
}
fun load(): Config = runCatching { read() }
.getOrElse @LogFailure { Config.DEFAULT } // logs the exception, then falls back
- A non-local
returninside the lambda still returns from the enclosing function. - A
SOURCEannotation also works on named functions and on lambdas that are not inlined, and an aspect in another module can target it, so one annotation can serve every case.