关于流程定义监听器的说明

  • 事件监听器只能作为​​extensionElements​​的子元素，声明在​​process​​元素上。不能在个别节点（activity）上定义（事件）监听器。
  • ​​delegateExpression​​​中的表达式，与其他表达式（例如在网关中的）不一样，不可以访问执行上下文。只能够引用在流程引擎配置中​​beans​​参数定义的bean；或是在使用spring（且没有定义beans参数）时，引用任何实现了监听器接口的spring bean。
  • 使用监听器的​​class​​属性时，只会创建唯一一个该类的实例。请确保监听器实现不依赖于成员变量，或确保多线程/上下文的使用安全。
  • 如果​​events​​属性使用了不合法的事件类型，或者使用了不合法的​​throwEvent​​值，会在流程定义部署时抛出异常（导致部署失败）。如果​​class​​或​​delegateExecution​​指定了不合法的值（不存在的类，不存在的bean引用，或者代理类没有实现监听器接口），在流程启动（或该流程定义的第一个有效事件分发给这个监听器）时，会抛出异常。请确保引用的类在classpath中，并且保证表达式能够解析为有效的实例。

通过API分发事件

可以通过API提供事件分发机制，向任何在引擎中注册的监听器分发自定义事件。建议（但不强制）只分发​​CUSTOM​​​类型的​​FlowableEvents​​​。使用​​RuntimeService​​分发事件：

/**
 * 将给定事件分发给所有注册监听器。
 * @param event 要分发的事件。
 *
 * @throws FlowableException 当分发事件发生异常，或者{@link FlowableEventDispatcher}被禁用。
 * @throws FlowableIllegalArgumentException 当给定事件不可分发
 */
 void dispatchEvent(FlowableEvent event);

支持的事件类型

下表列出引擎中的所有事件类型。每种类型对应​​org.flowable.engine.common.api.delegate.event.FlowableEventType​​中的一个枚举值。

Table 1. Supported events

事件名称

说明

事件类

ENGINE_CREATED

本监听器所属的流程引擎已经创建，并可以响应API调用。

​​org.flowable…FlowableEvent​​

ENGINE_CLOSED

本监听器所属的流程引擎已经关闭，不能再对该引擎进行API调用。

​​org.flowable…FlowableEvent​​

ENTITY_CREATED

新的实体已经创建。该实体包含在本事件里。

​​org.flowable…FlowableEntityEvent​​

ENTITY_INITIALIZED

新的实体已经创建并完全初始化。如果任何子实体作为该实体的一部分被创建，本事件会在子实体创建/初始化后触发，与 ​​ENTITY_CREATE​​ 事件相反。

​​org.flowable…FlowableEntityEvent​​

ENTITY_UPDATED

实体已经更新。该实体包含在本事件里。

​​org.flowable…FlowableEntityEvent​​

ENTITY_DELETED

实体已经删除。该实体包含在本事件里。

​​org.flowable…FlowableEntityEvent​​

ENTITY_SUSPENDED

实体已经暂停。该实体包含在本事件里。ProcessDefinitions（流程定义）, ProcessInstances（流程实例）与Tasks（任务）会分发本事件。

​​org.flowable…FlowableEntityEvent​​

ENTITY_ACTIVATED

实体已经激活。该实体包含在本事件里。ProcessDefinitions, ProcessInstances与Tasks会分发本事件。

​​org.flowable…FlowableEntityEvent​​

JOB_EXECUTION_SUCCESS

作业已经成功执行。该作业包含在本事件里。

​​org.flowable…FlowableEntityEvent​​

JOB_EXECUTION_FAILURE

作业执行失败。该作业与异常包含在本事件里。

​​org.flowable…FlowableEntityEvent​​​ 及 ​​org.flowable…FlowableExceptionEvent​​

JOB_RETRIES_DECREMENTED

作业重试次数已经由于执行失败而减少。该作业包含在本事件里。

​​org.flowable…FlowableEntityEvent​​

TIMER_SCHEDULED

已创建一个定时作业，并预计在未来时间点执行。

​​org.flowable…FlowableEntityEvent​​

TIMER_FIRED

定时器已经触发。

​​org.flowable…FlowableEntityEvent​​

JOB_CANCELED

作业已经取消。该作业包含在本事件里。作业会由于API调用取消，任务完成导致关联的边界定时器取消，也会由于新流程定义的部署而取消。

​​org.flowable…FlowableEntityEvent​​

ACTIVITY_STARTED

节点开始执行

​​org.flowable…FlowableActivityEvent​​

ACTIVITY_COMPLETED

节点成功完成

​​org.flowable…FlowableActivityEvent​​

ACTIVITY_CANCELLED

节点将要取消。节点的取消有三个原因（MessageEventSubscriptionEntity, SignalEventSubscriptionEntity, TimerEntity）。

​​org.flowable…FlowableActivityCancelledEvent​​

ACTIVITY_SIGNALED

节点收到了一个信号

​​org.flowable…FlowableSignalEvent​​

ACTIVITY_MESSAGE_RECEIVED

节点收到了一个消息。事件在节点接收消息前分发。节点接收消息后，会为该节点分发 ​​ACTIVITY_SIGNAL​​​ 或 ​​ACTIVITY_STARTED​​ 事件，取决于其类型（边界事件，或子流程启动事件）。

​​org.flowable…FlowableMessageEvent​​

ACTIVITY_MESSAGE_WAITING

一个节点已经创建了一个消息事件订阅，并正在等待接收消息。

​​org.flowable…FlowableMessageEvent​​

ACTIVITY_MESSAGE_CANCELLED

一个节点已经取消了一个消息事件订阅，因此接收这个消息不会再触发该节点。

​​org.flowable…FlowableMessageEvent​​

ACTIVITY_ERROR_RECEIVED

节点收到了错误事件。在节点实际处理错误前分发。该事件的​​activityId​​​为处理错误的节点。如果错误成功传递，后续会为节点发送 ​​ACTIVITY_SIGNALLED​​​ 或 ​​ACTIVITY_COMPLETE​​ 消息。

​​org.flowable…FlowableErrorEvent​​

UNCAUGHT_BPMN_ERROR

抛出了未捕获的BPMN错误。流程没有该错误的处理器。该事件的​​activityId​​为空。

​​org.flowable…FlowableErrorEvent​​

ACTIVITY_COMPENSATE

节点将要被补偿(compensate)。该事件包含将要执行补偿的节点id。

​​org.flowable…FlowableActivityEvent​​

MULTI_INSTANCE_ACTIVITY_STARTED

多实例节点开始执行

​​org.flowable…FlowableMultiInstanceActivityEvent​​

MULTI_INSTANCE_ACTIVITY_COMPLETED

多实例节点成功完成

​​org.flowable…FlowableMultiInstanceActivityEvent​​

MULTI_INSTANCE_ACTIVITY_CANCELLED

多实例节点将要取消。多实例节点的取消有三个原因（MessageEventSubscriptionEntity, SignalEventSubscriptionEntity, TimerEntity）。

​​org.flowable…FlowableMultiInstanceActivityCancelledEvent​​

VARIABLE_CREATED

流程变量已经创建。本事件包含变量名、取值，及关联的执行和任务（若有）。

​​org.flowable…FlowableVariableEvent​​

VARIABLE_UPDATED

变量已经更新。本事件包含变量名、取值，及关联的执行和任务（若有）。

​​org.flowable…FlowableVariableEvent​​

VARIABLE_DELETED

变量已经删除。本事件包含变量名、最后取值，及关联的执行和任务（若有）。

​​org.flowable…FlowableVariableEvent​​

TASK_ASSIGNED

任务已经分派给了用户。该任务包含在本事件里。

​​org.flowable…FlowableEntityEvent​​

TASK_CREATED

任务已经创建。本事件在 ​​ENTITY_CREATE​​ 事件之后分发。若该任务是流程的一部分，本事件会在任务监听器执行前触发。

​​org.flowable…FlowableEntityEvent​​

TASK_COMPLETED

任务已经完成。本事件在 ​​ENTITY_DELETE​​​ 事件前分发。若该任务是流程的一部分，本事件会在流程前进之前触发，并且会跟随一个 ​​ACTIVITY_COMPLETE​​ 事件，指向代表该任务的节点。

​​org.flowable…FlowableEntityEvent​​

PROCESS_CREATED

流程实例已经创建。已经设置所有的基础参数，但还未设置变量。

​​org.flowable…FlowableEntityEvent​​

PROCESS_STARTED

流程实例已经启动。在启动之前创建的流程时分发。PROCESS_STARTED事件在相关的ENTITY_INITIALIZED事件，以及设置变量之后分发。

​​org.flowable…FlowableEntityEvent​​

PROCESS_COMPLETED

流程实例已经完成。在最后一个节点的 ​​ACTIVITY_COMPLETED ​​ 事件后分发。当流程实例没有任何路径可以继续时，流程结束。

​​org.flowable…FlowableEntityEvent​​

PROCESS_COMPLETED_WITH_TERMINATE_END_EVENT

流程已经到达终止结束事件(terminate end event)并结束。

​​org.flowable…FlowableProcessTerminatedEvent​​

PROCESS_CANCELLED

流程已经被取消。在流程实例从运行时中删除前分发。流程实例由API调用​​RuntimeService.deleteProcessInstance​​取消。

​​org.flowable…FlowableCancelledEvent​​

MEMBERSHIP_CREATED

用户已经加入组。本事件包含了相关的用户和组的id。

​​org.flowable…FlowableMembershipEvent​​

MEMBERSHIP_DELETED

用户已经从组中移出。本事件包含了相关的用户和组的id。

​​org.flowable…FlowableMembershipEvent​​

MEMBERSHIPS_DELETED

组的所有用户将被移出。本事件在用户移出前抛出，因此关联关系仍然可以访问。因为性能原因，不会再为每个被移出的用户抛出 ​​MEMBERSHIP_DELETED​​ 事件。

​​org.flowable…FlowableMembershipEvent​​

引擎中所有的 ​​ENTITY_\*​​ 事件都与实体关联。下表列出每个实体分发的实体事件：

  • ​​ENTITY_CREATED, ENTITY_INITIALIZED, ENTITY_DELETED​​: 附件(Attachment)，备注(Comment)，部署(Deployment)，执行(Execution)，组(Group)，身份关联(IdentityLink)，作业(Job)，模型(Model)，流程定义(ProcessDefinition)，流程实例(ProcessInstance)，任务(Task)，用户(User)。
  • ​​ENTITY_UPDATED​​: 附件，部署，执行，组，身份关联，作业，模型，流程定义，流程实例，任务，用户。
  • ​​ENTITY_SUSPENDED, ENTITY_ACTIVATED​​: 流程定义，流程实例/执行，任务。

附加信息

监听器只会响应其所在引擎分发的事件。因此如果在同一个数据库上运行不同的引擎，则只有该监听器注册的引擎生成的事件，才会分发给该监听器。其他引擎生成的事件不会分发给这个监听器，而不论这些引擎是否运行在同一个JVM下。

某些事件类型（与实体相关）暴露了目标实体。按照事件类型的不同，有些实体不能被更新（如实体删除事件中的实体）。如果可能的话，请使用事件暴露的​​EngineServices​​来安全地操作引擎。即使这样，更新、操作事件中暴露的实体仍然需要小心。

历史不会分发实体事件，因为它们都有对应的运行时实体分发事件。