Package 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 Details

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