扩展点模式编辑器

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

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

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

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

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

我们想要执行下列操作:

  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],这意味着只能刚好有一个“解析器”元素。这是我们不太想要看到的一种情况。选择“解析器”引用,并将 maxOccurs 更改为“不受限制”。

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

扩展点模式编辑器 — 元素语法

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

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

  1. 选择“解析器”元素的“标识”属性,并在“描述”编辑器中输入以下内容:
    将用来引用此解析器的唯一名称。
  2. 选择“名称”属性,并添加下列文本:
    用来在用户界面中表示此解析器的可转换名称。
  3. 选择“类”属性,并添加下列文本(注意 HTML 标记):
    实现 <samp>com.example.xyz.IParser</samp> 接口的 Java 类的全限定名。
  4. 选择“方式属性,并添加以下文本:
    一个可选标志,指示此解析器实例将要运行的频率(缺省值为 <samp>always</samp>)。

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

  1. 从文本编辑器上方的组合框中选择“概述”,并添加以下文本:
    此扩展点用来插入附加解析器。解析器实际上并不工作 — 我们只是将它们用作扩展点模式的示例。
    应用
  2. 从组合框中选择“示例”,并添加以下文本:
          The following is an example of the extension point usage:
       <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”图像覆盖。此指示符告诉您上述元素有与它相关联的文本 — 这是检查文档中是否有某些地方丢失了说明的快速方法。

扩展点模式编辑器大纲

一旦完成了文档,就可以查看参考文档。可以采用两种方法来查看参考文档。在工作期间,都可以通过从弹出菜单中选择“预览参考文档”项来预览参考文档。或者,可以设置 PDE 首选项(“首选项 > 插件开发 > 编译器”,在“模式”选项卡下)来对每个模式文件更改自动创建参考文档。无论使用哪种方法来创建参考文档,此示例产生的文档看起来将如此

 
Copyright IBM Corporation and others 2000, 2003