camunda之-bpmn-消息事件（Message Events）

消息事件（Message Event）：

消息事件是一个引用了被命名的消息的事件

一个消息有一个名称和对应的消息负载

与信号不一样，消息事件始终指向单一的接收人

消息支持表达式,例如：<message id="messageId" name="name-${execution.processBusinessKey}" />这样就会动态的从流程参数中去获取到对应的值，并解析消息名称

消息开始事件名称不支持表达式，但是子流程的消息开始事件是支持表达式的

一、消息的API（Message Api）：

1.作为一个内嵌的流程引擎（Camunda engine），camunda不关心消息接收的部分。消息接收部分依赖于流程引擎所在的环境，并且需要平台特殊活动，例如：连接到JMS的队列/主题（Topic），或者一个web服务，或者一个rest请求，所以接收消息是用户需要去实现的部分即：用户自己实现从哪里接收消息，mq或者web服务或者rest接口。接到消息后，你可以选择关联到触发一个新的流程实例，或者触发一个等待的执行（execution）
2.使用运行时服务（Runtime Service’s ）关联消息和流程实例的方法：
- 流程引擎（Camunda engine）提供了一个基本的关联消息和流程实例的机制，这会通知（signal）一个等待特殊消息的执行（execution，即：消息中间事件），或者用匹配的消息开始事件实例化一个流程，RuntimeService提供了流式消息管理API
3.关联消息的结果是一个MessageCorrelationResult对象，不管是一个execution或者是一个processDefinition。如果是一个execution，则消息关联的是一个捕获消息中间事件（intermediate message catch event），如果是一个processDefinition，则消息关联的是一个消息开始事件。如果是execution，则可以通过result.getExecution()，获取Execution，如果是processDefinition则可以通过result.getProcessInstance()来获取ProcessInstance。
4.你可以通过messageName和businessKey来直接触发关联，也可以明确的查询出这个subscription（subscription：大意是消息事件创建的一个event subscription）来进行触发

// 通过messageName和businessKey来直接触发关联（开始一个流程）
MessageCorrelationResult result = runtimeService.createMessageCorrelation("messageName")
  .processInstanceBusinessKey("AB-123")
  .setVariable("payment_type", "creditCard")
  .correlateWithResult();
ProcessInstance pi = runtimeService.startProcessInstanceByKey("processWaitingInReceiveTask");
// 注释：messageName标识是定义在bpmn流程图的xml文件中的name属性中的
// 关联成功后只会返回Process Definition或者Execution (Process Instance)中的一个

//明确的查询出这个subscription（subscription：大意是消息事件创建的一个event subscription，即：触发一个消息中间事件）来进行触发
EventSubscription subscription = runtimeService.createEventSubscriptionQuery()
  .processInstanceId(pi.getId())
  .eventType("message")
  .singleResult();
runtimeService.messageEventReceived(subscription.getEventName(), subscription.getExecutionId());

5.使用一个messageName关联一个消息到多个匹配的executions，触发消息中间事件，或者实例化多个流程实例（批量操作）：

List<MessageCorrelationResult> results = runtimeService
  .createMessageCorrelation("aMessageName")
  .correlateAllWithResult();

6.在发起一个流程时，还可以获取到流程参数，通过一个布尔参数shouldDeserializeValues指定是否获取

MessageCorrelationResultWithVariables result = runtimeService
  .createMessageCorrelation("aMessageName")
  .setVariable("name", "value")
  .correlateWithResultAndVariables(shouldDeserializeValues);
//流程参数
VariableMap processVariables = result.getVariables();

7.还提供了通过本地执行参数（local execution variables）关联消息的能力,所谓local execution variables是指的当前作用域，我的理解是当前流程实例，例如当前在子流程里，就使用的子流程的变量，不会涉及到父流程的变量

List<MessageCorrelationResult> results = runtimeService
  .createMessageCorrelation("aMessageName")
  .localVariableEquals("localVarName", "localVarValue"))
  .correlateAllWithResult();

8.显示的触发一个消息（Explicitly Triggering a Message）

//触发一个消息开始事件
ProcessInstance startedProcessInstance = runtimeService
  .createMessageCorrelation("messageName")
  .processInstanceBusinessKey("businessKey")
  .setVariable("name", "value")
  .correlateStartMessage();
// or
MessageCorrelationResultWithVariables result = runtimeService
  .createMessageCorrelation("aMessageName")
  .processInstanceBusinessKey("businessKey")
  .startMessageOnly()
  .setVariable("name", "value")
  .correlateWithResultAndVariables(shouldDeserializeValues);
ProcessInstance startedProcessInstance = result.getProcessInstance();
VariableMap processVariables = result.getVariables();
//or
ProcessInstance startProcessInstanceByMessage(String messageName);
ProcessInstance startProcessInstanceByMessage(String messageName, Map<String, Object> processVariables);
ProcessInstance startProcessInstanceByMessage(String messageName, String businessKey, Map<String, Object> processVariables);
//触发消息中间事件
void messageEventReceived(String messageName, String executionId);
void messageEventReceived(String messageName, String executionId, HashMap<String, Object> processVariables);

9.查询消息事件订阅（Querying for Message Event Subscriptions：在进行中的消息事件的订阅，在ACT_RU_EVENT_SUBSCR表中）：
- 这个查询支持消息开始事件和消息中间事件
- 如果是消息开始事件，这个消息事件的订阅与一个特殊的流程定义，这个消息订阅可以用ProcessDefinitionQuery查询

//消息开始事件，查询流程定义信息
Execution execution = runtimeService.createExecutionQuery()
  .messageEventSubscriptionName("paymentReceived")
  .processVariableValueEquals("orderId", message.getOrderId())
  .singleResult();

- 这个查询只会返回null或者一个流程定义，如果流程定义发布了新的版本，会返回最新版本的流程定义
- 如果是消息中间事件，会返回一个特定的execution，这个消息订阅可以用ExecutionQuery查询

Execution execution = runtimeService.createExecutionQuery()
  .messageEventSubscriptionName("paymentReceived")
  .processVariableValueEquals("orderId", message.getOrderId())
  .singleResult();

二、消息开始事件（Message Start Event）：

消息开始事件可以用作，通过一个被命名的消息来开始一个流程实例。这允许我们在一堆的开始事件中选择正确的开始事件发起流程
当我们部署一个流程定义，且这个流程定义有一个或多个消息开始事件时，我们要注意以下几方面：
    1.在同一个流程定义中，不允许存在多个name相同的消息开始事件（例如：离职流程的流程定义中，不允许存在相同name的消息开始事件）
    2.在所有的部署的流程定义中，消息开始事件的name也必须是唯一（例如：离职流程和转正流程中，不允许存在相同name的消息开始事件）
    3.根据部署的最新版本的流程定义，之前版本的消息订阅（部署成功的消息订阅，即：老版本的流程定义中的消息开始事件会被取消，不会跟新版本并行监听消息来发起流程）将会被取消掉，新版本中没有出现的消息事件也会被取消
可以用RuntimeService的下列方法，通过触发消息开始事件来开始一个流程：

ProcessInstance startProcessInstanceByMessage(String messageName);
ProcessInstance startProcessInstanceByMessage(String messageName, Map<String, Object> processVariables);
ProcessInstance startProcessInstanceByMessage(String messageName, String businessKey, Map<String, Object> processVariables);

注释：
     1.messageName是由bpmn的xml文件中的messageEventDefinition元素的messageRef属性引用的消息元素的name属性中给出的名称
     2.在启动流程实例时，需要注意一下几个问题:
         - 消息开始事件只支持最外层的流程，不支持子流程，子流程可以用空开始事件
         - 如果流程定义有多个消息开始事件，runtimeService.startProcessInstanceByMessage(...)会选择一个合适的消息开始事件（根据messageName来确定正常的消息开始事件）
         - 如果流程有多个消息开始事件和一个空开始事件，runtimeService.startProcessInstanceByKey(...)和runtimeService.startProcessInstanceById(...)会用空开始事件开始一个流程实例
         - 如果流程有多个消息开始事件，且没有空开始事件，则runtimeService.startProcessInstanceByKey(...)和runtimeService.startProcessInstanceById(...)会抛出异常
         - 如果流程只有一个消息开始事件， runtimeService.startProcessInstanceByKey(...)和runtimeService.startProcessInstanceById(...)会通过消息开始事件开始一个流程
         - 如果流程是被调用活动开始的，那么消息开始事件只在一下两种情况下支持：
             1. 除了消息开始事件之外，流程还有一个空开始事件
             2.流程只有一个消息开始事件

一个流程可以被多个不同的消息事件发起，这对于那些需要不同的方式发起流程，却最终会以统一的方式运行的流程非常有用

图1：多个消息开始事件发起流程图

三、消息中间捕获事件（Message Intermediate Catching Event）：

当一个流程到达消息中间捕获事件时，它会等待在这里，直到一个有正确name的消息到达，流程才会继续往下走

图2：消息中间事件和消息边界事件

四、消息边界事件（Message Boundary Event）：

边界事件是一个捕获事件，它是依赖一个活动（activity，见上图2的完成订单的活动），这意味着，当这个活动是在运行状态下，这个消息边界事件在监听着一个被命名的消息，当消息到达后，有两种情况，这两种情况取决于于边界事件的配置（中断消息边界事件和不中断消息边界事件）：
1.中断消息边界事件，以图2为例：当消息边界事件接收到消息被触发后，完成订单的活动（activity）被中断
2.不中断消息边界事件：以图3为例：当不中断消息边界事件接收到消息被触发后，完成订单的活动和处理订单取消的活动同时处于running状态

图3：不中断消息边界事件

五、消息中间抛出事件（Message Intermediate Throwing Event）：

消息中间抛出事件会向外部服务发送一个消息，消息中间抛出事件的这个行为跟Service Task类似

图4：消息中间抛出事件

六、消息结束事件（Message End Event）：

当流程执行到消息结束事件时，当前路径下的执行结束，并且会发送一条消息，这个发消息的行为跟Service Task类似

图5：消息结束事件