Join Points
A JoinPoint describes one call of an intercepted function. AspectK creates one each time
the function runs and passes it to the matching advice.
JoinPoint Interface
interface JoinPoint {
val target: Any? // receiver object (null for top-level functions)
val signature: MethodSignature // compile-time method metadata
val args: List<Any?> // runtime arguments in declaration order
}
target — The Receiver
target is the object on which the intercepted method is called:
class UserService {
@Logged
fun getUser(id: String): User { ... }
}
@Aspect
object LoggingAspect {
@Before(target = [Logged::class])
fun log(jp: JoinPoint) {
val service = jp.target as? UserService // the UserService instance
println("Called on: $service")
}
}
For top-level functions, target is null:
signature — Method Metadata
MethodSignature holds metadata about the intercepted function, fixed at compile time:
data class MethodSignature(
val methodName: String, // simple function name
val annotations: List<AnnotationInfo>, // annotations on the function
val parameter: List<MethodParameter>, // parameter descriptors
val returnType: KClass<*>, // erased return type
val returnTypeName: String, // fully-qualified return type name
)
Example
@Before(target = [Logged::class])
fun inspect(jp: JoinPoint) {
val sig = jp.signature
println("name : ${sig.methodName}")
println("returnType : ${sig.returnTypeName}")
println("parameters : ${sig.parameter.map { "${it.name}: ${it.typeName}" }}")
println("annotations: ${sig.annotations.map { it.typeName }}")
}
Generic Type Erasure
When the return type is a type parameter such as T, returnType and returnTypeName
resolve to its upper bound:
fun <T> identity(value: T): T = value
// sig.returnType == Any::class
// sig.returnTypeName == "kotlin.Any"
fun <T : Number> double(value: T): T = value
// sig.returnType == Number::class
// sig.returnTypeName == "kotlin.Number"
args — Runtime Arguments
args is a List<Any?> of the arguments passed to the intercepted function, in declaration
order. A dispatch or extension receiver, when there is one, comes first (see
Supported Function Types). For a top-level function:
@Logged
fun transfer(fromId: String, toId: String, amount: Double) { ... }
@Before(target = [Logged::class])
fun log(jp: JoinPoint) {
val fromId = jp.args[0] as String // "acc-001"
val toId = jp.args[1] as String // "acc-002"
val amount = jp.args[2] as Double // 150.0
}
Nullable Arguments
For a nullable parameter, the matching args element may be null:
MethodParameter.isNullable tells you whether null is expected:
jp.signature.parameter.zip(jp.args).forEach { (param, value) ->
if (param.isNullable || value != null) {
println("${param.name} = $value")
}
}
AnnotationInfo — Annotation Details
Annotations on functions and parameters are exposed as AnnotationInfo:
data class AnnotationInfo(
val type: KClass<out Annotation>, // annotation class
val typeName: String, // FQN string
val args: List<Any?>, // explicitly provided argument values
val parameterNames: List<String>, // corresponding parameter names
)
jp.signature.annotations.forEach { info ->
println("@${info.typeName}")
info.parameterNames.zip(info.args).forEach { (name, value) ->
println(" $name = $value")
}
}
Note
args holds only the arguments written in source. Arguments left at their default
value are omitted, and parameterNames tells you which ones are present.
Supported Function Types
AspectK can intercept the function kinds below. The layout of target and args depends on
the kind:
Class member function
class UserService {
@Logged
fun getUser(id: String): User { ... }
}
// jp.target → UserService instance
// jp.args → [UserService instance, id]
The dispatch receiver is also the first element of args.
Top-level function
Extension function
The extension receiver is prepended to args; target is null.
@Logged
fun String.process(suffix: String) { ... }
// jp.target → null
// jp.args → [receiverString, suffix]
suspend function
args contains only the declared parameters. The continuation is not included.
@Logged
suspend fun fetchData(url: String): String { ... }
// jp.target → receiver instance (or null for top-level)
// jp.args → [url]
inline function
An inline lambda parameter is not a value, so its slot in args is null.
@Logged
inline fun <reified T> measure(label: String, block: () -> T): T = block()
// jp.target → null
// jp.args → [label, null]
Property getter
Same layout as a member function with no parameters.
class Config {
val name: String
@Logged get() = "aspectk"
}
// jp.target → Config instance
// jp.args → [Config instance]
Property setter
The receiver is args[0] and the incoming value is args[1].
class Config {
var name: String = ""
@Logged set(value) { field = value }
}
// jp.target → Config instance
// jp.args → [Config instance, newValue]
expect/actual function
Advice is injected into the actual declaration on each platform. The layout is the same as
for a top-level function.
// commonMain
@Logged
expect fun platformGreet(name: String)
// jp.target → null
// jp.args → [name]
Extension Functions
aspectk-runtime includes extension functions on JoinPoint, ProceedingJoinPoint,
MethodSignature and AnnotationInfo for the common lookups and casts.
JoinPoint extensions
getArg<T>(name: String): T
Returns the argument value for the parameter named name, cast to T.
Throws NoSuchElementException if the parameter does not exist, or ClassCastException
if the value cannot be cast.
@Around(target = [Transactional::class])
fun doAround(pjp: ProceedingJoinPoint): Any? {
val userId = pjp.getArg<String>("userId")
return pjp.proceed()
}
getArgOrNull<T>(name: String): T?
Returns the argument value for the parameter named name, cast to T, or null if
the parameter does not exist or the value cannot be cast.
@Before(target = [Logged::class])
fun doBefore(jp: JoinPoint) {
val label = jp.getArgOrNull<String>("label") ?: "unknown"
}
getTarget<T>(): T
Returns JoinPoint.target cast to T, for advice that needs to call the receiver's own
members. Throws ClassCastException if the cast fails, or NullPointerException if target
is null (top-level or companion-object function).
@Before(target = [Audited::class])
fun doBefore(jp: JoinPoint) {
val service = jp.getTarget<UserService>()
service.recordAccess()
}
getTargetOrNull<T>(): T?
Returns JoinPoint.target cast to T, or null if the target is null or cannot be
cast.
@Before(target = [Audited::class])
fun doBefore(jp: JoinPoint) {
jp.getTargetOrNull<UserService>()?.recordAccess()
}
findAnnotation<T : Annotation>(): AnnotationInfo?
Returns the AnnotationInfo for annotation T on the intercepted function, or null
if the annotation is not present. Delegates to MethodSignature.findAnnotation<T>().
@Before(target = [RateLimit::class])
fun doBefore(jp: JoinPoint) {
val rateLimit = jp.findAnnotation<RateLimit>() ?: return
val limit = rateLimit.getArg<Int>("maxCalls")
}
getAnnotationArgs<T : Annotation>(): Map<String, Any?>
Returns the arguments of annotation T on the intercepted function, by parameter name.
Throws NoSuchElementException if the function is not annotated with T.
@RateLimit(maxCalls = 5)
fun search(query: String) { /* ... */ }
@Before(RateLimit::class)
fun doBefore(jp: JoinPoint) {
val args = jp.getAnnotationArgs<RateLimit>() // {maxCalls=5}
val maxCalls = args["maxCalls"] as Int
}
Only the arguments written at the use site are present. A parameter left to its default value
has no entry, so read it with a fallback: args["scope"] as? String ?: "global".
getAnnotationArgsOrNull<T : Annotation>(): Map<String, Any?>?
Same as getAnnotationArgs, but returns null if the function is not annotated with T.
ProceedingJoinPoint extensions
Every function here also exists on SuspendProceedingJoinPoint, as a suspend function.
proceedAs<T>(): T
Proceeds with the original arguments and returns the result cast to T. Throws
ClassCastException if the result is not a T.
proceedAs<T>(vararg args: Any?): T
Proceeds with substituted arguments, as proceed(vararg args) does, and returns the result
cast to T.
proceedWith(vararg replacements: Pair<String, Any?>): Any?
Proceeds with the named arguments replaced and every other one kept. Unlike
proceed(vararg args), the arguments that don't change don't have to be passed again. Throws
NoSuchElementException if a name is not a parameter of the intercepted function.
@Normalized
fun find(tenant: String, name: String, limit: Int): List<User> { /* ... */ }
@Around(Normalized::class)
fun doAround(pjp: ProceedingJoinPoint): Any? =
pjp.proceedWith("name" to pjp.getArg<String>("name").trim())
MethodSignature extensions
findAnnotation<T : Annotation>(): AnnotationInfo?
Returns the AnnotationInfo for annotation T in MethodSignature.annotations, or
null if the annotation is not present.
@Before(target = [Secured::class])
fun doBefore(jp: JoinPoint) {
val secured = jp.signature.findAnnotation<Secured>() ?: return
val role = secured.getArg<String>("role")
}
AnnotationInfo extensions
getArg<T>(paramName: String): T
Returns the annotation argument value for the parameter named paramName, cast to T.
Throws NoSuchElementException if the parameter does not exist, or ClassCastException
if the value cannot be cast.
@Before(target = [RateLimit::class])
fun doBefore(jp: JoinPoint) {
val info = jp.findAnnotation<RateLimit>()!!
val maxCalls = info.getArg<Int>("maxCalls")
}
getArgOrNull<T>(paramName: String): T?
Returns the annotation argument value for the parameter named paramName, cast to T,
or null if the parameter does not exist or the value cannot be cast.