org.camunda.bpm.engine.runtime

Interface ProcessInstanceModificationBuilder

All Superinterfaces:

InstantiationBuilder<ProcessInstanceModificationInstantiationBuilder>

All Known Subinterfaces:

ProcessInstanceModificationInstantiationBuilder

All Known Implementing Classes:

ProcessInstanceModificationBuilderImpl

public interface ProcessInstanceModificationBuilder
extends InstantiationBuilder<ProcessInstanceModificationInstantiationBuilder>

A fluent builder to specify a modification of process instance state in terms of cancellation of activity instances and instantiations of activities and sequence flows. Allows to specify an ordered set of instructions that are all executed within one transaction. Individual instructions are executed in the order of their specification.

Author:

Thorben Lindhauer

Method Summary

Modifier and Type	Method and Description
ProcessInstanceModificationBuilder	cancelActivityInstance(String activityInstanceId) Submits the instruction:
ProcessInstanceModificationBuilder	cancelAllForActivity(String activityId) Submits the instruction:
ProcessInstanceModificationBuilder	cancellationSourceExternal(boolean external) A canceled process instance receives a termination state to indicate the source of the cancellation call.
ProcessInstanceModificationBuilder	cancelTransitionInstance(String transitionInstanceId) Submits the instruction:
void	execute() Execute all instructions.
void	execute(boolean skipCustomListeners, boolean skipIoMappings)
Batch	executeAsync() Execute all instructions asynchronously.
Batch	executeAsync(boolean skipCustomListeners, boolean skipIoMappings)
ProcessInstanceModificationBuilder	setAnnotation(String annotation) Provides annotation for the current modification.
ProcessInstanceModificationInstantiationBuilder	startAfterActivity(String activityId, String ancestorActivityInstanceId) Submits an instruction that behaves like startTransition(String,String) and always instantiates the single outgoing sequence flow of the given activity.
ProcessInstanceModificationInstantiationBuilder	startBeforeActivity(String activityId, String ancestorActivityInstanceId) Submits the instruction:
ProcessInstanceModificationInstantiationBuilder	startTransition(String transitionId, String ancestorActivityInstanceId) Submits the instruction:

Methods inherited from interface org.camunda.bpm.engine.runtime.InstantiationBuilder

startAfterActivity, startBeforeActivity, startTransition

Method Detail

startBeforeActivity

ProcessInstanceModificationInstantiationBuilder startBeforeActivity(String activityId,
                                                                    String ancestorActivityInstanceId)

Submits the instruction:

Start before the specified activity. Instantiate the given activity as a descendant of the given ancestor activity instance.

In particular:

• Instantiate all activities between the ancestor activity and the activity to execute
• Instantiate and execute the given activity (respects the asyncBefore attribute of the activity)

Parameters:

activityId - the activity to instantiate

ancestorActivityInstanceId - the ID of an existing activity instance under which the new activity instance should be created

startAfterActivity

ProcessInstanceModificationInstantiationBuilder startAfterActivity(String activityId,
                                                                   String ancestorActivityInstanceId)

Submits an instruction that behaves like startTransition(String,String) and always instantiates the single outgoing sequence flow of the given activity. Does not consider asyncAfter.

Parameters:

activityId - the activity for which the outgoing flow should be executed

Throws:

ProcessEngineException - if the activity has 0 or more than 1 outgoing sequence flows

startTransition

ProcessInstanceModificationInstantiationBuilder startTransition(String transitionId,
                                                                String ancestorActivityInstanceId)

Submits the instruction:

Start the specified sequence flow. Instantiate the given sequence flow as a descendant of the given ancestor activity instance.

In particular:

• Instantiate all activities between the ancestor activity and the activity to execute
• Execute the given transition (does not consider sequence flow conditions)

Parameters:

transitionId - the sequence flow to execute

ancestorActivityInstanceId - the ID of an existing activity instance under which the new transition should be executed

cancelActivityInstance

ProcessInstanceModificationBuilder cancelActivityInstance(String activityInstanceId)

Submits the instruction:

Cancel an activity instance in a process. If this instance has child activity instances (e.g. in a subprocess instance), these children, their grandchildren, etc. are cancelled as well.

Process instance cancellation will propagate upward, removing any parent process instances that are only waiting on the cancelled process to complete.

Parameters:

activityInstanceId - the id of the activity instance to cancel

cancelTransitionInstance

ProcessInstanceModificationBuilder cancelTransitionInstance(String transitionInstanceId)

Submits the instruction:

Cancel a transition instance (i.e. an async continuation) in a process.

Parameters:

transitionInstanceId - the id of the transition instance to cancel

cancelAllForActivity

ProcessInstanceModificationBuilder cancelAllForActivity(String activityId)

Submits the instruction:

Cancel all instances of the given activity in an arbitrary order, which are:

• activity instances of that activity
• transition instances entering or leaving that activity

Therefore behaves like cancelActivityInstance(String) for each individual activity instance and like cancelTransitionInstance(String) for each individual transition instance.

The cancellation order of the instances is arbitrary

Parameters:

activityId - the activity for which all instances should be cancelled

cancellationSourceExternal

ProcessInstanceModificationBuilder cancellationSourceExternal(boolean external)

A canceled process instance receives a termination state to indicate the source of the cancellation call. The state can have the following values:

• EXTERNALLY_TERMINATED: the cancellation was triggered by an external source. (e.g. REST call, external application)
• INTERNALLY_TERMINATED: the cancellation was triggered internally. (e.g. by the engine)

Parameters:

external - was the cancellation triggered by an external source? true for EXTERNALLY_TERMINATED, false for INTERNALLY_TERMINATED.

setAnnotation

ProcessInstanceModificationBuilder setAnnotation(String annotation)

Provides annotation for the current modification.

execute

void execute()

Execute all instructions. Custom execution and task listeners, as well as task input output mappings are executed.

Throws:

AuthorizationException - if the user has no Permissions.UPDATE permission on Resources.PROCESS_INSTANCE or no Permissions.UPDATE_INSTANCE permission on Resources.PROCESS_DEFINITION. if the process instance will be delete and the user has no Permissions.DELETE permission on Resources.PROCESS_INSTANCE or no Permissions.DELETE_INSTANCE permission on Resources.PROCESS_DEFINITION.

execute

void execute(boolean skipCustomListeners,
             boolean skipIoMappings)

Parameters:

skipCustomListeners - specifies whether custom listeners (task and execution) should be invoked when executing the instructions

skipIoMappings - specifies whether input/output mappings for tasks should be invoked throughout the transaction when executing the instructions

Throws:

AuthorizationException - if the user has no Permissions.UPDATE permission on Resources.PROCESS_INSTANCE or no Permissions.UPDATE_INSTANCE permission on Resources.PROCESS_DEFINITION. if the process instance will be delete and the user has no Permissions.DELETE permission on Resources.PROCESS_INSTANCE or no Permissions.DELETE_INSTANCE permission on Resources.PROCESS_DEFINITION.

executeAsync

Batch executeAsync()

Execute all instructions asynchronously. Custom execution and task listeners, as well as task input output mappings are executed.

Returns:

a batch job to be executed by the executor

Throws:

AuthorizationException - if the user has no Permissions.CREATE or BatchPermissions.CREATE_BATCH_MODIFY_PROCESS_INSTANCES permission on Resources.BATCH.

executeAsync

Batch executeAsync(boolean skipCustomListeners,
                   boolean skipIoMappings)

Parameters:

skipCustomListeners - specifies whether custom listeners (task and execution) should be invoked when executing the instructions

skipIoMappings - specifies whether input/output mappings for tasks should be invoked throughout the transaction when executing the instructions

Returns:

a batch job to be executed by the executor

Throws:

AuthorizationException - if the user has no Permissions.CREATE or BatchPermissions.CREATE_BATCH_MODIFY_PROCESS_INSTANCES permission on Resources.BATCH.