关于流程定义监听器的说明
- 事件监听器只能作为
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中的一个枚举值。
事件名称 | 说明 | 事件类 |
|---|---|---|
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来安全地操作引擎。即使这样，更新、操作事件中暴露的实体仍然需要小心。
历史不会分发实体事件，因为它们都有对应的运行时实体分发事件。
