Flowable 6.6.0 Eclipse设计器 - 5.扩展Flowable设计器 - 5.2图验证及自定义输出格式

Flowable 6.6.0 用户指南相关文档下载

• BPMN用户指南 第一部分 - 中文PDF精编版
• BPMN用户指南 第二部分 - 中文PDF精编版
• BPMN用户指南 第三部分 - 中文PDF精编版
• 应用程序指南 - 中文PDF精编版
• 应用程序指南 - 中英对照PDF精编版
• 应用程序指南 - Eclipse设计器中文PDF精编版
• 表单用户指南 - 中文PDF精编版
• 事件注册表用户指南 - 中文PDF精编版

有关Flowable文档的其他资料，参见：

《Flowable文档大全》

---

《Flowable 6.6.0 Eclipse设计器》

1 安装（Installation）

2 Flowable 设计器编辑器特性（Flowable Designer editor features）

3 Flowable设计器BPMN 特性（Flowable Designer BPMN features）

4 Flowable设计器部署特性（Flowable Designer deployment features）

5 扩展Flowable设计器（Extending Flowable Designer）

• 5.1 定制调色板（Customizing the palette）

  • 5.1.1 扩展设置（Eclipse/Maven）Extension setup (Eclipse/Maven)

  • 5.1.2 在Flowable设计器中应用扩展（Applying your extension to Flowable Designer）

  • 5.1.3 向调色板增加形状（Adding shapes to the palette）

  • 5.1.4 配置自定义服务任务的运行时执行（Configuring runtime execution of Custom Service Tasks）

  • 5.1.5 属性类型（Property types）

  • 5.1.6 禁用调色板的缺省形状（Disabling default shapes in the palette）

• 5.2 图验证及自定义输出格式（Validating diagrams and exporting to custom output formats）

---

5 扩展Flowable设计器（Extending Flowable Designer）

5.1 定制调色板（Customizing the palette）

5.2 图验证及自定义输出格式（Validating diagrams and exporting to custom output formats）

Besides customizing the palette, you can also create extensions to Flowable Designer that can perform validations and save information from the diagram to custom resources in the Eclipse workspace. There are built-in extension points for doing this and this section explains how to use them.

除了定制调色板之外，您还可以创建Flowable设计器的扩展，这些扩展可以执行验证，并将图中的信息保存到Eclipse工作区中的自定义资源中。有内置的扩展点来完成这项工作，本节将介绍如何使用它们。

Note
The ExportMarshaller functions were reintroduced recently. We are still working on the validation functionality. The documentation below details the old behavior and will be updated when the new functionality is available.

注意
最近重新引入了ExportMarshaller函数。我们仍在研究验证功能。下面的文档详细说明了旧的行为，并可能在新功能可用时进行更新。

Flowable Designer allows you to write extensions that validate diagrams. There are already validations of BPMN constructs in the tool by default, but you can add your own if you want to validate additional items, such as modeling conventions or the values in properties of CustomServiceTasks. These extensions are known as Process Validators.

Flowable设计器允许您编写验证图的扩展。默认情况下，工具中已存在BPMN构造的验证，但是如果您想验证其他项，例如建模约定或CustomServiceTasks属性中的值，您可以添加自己的验证。这些扩展被称为流程验证器（Process Validator）。

You can also customize Flowable Designer to publish to additional formats when saving diagrams. These extensions are called Export Marshallers and are invoked automatically by Flowable Designer on each save action by the user. This behavior can be enabled or disabled by setting a preference in Eclipse’s preferences dialog for each format for which there is an extension detected. Designer will make sure your ExportMarshaller is invoked when saving the diagram, depending on the user’s preference.

您还可以自定义Flowable设计器，以便在保存图表时发布为其他格式。这些扩展称为Export Marshaller，并在用户的每个保存操作上由Flowable设计器自动调用。通过在Eclipse的preferences对话框中为每个检测到扩展的格式设置一个首选项，可以启用或禁用此行为。设计器将确保在保存图时调用ExportMarshaller，具体取决于用户的首选项。

Often, you will want to combine a ProcessValidator and an ExportMarshaller. Let’s say you have a number of CustomServiceTasks in use that have properties you would like to use in the process that gets generated. However, before the process is generated, you want to validate some of those values first. Combining a ProcessValidator and ExportMarshaller is the best way to accomplish this and Flowable Designer enables you to plug your extensions into the tool seamlessly.

通常，您需要组合ProcessValidator和ExportMarshaller。假设您正在使用许多CustomServiceTasks，这些任务具有您希望在生成的流程中使用的属性。但是，在生成流程之前，您需要首先验证其中的一些值。结合ProcessValidator和ExportMarshaller是实现这一点的最佳方法，而Flowable 设计器使您能够无缝地将扩展插入到工具中。

To create a ProcessValidator or an ExportMarshaller, you need to create a different kind of extension than for extending the palette. The reason for this is simple: from your code you will need access to more APIs than those that are offered by the integration library. In particular, you will need classes that are available in Eclipse itself. So to get started, you should create an Eclipse plugin (which you can do by using Eclipse’s PDE support) and package it in a custom Eclipse product or feature. It’s beyond the scope of this user guide to explain all the details involved in developing Eclipse plugins, so the instructions below are limited to the functionality for extending Flowable Designer.

要创建ProcessValidator或ExportMarshaller，需要创建与调色板不同的扩展类型的扩展。原因很简单：从您的代码中，您将需要访问超出集成库提供范围的API。特别是，您将需要在Eclipse中可用的类。因此，首先，您应该创建一个Eclipse插件（可以通过使用Eclipse的PDE支持来实现），并将其打包到一个定制的Eclipse产品或特性中。解释开发Eclipse插件所涉及的所有细节超出了本用户指南的范围，因此下面的说明仅限于扩展Flowable设计器的功能。

Your bundle should be dependent on the following libraries:

绑定应依赖于以下库：

• org.eclipse.core.runtime
• org.eclipse.core.resources
• org.flowable.designer.eclipse
• org.flowable.designer.libs
• org.flowable.designer.util

Optionally, the org.apache.commons.lang bundle is available through Designer if you’d like to use that in your extension.

或者org.apache.commons.lang绑定可以通过Designer获得，如果您想在扩展中使用它。

Both ProcessValidators and ExportMarshallers are created by extending a base class. These base classes inherit some useful methods from their superclass, the AbstractDiagramWorker class. Using these methods you can create information, warning and error markers that show up in Eclipse’s problems view for the user to figure out what’s wrong or important. You can get to information about the diagram in the form of Resources and InputStreams. This information is provided from the DiagramWorkerContext, which is available from the AbstractDiagramWorker class.

ProcessValidator和ExportMarshaller都是通过扩展基类创建的。这些基类从它们的超类AbstractDiagramWorker类继承一些有用的方法。使用这些方法，您可以创建在Eclipse的problems视图中显示的信息、警告和错误标记（information, warning and error marker），以便用户找出哪些是错误的或哪些是重要的。您可以以Resources和InputStreams的形式获取有关图的信息。此信息从DiagramWorkerContext提供，可从AbstractDiagramWorker类获得。

It’s probably a good idea to invoke clearMarkers() as one of the first things you do in either a ProcessValidator or an ExportMarshaller; this will clear any previous markers for your worker (markers are automatically linked to the worker and clearing markers for one worker leaves other markers untouched). For example:

在ProcessValidator或ExportMarshaller中，作为首先完成的工作之一，调用clearMarkers()可能是个好主意；这将清除您的工作线程（worker）之前的所有标记（marker）（标记将自动链接到工作线程（worker），清除一个工作线程（worker）的标记（marker）不会影响其他标记）。例如：

// Clear markers for this diagram first
clearMarkersForDiagram();

You should also use the progress monitor provided (in the DiagramWorkerContext) to report your progress back to the user, because validations and marshalling actions can take up some time during which the user is forced to wait. Reporting progress requires some knowledge of how you should use Eclipse’s features. Take a look at this article for a thorough explanation of the concepts and usage.

您还应该使用提供的进度监视器（在DiagramWorkerContext中）向用户报告您的进度，因为验证（validations）和集结（marshalling）操作可能会占用一些时间，在此期间用户被迫等待。报告进度需要了解如何使用Eclipse的特性。请参阅本文（this article），以获得对概念和用法的全面解释。

5.2.1 创建ProcessValidator 扩展（Creating a ProcessValidator extension）

Create an extension to the org.flowable.designer.eclipse.extension.validation.ProcessValidator extension point in your plugin.xml file. For this extension point, you are required to subclass the AbstractProcessValidator class.

创建一个plugin.xml文件中 org.flowable.designer.eclipse.extension.validation.ProcessValidator扩展点的扩展。对于这个扩展点，您需要创建AbstractProcessValidator类的子类。

<?eclipse version="3.6"?>
<plugin>
  <extension
    point="org.flowable.designer.eclipse.extension.validation.ProcessValidator">
    <ProcessValidator
      class="org.acme.validation.AcmeProcessValidator">
    </ProcessValidator>
  </extension>
</plugin>

public class AcmeProcessValidator extends AbstractProcessValidator {
}

You have to implement a number of methods. Most importantly, implement getValidatorId() so you return a globally unique ID for your validator. This will enable you to invoke it from an ExportMarshaller, or even let someone else invoke your validator from their ExportMarshaller. Implement getValidatorName() and return a logical name for your validator. This name is shown to the user in dialogs. In getFormatName(), you can return the type of diagram the validator typically validates.

你必须实现一些方法。最重要的是，实现getValidatorId()，以便为验证器返回全局唯一的ID。这将使您能够从ExportMarshaller调用它，甚至允许其他人从他们的ExportMarshaller调用您的验证器。实现getValidatorName()并返回验证器的逻辑名称。此名称将在对话框中显示给用户。在getFormatName()中，可以返回验证器典型验证的图类型。

The validation work itself is done in the validateDiagram() method. From this point on, it’s up to your specific functionality as to what you code here. Typically, however, you will want to start by getting hold of the nodes in the diagram’s process, so you can iterate through them, collect, compare and validate data. This snippet shows you how to do this:

验证工作本身是在validateDiagram()方法中完成的。从这一点开始，取决于您在这里编写什么代码的特定功能。然而，通常情况下，您将希望从获得图的流程中的节点开始，这样您就可以遍历它们，收集、比较和验证数据。此代码片段向您演示如何执行此操作：

final EList<EObject> contents = getResourceForDiagram(diagram).getContents();
for (final EObject object : contents) {
  if (object instanceof StartEvent ) {
  // Perform some validations for StartEvents
  }
  // Other node types and validations
}

Don’t forget to invoke addProblemToDiagram() and/or addWarningToDiagram(), and so on as you go through your validations. Make sure you return a correct boolean result at the end to indicate whether you consider the validation as having succeeded or failed. This can be used by invoking ExportMarshaller to determine the next course of action.

在进行验证时，不要忘记调用addProblemToDiagram()和/或addWarningToDiagram()，等等。请确保在结尾处返回正确的布尔值结果，以指示您认为验证是成功的还是失败的。调用ExportMarshaller使用这个结果来确定下一个动作。

5.2.2 创建ExportMarshaller 扩展（Creating an ExportMarshaller extension）

Create an extension to the org.flowable.designer.eclipse.extension.ExportMarshaller extension point in your plugin.xml file. For this extension point, you are required to subclass the AbstractExportMarshaller class. This abstract base class provides you with a number of useful methods when marshalling to your own format, but most importantly, it allows you to save resources to the workspace and to invoke validators.

创建一个plugin.xml文件的org.flowable.designer.eclipse.extension.ExportMarshaller扩展。对于这个扩展点，您需要创建AbstractExportMarshaller类的子类。这个抽象基类在集结（marshalling）为自己的格式时为您提供了许多有用的方法，但最重要的是，它允许您将资源保存到工作区并调用验证器
。
An example implementation is available in Designer’s examples folder. This example shows how to use the methods in the base class to get the basics done, such as accessing the diagram’s InputStream, using its BpmnModel and saving resources to the workspace.

在设计器的examples文件夹中可以找到示例实现。这个例子展示了如何使用基类中的方法来完成基础工作，比如访问图的InputStream，使用它的BpmnModel，以及将资源保存到工作区。

<?eclipse version="3.6"?>
<plugin>
  <extension
    point="org.flowable.designer.eclipse.extension.ExportMarshaller">
    <ExportMarshaller
      class="org.acme.export.AcmeExportMarshaller">
    </ExportMarshaller>
  </extension>
  </plugin>

public class AcmeExportMarshaller extends AbstractExportMarshaller {
}

You are required to implement some methods, such as getMarshallerName() and getFormatName(). These methods are used to display options to the user and to show information in progress dialogs, so make sure the descriptions you return reflect the functionality you are implementing.
The bulk of your work is performed in the doMarshallDiagram() method.

您需要实现一些方法，例如getMarshallerName()和getFormatName()。这些方法用于向用户显示选项，并在进度对话框中显示信息，因此请确保返回的描述反映了正在实现的功能。
大部分工作是在doMarshallDiagram ()方法中执行的。

If you want to perform a certain validation first, you can invoke the validator directly from your marshaller. You receive a boolean result from the validator, so you know whether validation succeeded. In most cases you won’t want to proceed with marshalling the diagram if it’s not valid, but you might choose to go ahead anyway or even create a different resource if validation fails.

如果需要首先执行某个验证，可以直接从集结处理程序（marshaller）调用验证器（validator）。您从验证器（validator）收到一个布尔结果，因此您知道验证是否成功。在大多数情况下，如果图无效，您将不希望继续进行集结处理（marshalling），但是您可以选择继续进行，或者在验证失败时创建其他资源。

Once you have all the data you need, you should invoke the saveResource() method to create a file containing your data. You can invoke saveResource() as many times as you wish from a single ExportMarshaller; a marshaller can therefore be used to create more than one output file.

一旦你拥有了所有需要的数据，您就需要调用saveResource()来创建包含你的数据的文件。您可以根据需要从一个ExportMarshaller调用saveResource()多次，因为一个marshaller可以用来创建多个输出文件。

You can construct a filename for your output resource(s) by using the saveResource() method in the AbstractDiagramWorker class. There are a couple of useful variables you can have substituted, allowing you to create filenames such as _original-filename__my-format-name.xml. These variables are described in the Javadocs and defined by the ExportMarshaller interface. You can also use resolvePlaceholders() on a string (for example, a path) if you want to substitute the placeholders yourself. getURIRelativeToDiagram() will invoke this for you.

可以使用AbstractDiagramWorker类中的saveResource()方法为您的输出资源构造一个文件名。有几个有用的变量可以替换，允许您创建文件名，例如_original-filename__my-format-name.xml。这些变量在Javadocs中描述，并由ExportMarshaller接口定义。如果要自己替换占位符，也可以对字符串（例如路径）使用resolvePlaceholders ()。getURIRelativeToDiagram ()将为您调用此函数。

You should use the progress monitor provided to report your progress back to the user. How to do this is described in this article.

您应该使用提供的进度监视器向用户报告进度。此文（this article）将介绍如何做到这一点。