嵌入式工作流客户端接口文档.docx

4 工作流客户端文档
Business Key
Business Key是业务系统中用来标识一个流程实例的标识，工作流系统使用该标识可以找到相应的流程实例。例如在检察院系统中，是案件编号。业务系统在创建流程实例时将将值赋予创建的流程实例，以后每次都使用该值于工作流交互，工作流可以找到对应的流程实例。
Business Key在工作流中，作为一个流程实例变量存储在数据库中。工作流中的变量包括变量名、类型和值这些属性。配置一个作为Business Key的变量，需要指定变量名称和类型，供工作流系统使用。

配置business key示例如下：
<bean id="businessKey" class="com.thunisoft.wf.core.jbpm.businesskey.BusinessKeyImpl">
<property name="keyName"><value>ajbh</value></property>
<property name="keyType"><value>java.lang.String</value></property>
</ bean >
说明：
需要配置Business Key 的变量名称，Business Key的Java类型(keyType)。目前支持的Java类型包括：
n String，
n Long,
n Double
接口说明：
接口列表中，对流程依赖比较严重而不建议使用的接口排在后面。
获取工作流接口：
嵌入式工作流接口： com.thunisoft.wf.embedded. WorkflowFacade;
这个接口是嵌入式工作流的一个门面，集成了嵌入式工作流提供的相关服务集合。
可以通过下面这个静态方法获取工作流façade:
com.thunisoft.wf.embedded.WorkflowHelper.getWorkflowFacade();

关于工作流接口的准确定义和详细情况，请参考javadoc，在这里指出的是一个概要情况。UML图示如下：

流程实例相关接口：
开始新流程实例
/**
* create a new process instance, if instance has no start task, signal instance
* to leave the start state.<br>
*
* if contextVariables contains a key equals Business key, it should be covered.
*
* @param workflowName Process Definition name to create new instance
* @param keyValue Value of the new ProcessInstance Business key
* @param contextVariables Context variables for the new process instance
* @return Id of the new process instance , If failed, return null
* @throws WorkflowException
* @throws {@link IllegalArgumentException} If workflowName or keyValue is null,
* or key value's type is error.
*/
public Long startProcessInstance(String workflowName, Object keyValue,
Map contextVariables) throws WorkflowException;

流程实例变量管理
存放在流程实例Context内的变量，在整个流程实例范围内可见。
获取给定流程实例全流程范围内的变量
/**
* Get all variables stored in process instance context
* @param keyValue
* @return
* @throws WorkflowException
*/
public Map getProcessContextVarialbes(Object keyValue) throws WorkflowException;

增加变量到流程实例Context中：
一次增加多个流程变量：
/**
* Add variables to process context. If a variable is already exists, replace it
* @param keyValue
* @param variables Variables map, use key as variable name, value as variable value
* @throws WorkflowException
*/
public void addProcessVariable(Object keyValue, Map variables)
throws WorkflowException;

增加一个流程变量：（不要调用多次来代替上一个接口的功能）
/**
* Add a variable to process instance context
* @param keyValue Business key value
* @param name Variable name
* @param value Variable value
* @throws WorkflowException
* @throws IllegalArgumentException If name or value is null
*/
public void addProcessVarialbe(Object keyValue, String name, Object value) throws WorkflowException;
暂停执行流程实例
/**
* resume a process instance
* @param keyValue
* @throws WorkflowException
*/
public void resumeProcessInstance(Object keyValue) throws WorkflowException;
获取当前流程实例状态名称
/**
* Get name of current state
* @param keyValue Business key value
* @return Name of current state, or null if no matched process instance
* @throws WorkflowException
*/
public String getCurrentStateName(Object keyValue) throws WorkflowException;
流程跳转：【不建议使用】
通常情况下，流程跳转一般应该采用工作流中配置来完成，而不适宜通过业务系统调用下面的接口来完成。因为这使得业务系统代码强制性依赖于工作流程，从而显示流程流转逻辑的变化。相似的功能，可以通过在工作流定义中增加Action来完成。
沿默认路径跳转
/**
* singal process instance to next state, taking default transition
*
* @param keyValue Value of business key
* @return if no trace, return empty list
*/
public void singalProcessInstance(Object keyValue) throws WorkflowException;

沿给定路径跳转
/**
* signal process instance to next state, taking gived transition
*
* @param keyValue
* @param transition Transition name, if null, taking default transition
* @throws WorkflowException If transition is inexistent
*/
public void signalProcessInstance(Object keyValue, String transition)
throws WorkflowException;

分支沿默认路径跳转
/**
* signal a branch of process instance, taking default transition
* @param keyValue
* @param token Token path of the branch, If null ,take root token as default
* @throws WorkflowException
*/
public void signalProcessInstanceBranch(Object keyValue, String token)
throws WorkflowException;

分支沿着给定路径跳转

/**
* signal a branch of process instance, take gived transition
* @param keyValue
* @param token Token path of branch
* @param transition Transition name, if null, taking default transition
* @throws WorkflowException If transition is inexistent
*/
public void signalProcessInstanceBranch(Object keyValue, String token,
String transition) throws WorkflowException;

任务管理相关接口方法：

获取给定流程当前状态可以创建实例的任务：
返回的是可以创建的任务名称组成的列表。
/**
* Get task name of tasks on current state
* @param keyValue
* @return To do tasks on current state
* @throws WorkflowException
*/
public List getTodoTasks(Object keyValue) throws WorkflowException;

获取给定流程的历史任务实例：
/**
* get process instance history trace, all the task instance be wrapped with
* {@link Trace} object,any task instance has been started should be loaded
* order by create-time ASC
* @param keyValue Value of business key
* @return if no trace, return empty list
*/
public List getHistoryTraces(Object keyValue)
throws WorkflowException;

在给定流程当前状态上创建新任务实例：
/**
* Create a new task of given task on current state.
* @param keyValue
* @param taskName Task name
* @return Id of created task instance
* @throws WorkflowException If current state has no gived task
*/
public Long createTaskInstance(Object keyValue, String taskName)
throws WorkflowException;

结束一个任务（保存任务实例变量）
/**
* End given task instance, and save variables for given task instance
* @param taskInstanceId
* @param variable Variables to save
* @throws WorkflowException
*/
public void commitTaskInstance(Long taskInstanceId, Map variable)
throws WorkflowException;

结束一个任务（无变量）
/**
* End given task instance
* @param taskInstanceId
*/
public void commitTaskInstance(Long taskInstanceId);

保存任务实例
/**
* save the taskInstanceId, and add the variables to taskInstance
* @param taskInstanceId
* @param variables
* @throws WorkflowException
* @throws If taskInstanceId is null
*/
public void saveTaskInstance(Long taskInstanceId, Map variables)
throws WorkflowException;

取消任务实例
/**
* Cancel a unfinished task instance
* @param taskInstanceId
* @param variable
* @throws WorkflowException If task instance is finished
*/
public void cancelTaskInstance(Long taskInstanceId)
throws WorkflowException;

删除任务实例（不提供）
/**
* Delete given task instance
*
* @param taskInstanceId
* @return
* @throws WorkflowException
*/
public Long deleteTaskInstance(Long taskInstanceId)
throws WorkflowException;

在任意状态上创建任务实例【不建议使用】
/**
* Create a new instance of given task on given state
*
* @param keyValue Business key value
* @param stateName State name
* @param taskName Task name
* @param variable Variables to store in the new task instance
* @return Id of created task instance
* @throws WorkflowException
*/
public Long commitSpecialTaskInstance(Object keyValue, String stateName,
String taskName, Map variable) throws WorkflowException;
}