xfyユーザーエージェントは、xfyプラグインJARファイルを導入して機能を拡張することができます。この文書ではxfyプラグインの仕様のうち、以下の項目について説明します。
xfyユーザーエージェントで使用されるxfyプラグインJARファイルの仕様について説明します。
xfyユーザーエージェントは、xfyプラグインJARファイルを導入して機能を拡張することができます。この文書ではxfyプラグインの仕様のうち、以下の項目について説明します。
xfyプラグインは、その役割で３種類に分けられます。それぞれの種類と役割、配置場所は次のとおりです。
作成したxfyプラグインをxfyユーザーエージェントの実行環境に配置した例を示します。以下の例では、xfyプラグインを提供するベンダー名をcom.example、共通プラグイン名をFoo.jar、通常のxfyプラグイン名をBar.jarとします。
+- bin : xfyユーザーエージェントの実行ファイル群が配置されるフォルダ
+- common
| +- com.example : ベンダーごとに作成するフォルダ
| +- Foo.jar : 共通プラグインはこの位置
+- plugins
+- com.example : ベンダーごとに作成するフォルダ
+- Bar.jar : 通常のxfyプラグインはこの位置
ベンダー名やプラグイン名は、プラグインマニフェストファイルに設定したものを使用します。詳しくは「プラグインマニフェスト記載規約」をご覧ください。
xfy technologyの各プラグインのクラスパス解決には、仕様上複雑な問題が存在します。ここでは、xfyプラグインのクラスパス解決の仕様を説明し、注意すべき点について述べます。
通常のxfyプラグインは、次のプラグインをクラスパスに含んだ状態で運用されます。
commonフォルダ以下の共通プラグイン
このクラスパスの設定状態ではどのように動作するかを、次のようなxfyプラグインの構成を想定して説明します。
pluginsフォルダ以下に存在する
commonフォルダ以下に存在する
それぞれのxfyプラグインに実装されたクラスやインスタンスを相互に参照すると、次のような結果となります。
pluginsフォルダ以下にあるxfyプラグインからpluginsフォルダ以下にある別のxfyプラグインを利用するには、プラグインマニフェストファイル（manifest.xml）にインポート指定を記述します。インポート指定したときのxfyプラグインのクラスパス解決は、次のとおりです。
commonフォルダ以下の共通プラグイン
このクラスパスの設定状態ではどのように動作するかを、次のようなxfyプラグインの構成を想定して説明します。
前提：
pluginsフォルダ以下に存在する
各クラスの見え方
プラグインマニフェストファイルの仕様について、詳しくは「プラグインマニフェストファイルリファレンス」をご覧ください。
通常のxfyプラグインはそれぞれにクラスローダーが定義されて独立に動作します。共通プラグインでは、特別に共通に利用されます。
複数のプラグインから共通に利用したいようなクラスがある場合は、次のどちらかの方法を選択します。
ただし、インポートを利用した場合はクラスローダーが異なることにより、そのクラスのインスタンスまでは共通に利用できない（同一インスタンスとして見なせない）点に注意が必要です。
xfyプラグインは、Javaの圧縮ファイル形式であるJARファイルで作成します。xfyプラグインJARファイル内部のファイル構成は以下のとおりです。
MyPlugin.jar
+- manifest.xml : プラグインマニフェストファイル
+- クラスファイル群 : クラスファイル群をJavaのパッケージ構成に従って配置
+- META-INF : JARファイル作成時に自動的に生成 (xfyプラグインJARファイルに必須ではありません)
+- MANIFEST.MF : JARファイル作成時に自動的に生成 (xfyプラグインJARファイルに必須ではありません)
プラグインマニフェストファイル（manifest.xml）は、プラグインの構成情報を記述するXML形式のファイルです。プラグインマニフェストファイルの要素・属性は、「プラグインマニフェストファイルリファレンス」をご覧ください。また、プラグインマニフェストの記載規約は、「マニフェスト記載規約」をご覧ください。
例として、Foo.jarプラグインにcom.example.foo.bar1クラスとcom.example.foo.bar2クラスがあるときの、Foo.jar内の構成を示します。
Foo.jar
+- manifest.xml
+- com
| +- example
| +- foo
| +- bar1.class
| +- bar2.class
+- META-INF
+- MANIFEST.MF
xfyプラグインを作成するときは、プラグインマニフェストファイルを用意する必要があります。プラグインマニフェストファイルは、プラグインマニフェスト記述XMLの仕様に従って作成します。プラグインマニフェストファイルには、仕様のほかに、xfy technologyで守らなければならない規約があります。
以下の説明でプラグインマニフェスト記述に使用する要素を記述するときは、manifest:という名前空間接頭辞を使用します。
プラグイン名は、xfyプラグインを識別する名前です。プラグインマニフェストファイルでは、manifest:manifest要素のname属性に記述します。プラグイン名はxfyプラグインを作成するベンダーが自由に付けることができます。ただし、同じベンダーが作成する別のxfyプラグインに、同じプラグイン名を使用することはできません。
プラグイン名には、拡張子を除いたxfyプラグインのファイル名と同じ名前を使用します。プラグイン名に設定できる文字数は81文字までです。プラグイン名に使用できる文字は、次のとおりです。
a～z、A～Z）0～9）-）、アンダーバー（_）、ピリオド（.）ベンダー名は、xfyプラグインを作成するベンダーを識別する名前です。プラグインマニフェストファイルでは、manifest:manifest要素のvendor属性に記述します。xfyベンダー名は規約として、xfyプラグインを作成するベンダーが所持するドメイン名を逆順にした形式で記述します。この規約はJavaのパッケージ名を付けるときと同じと考えてよいでしょう。
［例１］xfy.comが提供するプラグインの場合、ベンダー名は「com.xfy」
［例２］justsystem.co.jpが提供するプラグインの場合、ベンダー名は「jp.co.justsystem」
ベンダー名は、xfyユーザーエージェントの環境にxfyプラグインを配置するときのフォルダ名と同じになります。ベンダー名に設定できる文字数は85文字までです。ベンダー名に使用できる文字は、次のとおりです。
a～z、A～Z）0～9）-）、アンダーバー（_）、ピリオド（.）プラグインマニフェストファイルには、xfyプラグインが動作対象とするxfyプラットフォームのバージョンを記述する必要があります。動作対象とするxfyプラットフォームのバージョンは、manifest:manifest要素のtargetXfyVersion属性に記述します。targetXfyVersion属性には、メジャーバージョンとマイナーバージョンだけを記述します。ビルド番号やリビジョンが記述された場合は、メジャーバージョンとマイナーバージョンだけが認識され、ビルド番号やリビジョンは無視されます。
targetXfyVersion属性は、xfyユーザーエージェントで使用されているxfyプラットフォームのバージョンと比較して、xfyプラグインを動作させることができるかできないかを判断するために使用されます。判断はxfyプラットフォームがxfyプラグインを読み込むときに、次の手順で行われます。
manifest:manifest要素のtargetXfyVersion属性の値を取得します。
targetXfyVersion属性の値以上である。
以下に具体的な値を使った例を示します。
| targetXfyVersion記述 | xfyプラットフォームのバージョン | 動作可否 |
| 1.3 | 1.3 | 可能 |
| 1.3 | 1.0 | 不可 |
| 1.3 | 1.6 | 可能 |
| 1.3 | 2.0 | 不可 |
| 1.3 | 1.3.5.7 | 可能 |
| 1.3 | 1.2.65535.99999999 | 不可 |
バージョンの記載方法や比較方法について、詳しくは「xfy technologyでのバージョン管理仕様」をご覧ください。
例として、xfyプラットフォーム1.3を対象としたFoo.jarのプラグインマニフェストファイルmanifest.xmlを示します。
<?xml version="1.0"?>
<manifest
xmlns="http://xmlns.xfy.com/plugin-manifest"
name="Foo"
vendor="com.example"
version="1.3.0.0"
targetXfyVersion="1.3">
<!-- プラグイン情報を記述 -->
</manifest>
「xfyプラグインの配置場所」で説明したように、manifest:manifest要素のname属性とvendor属性の値は、プラグインの配置場所に影響します。
上記の例で、Foo.jarが共通プラグインのときの配置場所は以下のとおりです。
+- bin : xfyユーザーエージェントの実行ファイル群が配置されるフォルダ
+- common
+- com.example : vendor属性の値
+- Foo.jar : name属性の値に拡張子.jarを結合したもの
また、Foo.jarが通常のxfyプラグインのときの配置場所は以下のとおりです。
+- bin : xfyユーザーエージェントの実行ファイル群が配置されるフォルダ
+- plugins
+- com.example : vendor属性の値
+- Foo.jar : name属性の値に拡張子.jarを結合したもの
xfyプラグインを変更するときは、互換性を意識しなければなりません。xfyプラグインには互換性ポリシーが存在します。
xfyプラグインのポリシーでは、上位互換性を保証し、下位互換性は保証しません。たとえば、xfyプラットフォーム1.3ではxfyプラットフォーム1.0用のプラグインも動作します。一方、xfyプラットフォーム1.3用のプラグインはxfyプラットフォーム1.0で動かなくてもかまいません。
xfyプラットフォームがメジャーバージョンアップするときは、互換性は上位・下位とも保証しません。
互換性ポリシーを守るために、xfyプラグインやxfyプラグインが属するパッケージを変更するときは、互換性が保たれる変更と互換性が保たれない変更を区別する必要があります。
xfyプラグインに変更を加えるときの、xfyプラグインのバージョン設定ポリシーは、プラグイン開発者が自由に定められます。バージョン設定およびバージョン設定ポリシーの例は、「xfy technologyでのバージョン管理仕様」をご覧ください。
下記の項目に該当する変更を１つでも加えると、xfyプラグインやパッケージの互換性が失われます。
次に挙げるような変更の場合は、xfyプラグインやパッケージの互換性が保たれます。