Flowable 6.6.0 BPMN使用者指南-（2）配置 - 2.18.4 向流程定義增加偵聽器

《Flowable 6.6.0 BPMN使用者指南》

2. 配置

• 2.1 建立ProcessEngine
• 2.2 ProcessEngineConfiguration Bean
• 2.3 資料庫配置
• 2.4 JNDI資料來源配置
• 2.5 支援的資料庫
• 2.6 建立資料庫表
• 2.7 資料庫表名說明
• 2.8 資料庫升級
• 2.9 作業執行器
• 2.10 作業執行器啟用
• 2.11 郵件伺服器配置
• 2.12 歷史（History）配置
• 2.13 非同步歷史配置（Async history configuration）
• 2.14 在表示式和指令碼中暴露bean
• 2.15 部署快取配置
• 2.16 日誌
• 2.17 對映診斷上下文
• 2.18 事件處理器（Event handlers）
  • 2.18.1 事件偵聽器（event-listener）實現
  • 2.18.2 配置和設定
  • 2.18.3 執行時增加偵聽器
  • 2.18.4 向流程定義增加偵聽器
  • 2.18.5 通過API分發事件
  • 2.18.6 支援的事件型別
  • 2.18.7 附加說明

Flowable 6.6.0 使用者指南相關文件下載

《精編Flowable 6.6.0 應用程式指南中文PDF版》
《精編Flowable 6.6.0 表單使用者指南中文PDF版》

有關Flowable文件的其他資料，參見：

《Flowable文件大全》

2.18.4 向流程定義增加偵聽器

It’s possible to add listeners to a specific process-definition. The listeners will only be called for events related to the process definition and to all events related to process instances that are started with that specific process definition. The listener implementations can be defined using a fully qualified classname, an expression that resolves to a bean that implements the listener interface or can be configured to throw a message/signal/error BPMN event.

可以將偵聽器新增到特定的流程定義中。僅針對與流程定義相關的事件呼叫偵聽器，以及針對使用該特定流程定義啟動的流程例項相關的所有事件呼叫偵聽器。偵聽器實現可以使用完全限定的類名來定義，該類名是一個解析為實現偵聽器介面的bean的表示式。偵聽器實現也可以配置為丟擲訊息/訊號/錯誤（message/signal/error）BPMN事件。

2.18.4.1 執行使用者定義邏輯的偵聽器

The snippet below adds 2 listeners to a process-definition. The first listener will receive events of any type, with a listener implementation based on a fully-qualified class name. The second listener is only notified when a job is successfully executed or when it failed, using a listener that has been defined in the beans property of the process engine configuration.

下面的程式碼片段將2個偵聽器新增到流程定義中。第一個偵聽器將接收任何型別的事件，偵聽器實現基於完全限定（fully-qualified）的類名。第二個偵聽器僅在作業成功執行或失敗時通知，使用流程引擎配置的beans屬性中定義的偵聽器。

<process id="testEventListeners">
  <extensionElements>
    <flowable:eventListener class="org.flowable.engine.test.MyEventListener" />
    <flowable:eventListener delegateExpression="${testEventListener}" events="JOB_EXECUTION_SUCCESS,JOB_EXECUTION_FAILURE" />
  </extensionElements>

  ...

</process>

For events related to entities, it’s also possible to add listeners to a process-definition that get only notified when entity-events occur for a certain entity type. The snippet below shows how this can be achieved. It can be used along for ALL entity-events (first example) or for specific event types only (second example).

對於與實體相關的事件，也可以將偵聽器新增到流程定義中，該流程定義僅在特定實體型別（certain entity type）的實體事件（entity-event）發生時收到通知。下面的程式碼片段展示瞭如何實現這一點。它可以用於針對所有實體事件（第一個示例）或僅用於針對特定事件型別（第二個示例）。

<process id="testEventListeners">
  <extensionElements>
    <flowable:eventListener class="org.flowable.engine.test.MyEventListener" entityType="task" />
    <flowable:eventListener delegateExpression="${testEventListener}" events="ENTITY_CREATED" entityType="task" />
  </extensionElements>

  ...

</process>

Supported values for the entityType are: attachment, comment, execution, identity-link, job, process-instance, process-definition, task.

entityType支援的值包括：attachment, comment, execution, identity-link, job, process-instance, process-definition, task（附件、註釋、執行、身份連線、作業、流程例項、流程定義、任務）。

2.18.4.2 丟擲BPMN事件的偵聽器

Another way of handling events being dispatched is to throw a BPMN event. Please bear in mind that it only makes sense to throw BPMN-events with certain kinds of Flowable event types. For example, throwing a BPMN event when the process-instance is deleted will result in an error. The snippet below shows how to throw a signal inside process-instance, throw a signal to an external process (global), throw a message-event inside the process-instance and throw an error-event inside the process-instance. Instead of using the class or delegateExpression, the attribute throwEvent is used, along with an additional attribute, specific to the type of event being thrown.

另一種處理被分發事件的方法是丟擲一個BPMN事件。請記住，只有丟擲與特定型別的Flowable事件關聯的BPMN事件才有意義。例如，當流程例項被刪除時丟擲BPMN事件將導致錯誤。下面的程式碼片段顯示瞭如何在流程例項內部丟擲訊號（signal）、向外部流程（全域性）丟擲訊號（globalSignal）、在流程例項內部丟擲訊息（message）事件，以及在流程例項內部丟擲錯誤（error）事件。沒有使用類或delegateExpression，而是使用了與所引發事件型別相關的throwEvent屬性以及一個附加屬性（signalName）。

<process id="testEventListeners">
  <extensionElements>
    <flowable:eventListener throwEvent="signal" signalName="My signal" events="TASK_ASSIGNED" />
  </extensionElements>
</process>

<process id="testEventListeners">
  <extensionElements>
    <flowable:eventListener throwEvent="globalSignal" signalName="My signal" events="TASK_ASSIGNED" />
  </extensionElements>
</process>

<process id="testEventListeners">
  <extensionElements>
    <flowable:eventListener throwEvent="message" messageName="My message" events="TASK_ASSIGNED" />
  </extensionElements>
</process>

<process id="testEventListeners">
  <extensionElements>
    <flowable:eventListener throwEvent="error" errorCode="123" events="TASK_ASSIGNED" />
  </extensionElements>
</process>

If additional logic is needed to decide whether or not to throw the BPMN-event, it’s possible to extend the listener-classes provided by Flowable. By overriding the isValidEvent(FlowableEvent event) in your subclass, the BPMN-event throwing can be prevented. The classes involved are org.flowable.engine.test.api.event.SignalThrowingEventListenerTest, org.flowable.engine.impl.bpmn.helper.MessageThrowingEventListener and org.flowable.engine.impl.bpmn.helper.ErrorThrowingEventListener.

如果需要額外的邏輯來決定是否丟擲BPMN事件，那麼可以擴充套件Flowable提供的偵聽器類。通過在子類中重寫isValidEvent（FlowableEvent事件），可以阻止丟擲BPMN事件。涉及的類有org.flowable.engine.test.api.event.SignalThrowingEventListenerTest，org.flowable.engine.impl.bpmn.helper.MessageThrowingEventListener和org.flowable.engine.impl.bpmn.helper.ErrorthrowingVentListener。

2.18.4.3 關於流程定義偵聽器的說明

• Event-listeners can only be declared on the process element, as a child-element of the extensionElements. Listeners cannot be defined on individual activities in the process.

• 事件偵聽器只能在process元素上宣告，並作為extensionElements的子元素。不能在流程中的單個活動上定義偵聽器。

• Expressions used in the delegateExpression do not have access to the execution-context, as other expressions (for example, in gateways) have. They can only reference beans defined in the beans property of the process engine configuration or when using Spring (and the beans property is absent) to any spring-bean that implements the listener interface.

• 與其他表示式（例如，在閘道器中）一樣，delegateExpression中使用的表示式不能訪問執行上下文（execution-context）。它們只能引用在流程引擎配置的beans屬性中定義的bean，或者當使用Spring（且沒有beans屬性）時，引用實現監聽器介面的Spring-bean。

• When using the class attribute of a listener, there will only be a single instance of that class created. Make sure the listener implementations do not rely on member-fields or ensure safe usage from multiple threads/contexts.

• 當使用監聽器的class屬性時，只會建立該類的一個例項。確保偵聽器實現不依賴成員欄位（member-field），或確保在多執行緒/上下文（multiple threads/contexts）時的安全使用。

• When an illegal event-type is used in the events attribute or illegal throwEvent value is used, an exception will be thrown when the process-definition is deployed (effectively failing the deployment). When an illegal value for class or delegateExecution is supplied (either a nonexistent class, a nonexistent bean reference or a delegate not implementing listener interface), an exception will be thrown when the process is started (or when the first valid event for that process-definition is dispatched to the listener). Make sure the referenced classes are on the classpath and that the expressions resolve to a valid instance.

• 如果events屬性中使用了非法事件型別，或使用了非法throwEvent值，在部署流程定義時將引發異常（實際上導致部署失敗）。如果為class或delegateExecution提供了非法值（不存在的類、不存在的bean引用或未實現偵聽器介面的委託（delegate）），在流程啟動時（或當該流程定義的第一個有效事件被分發到偵聽器時）將引發異常。確保引用的類位於類路徑（classpath）上，並且表示式解析為有效例項。