Flowable Event Registry API 深度指南:引擎、服务、查询与单元测试
Flowable Event Registry API 深度指南:引擎、服务、查询与单元测试
Flowable Event Registry(事件注册中心)是 Flowable 中负责事件定义与通道定义管理、事件收发与关联(correlation)的独立嵌入式引擎。本文以官方文档 eventregistry/ch03-API.md 为骨架,系统讲解其核心 API:从 EventRegistryEngine 的获取方式、三个核心服务(EventRepositoryService、EventRegistry、EventManagementService)的职责划分,到异常策略、类型安全查询 API、JUnit Jupiter 单元测试实践,再到 Web 应用中的生命周期管理。读完本文,你将掌握如何在自有应用中获取与销毁 Event Registry 引擎、使用服务收发事件、编写可自动部署定义的单元测试,以及将引擎平滑嵌入 Servlet 容器。
Event Registry Engine API 与服务
与 Flowable 的其他引擎(流程引擎、CMMN 引擎、DMN 引擎)一致,Event Registry 与外部交互的最常见方式是 Engine API。中心起点是 EventRegistryEngine,创建方式在 配置章节 中有多种说明。从 EventRegistryEngine 可以获取各类服务对象:
EventRegistryEngine eventRegistryEngine = EventRegistryEngines.getDefaultEventRegistryEngine();
EventRegistry eventRegistry = eventRegistryEngine.getEventRegistry();
EventRepositoryService eventRepositoryService = eventRegistryEngine.getEventRepositoryService();
EventManagementService eventManagementService = eventRegistryEngine.getEventManagementService();
EventRegistryEngine 及其服务对象都是线程安全的,可以持有单个引用并在整个服务器生命周期内共享。
EventRegistryEngines:引擎的集中管理入口
EventRegistryEngines 是引擎的静态门面(facade)。getDefaultEventRegistryEngine() 在首次调用时会初始化并构建一个 Event Registry 引擎,之后始终返回同一个引擎实例;引擎的创建与关闭分别由 EventRegistryEngines.init() 与 EventRegistryEngines.destroy() 负责。其源码位于 EventRegistryEngines.java:
init()会扫描 classpath 上的所有flowable.eventregistry.cfg.xml与flowable-eventregistry-context.xml资源(L51-L92)。- 对于每个
flowable.eventregistry.cfg.xml,按 Flowable 标准方式构建:EventRegistryEngineConfiguration.createEventRegistryEngineConfigurationFromInputStream(inputStream).buildEventRegistryEngine()(L156-L164)。 - 对于每个
flowable-eventregistry-context.xml,则走 Spring 方式:先创建 Spring 应用上下文,再从上下文中获取 Event Registry 引擎(L94-L108)。 - 默认引擎名为
"default"(NAME_DEFAULT常量,见 L39),通过getDefaultEventRegistryEngine()获取;getEventRegistryEngine("myName")可按名称获取指定引擎(L180-L195)。 - 从源码可以看到,
init()内部使用HashSet对 classpath 上扫描到的 URL 去重,避免某些类加载器重复返回同一 URL 导致引擎被重复启动(L65-L70)。 - 此外还提供
registerEventRegistryEngine()/unregister()供编程式注册引擎,以及getEventRegistryEngineInfos()查询初始化结果(EngineInfo列表)。
服务的无状态特性与集群支持
所有服务都是**无状态(stateless)**的。这意味着可以轻松将 Flowable Event Registry 部署在多个节点的集群上,所有节点共享同一个数据库,无需担心某个调用此前由哪台机器执行过——任何服务调用在任何节点上执行都是幂等的。
EventRepositoryService:部署与定义管理
EventRepositoryService 是与引擎打交道时最先需要的服务,负责管理与操作部署(Deployment)、事件定义(Event Definition)和通道定义(Channel Definition)。三者的关系如下:
- 事件定义(Event Definition):用于配置事件的 payload(载荷)与关联(correlation)参数,并定义与某个通道定义 key 的对应关系。
- 通道定义(Channel Definition):配置入站或出站事件的来源或目标。例如,一个通道定义可以配置一个指向 JMS 队列 orderQueue 的 JMS 监听器。
- 部署(Deployment):引擎内的打包单元。一个部署可包含多个事件定义与通道定义的 JSON 文件。部署即是将内容上传到引擎,引擎会逐一检查并解析所有事件与通道定义,随后存入数据库。从那一刻起,该部署即被系统感知,其中包含的任何事件定义与通道定义都可被使用。
其接口定义在 EventRepositoryService.java,主要操作包括:
- 查询引擎已知的部署、事件定义与通道定义:
createDeploymentQuery()、createEventDefinitionQuery()、createChannelDefinitionQuery(); - 检索定义的 POJO 版本,便于用 Java 而非 JSON 进行内省(introspection):
getEventModelById(String eventDefinitionId)、getEventModelByKey(String eventDefinitionKey)、getChannelModelById(...)、getChannelModelByKey(...),并支持租户(tenantId)与父部署(parentDeploymentId)维度的方法重载; - 部署管理:
createDeployment()(返回EventDeploymentBuilder)、deleteDeployment(String deploymentId)、setDeploymentCategory(...)、setDeploymentTenantId(...)、changeDeploymentParentDeploymentId(...); - 资源读取:
getDeploymentResourceNames(String deploymentId)、getResourceAsStream(String deploymentId, String resourceName)、getEventDefinitionResource(...)、getChannelDefinitionResource(...); - 定义分类调整:
setEventDefinitionCategory(...)、setChannelDefinitionCategory(...); - 编程式建模:
createEventModelBuilder()、createInboundChannelModelBuilder()、createOutboundChannelModelBuilder(),可在代码中直接构建并注册事件模型与出入站通道模型。
EventRegistry:事件收发中枢
EventRegistry(接口见 EventRegistry.java)负责接收与发送事件实例,并支持添加与移除事件消费者。其关键能力:
- 入站处理:
setInboundEventProcessor(InboundEventProcessor)注册负责处理新事件的处理器;适配器(InboundEventChannelAdapter)收到外部事件后调用eventReceived(InboundChannelModel, InboundEvent)交给注册中心处理; - 出站处理:
setOutboundEventProcessor(OutboundEventProcessor)注册负责发送事件的处理;sendEventOutbound(EventInstance, Collection<ChannelModel>)按给定通道模型发送事件,sendSystemEventOutbound(EventInstance)走系统出站处理器; - 消费者管理:
registerEventRegistryEventConsumer(EventRegistryEventConsumer)与removeFlowableEventRegistryEventConsumer(...)管理事件消费者(如流程引擎、CMMN 引擎注册的消费者); - 关联键生成:
generateKey(Map<String, Object> data)基于给定数据生成用于关联事件的唯一键。
EventManagementService:运维与元数据
EventManagementService 在编写使用 Event Registry 的自定义应用时通常不需要。它用于检索引擎版本、数据库表及其元数据等信息,属于运维辅助型服务。
异常策略
Flowable 的基础异常是 org.flowable.engine.FlowableException,属于非受检异常(unchecked)。API 在任何时刻都可能抛出该异常;特定方法中"预期"发生的异常会在方法 javadoc 中说明。例如:
/**
* Retrieves the Java representation of an event definition.
*
* @param eventDefinitionKey the event definition key, cannot be null
* @return the event model Java representation.
*/
EventModel getEventModelByKey(String eventDefinitionKey);
上述示例中,当传入的 key 不存在对应事件定义时会抛出异常;同时,由于 javadoc 明确声明 eventDefinitionKey 不能为 null,传入 null 时会抛出 FlowableIllegalArgumentException。
尽管 Flowable 有意避免过大的异常层级,但在特定场景下会抛出以下子类;其余在调用或执行期间发生且不匹配下列类型的错误,一律以普通 FlowableException 抛出:
FlowableOptimisticLockingException:数据存储中因并发访问同一数据条目发生乐观锁冲突时抛出。FlowableClassLoadingException:请求加载的类未找到或加载过程中出错时抛出。FlowableObjectNotFoundException:请求或操作的对象不存在时抛出。FlowableIllegalArgumentException:在 Event Registry API 调用中提供了非法参数、引擎配置中配置了非法值,或提供了非法值时抛出。
Query API:类型安全的流式查询
Query API 允许以流式(fluent)API编写完全类型安全的查询。可向查询添加各种条件(所有条件以逻辑 AND 组合应用),并可指定恰好一个排序。以下代码展示了一个示例:
List<EventDeployment> eventDeployments = eventRepositoryService.createDeploymentQuery()
.deploymentNameLike("deployment%")
.orderByDeployTime()
.list();
查询入口与定义查询的 API 一一对应:createDeploymentQuery() 返回 EventDeploymentQuery,createEventDefinitionQuery() 返回 EventDefinitionQuery,createChannelDefinitionQuery() 返回 ChannelDefinitionQuery(参见 EventRepositoryService.java)。与单元测试示例中的用法一致,事件定义查询同样支持 eventDefinitionKey("myEvent").latestVersion().singleResult() 这类条件组合,latestVersion() 只取最新版本,singleResult() 要求结果唯一。
单元测试
由于 Flowable Event Registry 是可嵌入式(embeddable)Java 引擎,为事件定义与通道定义编写单元测试就像编写普通单元测试一样简单。Flowable 支持 JUnit Jupiter 风格的单元测试。
注册 FlowableEventExtension
JUnit Jupiter 风格需要注册 org.flowable.eventregistry.test.FlowableEventExtension,通过 @ExtendWith(FlowableEventExtension.class) 完成注册。注册后,EventRegistryEngine 及其服务就可以作为参数注入测试方法与生命周期方法(@BeforeAll、@BeforeEach、@AfterEach、@AfterAll)。
每个测试执行前,引擎默认使用 classpath 上的 flowable.eventregistry.cfg.xml 资源初始化。若要指定不同的配置文件,需要使用 org.flowable.eventregistry.test.EventConfigurationResource 注解(见下方第二个示例)。当配置资源相同时,Event Registry 引擎会在多个单元测试之间静态缓存。
自动部署注解
借助 EventRegistryEngine,可以在测试方法上使用以下两个注解实现定义文件的自动部署与清理:
@EventDeploymentAnnotation(org.flowable.eventregistry.test.EventDeploymentAnnotation):测试前部署resources中指定的事件定义文件;若未指定资源,则部署与测试类同包下的testClassName.testMethod.event资源文件。测试结束时,部署连同其关联的事件与通道定义一并删除。@ChannelDeploymentAnnotation(org.flowable.eventregistry.test.ChannelDeploymentAnnotation):行为与上者对称,默认资源文件名为testClassName.testMethod.channel。测试结束时同样清理整个部署。
两个注解的扩展实现均位于 FlowableEventExtension.java 所在的测试支持包中,更多细节可查看对应注解类。
测试示例
JUnit Jupiter 测试(使用默认资源):
@ExtendWith(FlowableEventExtension.class)
class MyEventDefinitionTest {
@Test
@EventDeploymentAnnotation
void simpleEventDefinitionTest(EventRegistryEngine eventRegistryEngine) {
EventRepositoryService repositoryService = eventRegistryEngine.getEventRepositoryService();
EventDefinition eventDefinition = repositoryService.createEventDefinitionQuery()
.eventDefinitionKey("myEvent")
.latestVersion()
.singleResult();
assertNotNull(eventDefinition);
assertEquals("myEvent", eventDefinition.getKey());
assertEquals(1, eventDefinition.getVersion());
}
}
JUnit Jupiter 测试(使用自定义配置资源):
@ExtendWith(FlowableEventExtension.class)
@EventConfigurationResource("flowable.custom.eventregistry.cfg.xml")
class MyEventDefinitionTest {
@Test
@EventDeploymentAnnotation
void simpleEventDefinitionTest(EventRegistryEngine eventRegistryEngine) {
EventRepositoryService repositoryService = eventRegistryEngine.getEventRepositoryService();
EventDefinition eventDefinition = repositoryService.createEventDefinitionQuery()
.eventDefinitionKey("myEvent")
.latestVersion()
.singleResult();
assertNotNull(eventDefinition);
assertEquals("myEvent", eventDefinition.getKey());
assertEquals(1, eventDefinition.getVersion());
}
}
可以看到,注入的 eventRegistryEngine 直接作为测试方法参数,测试体内再获取 EventRepositoryService 执行查询,配合 @EventDeploymentAnnotation 免去了手工部署与清理的样板代码。
将 Event Registry 引擎嵌入 Web 应用
EventRegistryEngine 是线程安全类,可轻松在多个线程间共享。在 Web 应用中,这意味着可以在容器启动时创建一次引擎,并在容器关闭时销毁引擎。
以下代码片段展示了如何在纯 Servlet 环境中编写一个简单的 ServletContextListener 来初始化和销毁引擎:
public class EventRegistryEnginesServletContextListener implements ServletContextListener {
public void contextInitialized(ServletContextEvent servletContextEvent) {
EventRegistryEngines.init();
}
public void contextDestroyed(ServletContextEvent servletContextEvent) {
EventRegistryEngines.destroy();
}
}
contextInitialized 方法委托给 EventRegistryEngines.init():该方法会在 classpath 上查找 flowable.eventregistry.cfg.xml 资源文件,并为每个配置创建对应的 EventRegistryEngine(例如多个 JAR 各自携带配置文件时,会创建多个引擎)。如果 classpath 上存在多个此类资源文件,务必确保它们的文件名各不相同。当需要用到引擎时,可按以下方式获取:
EventRegistryEngines.getDefaultEventRegistryEngine()
或:
EventRegistryEngines.getEventRegistryEngine("myName");
当然,也可以使用 配置章节 中描述的任何一种引擎创建变体。contextDestroyed 方法则委托给 EventRegistryEngines.destroy(),该方法会正确关闭所有已初始化的引擎——从源码可见,destroy() 会遍历引擎映射逐个调用 close(),并清空所有 EngineInfo 缓存、将初始化标志复位(L219-L240),保证应用重启或容器销毁时不泄漏引擎资源。
围绕本文涉及的引擎与服务,可继续深入阅读仓库中的以下实现:EventRegistryEngine、EventRegistryEngines、EventRegistry 接口、EventRepositoryService 接口 及测试扩展 FlowableEventExtension。事件与通道定义的部署细节可参考 eventregistry/ch05-Deployment.md,Spring 集成方式见 eventregistry/ch04-Spring.md。