扩展点模式编辑器

可以两种方式来打开扩展点模式编辑器: 作为创建新扩展点的副产品,或者通过打开现有的扩展点模式。按照惯例,新模式与扩展点标识具有相同的名称,并且具有文件扩展名 .xsd。它们放置在插件目录树中的模式目录中。

在 PDE 中创建新扩展点时,还将创建初始模式文件, 并会打开模式编辑器以便进行编辑。可以立即定义模式,也可以关闭它,稍后再定义。制作完整的扩展点模式允许 PDE 为您的扩展点的用户提供自动帮助。

PDE 模式编辑器和插件清单编辑器基于相同的概念。它具有两个表单页面和一个源页面。由于 XML 模式很详细,并且它的源表单形式很难阅读, 所以,应该使用表单页面来执行大部分的编辑工作。源页面对于阅读所获得的源代码很有用。

示例:为“样本分析器”扩展点创建模式

先前我们已经创建了“样本分析器”扩展点和初始模式。现在,可以通过进入项目的模式文件夹, 并双击 parsers.xsd 文件来打开模式。这将打开模式编辑器。

我们想要执行下列操作:

  1. 为扩展点定义有效的 XML 元素和属性。
  2. 定义语法(内容模型)。
  3. 提供将合并到参考文档中的文档片段。

每个扩展点模式都是以“扩展”元素的声明开始。我们将添加称为“分析器”的新 XML 元素。

  1. 扩展点元素小节中的新建元素按钮。
  2. 移至“特性”视图,并将它的名称从“新元素”更改为“分析器”。
  3. 在仍然选择了新元素的状态下,按新建属性按钮。这将创建“新属性”来作为它的子代。在特性表中,将它的名称更改为“标识”,将使用更改为“必需”。
  4. 当仍在特性表中时,按本地工具栏上提供的“克隆此属性”按钮。这将创建该属性的副本。这是很有用的,原因是它允许我们快速定义所有属性而无需离开特性表。
  5. 将新属性的名称更改为“名称”。
  6. 再次克隆属性。这一次,将名称更改为“类”。此属性将用来表示必须实现特定 Java 接口的 Java 类的全限定名。需要指定此名称以便 PDE 稍后可以利用它。将种类从“字符串”更改为“Java”。将基于特性设置为 com.example.xyz.IParser。(此接口尚不存在,但是我们稍后将创建它。)

至此,模式编辑器看起来应为如下所示:

现在,我们将添加一种附加属性,它采用离散选项列表中的值。这就意味着需要创建基本字符串类型的枚举限制。此外,还将设置该属性的缺省值。

  1. 在选择了“分析器”元素的情况下,按新建属性按钮。在特性表中将它的名称更改为“方式”。

  2. 单击“限制”特性的值单元格以显示限制对话框。

  3. 将限制类型从“无”更改为“枚举”。

  4. 添加下列三个选项:“从不”、“始终”和“手工”。(这些是分析器扩展的三种假定方式)。

限制对话框看起来应为如下所示:

关闭该对话框时,将“使用”属性更改为“缺省值”, 将“值”属性更改为“始终”。这将建立缺省值。注意,当您在输入值时,状态行显示了错误消息,原因是它将有效值限制为三个枚举选项。一旦完成了输入,错误消息就应该消失,原因是“始终”是有效值。

由于我们已经定义了所有元素和属性,因此需要定义语法。我们的目标是定义“扩展”元素可以有任意数目的“分析器”元素作为子代。

  1. 选择“扩展”元素。它的初始内容模型显示空的序列合成器。

  2. 选择序列合成器,并从弹出菜单中选择新建 -> 引用 -> 分析器。这将把分析器引用添加到序列合成器中。

  3. 引用的缺省基数为 [1,1],这意味着只能有刚好一个“分析器”元素。这是我们不太想要看到的一种情况。选择“分析器”引用,并在特性表中将最小出现次数特性更改为 0,将最大出现次数更改为“不受限制”。

在定义语法之后,在语法部分下面的 DTD 模拟将显示所选元素的语法在 DTD 中看起来是什么样的。提供此信息是为了帮助仍然觉得使用 DTD 比使用 XML 模式更舒服的开发者。

由于我们已经定义了有效元素、属性和语法, 因此,需要提供一些有关扩展点的信息。有两种类型的模式文档片段:

第一种片段类型是在模式清单的“定义”页面中提供的。选择元素和属性时,可以在“描述”小节中添加关于它们的简短文本。期望的格式为原始 HTML(如同 Javadoc 一样),而文件将按原样复制到最终的参考文档中。

  1. 选择“分析器”元素的“标识”属性,并在“描述”编辑器中输入以下文本:
    将用来引用此分析器的唯一名称。

  2. 选择“名称”属性,并添加以下文本:
    用来在 UI 中表示此分析器的可转换名称。

  3. 选择“类”属性,并添加以下文本(注意 HTML 标记):
    实现 <samp>com.example.xyz.IParser</samp> 接口的 Java 类的全限定名。

  4. 选择“方式”属性,并添加以下文本:
    一个可选标志,指示此分析器实例将要运行的频率(缺省值为 <samp>always</samp>)。

现在需要为扩展点本身提供简短的文本描述。为此,切换到“文档”页面:

  1. 从文本编辑器上方的组合框中选择“概述”,并添加以下文本:
    此扩展点用来插入附加分析器。分析器实际上并不工作 — 我们只是将它们用作扩展点模式的示例。
    应用

  2. 从组合框中选择“示例”,并添加以下文本:

    以下是扩展点用法的示例:
    <p>
    <pre>
       <extension point="com.example.xyz.parsers">
          <parser
             id="com.example.xyz.parser1"
             name="Sample Parser 1"
             class="com.example.xyz.SampleParser1">
          </parser>
       </extension>
    </pre>
    </p>
    应用

  3. 选择“API 信息”,并添加以下文本:
    想要扩展此扩展点的插件必须实现 <samp>com.example.xyz.IParser</samp> 接口。
    应用
  4. 选择“所提供的实现”,并添加以下文本:
    “XYZ 插件”提供了分析器的缺省实现。
    应用

注意:提供示例时,有一些特殊的注意事项。通常,PDE 将把提供的文本当作原始 HTML 来对待, 并且将不考虑换行和超过一个字符的空白(即,可忽略的空白)。涉及常规文本时这样做是对的,但是在提供示例时却让人相当烦恼, 如果想要让示例看起来漂亮一点,则制表和垂直对齐是很重要的。PDE 对这种情况进行了妥善处理: 如果它检测到 HTML 标记 <pre>,则它将按原样采用内容(保留所有字符而不作修改), 直到看到关闭标记 </pre> 为止。这就是为何可以提供如上所示的示例,并确保它在最终参考文档中看起来比较漂亮的原因。

您可能已经注意到,当输入文档时, 编辑器“轮廓”视图中越来越多的元素得到“pen”图像覆盖。此指示符告诉您上述元素有与它相关联的文本 — 这是检查文档中是否有某些地方丢失了说明的快速方法。

一旦已经完成了文档,就可以在“doc”文件夹中查看参考文档 parsers.html。它是由已注册的 PDE 构建器构建的,以反映扩展点模式文件中的更改。对于此示例所得出的文档看起来类似于