Package org.camunda.bpm.engine.runtime

Interface MessageCorrelationBuilder

  • All Known Implementing Classes:
    MessageCorrelationBuilderImpl
    public interface MessageCorrelationBuilder

    A fluent builder for defining message correlation

    Author:
    Daniel Meyer, Christopher Zell

    • Method Detail

      • processInstanceBusinessKey

        MessageCorrelationBuilder processInstanceBusinessKey​(String businessKey)

        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.

        Parameters:
        businessKey - the businessKey to correlate on.
        Returns:
        the builder

      • processInstanceVariableEquals

        MessageCorrelationBuilder processInstanceVariableEquals​(String variableName,
                                                        Object variableValue)

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

        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

        MessageCorrelationBuilder processInstanceVariablesEqual​(Map<String,​Object> variables)

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

        Parameters:
        variables - the variables of the process instance to correlate on.
        Returns:
        the builder

      • localVariableEquals

        MessageCorrelationBuilder localVariableEquals​(String variableName,
                                              Object variableValue)

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

        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

        MessageCorrelationBuilder localVariablesEqual​(Map<String,​Object> variables)

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

        Parameters:
        variables - the local variables of the execution to correlate on.
        Returns:
        the builder

      • processInstanceId

        MessageCorrelationBuilder processInstanceId​(String id)

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

        Parameters:
        id - the id of the process instance to correlate on.
        Returns:
        the builder

      • processDefinitionId

        MessageCorrelationBuilder processDefinitionId​(String processDefinitionId)

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

        Parameters:
        processDefinitionId - the id of the process definition to correlate on.
        Returns:
        the builder

      • setVariable

        MessageCorrelationBuilder setVariable​(String variableName,
                                      Object variableValue)

        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.

        Parameters:
        variableName - the name of the variable to set
        variableValue - the value of the variable to set
        Returns:
        the builder

      • setVariableLocal

        MessageCorrelationBuilder setVariableLocal​(String variableName,
                                           Object variableValue)

        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.

        Parameters:
        variableName - the name of the variable to set
        variableValue - the value of the variable to set
        Returns:
        the builder

      • setVariables

        MessageCorrelationBuilder setVariables​(Map<String,​Object> variables)

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

        Parameters:
        variables - the map of variables
        Returns:
        the builder

      • setVariablesLocal

        MessageCorrelationBuilder setVariablesLocal​(Map<String,​Object> variables)

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

        Parameters:
        variables - the map of local variables
        Returns:
        the builder

      • startMessageOnly

        MessageCorrelationBuilder startMessageOnly()
        Specify that only start message can be correlated.
        Returns:
        the builder

      • correlate

        void correlate()
        Executes the message correlation.

      • correlateWithResultAndVariables

        MessageCorrelationResultWithVariables correlateWithResultAndVariables​(boolean deserializeValues)
        Executes the message correlation. If you do not need access to the process variables, use correlateWithResult() to avoid unnecessary variable access.
        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

        void correlateExclusively()

        Behaves like 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.

      • correlateAll

        void correlateAll()
        Executes the message correlation for multiple messages.

      • correlateAllWithResult

        List<MessageCorrelationResult> correlateAllWithResult()
        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 tenantId(String) or withoutTenantId().

        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.
        Throws:
        AuthorizationException -
      • if at least one execution is matched and the user has no Permissions.UPDATE permission on Resources.PROCESS_INSTANCE or no Permissions.UPDATE_INSTANCE permission on Resources.PROCESS_DEFINITION.
      • if one process definition is matched and the user has no Permissions.CREATE permission on Resources.PROCESS_INSTANCE and no Permissions.CREATE_INSTANCE permission on Resources.PROCESS_DEFINITION.
        • Since:
        7.6

      • correlateAllWithResultAndVariables

        List<MessageCorrelationResultWithVariables> correlateAllWithResultAndVariables​(boolean deserializeValues)
        Executes the message correlation. If you do not need access to the process variables, use correlateAllWithResult() to avoid unnecessary variable access.
        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.