事件监听与处理

事件调度器 EventDispatcher

所有的事件处理器都需要注册到 EventDispatcher 中, 当 EventDispatcher 收到消息推送时, 它便会将这个事件交给其内部的处理器依次进行处理。

你可以在 Application 中获取到 EventDispatcher：

val app = ...
val eventDispatcher = app.eventDispatcher // 获取事件调度器

注册事件处理器

想要处理事件, 你便需要向 EventDispatcher 注册事件处理器 EventListener。

val eventDispatcher = ...

dispatcher.register { // this: EventListenerContext
    // 处理事件...

    EventResult.empty() // 返回一个处理结果
}

Kotlin 中提供了一些扩展函数, 可用来更便捷地注册一个事件处理器。

处理所有类型的事件：

val eventDispatcher = ...

dispatcher.process { // this: EventListenerContext
    // 处理事件, 但是不需要返回值

}

处理指定类型的事件：

dispatcher.listen<Event> { // this: EventListenerContext
    // 处理事件

    EventResult.empty()
}

dispatcher.process<Event> { // this: EventListenerContext
    // 处理事件, 但是不需要返回值

}

Kotlin 中也提供了直接针对 Application 的便利扩展 listener：

val app = ...

app.listeners { // this: EventListenerRegistrar
    listen<Event> { ... }
    process { ... }
    process<Event> { ... }
}

事件处理器注册回执

当通过 register 注册一个事件处理器后, 会返回一个 EventListenerRegistrationHandle。可以将它称之为注册的回执, 或者句柄, 总之它的作用是通过调用 dispose 来“取消”这次注册的事件处理器。取消注册后, 对应的事件处理器将不再有效。

val handle = register(...)
handle.dispose()

注册事件处理器的额外属性

val dispatcher = ...
dispatcher.register({ // this: EventListenerRegistrationProperties
    // 配置一些信息
    // 优先级
    priority = -1 // 通常默认值为 0, 越小越优先
    // 添加一个要注册的事件处理器的专属拦截器
    addInterceptor {
        // 拦截...
        invoke() // 执行拦截链的后续并返回真实结果
    }
}) {
    // 处理事件, 返回处理结果...
    ...
}

那些扩展函数也同样支持：

dispatcher.listen<Event>(propertiesConsumer = {
    // 配置一些信息...
}) {
    // 处理事件, 返回处理结果...
    ...
}

dispatcher.process<Event>(propertiesConsumer = {
    // 配置一些信息...
}) {
    // 处理事件...
    ...
}

dispatcher.process(propertiesConsumer = {
    // 配置一些信息...
}) {
    // 处理事件...
    ...
}

事件处理器 EventListener

事件处理器 EventListener 是一个函数接口类型, 它定义了处理事件的方式：接收一个 EventListenerContext, 然后经过处理, 返回 EventResult。

在 Java 中, 你可以通过 `EventListeners` 的静态工厂API来通过 Java 友好的 lambda 方式构建阻塞或异步风格的实例。

var eventListener = EventListeners.async(context -> {
    // 处理事件...
    return CompletableFuture.completedFuture(EventResult.empty()); // 返回处理结果
});

var eventListener = EventListeners.async(Event.class, (context, event) -> {
    // 处理事件...
    return CompletableFuture.completedFuture(EventResult.empty()); // 返回处理结果
});

事件处理结果 EventResult

EventResult 是 EventListener 中处理完事件后的返回值类型。

大多数情况下你不需要自己实现 EventResult 。核心库中提供了 StandardEventResult 定义了部分常见、或具有特殊含义的类型, 并且在 EventResult 中提供静态API来直接获取它们。

事件处理器上下文 EventListenerContext

每一个事件处理器在处理事件时, 都会被提供一个 EventListenerContext。

事件上下文 EventContext

注解 API

simbot4 定义了一套注解API ，用来支持使用注解快速实现事件处理逻辑。这套注解API主要由 Spring Boot starter 进行实现。

class MyListeners {
    @Listener // 注解API，标记一个函数为事件处理函数
    suspend fun handle(event: Event) {
        // ...
    }
}

它被命名为 quantcat(量子猫)，你可以前往文章量子猫来了解更多。

事件推送

想要使事件处理器工作, 那么就要推送事件。可以通过 EventDispatcher.push 推送一个事件, 并得到一个处理结果流 Flow<EventResult>。

val resultFlow = dispatcher.push(event)
// 事件推送的结果流是冷流,
// 你必须收集这个流, 事件才会真正开始被处理
resultFlow.collect()

在 Java 中直接操作 Flow 可能会有一些困难, 你可以使用 EventProcessors 中提供的各种静态API来进行事件推送。

// 推送事件、并在异步中收集结果。
// 其中第三个参数 `application` 是用于执行异步任务的 `CoroutineScope` 类型,
// 你可以使用 `Application` （继承了 `CoroutineScope`）,
// 或者使用 Kotlin 的 `GlobalScope` （有关它的注意事项参见其文档注释）
var asyncListFuture = EventProcessors.pushAndCollectToAsync(dispatcher, event, application, new ArrayList<>());

// 如果希望收集为 List, 也有简写形式
var otherAsyncListFuture = EventProcessors.pushAndCollectToListAsync(dispatcher, event, application);

// 也可以使用 Java 中的 Collector, 就像在 Stream 中使用它一样
var asyncCollectListFuture = EventProcessors.pushAndCollectToAsync(dispatcher, event, application, Collectors.toList());

// 借助 Collector, 也可以实现一些复杂的结果收集, 比如：
// -> 只过滤出类型为 StandardEventResult.Simple 的结果
var asyncCollectSimpleListFuture = EventProcessors.pushAndCollectToAsync(
                dispatcher, event, application,
                Collectors.filtering(
                    result -> result instanceof StandardEventResult.Simple,
                    Collectors.toList()
                ));

// -> 根据是否为 StandardEventResult.Error 为依据分组, 并计算每组的结果数量
var asyncTypeCountingFuture = EventProcessors.pushAndCollectToAsync(
                dispatcher, event, application,
                Collectors.partitioningBy(
                    result -> result instanceof StandardEventResult.Error,
                    Collectors.counting()
                ));

你也可以将结果转化为响应式的 reactor.core.publisher.Flux。

var resultFlux = EventProcessors.pushAndAsFlux(dispatcher, event);
resultFlux.subscribe(result -> {
    // 事件推送的结果流是冷流, 因此转化后的 `Flux` 也是冷的,
    // 你必须消费其中的元素才能使得事件真正的被处理。
});

warning
使用 pushAndAsFlux 需要项目运行时环境中存在 kotlinx-coroutines-reactor。

如上面的示例中所说, 通过 push 得到的 Flow 结果是一个冷流, 因此你必须收集、消费其中的元素, 它才会使得事件被处理, 并且这也受到你对这个流的中间操作。

val flow = dispatcher.push(event)
flow.take(2) // 取前两个元素
    .collect {
        // 消费结果
    }

事件监听与处理﻿

事件调度器 EventDispatcher﻿

注册事件处理器﻿

tip

事件处理器注册回执﻿

注册事件处理器的额外属性﻿

事件处理器 EventListener﻿

tip

事件处理结果 EventResult﻿

Invalid﻿

Error﻿

tip

Empty﻿

Simple﻿

CollectableReactivelyResult﻿

支持的收集类型﻿

事件处理器上下文 EventListenerContext﻿

事件上下文 EventContext﻿

note

注解 API﻿

事件推送﻿

note

warning

事件调度器 EventDispatcher

注册事件处理器

事件处理器注册回执

注册事件处理器的额外属性

事件处理器 EventListener

事件处理结果 EventResult

Invalid

Error

Empty

Simple

CollectableReactivelyResult

支持的收集类型

事件处理器上下文 EventListenerContext

事件上下文 EventContext

注解 API

事件推送