org.ow2.bonita.facade.QueryRuntimeAPI Maven / Gradle / Ivy
/**
* Copyright (C) 2007 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 Charles Souillard - BonitaSoft S.A.
* Modified by Matthieu Chaffotte - BonitaSoft S.A.
**/
package org.ow2.bonita.facade;
import java.util.Collection;
import java.util.Date;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.ow2.bonita.facade.exception.ActivityNotFoundException;
import org.ow2.bonita.facade.exception.BonitaInternalException;
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.VariableNotFoundException;
import org.ow2.bonita.facade.runtime.ActivityInstance;
import org.ow2.bonita.facade.runtime.ActivityState;
import org.ow2.bonita.facade.runtime.Comment;
import org.ow2.bonita.facade.runtime.ProcessInstance;
import org.ow2.bonita.facade.runtime.TaskInstance;
import org.ow2.bonita.facade.uuid.ActivityInstanceUUID;
import org.ow2.bonita.facade.uuid.ProcessDefinitionUUID;
import org.ow2.bonita.facade.uuid.ProcessInstanceUUID;
/**
* Getters on workflow recorded data.
* Operations in this API applies to main entities managed by Nova Bonita such as:
* packages, processes, process instances, activities, tasks.
* Returned records are issued from recorded runtime informations (both runtime and archived workflow instances).
* @see org.ow2.bonita.definition.RoleMapper
* @see org.ow2.bonita.definition.PerformerAssign
* @see org.ow2.bonita.definition.Hook
* @author Pierre Vigneras, Charles Souillard
*/
public interface QueryRuntimeAPI {
public static final String DEFAULT_QUERIER = "queryList";
/**
* Returns all records of instance.
* An empty set is returned if no instance is found.
* @return a set containing all instance records.
* @throws BonitaInternalException if an exception occurs.
*/
Set getProcessInstances();
/**
* Returns all records of instance matching with the given ProcessInstanceUUID.
* If one of the ProcessInstanceUUID is not found, nothing is added to the result.
* An empty set is returned if no instance is found.
* @param instanceUUIDs the instances UUID.
* @return all records of instance matching with the given ProcessInstanceUUID.
* @throws BonitaInternalException if an exception occurs.
*/
Set getProcessInstances(Collection instanceUUIDs);
/**
* Returns all records of instance having one task in one of the given states.
* @param activityStates states
* @return all records of instance having one task in one of the given states.
* @throws BonitaInternalException if an exception occurs.
*/
Set getProcessInstancesWithTaskState(Collection activityStates);
/**
* Returns the record of the instance with the given UUID.
* @param instanceUUID the instance UUID.
* @return the record of the instance with the given UUID.
* @throws InstanceNotFoundException if no instance has been found with the given instance UUID.
* @throws BonitaInternalException if an exception occurs.
*/
ProcessInstance getProcessInstance(ProcessInstanceUUID instanceUUID) throws InstanceNotFoundException;
/**
* Returns all records of instance for the given process processDefinitionUUID.
* An empty set is returned if no instance is found.
* @param processUUID the process definition UUID.
* @return a set containing all instance records.
* @throws ProcessNotFoundException if no process has been found with the given process UUID.
* @throws BonitaInternalException if an exception occurs.
*/
Set getProcessInstances(ProcessDefinitionUUID processUUID) throws ProcessNotFoundException;
/**
* Returns the record of the activity with the given activity UUID.
* @param activityUUID the activity UUID.
* @return the activity record with the given instance UUID and activity id.
* @throws InstanceNotFoundException if no instance has been found with the given instance UUID.
* @throws ActivityNotFoundException if no activity has been found with the given activity id.
* @throws BonitaInternalException if an exception occurs.
*/
ActivityInstance getActivityInstance(ActivityInstanceUUID activityUUID) throws ActivityNotFoundException;
/**
* Returns all records of activity for the given process instance UUID.
* @param instanceUUID the instance UUID.
* @return the unordered set containing activity records.
* @throws InstanceNotFoundException if no instance has been found with the given instance UUID.
* @throws BonitaInternalException if an exception occurs.
*/
Set getActivityInstances(ProcessInstanceUUID instanceUUID) throws InstanceNotFoundException;
//all iterations
/**
* Returns records for all iterations and multi-instantiations that should happend for the given
* process instance UUID and activity Id.
* An empty set is returned if no instance is found.
* @param instanceUUID the instance UUID.
* @param activityId the activity Id (as specified into the XPDL file).
* @return the unordered set containing activity records.
* @throws InstanceNotFoundException if no instance has been found with the given instance UUID.
* @throws BonitaInternalException if an exception occurs.
*/
Set getActivityInstances(ProcessInstanceUUID instanceUUID,
String activityId) throws InstanceNotFoundException, ActivityNotFoundException;
/**
* Returns the record of the task with the given task UUID.
* @param taskUUID the task UUID.
* @return the record of the task with the given task UUID.
* @throws TaskNotFoundException if no task has been found with the given task UUID.
* @throws BonitaInternalException if an exception occurs.
*/
TaskInstance getTask(ActivityInstanceUUID taskUUID) throws TaskNotFoundException;
/**
* Returns all records of task for the given process instance UUID.
* @param instanceUUID the instance UUID.
* @return a set containing all task records for the instance.
* @throws InstanceNotFoundException if no instance has been found with the given instance UUID.
* @throws BonitaInternalException if an exception occurs.
*/
Set getTasks(ProcessInstanceUUID instanceUUID) throws InstanceNotFoundException;
/**
* Obtains the user tasks with state either READY or EXECUTING or SUSPENDED or FINISHED
* for the given instance and the authenticated user.
* @param instanceUUID the instance UUID.
* @param taskState the {@link org.ow2.bonita.facade.runtime.ActivityState state} of the task.
* @return a collection of task records. If no tasks are found, an empty collection is returned.
* @throws InstanceNotFoundException if no instance record is found with the given instance UUID.
* @throws BonitaInternalException if an other exception occurs.
*/
Collection getTaskList(ProcessInstanceUUID instanceUUID, ActivityState taskState)
throws InstanceNotFoundException;
Collection getTaskList(ProcessInstanceUUID instanceUUID, Collection taskStates)
throws InstanceNotFoundException;
/**
* Obtains the tasks with state either READY or EXECUTING or SUSPENDED or FINISHED for the given instance
* and for the given user.
* If the task has been assigned to a user, only this user can get the task into the returned list.
* Otherwise all the users that belong to the candidate list can get the task.
* @param instanceUUID the instance UUID.
* @param userId the userId for which the tasks are searched.
* @param taskState the {@link org.ow2.bonita.facade.runtime.ActivityState state} of the task.
* @return a collection of task records. If no tasks are found, an empty collection is returned.
* @throws InstanceNotFoundException if no instance record is found with the given instance UUID.
* @throws BonitaInternalException if an other exception occurs.
*/
Collection getTaskList(ProcessInstanceUUID instanceUUID, String userId, ActivityState taskState)
throws InstanceNotFoundException;
/**
* Obtains the user tasks with state either READY or EXECUTING or SUSPENDED or FINISHED
* for the authenticated user.
* If the task has been assigned to a user, only this user can get the task into the returned list.
* Otherwise all the users that belong to the candidate list can get the task.
* @param taskState the {@link org.ow2.bonita.facade.runtime.ActivityState state} of the task.
* @return a collection of task records. If no tasks are found, an empty collection is returned.
* @throws BonitaInternalException if an other exception occurs.
*/
Collection getTaskList(ActivityState taskState);
/**
*
* Obtains the user tasks with state either READY or EXECUTING or SUSPENDED or FINISHED
* for the given user.
* If the task has been assigned to a user, only this user can get the task into the returned list.
* Otherwise all the users that belong to the candidate list can get the task.
* @param userId the userId for which the tasks are searched.
* @param taskState the {@link org.ow2.bonita.facade.runtime.ActivityState state} of the task.
* @return a collection of task records. If no tasks are found, an empty collection is returned.
* @throws BonitaInternalException if an other exception occurs.
*/
Collection getTaskList(String userId, ActivityState taskState);
ActivityState getActivityInstanceState(ActivityInstanceUUID activityUUID) throws ActivityNotFoundException;
/**
* Obtains a variable defined as local to the activity for the given activity UUID and variable Id.
* The activity should either be executed or currently pointed by the a process execution.
* @param activityUUID the activity UUID.
* @param variableId the value of the Id attribute of the DataField element defined into the XPDL file.
* @return 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}).
* @throws ActivityNotFoundException if this activity is not pointed by a process execution
* and the execution informations for this activity has not been recorded.
* @throws VariableNotFoundException if no variable is found with the given id.
* @throws BonitaInternalException if an other exception occurs.
*/
Object getActivityInstanceVariable(ActivityInstanceUUID activityUUID,
String variableId) throws ActivityNotFoundException, VariableNotFoundException;
/**
* Obtains the variables defined as local to the activity for the given activity UUID.
* An empty map is returned if no variable is found.
* @param activityUUID the activity UUID.
* @return the map of activity variables where key is the variable id and value is 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})).
* @throws ActivityNotFoundException if this activity is not pointed by a process execution
* and the execution informations for this activity has not been recorded.
* @throws BonitaInternalException if an other exception occurs.
*/
Map getActivityInstanceVariables(ActivityInstanceUUID activityUUID)throws ActivityNotFoundException;
/**
* Obtains a variable for the given activity and variable Id.
* This variable could be local to the activity or global to the process.
* The activity should either be executed or currently pointed by the a process execution.
* @param activityUUID the activity UUID.
* @param variableId the value of the Id attribute of the DataField element defined into the XPDL file.
* @return 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}).
* @throws ActivityNotFoundException if this activity is not pointed by a process execution
* and the execution informations for this activity has not been recorded.
* @throws VariableNotFoundException if no variable is found with the given id.
* @throws BonitaInternalException if an other exception occurs.
*/
Object getVariable(ActivityInstanceUUID activityUUID, String variableId)
throws ActivityNotFoundException, VariableNotFoundException;
/**
* Obtains the activity variables (including global process and local activity variables)
* for the given activity UUID.
* An empty map is returned if no variable is found.
* @param activityUUID the activity UUID.
* @return the map of activity variables where key is the variable id and value is 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}).
* @throws ActivityNotFoundException if this activity is not pointed by a process execution
* and the execution informations for this activity has not been recorded.
* @throws InstanceNotFoundException if no recorded informations is found with the given instance UUID.
* @throws BonitaInternalException if an other exception occurs.
*/
Map getVariables(ActivityInstanceUUID activityUUID)
throws InstanceNotFoundException, ActivityNotFoundException;
/**
* Obtains a process variable for the given process instance UUID and variable Id.
* @param instanceUUID the instance UUID.
* @param variableId the variable id.
* @return 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}).
* @throws InstanceNotFoundException if no instance has found with the given instance UUID.
* @throws VariableNotFoundException if no variable is found with the given id.
* @throws BonitaInternalException if an other exception occurs.
*/
Object getProcessInstanceVariable(ProcessInstanceUUID instanceUUID,
String variableId) throws InstanceNotFoundException, VariableNotFoundException;
/**
* Obtains the process variables for the given process instance UUID.
* An empty map is returned if no process variable is found.
* @param instanceUUID the instance UUID.
* @return the map of process variables where key is the variable id and value is the variable object.
* @throws InstanceNotFoundException if no instance has been found with the given instance UUID.
* @throws BonitaInternalException if an other exception occurs.
*/
Map getProcessInstanceVariables(ProcessInstanceUUID instanceUUID) throws InstanceNotFoundException;
/**
* Obtains the comment feed of a ProcessInstance.
* An empty List is returned if the Process has no feed.
* @param instanceUUID the instance UUID
* @return the list of the comments
* @throws InstanceNotFoundException if no instance was found with the given instance UUID.
*/
List getCommentFeed(ProcessInstanceUUID instanceUUID) throws InstanceNotFoundException;
/**
* return true if the given task is READY and :
* - if the task is assigned: if the assigned user is the logged user
* - if the task is not assigned: if the logged user is in the candidates list
* @param taskUUID
* @return
* @throws TaskNotFoundException
*/
boolean canExecuteTask(ActivityInstanceUUID taskUUID) throws TaskNotFoundException;
/**
* Returns all instances started by the logged user
*/
Set getUserInstances();
/**
* returns all new process instances in which the logged user is concerned:
* if at least one task (executed or not):
* - is assigned to the logged user
* - is not assined and the logged user is in the candidates list
* For all returned instances, the given labels are added to the label list.
* @param labelIds
* @return
*/
Set getNewWebProcessInstances(Collection labelIds);
Set getWebProcessInstances(String labelId);
Map getAttachments(ProcessInstanceUUID instanceUUID);
Map getAttachments(ProcessInstanceUUID instanceUUID, Set attachmentNames);
byte[] getAttachment(ProcessInstanceUUID instanceUUID, String attachmentName);
}