org.camunda.bpm.engine.runtime.ProcessInstanceModificationBuilder Maven / Gradle / Ivy
/*
* Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH
* under one or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information regarding copyright
* ownership. Camunda licenses this file to you under the Apache License,
* Version 2.0; you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.camunda.bpm.engine.runtime;
import org.camunda.bpm.engine.AuthorizationException;
import org.camunda.bpm.engine.ProcessEngineException;
import org.camunda.bpm.engine.authorization.BatchPermissions;
import org.camunda.bpm.engine.authorization.Permissions;
import org.camunda.bpm.engine.authorization.Resources;
import org.camunda.bpm.engine.batch.Batch;
/**
* 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
*/
public interface ProcessInstanceModificationBuilder extends
InstantiationBuilder {
/**
* 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)
*
*
*
* @param activityId the activity to instantiate
* @param ancestorActivityInstanceId the ID of an existing activity instance under which the new
* activity instance should be created
*/
ProcessInstanceModificationInstantiationBuilder startBeforeActivity(String activityId, String ancestorActivityInstanceId);
/**
* Submits an instruction that behaves like {@link #startTransition(String,String)} and always instantiates
* the single outgoing sequence flow of the given activity. Does not consider asyncAfter.
*
* @param 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
*/
ProcessInstanceModificationInstantiationBuilder startAfterActivity(String activityId, 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)
*
*
*
* @param transitionId the sequence flow to execute
* @param ancestorActivityInstanceId the ID of an existing activity instance under which the new
* transition should be executed
*/
ProcessInstanceModificationInstantiationBuilder startTransition(String transitionId, String ancestorActivityInstanceId);
/**
* 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.
*
* @param activityInstanceId the id of the activity instance to cancel
*/
ProcessInstanceModificationBuilder cancelActivityInstance(String activityInstanceId);
/**
* Submits the instruction:
*
* Cancel a transition instance (i.e. an async continuation) in a process.
*
* @param transitionInstanceId the id of the transition instance to cancel
*/
ProcessInstanceModificationBuilder cancelTransitionInstance(String transitionInstanceId);
/**
* 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 {@link #cancelActivityInstance(String)} for each individual
* activity instance and like {@link #cancelTransitionInstance(String)} for each
* individual transition instance.
*
* The cancellation order of the instances is arbitrary
*
* @param activityId the activity for which all instances should be cancelled
*/
ProcessInstanceModificationBuilder cancelAllForActivity(String activityId);
/**
*
* 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)
*
*
* @param external
* was the cancellation triggered by an external source?
* true for EXTERNALLY_TERMINATED,
* false for INTERNALLY_TERMINATED.
*/
ProcessInstanceModificationBuilder cancellationSourceExternal(boolean external);
/** Provides annotation for the current modification. */
ProcessInstanceModificationBuilder setAnnotation(String annotation);
/**
* Execute all instructions. Custom execution and task listeners, as well as task input output mappings
* are executed.
*
* @throws AuthorizationException
* if the user has no {@link Permissions#UPDATE} permission on {@link Resources#PROCESS_INSTANCE}
* or no {@link Permissions#UPDATE_INSTANCE} permission on {@link Resources#PROCESS_DEFINITION}.
* if the process instance will be delete and the user has no {@link Permissions#DELETE} permission
* on {@link Resources#PROCESS_INSTANCE} or no {@link Permissions#DELETE_INSTANCE} permission on
* {@link Resources#PROCESS_DEFINITION}.
*/
void execute();
/**
* @param skipCustomListeners specifies whether custom listeners (task and execution)
* should be invoked when executing the instructions
* @param 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 {@link Permissions#UPDATE} permission on {@link Resources#PROCESS_INSTANCE}
* or no {@link Permissions#UPDATE_INSTANCE} permission on {@link Resources#PROCESS_DEFINITION}.
* if the process instance will be delete and the user has no {@link Permissions#DELETE} permission
* on {@link Resources#PROCESS_INSTANCE} or no {@link Permissions#DELETE_INSTANCE} permission on
* {@link Resources#PROCESS_DEFINITION}.
*/
void execute(boolean skipCustomListeners, boolean skipIoMappings);
/**
* Execute all instructions asynchronously. Custom execution and task listeners, as well as task input output mappings
* are executed.
*
* @throws AuthorizationException
* if the user has no {@link Permissions#CREATE} or
* {@link BatchPermissions#CREATE_BATCH_MODIFY_PROCESS_INSTANCES} permission on {@link Resources#BATCH}.
*
* @return a batch job to be executed by the executor
*/
Batch executeAsync();
/**
* @param skipCustomListeners specifies whether custom listeners (task and execution)
* should be invoked when executing the instructions
* @param 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 {@link Permissions#CREATE} or
* {@link BatchPermissions#CREATE_BATCH_MODIFY_PROCESS_INSTANCES} permission on {@link Resources#BATCH}.
*
* @return a batch job to be executed by the executor
*/
Batch executeAsync(boolean skipCustomListeners, boolean skipIoMappings);
}