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

Method Summary

void	correlate() Executes the message correlation.
void	correlateAll() Executes the message correlation for multiple messages.
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
ProcessInstance	correlateStartMessage() Executes the message correlation.
MessageCorrelationBuilder	processDefinitionId(String processDefinitionId) Correlate the message such that a process definition with the given id is selected.
MessageCorrelationBuilder	processInstanceBusinessKey(String businessKey) Correlate the message such that the process instance has a business key with the given name.
MessageCorrelationBuilder	processInstanceId(String id) Correlate the message such that a process instance with the given id is selected.
MessageCorrelationBuilder	processInstanceVariableEquals(String variableName, Object variableValue) Correlate the message such that the process instance has a variable with the given name and value.
MessageCorrelationBuilder	processInstanceVariablesEqual(Map<String,Object> variables) Correlate the message such that the process instance has the given variables.
MessageCorrelationBuilder	setVariable(String variableName, Object variableValue) Pass a variable to the execution waiting on the message.
MessageCorrelationBuilder	setVariables(Map<String,Object> variables) Pass a map of variables to the execution waiting on the message.
MessageCorrelationBuilder	tenantId(String tenantId) Specify a tenant to deliver the message to.
MessageCorrelationBuilder	withoutTenantId() Specify that the message can only be received on executions or process definitions which belongs to no tenant.

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

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().

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

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

tenantId

MessageCorrelationBuilder tenantId(String tenantId)

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 processInstanceId(String) or processDefinitionId(String).

Parameters:

tenantId - the id of the tenant

Returns:

the builder

withoutTenantId

MessageCorrelationBuilder withoutTenantId()

Specify that the message can only be received on executions or process definitions which belongs to no tenant. Cannot be used in combination with processInstanceId(String) or processDefinitionId(String).

Returns:

the builder

correlate

void correlate()

Executes the message correlation.

This will result in either:

• Exactly one waiting execution is notified to continue. The notification is performed synchronously.
• 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 too many executions / process definitions match the correlation or that no execution and process definition matches the correlation.

Throws:

MismatchingMessageCorrelationException - if none or more than one execution or process definition is matched by the correlation

AuthorizationException -

if 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.

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.

This will result in any number of the following:

• Any number of waiting executions are notified to continue. The notification is performed synchronously.
• Any number of process instances are started which have a message start event that matches the message name. The instantiation is performed synchronously.

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

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.

correlateStartMessage

ProcessInstance correlateStartMessage()

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.

Returns:

the newly created process instance

Throws:

MismatchingMessageCorrelationException - if none or more than one process definition is matched by the correlation

AuthorizationException - 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.