概述

注意：本文中 Activiti 的版本为 5.22，为 5.X 系列的最后一个 RELEASE 版本。目前 Activiti 已经发展到了 7.X 版本，为啥还用 5.X 版本，还是存量项目的原因。

我们的需求是将 Activiti 官网的 Demo 的流程设计器功能整合到我们项目中，主要需要的功能是 Web 流程设计器 —— Activiti Modeler。Web 流程设计器的查找和保存功能是使用了 RestFul API 调用的，将源码中的 editor-app 引入再定制化改造即可。除了查找和保存之外，我们还需要查询流程图列表、新建流程图、删除流程图等功能，可是发现这部分并没有使用 RestFul API，这几个功能是在后台实现的，需要阅读源码查看这几个功能如何实现。

在阅读源码发现 Activiti 在前端 Demo 部分还是比较混乱，前后端严重耦合，现在理清如下：

Activiti Webapp Explorer：指的是官方的 Demo Webapp 工程
Activiti Explorer：主要使用 vaadin 来渲染 Activiti Webapp Explorer 中的页面
Activiti Modeler： Web 端流程设计器，后端项目只有 3 个类提供 RestFul 接口，而前端项目则放到了Activiti Webapp Explorer 工程中，使用的是 AngularJS，Activiti Modeler 在 Activiti@5.17 版本由 Alfresco Activiti Enterprise 捐赠。
Diagram Viewer: Activiti 官方在 5.12 版本中添加的新组件,以 Raphaël 为基础库，用 REST 方式(从 Activiti - Diagram - REST 模块)获取 JSON 数据生成流程图并把流程的处理过程用不同的颜色加以标注。

Activiti Webapp Explorer

Activiti Explorer的 Webapp 工程在源码中的位置为 modules/activiti-webapp-explorer2/src/main/webapp，这个工程是官方Demo的核心工程。

比较奇怪的是这个 module 在 pom 文件中的 name 为 Activiti - Webapp - Explorer V2,而整个工程并没有 V1 版本，而且这个 module 没有放到 activiti-explorer 中，而是独立开来，在 pom.xml 文件中依赖了 activiti-explorer。

主要的 activiti 相关依赖：

activiti-engine
activiti-spring
activiti-explorer
activiti-modeler
activiti-diagram-rest
activiti-simple-workflow

查看 web.xml 文件：

Listener

首先添加了一个 WebConfigurer 的 listener 用来加载 Spring context：

<!-- To load the Spring context -->
<listener>
	<listener-class>org.activiti.explorer.servlet.WebConfigurer</listener-class>
</listener>

WebConfigurer 中配置了一个 mapping 用来相应相关的 REST 请求：

...
dispatcherServlet.addMapping("/service/*");
...

第二个 listener 用来支持 Spring Beans 的 session-scoped 作用域：

<!-- To allow session-scoped beans in Spring -->
<listener>
	<listener-class>org.springframework.web.context.request.RequestContextListener</listener-class>
</listener>

Filter

定义了两个 filter

第一个 filter 为 ExplorerFilter

<filter>
	<filter-name>UIFilter</filter-name>
	<filter-class>org.activiti.explorer.filter.ExplorerFilter</filter-class>
</filter>
...
<filter-mapping>
	<filter-name>UIFilter</filter-name>
	<url-pattern>/*</url-pattern>
</filter-mapping>

查看 ExplorerFilter 类主要做了如下事情：

判断请求地址是否以 "/ui"、"/VAADIN"、"/modeler.html"、"/editor-app"、"/service"、"/diagram-viewer"开头：

若否，则将请求地址添加 "/ui"
若是，判断是否以 "/service" 开头
- 若是，判断用户是否登陆，没登录报错，登陆则继续
- 若否，则继续

第二个 filter 为 JSONPFilter, 对 "/service" 开头的请求进行过滤，处理 jsonp 的请求：

<filter>
    <filter-name>JSONPFilter</filter-name>
    <filter-class>org.activiti.explorer.servlet.JsonpCallbackFilter</filter-class>
</filter>
...
<filter-mapping>
    <filter-name>JSONPFilter</filter-name>
    <url-pattern>/service/*</url-pattern>
</filter-mapping>

servlet

定义了名为 Vaadin Application Servlet 的 servlet，响应 "/ui" 、"/VAADIN" 开头的请求：

<servlet>
	<servlet-name>Vaadin Application Servlet</servlet-name>
	<servlet-class>org.activiti.explorer.servlet.ExplorerApplicationServlet</servlet-class>
	<init-param>
		<param-name>widgetset</param-name>
		<param-value>org.activiti.explorer.CustomWidgetset</param-value>
	</init-param>
</servlet>

<servlet-mapping>
	<servlet-name>Vaadin Application Servlet</servlet-name>
	<url-pattern>/ui/*</url-pattern>
</servlet-mapping>

<servlet-mapping>
	<servlet-name>Vaadin Application Servlet</servlet-name>
	<url-pattern>/VAADIN/*</url-pattern>
</servlet-mapping>

查看 ExplorerApplicationServlet 发现出现了一大段用java拼html片段的代码，主要作用是渲染根据浏览器类型渲染不同的css：

  @Override
  protected void writeAjaxPageHtmlVaadinScripts(Window window, String themeName, Application application, BufferedWriter page, String appUrl, String themeUri,
          String appId, HttpServletRequest request) throws ServletException, IOException {
    super.writeAjaxPageHtmlVaadinScripts(window, themeName, application, page, appUrl, themeUri, appId, request);
    
    String browserDependentCss = "<script type=\"text/javascript\">//<![CDATA[" +
      "var mobi = ['opera', 'iemobile', 'webos', 'android', 'blackberry', 'ipad', 'safari'];" +
      "var midp = ['blackberry', 'symbian'];" +
      "var ua = navigator.userAgent.toLowerCase();" +
      "if ((ua.indexOf('midp') != -1) || (ua.indexOf('mobi') != -1) || ((ua.indexOf('ppc') != -1) && (ua.indexOf('mac') == -1)) || (ua.indexOf('webos') != -1)) {" +
      "  document.write('<link rel=\"stylesheet\" href=\"" + themeUri +"/allmobile.css\" type=\"text/css\" media=\"all\"/>');" +
      "  if (ua.indexOf('midp') != -1) {" +
      "    for (var i = 0; i < midp.length; i++) {" +
      "      if (ua.indexOf(midp[i]) != -1) {" +
      "        document.write('<link rel=\"stylesheet\" href=\"" + themeUri +"' + midp[i] + '.css\" type=\"text/css\"/>');" +
      "      }" +
      "    }"+
      "  }" +
     "   else {"+
     "     if ((ua.indexOf('mobi') != -1) || (ua.indexOf('ppc') != -1) || (ua.indexOf('webos') != -1)) {" +
     "       for (var i = 0; i < mobi.length; i++) {" +
     "         if (ua.indexOf(mobi[i]) != -1) {" +
     "           if ((mobi[i].indexOf('blackberry') != -1) && (ua.indexOf('6.0') != -1)) {" +
     "             document.write('<link rel=\"stylesheet\" href=\"" + themeUri + "' + mobi[i] + '6.0.css\" type=\"text/css\"/>');" +
     "           }" +
     "           else {" +
     "             document.write('<link rel=\"stylesheet\" href=\"" + themeUri + "' + mobi[i] + '.css\" type=\"text/css\"/>');" +
     "           }" +
     "          break;" +
     "         }" +
     "       }" +
     "     }" +
     "   }" +
     " }" +
     "if ((navigator.userAgent.indexOf('iPhone') != -1) || (navigator.userAgent.indexOf('iPad') != -1)) {" +
     " document.write('<meta name=\"viewport\" content=\"width=device-width\" />');" +
    "}" +
    "  //]]>" +
    "</script>" +
    "<!--[if lt IE 7]><link rel=\"stylesheet\" type=\"text/css\" href=\"" + themeUri + "/lt7.css\" /><![endif]-->";
    
    page.write(browserDependentCss);
  }

从下面代码可以看出，整个前端页面由ExplorerApp 来渲染：

  @Override
  protected Class< ? extends Application> getApplicationClass() throws ClassNotFoundException {
    return ExplorerApp.class;
  }

  @Override
  protected Application getNewApplication(HttpServletRequest request) {
    return (Application) applicationContext.getBean(ExplorerApp.class);
  }

至此，终于找到了Activiti App的页面入口 ExplorerApp

Activiti App的页面入口 `ExplorerApp`

初始化显示Login页面：

  public void init() {
    setMainWindow(mainWindow);
    mainWindow.showLoginPage();
  }

页面与类的对应关系：

登陆页面：LoginPage
主页面布局：MainLayout
已部署流程定义：ProcessDefinitionPage
流程设计工作区：EditorProcessDefinitionPage

已部署流程定义：`ProcessDefinitionPage`

主要关注 4 个功能的代码：

查询已部署的流程定义的列表
启动流程
转换为可编辑模型？（有一些是禁用的）
根据流程定义ID查询流程定义信息

1、查询已部署的流程定义的列表

主要查询的代码如下：

  // DefaultProcessDefinitionFilter.java
  ...
  public ProcessDefinitionQuery getQuery(RepositoryService repositoryService) {
    return getBaseQuery(repositoryService)
            .orderByProcessDefinitionName().asc()
            .orderByProcessDefinitionKey().asc(); // name is not unique, so we add the order on key (so we can use it in the comparsion of ProcessDefinitionListItem)
  }
  ...
  protected ProcessDefinitionQuery getBaseQuery(RepositoryService repositoryService) {
    return repositoryService
            .createProcessDefinitionQuery()
            .latestVersion()
            .active();
  }
  ...

获取到了 ProcessDefinitionQuery 就可以获取 ProcessDefinition 列表：


List<ProcessDefinition> processDefinitions = processDefinitionQuery.listPage(start, count);

processDefinition 的结构如下：

2、启动流程

需要注意的是，在启动流程还增加了一个判断 process-definition 是否定义了一个 start-form，由于在我们实际使用中不会使用到 start-form，所以我们在改写这块功能的时候增加一个能否发布的判断：是否存在 start-form，若存在，则不能启动；后面的启动后判断当前用户是否存在该流程的任务功能可以忽略。

// StartProcessInstanceClickListener.java

public void buttonClick(ClickEvent event) {
    // Check if process-definition defines a start-form
    
    StartFormData startFormData = formService.getStartFormData(processDefinition.getId());
    if(startFormData != null && ((startFormData.getFormProperties() != null && !startFormData.getFormProperties().isEmpty()) || startFormData.getFormKey() != null)) {
      parentPage.showStartForm(processDefinition, startFormData);
    } else {
      // Just start the process-instance since it has no form.
      // TODO: Error handling
      ProcessInstance processInstance = runtimeService.startProcessInstanceById(processDefinition.getId());
      
      // Show notification of success
      notificationManager.showInformationNotification(Messages.PROCESS_STARTED_NOTIFICATION, getProcessDisplayName(processDefinition));
      
      // Switch to inbox page in case a task of this process was created
      List<Task> loggedInUsersTasks = taskService.createTaskQuery()
        .taskAssignee(ExplorerApp.get().getLoggedInUser().getId())
        .processInstanceId(processInstance.getId())
        .list();
      if (!loggedInUsersTasks.isEmpty()) {
        ExplorerApp.get().getViewManager().showInboxPage(loggedInUsersTasks.get(0).getId());
      }
    }
  }

TODO：判断是否能够启动流程逻辑：

已经启动过的流程不能再启动；
存在start-form，若存在不能启动

3、转换为可编辑模型

能否转换为可编辑模块逻辑：

// ProcessDefinitionDetailPanel.java

    if(((ProcessDefinitionEntity) processDefinition).isGraphicalNotationDefined() == false) {
      editProcessDefinitionButton.setEnabled(false);
    }

需要注意的是转换需要弹窗让用户二次确认

转换逻辑：


// ConvertProcessDefinitionPopupWindow.java

        try {
          InputStream bpmnStream = repositoryService.getResourceAsStream(processDefinition.getDeploymentId(), processDefinition.getResourceName());
          XMLInputFactory xif = XmlUtil.createSafeXmlInputFactory();
          InputStreamReader in = new InputStreamReader(bpmnStream, "UTF-8");
          XMLStreamReader xtr = xif.createXMLStreamReader(in);
          BpmnModel bpmnModel = new BpmnXMLConverter().convertToBpmnModel(xtr);
          
          if (bpmnModel.getMainProcess() == null || bpmnModel.getMainProcess().getId() == null) {
            notificationManager.showErrorNotification(Messages.MODEL_IMPORT_FAILED, 
                i18nManager.getMessage(Messages.MODEL_IMPORT_INVALID_BPMN_EXPLANATION));
          } else {
          
            if (bpmnModel.getLocationMap().isEmpty()) {
              notificationManager.showErrorNotification(Messages.MODEL_IMPORT_INVALID_BPMNDI,
                  i18nManager.getMessage(Messages.MODEL_IMPORT_INVALID_BPMNDI_EXPLANATION));
            } else {
          
              BpmnJsonConverter converter = new BpmnJsonConverter();
              ObjectNode modelNode = converter.convertToJson(bpmnModel);
              Model modelData = repositoryService.newModel();
              
              ObjectNode modelObjectNode = new ObjectMapper().createObjectNode();
              modelObjectNode.put(MODEL_NAME, processDefinition.getName());
              modelObjectNode.put(MODEL_REVISION, 1);
              modelObjectNode.put(MODEL_DESCRIPTION, processDefinition.getDescription());
              modelData.setMetaInfo(modelObjectNode.toString());
              modelData.setName(processDefinition.getName());
              
              repositoryService.saveModel(modelData);
              
              repositoryService.addModelEditorSource(modelData.getId(), modelNode.toString().getBytes("utf-8"));
              
              close();
              ExplorerApp.get().getViewManager().showEditorProcessDefinitionPage(modelData.getId());

	          URL explorerURL = ExplorerApp.get().getURL();
	          URL url = new URL(explorerURL.getProtocol(), explorerURL.getHost(), explorerURL.getPort(),
			          explorerURL.getPath().replace("/ui", "") + "modeler.html?modelId=" + modelData.getId());
              ExplorerApp.get().getMainWindow().open(new ExternalResource(url));
            }
          }
          
        } catch(Exception e) {
          notificationManager.showErrorNotification("error", e);
        }

4、根据流程定义ID查询流程定义信息

分为两种：

通过 rest 接口获取流程 diagram 信息，并通过 Diagram Viewer 模块渲染图标
直接获取图片

方式一：通过 rest 接口获取流程 diagram 信息

// ProcessDefinitionDiagramLayoutResource.java

@RestController
public class ProcessDefinitionDiagramLayoutResource extends BaseProcessDefinitionDiagramLayoutResource {

  @RequestMapping(value="/process-definition/{processDefinitionId}/diagram-layout", method = RequestMethod.GET, produces = "application/json")
  public ObjectNode getDiagram(@PathVariable String processDefinitionId) {
    return getDiagramNode(null, processDefinitionId);
  }
}

！注意获取 processDefinition 和 deployment 的方法：

// AbstractProcessDefinitionDetailPanel.java
// Members
  protected ProcessDefinition processDefinition;
  protected Deployment deployment;

    this.processDefinition = repositoryService.getProcessDefinition(processDefinitionId);

    if(processDefinition != null) {
      deployment = repositoryService.createDeploymentQuery().deploymentId(processDefinition.getDeploymentId()).singleResult();
    }

方式二：直接获取图片

// ProcessDefinitionInfoComponent.java

StreamResource diagram = null;
      
      // Try generating process-image stream
      if(processDefinition.getDiagramResourceName() != null) {
         diagram = new ProcessDefinitionImageStreamResourceBuilder()
          .buildStreamResource(processDefinition, repositoryService);
      }

流程设计工作区：`EditorProcessDefinitionPage`

主要关注 8 个功能的代码：

查询流程设计工作区模型列表
根据模型Id获取模型信息
新建模型
删除模型
部署模型
导入模型
导出模型
查询左侧stencilset列表信息

1、查询流程设计工作区模型列表

获取列表方法：

List<Model> modelList = repositoryService.createModelQuery().list();

Model的结构如下：

2、根据模型Id获取模型信息

// ModelEditorJsonRestResource.java


@RequestMapping(value="/model/{modelId}/json", method = RequestMethod.GET, produces = "application/json")
  public ObjectNode getEditorJson(@PathVariable String modelId) {
    ObjectNode modelNode = null;
    
    Model model = repositoryService.getModel(modelId);
      
    if (model != null) {
      try {
        if (StringUtils.isNotEmpty(model.getMetaInfo())) {
          modelNode = (ObjectNode) objectMapper.readTree(model.getMetaInfo());
        } else {
          modelNode = objectMapper.createObjectNode();
          modelNode.put(MODEL_NAME, model.getName());
        }
        modelNode.put(MODEL_ID, model.getId());
        ObjectNode editorJsonNode = (ObjectNode) objectMapper.readTree(
            new String(repositoryService.getModelEditorSource(model.getId()), "utf-8"));
        modelNode.put("model", editorJsonNode);
        
      } catch (Exception e) {
        LOGGER.error("Error creating model JSON", e);
        throw new ActivitiException("Error creating model JSON", e);
      }
    }
    return modelNode;
  }

3、新建模型


// NewModelPopupWindow.java

    ObjectMapper objectMapper = new ObjectMapper();
    ObjectNode editorNode = objectMapper.createObjectNode();
    editorNode.put("id", "canvas");
    editorNode.put("resourceId", "canvas");
    ObjectNode stencilSetNode = objectMapper.createObjectNode();
    stencilSetNode.put("namespace", "http://b3mn.org/stencilset/bpmn2.0#");
    editorNode.put("stencilset", stencilSetNode);
    Model modelData = repositoryService.newModel();
    
    ObjectNode modelObjectNode = objectMapper.createObjectNode();
    modelObjectNode.put(MODEL_NAME, (String) nameTextField.getValue());
    modelObjectNode.put(MODEL_REVISION, 1);
    String description = null;
    if (StringUtils.isNotEmpty((String) descriptionTextArea.getValue())) {
      description = (String) descriptionTextArea.getValue();
    } else {
      description = "";
    }
    modelObjectNode.put(MODEL_DESCRIPTION, description);
    modelData.setMetaInfo(modelObjectNode.toString());
    modelData.setName((String) nameTextField.getValue());
    
    repositoryService.saveModel(modelData);
    repositoryService.addModelEditorSource(modelData.getId(), editorNode.toString().getBytes("utf-8"));

4、删除模型

repositoryService.deleteModel(modelData.getId());

5、部署模型

// EditorProcessDefinitionDetailPanel.java
protected void deployModelerModel(final ObjectNode modelNode) {
    BpmnModel model = new BpmnJsonConverter().convertToBpmnModel(modelNode);
    byte[] bpmnBytes = new BpmnXMLConverter().convertToXML(model);
    
    String processName = modelData.getName() + ".bpmn20.xml";
    Deployment deployment = repositoryService.createDeployment()
            .name(modelData.getName())
            .addString(processName, new String(bpmnBytes))
            .deploy();

    ExplorerApp.get().getViewManager().showDeploymentPage(deployment.getId());
  }

6、导入模型

参考这段代码：

// ImportUploadReceiver.java
public class ImportUploadReceiver implements Receiver, FinishedListener, ModelDataJsonConstants {
  
  ...

  protected void deployUploadedFile() {
    try {
      try {
        if (fileName.endsWith(".bpmn20.xml") || fileName.endsWith(".bpmn")) {
          validFile = true;
            
          XMLInputFactory xif = XmlUtil.createSafeXmlInputFactory();
          InputStreamReader in = new InputStreamReader(new ByteArrayInputStream(outputStream.toByteArray()), "UTF-8");
          XMLStreamReader xtr = xif.createXMLStreamReader(in);
          BpmnModel bpmnModel = new BpmnXMLConverter().convertToBpmnModel(xtr);
          
          if (bpmnModel.getMainProcess() == null || bpmnModel.getMainProcess().getId() == null) {
            notificationManager.showErrorNotification(Messages.MODEL_IMPORT_FAILED, 
                i18nManager.getMessage(Messages.MODEL_IMPORT_INVALID_BPMN_EXPLANATION));
          } else {
          
            if (bpmnModel.getLocationMap().isEmpty()) {
              notificationManager.showErrorNotification(Messages.MODEL_IMPORT_INVALID_BPMNDI,
                  i18nManager.getMessage(Messages.MODEL_IMPORT_INVALID_BPMNDI_EXPLANATION));
            } else {
            
              String processName = null;
              if (StringUtils.isNotEmpty(bpmnModel.getMainProcess().getName())) {
                processName = bpmnModel.getMainProcess().getName();
              } else {
                processName = bpmnModel.getMainProcess().getId();
              }
              
              modelData = repositoryService.newModel();
              ObjectNode modelObjectNode = new ObjectMapper().createObjectNode();
              modelObjectNode.put(MODEL_NAME, processName);
              modelObjectNode.put(MODEL_REVISION, 1);
              modelData.setMetaInfo(modelObjectNode.toString());
              modelData.setName(processName);
              
              repositoryService.saveModel(modelData);
              
              BpmnJsonConverter jsonConverter = new BpmnJsonConverter();
              ObjectNode editorNode = jsonConverter.convertToJson(bpmnModel);
              
              repositoryService.addModelEditorSource(modelData.getId(), editorNode.toString().getBytes("utf-8"));
            }
          }
        } else {
          notificationManager.showErrorNotification(Messages.MODEL_IMPORT_INVALID_FILE,
          		i18nManager.getMessage(Messages.MODEL_IMPORT_INVALID_FILE_EXPLANATION));
        }
      } catch (Exception e) {
        String errorMsg = e.getMessage().replace(System.getProperty("line.separator"), "<br/>");
        notificationManager.showErrorNotification(Messages.MODEL_IMPORT_FAILED, errorMsg);
      }
    } finally {
      if (outputStream != null) {
        try {
          outputStream.close();
        } catch (IOException e) {
          notificationManager.showErrorNotification("Server-side error", e.getMessage());
        }
      }
    }
  }
  
  protected void showUploadedDeployment() {
    viewManager.showEditorProcessDefinitionPage(modelData.getId());
  }
  
}

7、导出模型

// EditorProcessDefinitionDetailPanel.java

protected void exportModel() {
    final FileResource stream = new FileResource(new File(""), ExplorerApp.get()) {
      
      private static final long serialVersionUID = 1L;

        @Override
        public DownloadStream getStream() {
          DownloadStream ds = null;
          try {
            
            byte[] bpmnBytes = null;
            String filename = null;
            if (SimpleTableEditorConstants.TABLE_EDITOR_CATEGORY.equals(modelData.getCategory())) {
              WorkflowDefinition workflowDefinition = ExplorerApp.get().getSimpleWorkflowJsonConverter()
              		.readWorkflowDefinition(repositoryService.getModelEditorSource(modelData.getId()));
              
              filename = workflowDefinition.getName();
              WorkflowDefinitionConversion conversion = 
                      ExplorerApp.get().getWorkflowDefinitionConversionFactory().createWorkflowDefinitionConversion(workflowDefinition);
              bpmnBytes = conversion.getBpmn20Xml().getBytes("utf-8");
            } else {
            	JsonNode editorNode = new ObjectMapper().readTree(repositoryService.getModelEditorSource(modelData.getId()));
              BpmnJsonConverter jsonConverter = new BpmnJsonConverter();
              BpmnModel model = jsonConverter.convertToBpmnModel(editorNode);
              filename = model.getMainProcess().getId() + ".bpmn20.xml";
              bpmnBytes = new BpmnXMLConverter().convertToXML(model);
            }
           
            ByteArrayInputStream in = new ByteArrayInputStream(bpmnBytes);
            ds = new DownloadStream(in, "application/xml", filename);
            // Need a file download POPUP
            ds.setParameter("Content-Disposition", "attachment; filename=" + filename);
          } catch(Exception e) {
            LOGGER.error("failed to export model to BPMN XML", e);
            ExplorerApp.get().getNotificationManager().showErrorNotification(Messages.PROCESS_TOXML_FAILED, e);
          }
          return ds;
        }
    };
    stream.setCacheTime(0);
    ExplorerApp.get().getMainWindow().open(stream);
  }

8、查询左侧stencilset列表信息

// StencilsetRestResource.java

public class StencilsetRestResource {
  
  @RequestMapping(value="/editor/stencilset", method = RequestMethod.GET, produces = "application/json;charset=utf-8")
  public @ResponseBody String getStencilset() {
    InputStream stencilsetStream = this.getClass().getClassLoader().getResourceAsStream("stencilset.json");
    try {
      return IOUtils.toString(stencilsetStream, "utf-8");
    } catch (Exception e) {
      throw new ActivitiException("Error while loading stencil set", e);
    }
  }
}