拡張ポイント・スキーマ・エディター

拡張ポイント・スキーマ・エディターは次の 2 つの方法で開くことができます。 新規拡張ポイントを作成したとき同時に開く方法、あるいは既存の拡張ポイント・スキーマを開くという方法です。  規則では、新規のスキーマは、.exsd ファイル拡張子を持つ拡張ポイント ID と同じ名前です。 新規のスキーマは、プラグインのディレクトリー・ツリーの schema ディレクトリーに配置されます。  

新規拡張ポイントが PDE で作成される際に初期スキーマ・ファイルも作成され、 スキーマ・エディターが開いて編集が可能になります。 すぐにスキーマを定義することも、閉じた後で定義することもできます。 完全な拡張ポイント・スキーマを作成することにより、PDE で、拡張ポイントのユーザーに自動化された支援を提供できるようになります。

PDE のスキーマ・エディターは、プラグインのマニフェスト・エディターと同じ概念に基づいています。  PDE スキーマ・エディターには、2 つのフォーム・ページと 1 つのソース・ページがあります。  XML スキーマは詳細であり、そのソース形式では読みにくいことがあるので、 編集には、ほとんどの場合、フォーム・ページを使用してください。  ソース・ページは、作成されたソース・コードの読み取りに役立ちます。

例: 「Sample Parsers」拡張ポイントのスキーマの作成

先に「Sample Parsers」拡張ポイントと初期スキーマを作成しました。 ここで、プロジェクトの「スキーマ」フォルダーで、 parsers.exsd ファイルをダブルクリックすることにより、スキーマを開くことができます。  これによりスキーマ・エディターを開きます。

以下を行います。

  1. 拡張ポイントに、妥当な XML エレメントと属性を定義します。
  2. 文法 (内容モデル) を定義します。
  3. 参照文書にマージするドキュメンテーションの断片を提供します。

すべての拡張ポイント・スキーマは、「拡張」エレメントの宣言で開始します。「parser」という新規の XML エレメントを追加します。

  1. 拡張ポイントのエレメント」セクションの 「新規エレメント」ボタンを押します。
  2. 「プロパティー」ビューに移動し、その名前を「New_Element」から「parser」に変更します。
  3. 新規のエレメントを選択したまま、「新規属性」ボタンを押します。 その新規エレメントの子として「新規属性」が作成されます。 プロパティー・シートで、その「名前」を「ID」に変更し、「使用」を「required」に変更します。
  4. プロパティー・シートを開いたまま、 ローカルのツールバーの「この属性をクローン」ボタンを押します。 その属性のコピーが作成されます。 プロパティー・シートから移動せずに、すべての属性を迅速に定義することができるため、 これは役立ちます。
  5. 新規の属性の名前を「name」にします。
  6. もう一度この属性のクローンを作成します。 今度は、その名前を「class」に変更します。  この属性は、 特定の Java インターフェースをインプリメントしなければならない Java クラスの完全修飾名を表すために使用されます。 PDE が後で利用できるようにするために、これを指定する必要があります。 「種類」を「string」から「java」に変更します。  basedOn プロパティーを com.example.xyz.IParser に設定します。  (このインターフェースはまだ存在していません。後で作成します。)

これまでに、スキーマ・エディターは次のようになっています。

拡張ポイント・スキーマ・エディター - 定義ページ

次に、離散的な値の選択リストから値を得る追加属性を追加します。  つまり、基本ストリング型から列挙型の制限を作成する必要があります。  さらに、その属性にデフォルト値を設定します。

  1. 「パーサー」エレメントを選択するとき、「新規属性」ボタンを押します。  プロパティー・シートでその名前を「mode」に変更します。
  2. 「制限」プロパティーの値セルをクリックして、制限ダイアログを立ち上げます。 
  3. 制限型を「none」から「enumeration」に変更します。
  4. 次の 3 つの選択項目を追加します。「never」、「always」、および「manual」。  (これらはパーサー拡張の 3 つの仮想モードです。)

制限ダイアログは次のようになっています。

型制限ダイアログ

「使用」属性を「default」に変更し、 「値」属性を「always」に変更して、このダイアログを閉じます。  これにより、デフォルト値が確定します。 値の入力中に、 状況表示行にエラー・メッセージが表示されることに注意してください。 これは、有効な値は、3 つの列挙型選択項目に制限されているからです。 「always」は有効な値なので、入力し終わるとエラー・メッセージは消えます。

すべてのエレメントと属性を定義したので、次に文法を定義する必要があります。 ここでの目標は、任意の数の「パーサー」エレメントを、 「拡張」エレメントの子として持つことができるようにすることです。 

  1. 「拡張」エレメントの選択します。 初期内容モデルには、空のシーケンス・コンポジターが表示されます。
  2. シーケンス・コンポジターを選択し、「新規」>「参照」>「パーサー」をポップアップ・メニューから選択します。 これにより、シーケンス・コンポジターにパーサー参照が追加されます。
  3. 参照のデフォルトの基数は、[1,1] で、正確に 1 つの「パーサー」エレメントが可能です。 しかし、ここで必要としているものは異なります。 「パーサー」の参照を選択し、maxOccurs を「unbounded」に変更します。

文法の定義が終了した後、文法セクションの下の「DTD 近似値」に、 選択されているエレメントの文法が DTD ではどのようになるかが表示されます。  XML スキーマよりも DTD の方を使い慣れている開発者の役に立つように、この情報が提供されています。

拡張ポイント・スキーマ・エディター - エレメント規則

有効なエレメント、属性、および文法を定義したので、次に拡張ポイントに関する情報を提供する必要があります。 スキーマ・ドキュメンテーションの断片には、以下の 2 種類があります。

最初の断片のタイプは、スキーマのマニフェストの「定義」ページで提供されます。 エレメントと属性を選択し、「説明」セクションにそれらに関する簡単なテキストを追加することができます。 期待されるフォーマットは、(Javadoc の場合と同様) HTML そのものであり、テキストはそのまま最終の参照文書にコピーされます。

  1. 「パーサー」エレメントの「ID」属性を選択し、「説明」エディターに次のように入力します。
    「このパーサーを参照するために使用される固有の名前」
  2. 「名前」属性を選択し、次のテキストを追加します。
    「このパーサーを UI で表示するために使用される変換可能な名前」
  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> との間の内容を そのまま (すべての文字を変更せずに) 受け取ることにより、この状態の妥協点を見出します。 したがって、最終の参照文書としての見栄えの良い、上記のようなサンプルを提供することができます。

ドキュメンテーションを入力していると、エディターの「アウトライン」ビューのエレメントの上に 「ペン」のイメージが次々と重ねられていくことに気付くことでしょう。 この小さな標識は、当該のエレメントに何らかのテキストが関連付けられていることを示しており、 ドキュメンテーションが文書内のどこかで欠落しているかどうかを迅速に確認することができます。

拡張ポイント・スキーマ・エディターのアウトライン

ドキュメンテーションに関する作業を終了した後には、 参照ドキュメンテーションを表示することができます。 これには 2 つの方法があります。 ポップアップ・メニューから「参照文書のプレビュー」項目を選択することによって、 作業の間いつでも、参照文書をプレビューすることができます。 あるいは、PDE 設定を (「設定」>「プラグイン開発」>「コンパイラー」の「スキーマ」タブの下で) セットアップして、 各スキーマ・ファイルが変更されるたびに自動的に参照ドキュメンテーションを作成することができます。 作成のメソッドに関わらず、この例で作成される文書はこのようになります。