Class MessageCorrelationBuilderImpl
- All Implemented Interfaces:
MessageCorrelationBuilder
- Author:
- Daniel Meyer, Christopher Zell
-
Field Summary
Modifier and TypeFieldDescriptionprotected String
protected CommandContext
protected CommandExecutor
protected VariableMap
protected VariableMap
protected boolean
protected boolean
protected boolean
protected String
protected VariableMap
protected VariableMap
protected VariableMap
protected String
protected String
protected boolean
protected String
-
Constructor Summary
ConstructorDescriptionMessageCorrelationBuilderImpl
(CommandContext commandContext, String messageName) MessageCorrelationBuilderImpl
(CommandExecutor commandExecutor, String messageName) -
Method Summary
Modifier and TypeMethodDescriptionvoid
Executes the message correlation.void
Executes the message correlation for multiple messages.Executes the message correlation for multiple messages and returns a list of message correlation results.correlateAllWithResultAndVariables
(boolean deserializeValues) Executes the message correlation.void
Behaves likeMessageCorrelationBuilder.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 reachedExecutes the message correlation.Executes the message correlation and returns aMessageCorrelationResult
object.correlateWithResultAndVariables
(boolean deserializeValues) Executes the message correlation.protected void
protected void
protected void
protected void
protected void
protected void
protected void
protected void
protected void
protected <T> T
boolean
boolean
boolean
localVariableEquals
(String variableName, Object variableValue) Correlate the message such that the execution has a local variable with the given name and value.localVariablesEqual
(Map<String, Object> variables) Correlate the message such that the execution has the given variables as local variables.processDefinitionId
(String processDefinitionId) Correlate the message such that a process definition with the given id is selected.processInstanceBusinessKey
(String businessKey) Correlate the message such that the process instance has a business key with the given name.Correlate the message such that a process instance with the given id is selected.processInstanceVariableEquals
(String variableName, Object variableValue) Correlate the message such that the process instance has a variable with the given name and value.processInstanceVariablesEqual
(Map<String, Object> variables) Correlate the message such that the process instance has the given variables.setVariable
(String variableName, Object variableValue) Pass a variable to the execution waiting on the message.setVariableLocal
(String variableName, Object variableValue) Pass a local variable to the execution waiting on the message.setVariables
(Map<String, Object> variables) Pass a map of variables to the execution waiting on the message.setVariablesLocal
(Map<String, Object> variables) Pass a map of local variables to the execution waiting on the message.setVariablesToTriggeredScope
(Map<String, Object> variables) Pass a map of variables to the new scope triggered by message correlation.setVariableToTriggeredScope
(String variableName, Object variableValue) Pass a variable to the new scope triggered by message correlation.Specify that only start message can be correlated.Specify a tenant to deliver the message to.Specify that the message can only be received on executions or process definitions which belongs to no tenant.
-
Field Details
-
commandExecutor
-
commandContext
-
isExclusiveCorrelation
protected boolean isExclusiveCorrelation -
messageName
-
businessKey
-
processInstanceId
-
processDefinitionId
-
correlationProcessInstanceVariables
-
correlationLocalVariables
-
payloadProcessInstanceVariables
-
payloadProcessInstanceVariablesLocal
-
payloadProcessInstanceVariablesToTriggeredScope
-
tenantId
-
isTenantIdSet
protected boolean isTenantIdSet -
startMessagesOnly
protected boolean startMessagesOnly -
executionsOnly
protected boolean executionsOnly
-
-
Constructor Details
-
MessageCorrelationBuilderImpl
-
MessageCorrelationBuilderImpl
-
-
Method Details
-
processInstanceBusinessKey
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 interfaceMessageCorrelationBuilder
- 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 interfaceMessageCorrelationBuilder
- 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
Description copied from interface:MessageCorrelationBuilder
Correlate the message such that the process instance has the given variables.
- Specified by:
processInstanceVariablesEqual
in interfaceMessageCorrelationBuilder
- Parameters:
variables
- the variables of the process instance to correlate on.- Returns:
- the builder
-
localVariableEquals
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 interfaceMessageCorrelationBuilder
- 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
Description copied from interface:MessageCorrelationBuilder
Correlate the message such that the execution has the given variables as local variables.
- Specified by:
localVariablesEqual
in interfaceMessageCorrelationBuilder
- Parameters:
variables
- the local variables of the execution to correlate on.- Returns:
- the builder
-
ensureCorrelationProcessInstanceVariablesInitialized
protected void ensureCorrelationProcessInstanceVariablesInitialized() -
ensureCorrelationLocalVariablesInitialized
protected void ensureCorrelationLocalVariablesInitialized() -
processInstanceId
Description copied from interface:MessageCorrelationBuilder
Correlate the message such that a process instance with the given id is selected.
- Specified by:
processInstanceId
in interfaceMessageCorrelationBuilder
- Parameters:
id
- the id of the process instance to correlate on.- Returns:
- the builder
-
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()
orMessageCorrelationBuilder.startMessageOnly()
flag.- Specified by:
processDefinitionId
in interfaceMessageCorrelationBuilder
- Parameters:
processDefinitionId
- the id of the process definition to correlate on.- Returns:
- the builder
-
setVariable
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 interfaceMessageCorrelationBuilder
- Parameters:
variableName
- the name of the variable to setvariableValue
- the value of the variable to set- Returns:
- the builder
-
setVariableLocal
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 interfaceMessageCorrelationBuilder
- Parameters:
variableName
- the name of the variable to setvariableValue
- 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 interfaceMessageCorrelationBuilder
- Parameters:
variableName
- the name of the variable to setvariableValue
- the value of the variable to set- Returns:
- the builder
-
setVariables
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 interfaceMessageCorrelationBuilder
- Parameters:
variables
- the map of variables- Returns:
- the builder
-
setVariablesLocal
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 interfaceMessageCorrelationBuilder
- Parameters:
variables
- the map of local variables- Returns:
- the builder
-
setVariablesToTriggeredScope
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 interfaceMessageCorrelationBuilder
- Parameters:
variables
- the map of variables- Returns:
- the builder
-
ensurePayloadProcessInstanceVariablesInitialized
protected void ensurePayloadProcessInstanceVariablesInitialized() -
ensurePayloadProcessInstanceVariablesLocalInitialized
protected void ensurePayloadProcessInstanceVariablesLocalInitialized() -
ensurePayloadProcessInstanceVariablesToTriggeredScopeInitialized
protected void ensurePayloadProcessInstanceVariablesToTriggeredScopeInitialized() -
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 withMessageCorrelationBuilder.processInstanceId(String)
orMessageCorrelationBuilder.processDefinitionId(String)
.- Specified by:
tenantId
in interfaceMessageCorrelationBuilder
- Parameters:
tenantId
- the id of the tenant- Returns:
- the builder
-
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 withMessageCorrelationBuilder.processInstanceId(String)
orMessageCorrelationBuilder.processDefinitionId(String)
.- Specified by:
withoutTenantId
in interfaceMessageCorrelationBuilder
- Returns:
- the builder
-
startMessageOnly
Description copied from interface:MessageCorrelationBuilder
Specify that only start message can be correlated.- Specified by:
startMessageOnly
in interfaceMessageCorrelationBuilder
- Returns:
- the builder
-
executionsOnly
-
correlate
public void correlate()Description copied from interface:MessageCorrelationBuilder
Executes the message correlation.- Specified by:
correlate
in interfaceMessageCorrelationBuilder
-
correlateWithResult
Description copied from interface:MessageCorrelationBuilder
Executes the message correlation and returns aMessageCorrelationResult
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.
MessageCorrelationResult.getResultType()
.- Specified by:
correlateWithResult
in interfaceMessageCorrelationBuilder
- 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, useMessageCorrelationBuilder.correlateWithResult()
to avoid unnecessary variable access.- Specified by:
correlateWithResultAndVariables
in interfaceMessageCorrelationBuilder
- Parameters:
deserializeValues
- if false, returnedSerializableValue
s 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 reachedCAUTION: 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 interfaceMessageCorrelationBuilder
-
correlateAll
public void correlateAll()Description copied from interface:MessageCorrelationBuilder
Executes the message correlation for multiple messages.- Specified by:
correlateAll
in interfaceMessageCorrelationBuilder
-
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)
orMessageCorrelationBuilder.withoutTenantId()
.- Specified by:
correlateAllWithResult
in interfaceMessageCorrelationBuilder
- 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, useMessageCorrelationBuilder.correlateAllWithResult()
to avoid unnecessary variable access.- Specified by:
correlateAllWithResultAndVariables
in interfaceMessageCorrelationBuilder
- Parameters:
deserializeValues
- if false, returnedSerializableValue
s 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
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 interfaceMessageCorrelationBuilder
- Returns:
- the newly created process instance
-
ensureProcessDefinitionIdNotSet
protected void ensureProcessDefinitionIdNotSet() -
ensureProcessInstanceAndTenantIdNotSet
protected void ensureProcessInstanceAndTenantIdNotSet() -
ensureCorrelationVariablesNotSet
protected void ensureCorrelationVariablesNotSet() -
ensureProcessDefinitionAndTenantIdNotSet
protected void ensureProcessDefinitionAndTenantIdNotSet() -
execute
-
getCommandExecutor
-
getCommandContext
-
getMessageName
-
getBusinessKey
-
getProcessInstanceId
-
getProcessDefinitionId
-
getCorrelationProcessInstanceVariables
-
getCorrelationLocalVariables
-
getPayloadProcessInstanceVariables
-
getPayloadProcessInstanceVariablesLocal
-
getPayloadProcessInstanceVariablesToTriggeredScope
-
isExclusiveCorrelation
public boolean isExclusiveCorrelation() -
getTenantId
-
isTenantIdSet
public boolean isTenantIdSet() -
isExecutionsOnly
public boolean isExecutionsOnly()
-