События сигнала
События сигнала ссылаются на именованный сигнал. Сигнал это событие с глобальной областью видимости (широковещательная рассылка, broadcast): он доставляется всем активным обработчикам.
Ниже пример взаимодействия двух отдельных процессов через сигналы. Первый процесс запускается при обновлении или изменении страхового полиса. После того как сотрудник проверит изменения, генерируется событие сигнала о том, что полис изменён:
Этот сигнал могут перехватить все экземпляры процессов, которые на него подписаны. Ниже пример процесса, который подписывается на этот сигнал.
| Событие сигнала рассылается всем активным обработчикам. В примере выше событие получат все экземпляры процесса, перехватывающего сигнал. |
Определение события сигнала
Определение события сигнала объявляется элементом signalEventDefinition. Атрибут signalRef ссылается на элемент signal, объявленный как дочерний элемент корневого элемента definitions. Ниже фрагмент процесса, в котором промежуточные события генерируют и перехватывают сигнал. Элементы signalEventDefinition ссылаются на «глобальный» элемент сигнала.
<definitions>
<!-- объявление сигнала -->
<signal id="alertSignal" name="alert" />
<process id="catchSignal">
<intermediateThrowEvent id="throwSignalEvent" name="Alert">
<!-- signal event definition -->
<signalEventDefinition signalRef="alertSignal" />
</intermediateThrowEvent>
<!-- ... -->
<intermediateCatchEvent id="catchSignalEvent" name="On Alert">
<!-- signal event definition -->
<signalEventDefinition signalRef="alertSignal" />
</intermediateCatchEvent>
<!-- ... -->
</process>
</definitions>
| В отличие от других событий, например событий ошибки, сигнал при перехвате не поглощается. Если два активных граничных события сигнала перехватывают один и тот же сигнал, сработают оба, даже если они относятся к разным экземплярам процессов. |
Выражения
В имени сигнала в определении события сигнала можно использовать выражения. Имя вычисляется, когда процесс входит в область видимости сигнала. Например, выражение в имени вычисляется, когда экземпляр процесса доходит до промежуточного события-перехватчика сигнала.
Так имя сигнала можно формировать динамически из переменных процесса. Это пригодится, например, когда нужно прерывать параллельные ветки выполнения. Пример:
<signal id="alertSignal" name="alert-${execution.processBusinessKey}" />
API сигналов
Генерация сигналов
Сигнал генерирует экземпляр процесса через BPMN-конструкцию или приложение через Java API. Для программной генерации сигналов в RuntimeService есть fluent API:
// широковещательная рассылка сигнала
runtimeService
.createSignalEvent("signalName")
.setVariables(variables)
.send();
// доставка сигнала конкретному выполнению
runtimeService
.createSignalEvent("signalName")
.executionId(executionId)
.setVariables(variables)
.send();
Можно также вызвать один из методов RuntimeService:
RuntimeService.signalEventReceived(String signalName);
RuntimeService.signalEventReceived(String signalName, String executionId);
Если указан executionId, сигнал доставляется только этому выполнению. Иначе сигнал рассылается всем подписанным обработчикам (broadcast).
| Событие сигнала не коррелирует с конкретным экземпляром процесса, а рассылается всем экземплярам. Если сигнал нужно доставить только одному экземпляру процесса, не используйте BPMN-событие генерации сигнала. Вместо этого выполните корреляцию вручную через запросы и доставьте сигнал нужному выполнению программно. |
Перехват событий сигнала
Стартовое событие сигнала
Стартовое событие сигнала запускает экземпляр процесса именованным сигналом.
При развертывании определения процесса с одним или несколькими стартовыми событиями сигнала действуют правила:
-
Имя сигнала стартового события должно быть уникальным в пределах определения процесса: два стартовых события сигнала с одинаковым именем в одном определении недопустимы. Если несколько стартовых событий сигнала ссылаются на один сигнал или на сигналы с одинаковым именем, движок выбрасывает исключение при развертывании.
-
В отличие от стартовых событий сообщения, имя сигнала стартового события не обязано быть уникальным среди всех развернутых определений процессов.
-
Версионирование процессов: при развертывании новой версии определения процесса подписки на сигналы предыдущей версии отменяются. Это касается и событий сигнала, которых нет в новой версии.
Экземпляр процесса со стартовыми событиями сигнала запускается, когда генерируется сигнал с нужным именем. Сигнал может сгенерировать другой процесс (промежуточным или завершающим событием-генератором сигнала) или приложение методами RuntimeService:
void signalEventReceived(String signalName);
void signalEventReceived(String signalName, Map<String, Object> processVariables);
| Один сгенерированный сигнал может запустить несколько экземпляров процессов, если у нескольких определений процессов есть стартовое событие сигнала с одинаковым именем. |
В XML стартовое событие сигнала объявляется как обычное стартовое событие с дочерним элементом signalEventDefinition:
<startEvent id="signalStart" >
<signalEventDefinition signalRef="alertSignal" />
</startEvent>
Промежуточное событие-перехватчик сигнала
Когда токен доходит до промежуточного события-перехватчика сигнала, он ждёт, пока не придёт сигнал с нужным именем.
<intermediateCatchEvent id="signal">
<signalEventDefinition signalRef="newCustomerSignal" />
</intermediateCatchEvent>
Расширения OpenBPM Engine
Для промежуточного события-перехватчика сигнала поддерживаются следующие расширения:
Атрибуты |
Нет |
Элементы расширений |
|
Ограничения |
Нет |
Граничное событие сигнала
Когда выполнение доходит до активити, к которой прикреплено граничное событие сигнала, событие начинает перехватывать сигналы с нужным именем.
| В отличие от других событий, например граничного события ошибки, граничное событие сигнала перехватывает сигналы не только из области видимости своей активити. У события сигнала глобальная область видимости (broadcast): сигнал можно сгенерировать откуда угодно, даже из другого экземпляра процесса. |
<boundaryEvent id="boundary" attachedToRef="task" cancelActivity="true">
<signalEventDefinition signalRef="alertSignal"/>
</boundaryEvent>
Генерация событий сигнала
Промежуточное событие-генератор сигнала
Промежуточное событие-генератор сигнала генерирует заданный сигнал.
Сигнал рассылается всем активным обработчикам, то есть всем событиям-перехватчикам сигнала. Сигналы можно публиковать синхронно или асинхронно.
-
По умолчанию сигнал доставляется синхронно: экземпляр процесса, сгенерировавший сигнал, ждёт, пока сигнал будет доставлен всем перехватывающим экземплярам процессов. Перехватывающие экземпляры уведомляются в той же транзакции, что и генерирующий экземпляр. Поэтому если один из уведомлённых экземпляров завершится технической ошибкой (выбросит исключение), ошибкой завершатся все участвующие экземпляры.
-
Сигнал можно доставить и асинхронно. Тогда движок определяет, какие обработчики активны в момент, когда выполнение доходит до события-генератора сигнала. Для каждого активного обработчика сохраняется асинхронное уведомление, задание (job), которое затем выполняет исполнитель заданий (Job Executor).
Промежуточное событие сигнала определяется как промежуточное событие-генератор с элементом signalEventDefinition.
<intermediateThrowEvent id="signal">
<signalEventDefinition signalRef="newCustomerSignal" />
</intermediateThrowEvent>
Асинхронная генерация сигнала задаётся атрибутом camunda:async элемента signalEventDefinition:
<intermediateThrowEvent id="signal">
<signalEventDefinition signalRef="newCustomerSignal" camunda:async="true" />
</intermediateThrowEvent>
Завершающее событие сигнала
Завершающее событие сигнала генерирует заданный сигнал и завершает текущий путь выполнения. В остальном оно ведёт себя так же, как промежуточное событие-генератор сигнала.
<endEvent id="signal">
<signalEventDefinition signalRef="newCustomerSignal" />
</endEvent>
Передача переменных
Переменные процесса можно передать из экземпляра, генерирующего сигнал, во все экземпляры процессов, которые его перехватывают. Данные копируются в перехватывающий экземпляр, когда его запускает стартовое событие сигнала или перед выходом из состояния ожидания в промежуточном событии-перехватчике сигнала.
<signalEventDefinition signalRef="newCustomerSignal">
<extensionElements>
<camunda:in source="throwingVariableName" target="catchingVariableName" />
</extensionElements>
</signalEventDefinition>
Переменные, объявленные в элементах camunda:in, устанавливаются в самой верхней области видимости перехватывающего экземпляра процесса.
Можно также использовать выражения и изменять данные перед передачей в перехватывающие процессы.
<signalEventDefinition signalRef="newCustomerSignal">
<extensionElements>
<camunda:in sourceExpression="${X + 5}" target="Y" />
</extensionElements>
</signalEventDefinition>
Переменная процесса Y в перехватывающих экземплярах получит значение (X + 5), где X это переменная процесса в генерирующем экземпляре.
Можно также передать в перехватывающие процессы все переменные экземпляра, генерирующего сигнал.
<signalEventDefinition signalRef="newCustomerSignal">
<extensionElements>
<camunda:in variables="all" />
</extensionElements>
</signalEventDefinition>
С local="true" передаются только локальные переменные выполнения, на котором работает событие-генератор сигнала. Это переменные, которые можно объявить как входные параметры.
<signalEventDefinition signalRef="newCustomerSignal">
<extensionElements>
<camunda:in variables="all" local="true" />
</extensionElements>
</signalEventDefinition>
Варианты можно сочетать. Например, передать только локальные переменные, одну переменную верхнего уровня и выражение с этой же переменной.
<signalEventDefinition signalRef="newCustomerSignal">
<extensionElements>
<camunda:in variables="all" local="true" />
<camunda:in source="X" target="Y" />
<camunda:in sourceExpression="${X + 5}" target="Z" />
</extensionElements>
</signalEventDefinition>
Передача бизнес-ключа
Кроме переменных процесса, в перехватывающие экземпляры можно передать бизнес-ключ (business key). Это работает только для экземпляров процессов, которые запускаются стартовым событием сигнала.
<signalEventDefinition signalRef="newCustomerSignal">
<extensionElements>
<camunda:in businessKey="${execution.processBusinessKey}" />
</extensionElements>
</signalEventDefinition>
Элемент camunda:in для бизнес-ключа можно использовать вместе с элементами camunda:in для переменных процесса.
Документация создана на основе Camunda 7 Docs (Camunda, docs.camunda.org) и распространяется по лицензии Creative Commons Attribution-ShareAlike 3.0 Unported.