Package org.camunda.bpm.engine.impl

Class MessageCorrelationBuilderImpl

java.lang.Object
org.camunda.bpm.engine.impl.MessageCorrelationBuilderImpl
All Implemented Interfaces:
MessageCorrelationBuilder
public class MessageCorrelationBuilderImpl extends Object implements MessageCorrelationBuilder
Author:
Daniel Meyer, Christopher Zell

  • Field Details

    • commandExecutor

      protected CommandExecutor commandExecutor

    • commandContext

      protected CommandContext commandContext

    • isExclusiveCorrelation

      protected boolean isExclusiveCorrelation

    • messageName

      protected String messageName

    • businessKey

      protected String businessKey

    • processInstanceId

      protected String processInstanceId

    • processDefinitionId

      protected String processDefinitionId

    • correlationProcessInstanceVariables

      protected VariableMap correlationProcessInstanceVariables

    • correlationLocalVariables

      protected VariableMap correlationLocalVariables

    • payloadProcessInstanceVariables

      protected VariableMap payloadProcessInstanceVariables

    • payloadProcessInstanceVariablesLocal

      protected VariableMap payloadProcessInstanceVariablesLocal

    • payloadProcessInstanceVariablesToTriggeredScope

      protected VariableMap payloadProcessInstanceVariablesToTriggeredScope

    • tenantId

      protected String tenantId

    • isTenantIdSet

      protected boolean isTenantIdSet

    • startMessagesOnly

      protected boolean startMessagesOnly

    • executionsOnly

      protected boolean executionsOnly

  • Constructor Details

    • MessageCorrelationBuilderImpl

      public MessageCorrelationBuilderImpl(CommandExecutor commandExecutor, String messageName)

    • MessageCorrelationBuilderImpl

      public MessageCorrelationBuilderImpl(CommandContext commandContext, String messageName)

  • Method Details

    • processInstanceBusinessKey

      public MessageCorrelationBuilder processInstanceBusinessKey(String businessKey)
      Description copied from interface: MessageCorrelationBuilder

      Correlate the message such that the process instance has a business key with the given name. If the message is correlated to a message start event then the given business key is set on the created process instance.

      Specified by:
      processInstanceBusinessKey in interface MessageCorrelationBuilder
      Parameters:
      businessKey - the businessKey to correlate on.
      Returns:
      the builder

    • processInstanceVariableEquals

      public MessageCorrelationBuilder processInstanceVariableEquals(String variableName, Object variableValue)
      Description copied from interface: MessageCorrelationBuilder

      Correlate the message such that the process instance has a variable with the given name and value.

      Specified by:
      processInstanceVariableEquals in interface MessageCorrelationBuilder
      Parameters:
      variableName - the name of the process instance variable to correlate on.
      variableValue - the value of the process instance variable to correlate on.
      Returns:
      the builder

    • processInstanceVariablesEqual

      public MessageCorrelationBuilder processInstanceVariablesEqual(Map<String,Object> variables)
      Description copied from interface: MessageCorrelationBuilder

      Correlate the message such that the process instance has the given variables.

      Specified by:
      processInstanceVariablesEqual in interface MessageCorrelationBuilder
      Parameters:
      variables - the variables of the process instance to correlate on.
      Returns:
      the builder

    • localVariableEquals

      public MessageCorrelationBuilder localVariableEquals(String variableName, Object variableValue)
      Description copied from interface: MessageCorrelationBuilder

      Correlate the message such that the execution has a local variable with the given name and value.

      Specified by:
      localVariableEquals in interface MessageCorrelationBuilder
      Parameters:
      variableName - the name of the local variable to correlate on.
      variableValue - the value of the local variable to correlate on.
      Returns:
      the builder

    • localVariablesEqual

      public MessageCorrelationBuilder localVariablesEqual(Map<String,Object> variables)
      Description copied from interface: MessageCorrelationBuilder

      Correlate the message such that the execution has the given variables as local variables.

      Specified by:
      localVariablesEqual in interface MessageCorrelationBuilder
      Parameters:
      variables - the local variables of the execution to correlate on.
      Returns:
      the builder

    • ensureCorrelationProcessInstanceVariablesInitialized

      protected void ensureCorrelationProcessInstanceVariablesInitialized()

    • ensureCorrelationLocalVariablesInitialized

      protected void ensureCorrelationLocalVariablesInitialized()

    • processInstanceId

      public MessageCorrelationBuilder processInstanceId(String id)
      Description copied from interface: MessageCorrelationBuilder

      Correlate the message such that a process instance with the given id is selected.

      Specified by:
      processInstanceId in interface MessageCorrelationBuilder
      Parameters:
      id - the id of the process instance to correlate on.
      Returns:
      the builder

    • processDefinitionId

      public MessageCorrelationBuilder processDefinitionId(String processDefinitionId)
      Description copied from interface: MessageCorrelationBuilder

      Correlate the message such that a process definition with the given id is selected. Is only supported for MessageCorrelationBuilder.correlateStartMessage() or MessageCorrelationBuilder.startMessageOnly() flag.

      Specified by:
      processDefinitionId in interface MessageCorrelationBuilder
      Parameters:
      processDefinitionId - the id of the process definition to correlate on.
      Returns:
      the builder

    • setVariable

      public MessageCorrelationBuilder setVariable(String variableName, Object variableValue)
      Description copied from interface: MessageCorrelationBuilder

      Pass a variable to the execution waiting on the message. Use this method for passing the message's payload.

      Invoking this method multiple times allows passing multiple variables.

      Specified by:
      setVariable in interface MessageCorrelationBuilder
      Parameters:
      variableName - the name of the variable to set
      variableValue - the value of the variable to set
      Returns:
      the builder

    • setVariableLocal

      public MessageCorrelationBuilder setVariableLocal(String variableName, Object variableValue)
      Description copied from interface: MessageCorrelationBuilder

      Pass a local variable to the execution waiting on the message. Use this method for passing the message's payload.

      Invoking this method multiple times allows passing multiple variables.

      Specified by:
      setVariableLocal in interface MessageCorrelationBuilder
      Parameters:
      variableName - the name of the variable to set
      variableValue - the value of the variable to set
      Returns:
      the builder

    • setVariableToTriggeredScope

      public MessageCorrelationBuilder setVariableToTriggeredScope(String variableName, Object variableValue)
      Description copied from interface: MessageCorrelationBuilder

      Pass a variable to the new scope triggered by message correlation. Use this method for passing the message's payload.

      Invoking this method multiple times allows passing multiple variables.

      Specified by:
      setVariableToTriggeredScope in interface MessageCorrelationBuilder
      Parameters:
      variableName - the name of the variable to set
      variableValue - the value of the variable to set
      Returns:
      the builder

    • setVariables

      public MessageCorrelationBuilder setVariables(Map<String,Object> variables)
      Description copied from interface: MessageCorrelationBuilder

      Pass a map of variables to the execution waiting on the message. Use this method for passing the message's payload

      Specified by:
      setVariables in interface MessageCorrelationBuilder
      Parameters:
      variables - the map of variables
      Returns:
      the builder

    • setVariablesLocal

      public MessageCorrelationBuilder setVariablesLocal(Map<String,Object> variables)
      Description copied from interface: MessageCorrelationBuilder

      Pass a map of local variables to the execution waiting on the message. Use this method for passing the message's payload

      Specified by:
      setVariablesLocal in interface MessageCorrelationBuilder
      Parameters:
      variables - the map of local variables
      Returns:
      the builder

    • setVariablesToTriggeredScope

      public MessageCorrelationBuilder setVariablesToTriggeredScope(Map<String,Object> variables)
      Description copied from interface: MessageCorrelationBuilder

      Pass a map of variables to the new scope triggered by message correlation. Use this method for passing the message's payload.

      Specified by:
      setVariablesToTriggeredScope in interface MessageCorrelationBuilder
      Parameters:
      variables - the map of variables
      Returns:
      the builder

    • ensurePayloadProcessInstanceVariablesInitialized

      protected void ensurePayloadProcessInstanceVariablesInitialized()

    • ensurePayloadProcessInstanceVariablesLocalInitialized

      protected void ensurePayloadProcessInstanceVariablesLocalInitialized()

    • ensurePayloadProcessInstanceVariablesToTriggeredScopeInitialized

      protected void ensurePayloadProcessInstanceVariablesToTriggeredScopeInitialized()

    • tenantId

      public MessageCorrelationBuilder tenantId(String tenantId)
      Description copied from interface: MessageCorrelationBuilder
      Specify a tenant to deliver the message to. The message can only be received on executions or process definitions which belongs to the given tenant. Cannot be used in combination with MessageCorrelationBuilder.processInstanceId(String) or MessageCorrelationBuilder.processDefinitionId(String).
      Specified by:
      tenantId in interface MessageCorrelationBuilder
      Parameters:
      tenantId - the id of the tenant
      Returns:
      the builder

    • withoutTenantId

      public MessageCorrelationBuilder withoutTenantId()
      Description copied from interface: MessageCorrelationBuilder
      Specify that the message can only be received on executions or process definitions which belongs to no tenant. Cannot be used in combination with MessageCorrelationBuilder.processInstanceId(String) or MessageCorrelationBuilder.processDefinitionId(String).
      Specified by:
      withoutTenantId in interface MessageCorrelationBuilder
      Returns:
      the builder

    • startMessageOnly

      public MessageCorrelationBuilder startMessageOnly()
      Description copied from interface: MessageCorrelationBuilder
      Specify that only start message can be correlated.
      Specified by:
      startMessageOnly in interface MessageCorrelationBuilder
      Returns:
      the builder

    • executionsOnly

      public MessageCorrelationBuilder executionsOnly()

    • correlate

      public void correlate()
      Description copied from interface: MessageCorrelationBuilder
      Executes the message correlation.
      Specified by:
      correlate in interface MessageCorrelationBuilder

    • correlateWithResult

      public MessageCorrelationResult correlateWithResult()
      Description copied from interface: MessageCorrelationBuilder
      Executes the message correlation and returns a MessageCorrelationResult object.

      The call of this method will result in either:

      • Exactly one waiting execution is notified to continue. The notification is performed synchronously. The result contains the execution id.
      • Exactly one Process Instance is started in case the message name matches a message start event of a process. The instantiation is performed synchronously. The result contains the start event activity id and process definition.
      • MismatchingMessageCorrelationException is thrown. This means that either too many executions / process definitions match the correlation or that no execution and process definition matches the correlation.

      The result can be identified by calling the MessageCorrelationResult.getResultType().
      Specified by:
      correlateWithResult in interface MessageCorrelationBuilder
      Returns:
      The result of the message correlation. Result contains either the execution id or the start event activity id and the process definition.

    • correlateWithResultAndVariables

      public MessageCorrelationResultWithVariables correlateWithResultAndVariables(boolean deserializeValues)
      Description copied from interface: MessageCorrelationBuilder
      Executes the message correlation. If you do not need access to the process variables, use MessageCorrelationBuilder.correlateWithResult() to avoid unnecessary variable access.
      Specified by:
      correlateWithResultAndVariables in interface MessageCorrelationBuilder
      Parameters:
      deserializeValues - if false, returned SerializableValues will not be deserialized (unless they are passed into this method as a deserialized value or if the BPMN process triggers deserialization)
      Returns:
      The result of the message correlation. Result contains either the execution id or the start event activity id, the process definition, and the process variables.

    • correlateExclusively

      public void correlateExclusively()
      Description copied from interface: MessageCorrelationBuilder

      Behaves like MessageCorrelationBuilder.correlate(), however uses pessimistic locking for correlating a waiting execution, meaning that two threads correlating a message to the same execution in parallel do not end up continuing the process in parallel until the next wait state is reached

      CAUTION: Wherever there are pessimistic locks, there is a potential for deadlocks to occur. This can either happen when multiple messages are correlated in parallel, but also with other race conditions such as a message boundary event on a user task. The process engine is not able to detect such a potential. In consequence, the user of this API should investigate this potential in his/her use case and implement countermeasures if needed.

      A less error-prone alternative to this method is to set appropriate async boundaries in the process model such that parallel message correlation is solved by optimistic locking.

      Specified by:
      correlateExclusively in interface MessageCorrelationBuilder

    • correlateAll

      public void correlateAll()
      Description copied from interface: MessageCorrelationBuilder
      Executes the message correlation for multiple messages.
      Specified by:
      correlateAll in interface MessageCorrelationBuilder

    • correlateAllWithResult

      public List<MessageCorrelationResult> correlateAllWithResult()
      Description copied from interface: MessageCorrelationBuilder
      Executes the message correlation for multiple messages and returns a list of message correlation results.

      This will result in any number of the following:

      • Any number of waiting executions are notified to continue. The notification is performed synchronously. The result list contains the execution ids of the notified executions.
      • Any number of process instances are started which have a message start event that matches the message name. The instantiation is performed synchronously. The result list contains the start event activity ids and process definitions from all activities on that the messages was correlated to.

      Note that the message correlates to all tenants if no tenant is specified using MessageCorrelationBuilder.tenantId(String) or MessageCorrelationBuilder.withoutTenantId().

      Specified by:
      correlateAllWithResult in interface MessageCorrelationBuilder
      Returns:
      The result list of the message correlations. Each result contains either the execution id or the start event activity id and the process definition.

    • correlateAllWithResultAndVariables

      public List<MessageCorrelationResultWithVariables> correlateAllWithResultAndVariables(boolean deserializeValues)
      Description copied from interface: MessageCorrelationBuilder
      Executes the message correlation. If you do not need access to the process variables, use MessageCorrelationBuilder.correlateAllWithResult() to avoid unnecessary variable access.
      Specified by:
      correlateAllWithResultAndVariables in interface MessageCorrelationBuilder
      Parameters:
      deserializeValues - if false, returned SerializableValues will not be deserialized (unless they are passed into this method as a deserialized value or if the BPMN process triggers deserialization)
      Returns:
      The result list of the message correlations. Each result contains either the execution id or the start event activity id, the process definition, and the process variables.

    • correlateStartMessage

      public ProcessInstance correlateStartMessage()
      Description copied from interface: MessageCorrelationBuilder
      Executes the message correlation.

      This will result in either:

      • Exactly one Process Instance is started in case the message name matches a message start event of a process. The instantiation is performed synchronously.
      • MismatchingMessageCorrelationException is thrown. This means that either no process definition or more than one process definition matches the correlation.

      Specified by:
      correlateStartMessage in interface MessageCorrelationBuilder
      Returns:
      the newly created process instance

    • ensureProcessDefinitionIdNotSet

      protected void ensureProcessDefinitionIdNotSet()

    • ensureProcessInstanceAndTenantIdNotSet

      protected void ensureProcessInstanceAndTenantIdNotSet()

    • ensureCorrelationVariablesNotSet

      protected void ensureCorrelationVariablesNotSet()

    • ensureProcessDefinitionAndTenantIdNotSet

      protected void ensureProcessDefinitionAndTenantIdNotSet()

    • execute

      protected <T> T execute(Command<T> command)

    • getCommandExecutor

      public CommandExecutor getCommandExecutor()

    • getCommandContext

      public CommandContext getCommandContext()

    • getMessageName

      public String getMessageName()

    • getBusinessKey

      public String getBusinessKey()

    • getProcessInstanceId

      public String getProcessInstanceId()

    • getProcessDefinitionId

      public String getProcessDefinitionId()

    • getCorrelationProcessInstanceVariables

      public Map<String,Object> getCorrelationProcessInstanceVariables()

    • getCorrelationLocalVariables

      public Map<String,Object> getCorrelationLocalVariables()

    • getPayloadProcessInstanceVariables

      public Map<String,Object> getPayloadProcessInstanceVariables()

    • getPayloadProcessInstanceVariablesLocal

      public VariableMap getPayloadProcessInstanceVariablesLocal()

    • getPayloadProcessInstanceVariablesToTriggeredScope

      public VariableMap getPayloadProcessInstanceVariablesToTriggeredScope()

    • isExclusiveCorrelation

      public boolean isExclusiveCorrelation()

    • getTenantId

      public String getTenantId()

    • isTenantIdSet

      public boolean isTenantIdSet()

    • isExecutionsOnly

      public boolean isExecutionsOnly()