org.ow2.bonita.facade
Interface RuntimeAPI


public interface RuntimeAPI

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:

Author:
Marc Blachon, Guillaume Porcher, Charles Souillard, Miguel Valdes, Pierre Vigneras
See Also:
TxHook

Method Summary
 void addComment(ProcessInstanceUUID instanceUUID, ActivityInstanceUUID activityUUID, java.lang.String message, java.lang.String userId)
          Add a comment to the ProcessInstance feed.
 void addProcessMetaData(ProcessDefinitionUUID uuid, java.lang.String key, java.lang.String value)
          Add a process meta data.
 void assignTask(TaskUUID taskUUID)
          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.
 void assignTask(TaskUUID taskUUID, java.util.Set<java.lang.String> candidates)
          Forces to replace the candidates set of the given task by the given candidates set.
 void assignTask(TaskUUID taskUUID, java.lang.String actorId)
          Forces to assign the given task to the given actor id.
 void cancelProcessInstance(ProcessInstanceUUID instanceUUID)
          Cancel the process instance with the given instance UUID.
 void deleteAllProcessInstances(ProcessDefinitionUUID processUUID)
          Deletes all runtime objects for all instances created with the given process UUID and delete also all there recorded data from the journal.
 void deleteProcessInstance(ProcessInstanceUUID instanceUUID)
          Deletes all runtime objects for the process instance with the given instance UUID and delete also recorded data from the journal.
 void deleteProcessMetaData(ProcessDefinitionUUID uuid, java.lang.String key)
          Delete a process meta data.
 java.lang.Object evaluateGroovyExpression(java.lang.String expression, ActivityInstanceUUID activityUUID)
          Evaluates an expression using Groovy.
 java.lang.Object evaluateGroovyExpression(java.lang.String expression, ProcessInstanceUUID instanceUUID)
          Evaluates an expression using Groovy.
 void finishTask(TaskUUID taskUUID, boolean taskAssign)
          Finishes the task.
 ProcessInstanceUUID instantiateProcess(ProcessDefinitionUUID processUUID)
          Creates an instance of the specified process and start the execution.
 ProcessInstanceUUID instantiateProcess(ProcessDefinitionUUID processUUID, java.util.Map<java.lang.String,java.lang.Object> variables)
          Creates an instance of the specified process with the added variable map and start the execution.
 void resumeTask(TaskUUID taskUUID, boolean taskAssign)
          Resumes the task if the task has SUSPENDED state.
 void setActivityInstanceVariable(ActivityInstanceUUID activityUUID, java.lang.String variableId, java.lang.Object variableValue)
          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 Enumeration class for variableValue. The field selectedValue can contain only one value from the possibleValues list field.
 void setProcessInstanceVariable(ProcessInstanceUUID instanceUUID, java.lang.String variableId, java.lang.Object variableValue)
          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 Enumeration class for variableValue. The field selectedValue of Enumeration type can contain only one value from the possibleValues list field.
 void setVariable(ActivityInstanceUUID activityUUID, java.lang.String variableId, java.lang.Object variableValue)
           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.
 void startTask(TaskUUID taskUUID, boolean assignTask)
          Starts the task.
 void suspendTask(TaskUUID taskUUID, boolean assignTask)
          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.
 void unassignTask(TaskUUID taskUUID)
          If this task had a userId set, set it to null.
 

Method Detail

instantiateProcess

ProcessInstanceUUID instantiateProcess(ProcessDefinitionUUID processUUID)
                                       throws ProcessNotFoundException
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.

Parameters:
processUUID - the process UUID.
Returns:
the UUID of the created instance.
Throws:
ProcessNotFoundException - if the process has not been found.
BonitaInternalException - if an exception occurs.

instantiateProcess

ProcessInstanceUUID instantiateProcess(ProcessDefinitionUUID processUUID,
                                       java.util.Map<java.lang.String,java.lang.Object> variables)
                                       throws ProcessNotFoundException,
                                              VariableNotFoundException
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.

Parameters:
processUUID - the process UUID.
variables - variables added to the variables already set within the process definition the variable object can be: an Enumeration, a plain String, a Boolean, a Date, a Long or a Double.
Returns:
the UUID of the created instance.
Throws:
ProcessNotFoundException - if the process has not been found.
BonitaInternalException - if an exception occurs.
VariableNotFoundException

startTask

void startTask(TaskUUID 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.

Parameters:
taskUUID - the task UUID.
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.
IllegalTaskStateException - if the state of the task has not READY state.
BonitaInternalException - if an exception occurs.

finishTask

void finishTask(TaskUUID taskUUID,
                boolean taskAssign)
                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.

Parameters:
taskUUID - the task UUID.
Throws:
TaskNotFoundException - if the task has not been found.
IllegalTaskStateException - if the state of the task has not EXECUTING state.
BonitaInternalException - if an exception occurs.

suspendTask

void suspendTask(TaskUUID taskUUID,
                 boolean assignTask)
                 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.

Parameters:
taskUUID - the task UUID.
Throws:
TaskNotFoundException - if the task has not been found.
IllegalTaskStateException - if the state of the task has not either READY or EXECUTING state.
BonitaInternalException - if an exception occurs.

resumeTask

void resumeTask(TaskUUID taskUUID,
                boolean taskAssign)
                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.

Parameters:
taskUUID - the task UUID.
Throws:
TaskNotFoundException - if the task has not been found.
IllegalTaskStateException - if the state of the task has not SUSPENDED state.
BonitaInternalException - if an other exception occurs.

assignTask

void assignTask(TaskUUID taskUUID)
                throws TaskNotFoundException
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.

Parameters:
taskUUID - the task UUID.
Throws:
TaskNotFoundException - if the task has not been found.
BonitaInternalException - if an other exception occurs.

assignTask

void assignTask(TaskUUID taskUUID,
                java.lang.String actorId)
                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.

Parameters:
taskUUID - the task UUID.
actorId - the actor id.
Throws:
TaskNotFoundException - if the task has not been found.

assignTask

void assignTask(TaskUUID taskUUID,
                java.util.Set<java.lang.String> candidates)
                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.

Parameters:
taskUUID - the task UUID.
candidates - the set of candidate actors.
Throws:
TaskNotFoundException - if the task has not been found.

unassignTask

void unassignTask(TaskUUID taskUUID)
                  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.

Parameters:
taskUUID - the task UUID.
candidates - the set of candidate actors.
Throws:
TaskNotFoundException - if the task has not been found.

setProcessInstanceVariable

void setProcessInstanceVariable(ProcessInstanceUUID instanceUUID,
                                java.lang.String variableId,
                                java.lang.Object variableValue)
                                throws InstanceNotFoundException,
                                       VariableNotFoundException
Searches for variable with id variableId within the given process instance with ProcessInstanceUUID instanceUUID.
If the variable is found, the given value is set.
The field selectedValue of Enumeration type can contain only one value from the possibleValues list field.

Parameters:
instanceUUID - the instance UUID.
variableId - the variable id.
variableValue - the variable value (can be: an Enumeration, a plain String, a Boolean, a Date, a Long or a Double).
Throws:
InstanceNotFoundException - if the instance has not been found.
VariableNotFoundException - if the variable has not been found.
BonitaInternalException - if an exception occurs.

cancelProcessInstance

void cancelProcessInstance(ProcessInstanceUUID instanceUUID)
                           throws InstanceNotFoundException,
                                  UncancellableInstanceException
Cancel the process instance with the given instance UUID. If the instance represented by the given instanceUUID has a parentInstance, then UncancellableInstanceException is thrown.

Parameters:
instanceUUID - the instance UUID.
Throws:
InstanceNotFoundException - if if the instance has not been found.
BonitaInternalException - if an exception occurs.
UncancellableInstanceException

setVariable

void setVariable(ActivityInstanceUUID activityUUID,
                 java.lang.String variableId,
                 java.lang.Object variableValue)
                 throws ActivityNotFoundException,
                        VariableNotFoundException

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.

The field selectedValue of Enumeration type can contain only one value from the possibleValues list field.

Parameters:
activityUUID - the activity UUID.
variableId - the variable id.
variableValue - the variable value (can be: an Enumeration, a plain String, a Boolean, a Date, a Long or a Double).
Throws:
VariableNotFoundException - if the variable has not been found.
BonitaInternalException - if an exception occurs.
ActivityNotFoundException

setActivityInstanceVariable

void setActivityInstanceVariable(ActivityInstanceUUID activityUUID,
                                 java.lang.String variableId,
                                 java.lang.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.
The field selectedValue can contain only one value from the possibleValues list field.

Parameters:
activityUUID - the activity UUID.
variableId - the variable id.
variableValue - the variable value(can be: an Enumeration, a plain String, a Boolean, a Date, a Long or a Double).
Throws:
ActivityNotFoundException - if the activity has not been found.
VariableNotFoundException - if the variable has not been found.
BonitaInternalException - if an exception occurs.

deleteProcessInstance

void deleteProcessInstance(ProcessInstanceUUID instanceUUID)
                           throws InstanceNotFoundException,
                                  UndeletableInstanceException
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.

Parameters:
instanceUUID - the instance UUID.
Throws:
InstanceNotFoundException - if if the instance has not been found.
BonitaInternalException - if an exception occurs.
UndeletableInstanceException

deleteAllProcessInstances

void deleteAllProcessInstances(ProcessDefinitionUUID processUUID)
                               throws ProcessNotFoundException,
                                      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.

Parameters:
processUUID - the process UUID.
Throws:
ProcessNotFoundException - if the process with the given UUID does not exists.
BonitaInternalException - if an exception occurs.
UndeletableInstanceException

addComment

void addComment(ProcessInstanceUUID instanceUUID,
                ActivityInstanceUUID activityUUID,
                java.lang.String message,
                java.lang.String userId)
                throws InstanceNotFoundException,
                       ActivityNotFoundException
Add a comment to the ProcessInstance feed. if the comment was not set in an activity

Parameters:
instanceUUID - the process instance UUID
activityUUID - the activity UUID, can be null
message - the comment
userId - the userId
Throws:
InstanceNotFoundException - if the instance has not been found.
ActivityNotFoundException - if the activity has not been found.

addProcessMetaData

void addProcessMetaData(ProcessDefinitionUUID uuid,
                        java.lang.String key,
                        java.lang.String value)
                        throws ProcessNotFoundException
Add a process meta data.

Parameters:
uuid - the process UUID.
key - the key of the meta data
value - the value of the meta data
Throws:
ProcessNotFound - if the process with the given UUID does not exists.
ProcessNotFoundException

deleteProcessMetaData

void deleteProcessMetaData(ProcessDefinitionUUID uuid,
                           java.lang.String key)
                           throws ProcessNotFoundException
Delete a process meta data.

Parameters:
uuid - the process UUID
key - the key of the meta data
Throws:
ProcessNotFoundException - if the process with the given UUID does not exists.

evaluateGroovyExpression

java.lang.Object evaluateGroovyExpression(java.lang.String expression,
                                          ProcessInstanceUUID instanceUUID)
                                          throws InstanceNotFoundException
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.

Parameters:
expression - the expression
instanceUUID - the process instance UUID
Returns:
either an Object if the expression is a Groovy one or a String
Throws:
InstanceNotFoundException - if the instance has not been found.

evaluateGroovyExpression

java.lang.Object evaluateGroovyExpression(java.lang.String expression,
                                          ActivityInstanceUUID activityUUID)
                                          throws InstanceNotFoundException,
                                                 ActivityNotFoundException
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.

Parameters:
expression - the expression
activityUUID - the activityUUID
Returns:
either an Object if the expression is a Groovy one or a String
Throws:
InstanceNotFoundException - if the instance has not been found.
ActivityNotFoundException - if the activity has not been found.


Copyright © 2009 OW2 Consortium. All Rights Reserved.