Listener

annotation class Listener(val id: String = "", val priority: Int = PriorityConstant.NORMAL, val async: Boolean = false)(source)

标记一个函数为监听器/监听函数,并尝试自动检测其监听类型。

当标记在一个函数上的时候,应当提供至多一个事件类型的参数作为你需要监听的事件类型。eg:

@Listener
suspend fun ChannelMessageEvent.myListener() { ... }

默认情况下,此函数的ID为其全限定名,你可以通过 @Listener(id="...") 指定一个ID。 当不指定的时候默认为当前标记对象的全限定二进制名称或随机UUID字符串。

在 Boot相关模块下,@Listener 会检测标记函数的返回值类型。如果返回值类型为 EventListenerBuilder 或者 EventListener, 则会将当前函数会直接被当作为一个需要注册的bean,而不再解析为一个函数式的监听函数。

以Spring环境下为例,上述情况的函数将会被视作一个 Spring Bean 出处理,相当于标记了 @Bean, 并不会再作为监听函数注册。

需要注意的是,如果作为一个 EventListenerBuilderEventListener Bean 注册的话,被标记函数不可为挂起函数。

@Component
class Foo {
@Listener
suspend fun EventProcessingContext.listener(event: FooEvent) {
// 此函数为普通的监听函数
// 可以使用挂起函数
}

@Listener
fun fooListenerBuilder(): EventListenerBuilder {
// 此函数的返回值会作为Bean注册,不会被作为监听函数。
// 不可使用挂起函数
return ...
}

@Listener
fun fooListenerBuilder() = buildSimpleListener(FooEvent) {
// 此函数的返回值会作为Bean注册,不会被作为监听函数。
// 不可使用挂起函数

id = "..."
match { condition1 }
match { condition2 }
handle {
// ...
EventResult.defaults()
}

}

@Bean
fun barListenerBuilder(): EventListenerBuilder {
// 更推荐养成使用明确区分二者注解的标准写法的习惯。
// 不可使用挂起函数
return ...
}

@Bean
fun barListener(): EventListener {
// 更推荐养成使用明确区分二者注解的标准写法的习惯。
// 不可使用挂起函数
return ...
}
}

当通过直接返回 EventListener 或者 EventListenerBuilder 的形式注册监听函数的时候,@Listener 将仅作为标记用, 其中的所有参数( 例如 idasync)都将无效。

⚠️注意: 与在 spring 环境下不同,在 boot 模块中支持通过 @Listener 注册一个 EventListenerBuilderEventListener, 但是不支持这个被标记的函数存在参数。这也是为什么建议在任何环境下都使用明确的注解: 如果是注册 EventListenerBuilderEventListener,最好使用明确的 @Beans 或者 @Bean, 而不是统一使用 @Listener

Parameters

id

监听函数ID。

priority

此事件的优先级。

async

此函数是否为异步函数。 如果为 object 类型,则会直接获取实例,否则会尝试通过可用途径获取对应结果。

See also

Properties

Link copied to clipboard
val async: Boolean = false
Link copied to clipboard
val id: String
Link copied to clipboard