org.ow2.bonita.facade.RuntimeAPI Maven / Gradle / Ivy
/**
* Copyright (C) 2006 Bull S. A. S.
* Bull, Rue Jean Jaures, B.P.68, 78340, Les Clayes-sous-Bois
* This library is free software; you can redistribute it and/or modify it under the terms
* of the GNU Lesser General Public License as published by the Free Software Foundation
* version 2.1 of the License.
* This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
* without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
* See the GNU Lesser General Public License for more details.
* You should have received a copy of the GNU Lesser General Public License along with this
* program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
* Floor, Boston, MA 02110-1301, USA.
*
* Modified by Matthieu Chaffotte - BonitaSoft S.A.
**/
package org.ow2.bonita.facade;
import java.util.Collection;
import java.util.Date;
import java.util.Map;
import org.ow2.bonita.facade.exception.ActivityNotFoundException;
import org.ow2.bonita.facade.exception.BonitaInternalException;
import org.ow2.bonita.facade.exception.IllegalTaskStateException;
import org.ow2.bonita.facade.exception.InstanceNotFoundException;
import org.ow2.bonita.facade.exception.ProcessNotFoundException;
import org.ow2.bonita.facade.exception.TaskNotFoundException;
import org.ow2.bonita.facade.exception.UncancellableInstanceException;
import org.ow2.bonita.facade.exception.UndeletableInstanceException;
import org.ow2.bonita.facade.exception.VariableNotFoundException;
import org.ow2.bonita.facade.uuid.ActivityInstanceUUID;
import org.ow2.bonita.facade.uuid.ProcessDefinitionUUID;
import org.ow2.bonita.facade.uuid.ProcessInstanceUUID;
import org.ow2.bonita.util.GroovyException;
/**
* To manage process, process instance and task life cycle operations as well as to set/add/update
* variables within activity or instance.
*
* Default states for process, processes instances, tasks (aka manual activities) are:
*
* - {@link org.ow2.bonita.facade.def.majorElement.ProcessDefinition.ProcessState States for process}: UNDEPLOYED, DEPLOYED
* - {@link org.ow2.bonita.facade.runtime.InstanceState States for process instance}: INITIAL, STARTED, FINISHED
* - {@link org.ow2.bonita.facade.runtime.ActivityState States for task}: INITIAL, READY, EXECUTING, SUSPENDED, FINISHED
*
* @see org.ow2.bonita.definition.TxHook
* @author Marc Blachon, Guillaume Porcher, Charles Souillard, Miguel Valdes, Pierre Vigneras
*/
public interface RuntimeAPI {
/**
* Creates an instance of the specified process and start the execution.
* returned instance has STARTED state.
* If the first activity has StartMode=manual then a task has been created.
* If the first activity has StartMode=automatic then the automatic behavior
* of the activity has been started.
* @param processUUID the process UUID.
* @return the UUID of the created instance.
* @throws ProcessNotFoundException if the process has not been found.
* @throws BonitaInternalException if an exception occurs.
*/
ProcessInstanceUUID instantiateProcess(ProcessDefinitionUUID processUUID) throws ProcessNotFoundException;
/**
* Creates an instance of the specified process with the added variable map
* and start the execution.
* returned instance has STARTED state.
* If the first activity has StartMode=manual then a task has been created.
* If the first activity has StartMode=automatic then the automatic behavior
* of the activity has been started.
* @param processUUID the process UUID.
* @param variables variables added to the variables already set within the process definition
* the variable object can be: an {@link org.ow2.bonita.facade.runtime.var.Enumeration Enumeration},
* a plain {@link String}, a {@link Boolean}, a {@link Date}, a {@link Long} or a {@link Double}.
* @return the UUID of the created instance.
* @throws ProcessNotFoundException if the process has not been found.
* @throws BonitaInternalException if an exception occurs.
*/
ProcessInstanceUUID instantiateProcess(ProcessDefinitionUUID processUUID, Map variables, Map attachments)
throws ProcessNotFoundException, VariableNotFoundException;
/**
* Executes the given task. It is equivalent to call startFinish and then finishTask. Only one things differs: start and finish are executed in the same transaction.
* @param taskUUID
* @param assignTask
* @throws TaskNotFoundException
* @throws IllegalTaskStateException
*/
void executeTask(ActivityInstanceUUID taskUUID, boolean assignTask) throws TaskNotFoundException, IllegalTaskStateException;
/**
* Starts the task. If successful, this operation changes task state from READY to EXECUTING.
* If the boolean assignTask is true the task is also assigned to the logged user
* otherwise the assignment of the task is not affected by this operation.
* @param taskUUID the task UUID.
* @param assignTask true to assign the task to the logged user; false to don't assign the task.
* @throws TaskNotFoundException if the task has not been found.
* @throws IllegalTaskStateException if the state of the task has not READY state.
* @throws BonitaInternalException if an exception occurs.
*/
void startTask(ActivityInstanceUUID taskUUID, boolean assignTask) throws TaskNotFoundException, IllegalTaskStateException;
/**
* Finishes the task. If successful, this operation changes task state from EXECUTING to FINISHED.
* If the boolean assignTask is true the task is also assigned to the logged user
* otherwise the assignment of the task is not affected by this operation.
* @param taskUUID the task UUID.
* @throws TaskNotFoundException if the task has not been found.
* @throws IllegalTaskStateException if the state of the task has not EXECUTING state.
* @throws BonitaInternalException if an exception occurs.
*/
void finishTask(ActivityInstanceUUID taskUUID, boolean taskAssign) throws TaskNotFoundException, IllegalTaskStateException;
/**
* Suspends the task if the task has EXECUTING state.
* If successful, this operation changes task state from EXECUTING to SUSPENDED.
* If the boolean assignTask is true the task is also assigned to the logged user
* otherwise the assignment of the task is not affected by this operation.
* @param taskUUID the task UUID.
* @throws TaskNotFoundException if the task has not been found.
* @throws IllegalTaskStateException if the state of the task has not either READY or EXECUTING state.
* @throws BonitaInternalException if an exception occurs.
*/
void suspendTask(ActivityInstanceUUID taskUUID, boolean assignTask) throws TaskNotFoundException,
IllegalTaskStateException;
/**
* Resumes the task if the task has SUSPENDED state.
* If successful, this operation changes task state from SUSPENDED to EXECUTING.
* If the boolean assignTask is true the task is also assigned to the logged user
* otherwise the assignment of the task is not affected by this operation.
* @param taskUUID the task UUID.
* @throws TaskNotFoundException if the task has not been found.
* @throws IllegalTaskStateException if the state of the task has not SUSPENDED state.
* @throws BonitaInternalException if an other exception occurs.
*/
void resumeTask(ActivityInstanceUUID taskUUID, boolean taskAssign) throws TaskNotFoundException,
IllegalTaskStateException;
/**
* Launches the execution of both roleMapper and performerAssignment for the given task.
* If a roleMapper has been defined within the participant referenced by the performer of the task,
* it is executed.
* If a performerAssignment has been defined within the activity of the task it is also
* executed.
* @param taskUUID the task UUID.
* @throws TaskNotFoundException if the task has not been found.
* @throws BonitaInternalException if an other exception occurs.
*/
void assignTask(ActivityInstanceUUID taskUUID) throws TaskNotFoundException;
/**
* Forces to assign the given task to the given actor id. If a set of candidates was already set, this method doesn't
* update it.
* @param taskUUID the task UUID.
* @param actorId the actor id.
* @throws TaskNotFoundException if the task has not been found.
*/
void assignTask(ActivityInstanceUUID taskUUID, String actorId) throws TaskNotFoundException;
/**
* Forces to replace the candidates set of the given task by the given candidates set.
* If a userId was already set, this method doesn't update it.
* @param taskUUID the task UUID.
* @param candidates the set of candidate actors.
* @throws TaskNotFoundException if the task has not been found.
*/
void assignTask(ActivityInstanceUUID taskUUID, java.util.Set candidates) throws TaskNotFoundException;
/**
* If this task had a userId set, set it to null. If a set of candidates was already set,
* this method doesn't update it.
* @param taskUUID the task UUID.
* @throws TaskNotFoundException if the task has not been found.
*/
void unassignTask(ActivityInstanceUUID taskUUID) throws TaskNotFoundException;
/**
* Searches for variable with id variableId within the given process instance
* with ProcessInstanceUUID instanceUUID.
* If the variable is found, the given value is set.
*
* - If the XPDL dataField is String type then use instance of
* java.lang.String class for variableValue.
* - If the XPDL dataField is Enumeration type then use instance of
* {@link org.ow2.bonita.facade.runtime.var.Enumeration Enumeration} class for variableValue.
*
* The field selectedValue of Enumeration type can contain only one value
* from the possibleValues list field.
* @param instanceUUID the instance UUID.
* @param variableId the variable id.
* @param variableValue the variable value (can be: an {@link org.ow2.bonita.facade.runtime.var.Enumeration Enumeration},
* a plain {@link String}, a {@link Boolean}, a {@link Date}, a {@link Long} or a {@link Double}).
* @throws InstanceNotFoundException if the instance has not been found.
* @throws VariableNotFoundException if the variable has not been found.
* @throws BonitaInternalException if an exception occurs.
*/
void setProcessInstanceVariable(ProcessInstanceUUID instanceUUID, String variableId, Object variableValue)
throws InstanceNotFoundException, VariableNotFoundException;
void setProcessInstanceWebLabels(Collection instanceUUIDs, Collection labelIds) throws InstanceNotFoundException;
void setProcessInstanceWebLabels(ProcessInstanceUUID instanceUUID, Collection labelIds) throws InstanceNotFoundException;
/**
* Cancel the process instance with the given instance UUID.
* If the instance represented by the given instanceUUID has a parentInstance, then UncancellableInstanceException is thrown.
* @param instanceUUID the instance UUID.
* @throws InstanceNotFoundException if if the instance has not been found.
* @throws BonitaInternalException if an exception occurs.
*/
void cancelProcessInstance(ProcessInstanceUUID instanceUUID) throws InstanceNotFoundException, UncancellableInstanceException;
void cancelProcessInstances(Collection instanceUUIDs) throws InstanceNotFoundException, UncancellableInstanceException;
/**
*
* Searches for variable with id variableId within the given activity instance
* with the given UUID.
* If the variable is found within the activity, the given value is set.
* If the variable is not found within the activity the search is performed
* within the process instance.
* If the variable is found within the process instance, the given value is set.
*
*
* - If the XPDL dataField is String type then use instance of
* java.lang.String class for variableValue.
* - If the XPDL dataField is Enumeration type then use instance of
* {@link org.ow2.bonita.facade.runtime.var.Enumeration Enumeration} class for variableValue.
*
* The field selectedValue of Enumeration type can contain only one value
* from the possibleValues list field.
* @param activityUUID the activity UUID.
* @param variableId the variable id.
* @param variableValue the variable value (can be: an {@link org.ow2.bonita.facade.runtime.var.Enumeration Enumeration},
* a plain {@link String}, a {@link Boolean}, a {@link Date}, a {@link Long} or a {@link Double}).
* @throws VariableNotFoundException if the variable has not been found.
* @throws BonitaInternalException if an exception occurs.
*/
void setVariable(ActivityInstanceUUID activityUUID, String variableId, Object variableValue)
throws ActivityNotFoundException, VariableNotFoundException;
/**
* Searches for variable with the given activity UUID and variable Id.
* If the activity variable is found, the given value is set.
*
* - If the XPDL dataField has String type then use instance of
* java.lang.String class for variableValue.
* - If the XPDL dataField has EnumerationType type then use instance of
* {@link org.ow2.bonita.facade.runtime.var.Enumeration Enumeration} class for variableValue.
*
* The field selectedValue can contain only one value from the possibleValues list field.
* @param activityUUID the activity UUID.
* @param variableId the variable id.
* @param variableValue the variable value(can be: an {@link org.ow2.bonita.facade.runtime.var.Enumeration Enumeration},
* a plain {@link String}, a {@link Boolean}, a {@link Date}, a {@link Long} or a {@link Double}).
* @throws ActivityNotFoundException if the activity has not been found.
* @throws VariableNotFoundException if the variable has not been found.
* @throws BonitaInternalException if an exception occurs.
*/
void setActivityInstanceVariable(ActivityInstanceUUID activityUUID,
String variableId, Object variableValue) throws ActivityNotFoundException, VariableNotFoundException;
/**
* Deletes all runtime objects for the process instance with the given instance UUID
* and delete also recorded data from the journal.
* If this instance was not found in the journal, then the archived instance is deleted from history.
* If the instance represented by the given instanceUUID has a parentInstance, then UndeletableInstanceException is thrown.
* @param instanceUUID the instance UUID.
* @throws InstanceNotFoundException if if the instance has not been found.
* @throws BonitaInternalException if an exception occurs.
*/
void deleteProcessInstance(ProcessInstanceUUID instanceUUID) throws InstanceNotFoundException, UndeletableInstanceException;
void deleteProcessInstances(Collection instanceUUIDs) throws InstanceNotFoundException, UndeletableInstanceException;
/**
* Deletes all runtime objects for all instances created with the given process UUID
* and delete also all there recorded data from the journal.
* If instances some instances of this process were not found in the journal,
* then the archived instances are deleted from history.
* @param processUUID the process UUID.
* @throws ProcessNotFoundException if the process with the given UUID does not exists.
* @throws BonitaInternalException if an exception occurs.
*/
void deleteAllProcessInstances(ProcessDefinitionUUID processUUID) throws ProcessNotFoundException, UndeletableInstanceException;
/**
* Add a comment to the ProcessInstance feed.
* if the comment was not set in an activity
* @param instanceUUID the process instance UUID
* @param activityUUID the activity UUID, can be null
* @param message the comment
* @param userId the userId
* @throws InstanceNotFoundException if the instance has not been found.
* @throws ActivityNotFoundException if the activity has not been found.
*/
void addComment(final ProcessInstanceUUID instanceUUID, ActivityInstanceUUID activityUUID, String message, String userId)
throws InstanceNotFoundException, ActivityNotFoundException;
/**
* Add a process meta data.
* @param uuid the process UUID.
* @param key the key of the meta data
* @param value the value of the meta data
* @throws ProcessNotFound if the process with the given UUID does not exists.
*/
void addProcessMetaData(ProcessDefinitionUUID uuid, String key, String value) throws ProcessNotFoundException;
/**
* Delete a process meta data.
* @param uuid the process UUID
* @param key the key of the meta data
* @throws ProcessNotFoundException if the process with the given UUID does not exists.
*/
void deleteProcessMetaData(ProcessDefinitionUUID uuid, String key) throws ProcessNotFoundException;
/**
* Evaluates an expression using Groovy.
* If more than one Groovy expressions are in the expression, they must start with ${
* and finish with }. It returns an Object if the expression is an only Groovy one or a String
* if the expression contains String and or more than one Groovy expression.
* @param expression the expression
* @param instanceUUID the process instance UUID
* @return either an Object if the expression is a Groovy one or a String
* @throws InstanceNotFoundException if the instance has not been found.
* @throws GroovyException if the expression is not a Groovy one.
*/
Object evaluateGroovyExpression(String expression, ProcessInstanceUUID instanceUUID)
throws InstanceNotFoundException, GroovyException;
/**
* Evaluates an expression using Groovy.
* If more than one Groovy expressions are in the expression, they must start with ${
* and finish with }. It returns an Object if the expression is an only Groovy one or a String
* if the expression contains String and or more than one Groovy expression.
* @param expression the expression
* @param activityUUID the activityUUID
* @return either an Object if the expression is a Groovy one or a String
* @throws InstanceNotFoundException if the instance has not been found.
* @throws ActivityNotFoundException if the activity has not been found.
* @throws GroovyException if the expression is not a Groovy one.
*/
Object evaluateGroovyExpression(String expression, ActivityInstanceUUID activityUUID)
throws InstanceNotFoundException, ActivityNotFoundException, GroovyException;
void setAttachment(ProcessInstanceUUID instanceUUID, String name, byte[] value);
void setAttachments(ProcessInstanceUUID instanceUUID, Map attachments);
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy