Eclipse の API Tools の紹介

Eclipse を使ってアプリケーションの API を管理する

Application Public Interface (API) を作成し、さらに、異なるリリース間での API を管理することは非常に困難なものです。このプロセスを容易に、そして日々の開発作業にシームレスに統合するために、Eclipse の PDE API Tools ツールを利用する方法を学びましょう。ただしこの記事は Eclipse V3.4 (Ganymede) のみを対象にしていますので注意してください。

Chris Aniszczyk, Principal Consultant, Code 9

Chris AniszczykChris Aniszczyk は Eclipse の PDE (Plug-in Development Environment) プロジェクトの技術リーダーであり、Code 9 の代表コンサルタントでもあります。彼はさまざまな Eclipse プロジェクトのコミッターとして、Eclipse コミュニティーの至る所に登場しています。Eclipse Architecture Council の評議員であり、Eclipse Foundation の代表委員会の委員であり、Eclipse Technology PMC の委員でもあります。彼は熱心にブログを書き、ソフトウェアに関して積極的に発言し、またツールや Eclipse に関するすべてに関しても熱心です。彼は冷たい飲み物を口にしながら、いつでもオープンソースや Eclipse に関する議論に応じてくれます。



2008年 9月 16日

Eclipse PDE (Plug-in Development Environment) の API Tools (API: Application Public Interface) の詳細に入る前に、Eclipse では API とはどのようなものなのかを少し説明しましょう。

Application Public Interface (API) とは何か

Eclipse で次のような警告やエラーが表示され、どういう意味なのかと思った経験はないでしょうか。

図 1. 推奨されないアクセス
推奨されないアクセス

内部パッケージs

あるパッケージがプラグインの中で実際に API になるかどうかは、命名規則の他に、そのパッケージが MANIFEST.MF ファイルの中にエクスポートされているかどうかに依存します。エクスポートされている場合には、そのパッケージは API とみなされます。API にしないためには、エクスポートされるパッケージに x-internal:=true という属性を付加します。こうすることで 「エクスポートしたパッケージは使用可能、ただし内部用と見なす」と Eclipse に指示するのです。

こうした警告が表示される原因として最も可能性が高いのは、パブリックにアクセスされるように作られていないコードに対して何らかの形式の API を使ってアクセスしている場合です。一般的に、API 要素は適切にドキュメント化されており、また何らかの形式の仕様を持っています。その一方、API 要素ではない要素は内部実装の詳細と見なされ、通常は公開ドキュメントなしで出荷されます。そうした内部要素にアクセスすると、Eclipse は上の図のように注意を促すのです。つまり変更される可能性のある、正式にはサポートされていないコードにアクセスしていることを Eclipse に丁重に警告しているのです。では一体、APIとは何なのでしょう。

Eclipse は Java™ プログラミング言語をベースにしているため、API 要素には 4 つのタイプがあります。ではそれぞれのタイプを調べてみましょう。

API パッケージ
少なくとも 1 つの API クラスまたは API インターフェースを含むパッケージです。
表 1. Eclipse プラットフォームでのパッケージの命名規則
命名規則パッケージの例
org.eclipse.xyz.*org.eclipse.ui, org.eclipse.swt.widgets
org.eclipse.xyz.internal.*org.eclipse.compare.internal, org.eclipse.ui.internal
org.eclipse.xyz.internal.provisional.*org.eclipse.equinox.internal.provisional.p2.engine
API クラスまたはインターフェース
API パッケージ内の public クラス/インターフェース、または、他の何らかの API クラス/インターフェースで宣言または継承される public/protected クラス/インターフェースのメンバー。
API メソッド
API クラス/インターフェースで宣言または継承される public/protected メソッドまたはコンストラクター。
API フィールド
API クラス/インターフェースで宣言または継承される public/protected フィールド。

これで API 要素の種類がわかったので、ここからは API Tools について、また API Tools を使ってこうした API 要素を扱う方法について説明しましょう。

API Tools とは何か

API Tools の目標は、API を適切な状態に維持することです。API Tools はそのために、API の欠陥をレポートします (例えばバイナリーに互換性がない、プラグインのバージョン番号が不正、@since タグの欠如または不正、API ではないコードがプラグインの間で使われている、など)。具体的には、API Tools は次のような目的のために設計されています。

  • ソフトウェア・コンポーネントまたはソフトウェア製品の 2 つのバージョンの間でのバイナリーの互換性の問題を検出する。
  • Eclipse のバージョン管理規則に基づいてプラグインのバージョン番号を更新する。
  • 新たに追加されたクラスやインターフェース、メソッドの @since タグを更新する。
  • 特別な制限を持つ型にアノテーションを付けるために、新しい javadoc タグとコード・アシストを提供する。
  • (MANIFEST.MF の中にある) 既存の情報を活用してバンドルの間でのパッケージの可視性を定義する。
  • API ではないコードがプラグインの間で使われていることを検出する。
  • API ではない型が API の中に入り込んでいることを検出する。

API Tools を追加する

プロジェクトの中で API Tools を使うためには、API Baseline の設定、そして対象とするプロジェクトへの API Tools ネイチャーの追加、という 2 つのことをする必要があります。

API Baseline の設定

API の規則に違反していないかどうかを知るためには、互換性分析のための、何らかのベースライン (基準) を設定する必要があります。これは API Tools では API Baseline と呼ばれ、API Baselines の Preferences ページで設定されます (図 2)。API Baseline を設定するには、Eclipse ベースの既存のインストールを指定するだけです。すると、API Tools はそのインストールの中にあるプラグインをスキャンして即座に API Baseline を生成してくれます。API Baseline が設定できたら、Eclipse プロジェクトが API Tools を利用できるように設定する必要があります。このプロセスをビルド・システムの一部としてヘッドレス環境でも行えることに注意してください。ただしこの記事ではそれについては説明しませんので、API Tools のウィキで詳しい情報を調べるようにお勧めします (「参考文献」を参照)。

図 2. API Baseline を追加する
API Baseline を追加する

API Tools プロジェクト・ネイチャーを追加する

API Tools に関連するエラーや警告を表示するためには、そのプロジェクトに API Analysis ネイチャーとビルダーを追加する必要があります。そのための方法は 2 つあり、どちらの方法を使うかは API Tools を既存のプロジェクトに適用するのかどうかに依存します。既存のプロジェクトに対して作業する場合の推奨の方法は、API Tooling Setup ウィザード (図 3) を使う方法です。このウィザードにアクセスするためには、そのプロジェクトを右クリックして PDE Tools > API Tooling Setup を選択します。このウィザードの中で、API Tools を使うように変換したいプロジェクトをクリックして、Finish をクリックします。それで終わりです。

図 3. API Tooling Setup ウィザード
API Tooling Setup ウィザード

API Tools を利用するための、もう 1 つの方法は、プラグイン・プロジェクトを作成する時点で設定する方法です。Eclipse V3.4 では New Plug-in Project ウィザードが機能強化され、プロジェクトに API Analysis ネイチャーを追加するための、Enable API Analysis というチェックボックスが追加されています。

図 4. New Plug-in Project ウィザードでの API Tools
New Plug-in Project ウィザードでの API Tools

API Tools を使う

API Tools を使うようにプロジェクトを設定する方法はわかったので、API Tools がどのように役立つのかを示す例をいくつか調べてみましょう。API Tools には、さまざまな API 要素に制限を強制するための一連のアノテーションが用意されています。

表 2. API に対する制限
アノテーション適用される API 要素説明
@noimplementインターフェースクライアントがこのインターフェースを実装してはならないことを示します。このアノテーションが付いたインターフェースに対して implements または extends キーワードを使うすべてのクラスには、問題があることを示すフラグが立てられます。
@noextendクラスクライアントがこのクラスを継承してはならないことを示します。このアノテーションが付いたクラスに対して extends キーワードを使用するすべてのクラスには、問題があることを示すフラグが立てられます。
@noinstantiateクラスクライアントがこのクラスをインスタンス化してはならないことを示します。このアノテーションが付いたクラスを何らかのコンストラクターでインスタンス化するすべてのコードには、問題があることを示すフラグが立てられます。
@nooverrideメソッドクライアントがこのメソッドを再宣言してはならないことを示します。このアノテーションが付いたメソッドを無効にするメソッドを定義するすべてのサブクラスには、問題があることを示すフラグが立てられます。
@noreferenceメソッド、コンストラクター、(final ではない) フィールドクライアントが、このメソッド、コンストラクター、final ではないフィールドを参照してはならないことを示します。このアノテーションが付いたメソッドまたはコンストラクターを直接呼び出すコード、またはこのアノテーションが付いた final ではないフィールドを参照するすべてのコードには、問題があることを示すフラグが立てられます。

API を制限するために利用可能なアノテーションの種類がわかったので、これらが実際にはどのように機能するのかを示す例を見てみましょう。

API に対する制限の例

非常に簡単な例から始めましょう。たとえばウィジェットを作成できる API を持つプラグインを考えてみます。

リスト 1. IWidget.java
package org.eclipse.example.widgetfactory;

/**
 * A simple widget
 * 
 *@noimplement
 */
public interface IWidget {
	
	public String getName();
	
	public long getId();

}

この例では、ウィジェットは名前と ID を持っています。このインターフェースにアノテーションを付けて制限を加え、このインターフェースを実装しないようにクライアントに伝えます (こうすることで、クライアントに下記の抽象ウィジェットを実装させます)。

リスト 2. AbstractWidget.java
package org.eclipse.example.widgetfactory;

/**
 * An abstract widget
 */
public abstract class AbstractWidget implements IWidget {
	
	/**
	 *@nooverride
	 */
	public long getId() {
		return Math.round(Math.random());
	}

}

この抽象ウィジェットには 1 つのメソッドがあり、そのメソッドにはこのメソッドをオーバーライドしないようにクライアントに伝える API に対して制限をするためのアノテーションが付けられています。では誰もが使用できるデフォルトのウィジェットを作成してみましょう。

リスト 3. DefaultWidget.java
package org.eclipse.example.widgetfactory;

/**
 * A default widget, this class isn't meant to be extended.
 * 
 * Implementation is provided as-is.
 * 
 *@noextend
 */
public class DefaultWidget extends AbstractWidget {

	public String getName() {
		return "The default widget";
	}

}

クライアントのために提供した、このデフォルトのウィジェットは、単純にリスト 3 にあるとおりの動作をします。つまりこのウィジェットを使用することはできますが、継承することはできません。独自のプラグインの中でこのクラスを継承したり、誰もが使用できる他のデフォルト・ウィジェットを作成したりすることは自由です。そこで、私達がこのウィジェット API のクライアントであると仮定し、どんなことが起こるのかを調べてみましょう。まず、2 つのクラス、(IWidget を実装する) MyWidget と (DefaultWidget を継承する) MyDefaultWidget を作成します。私達がこのウィジェット API のクライアントであるとすると、何が表示されるのでしょう。MyWidget クラスの場合には、実装してはならない API インターフェースをクライアントが実装しているという警告が表示されます (図 5)。MyDefaultWidget クラスの場合には、継承してはならない DefaultWidget クラスを継承しているという警告と、オーバーライドしてはならない getId() メソッドをオーバーライドしているという警告が表示されます。

図 5. MyWidget.java
MyWidget.java
図 6. MyDefaultWidget.java
MyDefaultWidget.java

この簡単な例から、API がどう使われているかという情報が API クライアントに対してどう表示されるか、明確に理解できたはずです。

バイナリーの互換性の問題

API を宣言する際の困難な問題として、ソフトウェアのバージョンがいくつもある中で、実際に API の規則に違反しているのはどういう場合なのかを判断しなければなりません。例えば簡単に API の規則に違反してしまう例として、既に定義されている API メソッドのメソッド・シグニチャーを変更してしまう場合があります。これを説明するために、一般的な PluginRegistry クラスを持つ Eclipse コード・ベースの中で実際に試してみます。

図 7. バイナリーに互換性がない変更
バイナリーに互換性がない変更

この場合は既存の API メソッドである findEntry(String id) を変更していますが、API Tools は賢明なことに、その変更はこの API クラスのクライアントとしての規則に違反することを検出します。API の規則に違反してしまう場合は他にも数多くあり、API Tools を利用すると、そのすべてをチェックすることができます。しかもさらに良いことに、こうしたバイナリーに互換性がない変更を、API Tools の Preferences ページを使って構成することができるのです。

図 8. API Tools の Preferences
API Tools の Preferences

バージョン管理

API を扱う際に表面化する、もう 1 つの困難な問題にバージョン管理があります。私の意見では、バージョン管理には 2 つの側面があります。1 つの側面はバージョン管理の手段を考えることであり、もう 1 つの側面はそのバージョン管理手段を実行することです。API Tools は Eclipse のバージョン管理のガイドライン (「参考文献」を参照) に従っており、このガイドラインは OSGi によるバージョン管理の仕組みに大きく依存しています。簡単にするために、バージョン番号は 3 つの整数と 1 つのストリングという 4 つのセグメントで構成されており、それぞれ major.minor.service.qualifier という名前が付けられています。

ヘッドレス環境での API Tools と API Reports

この記事では説明しませんが、API Tools をヘッドレス環境で使うことができます。Eclipse のビルドではまさにこれが行われ、API Baselinesと API Reports が生成されます。API Tools には、それを補助するための Ant タスクがいくつか含まれています。これらの Ant タスクについての詳細は org.eclipse.pde.api.tools プラグインを調べてみてください。

それぞれのバージョン・セグメントには異なる役割があります。major セグメントが異なる場合は API の規則に違反していること (API の互換性がないこと) を示し、minor セグメントは (新しい API など) 外部から見える変更が行われたことを示し、service セグメントはバグの修正と開発ストリームの変更を示し、そして qualifier セグメントは特定のビルドを示します。

新しい API メソッドの追加やバグの修正など、プラグインに対して何らかの変更をした場合、プラグインのバージョン番号を変更するタイミングを覚えておくという部分が常に困難で間違いやすい部分です。従来は、API が新たに変更された場合ではなく、何を変更した場合にもマイナー・バージョンを上げてしまうという問題がよくありました。例えば Eclipse SDK で 3.4 用のファイルを開いたときに、構わず単純にマイナー・バージョンを上げてしまうことは普通でした (これは実際にそのマイナー・バージョンの変更を必要とする変更がこれから行われる、ということを前提にしています)。しかし API Tools を利用すると、バージョン管理でエラーを起こしやすいという問題がなくなります。なぜなら API Tools は、そのプラグインにとって適切なバージョンは何かを API Baseline に基づいて指示することができ、またそのバージョンを強制することができるからです。例えばバージョン 3.3.0 対応のプラグインの API クラスにメソッドを追加した場合に API Tools がどんな表示をするか、想像してみてください。

図 9. バージョン・エラー
バージョン・エラー

API Tools は 2 つのエラーを表示します。1 つのエラーは、そのメソッドが 3.4 API の一部であることを明確に表現するために、そのメソッドの @since タグを更新する必要があることを示します。もう 1 つのエラーは、そのプラグインのバージョンを MANIFEST.MF ファイルに追加する必要があることを示します。この特定のエラーを詳細に調べてみると、API Tools はバージョン番号を正しいバージョンに更新するための適切で簡単な修正方法まで親切に教えてくれることがわかります。

図 10. MANIFEST.MF を簡単に修正する方法
MANIFEST.MF を簡単に修正する方法

まとめ

この記事では API Tools を簡単に紹介し、その機能をいくつか説明しました。重要な注意点として、この記事は API Tools を使うことで Eclipse プロジェクトに対して行えることの、ほんの表面的な部分を紹介したに過ぎません。例えば API Tools をヘッドレス環境で使うことができ、また API 違反をキャッチするレポートを API Tools を使って生成することもできます。この記事を読んだことで、API とバージョン管理の重要性を理解することができ、また皆さんもプロジェクトの中で API Tools を使い始めることができるようになれたことを願います。

参考文献

学ぶために

  • Eclipse の PDE (Plug-in Development Environment) について学んでください。
  • Eclipse Foundation で PDE API Tools について学んでください。
  • Eclipse platform API rules of engagement」を読み、Eclipse API の詳しい歴史と背景を学んでください。
  • Eclipse Platform API Specification」には Eclipse API の一覧があります。
  • Eclipse ではどのようにプラグインをバージョン管理しているかを学ぶために、Eclipse の Version Numbering のページを読んでください。
  • OSGi に関心のある方は OSGi Alliance の Web ページを見てください。
  • Eclipse コミュニティーでの出来事に関心のある方は PlanetEclipse を調べてみてください。
  • Eclipse Plug-in Central には利用可能な Eclipse プラグインの一覧があります。
  • EclipseLive には Eclipse のさまざまな技術を解説したウェビナーが用意されています。
  • Eclipse のコミッター達と出会い、また Eclipse のさまざまなプロジェクトについて学ぶために、Eclipse の主要カンファレンスである EclipseCon に参加してください。
  • Eclipse の推奨読み物リスト」を調べてみてください。
  • developerWorks には他にも Eclipse に関する資料が豊富に用意されています。
  • Eclipse が初めての人は、developerWorks の記事「Eclipse Platform 入門」を読んでください。Eclipse の起源やアーキテクチャー、またプラグインを使って Eclipse を拡張する方法などを学ぶことができます。
  • IBM developerWorks の Eclipse project resources を利用して Eclipse のスキルを磨いてください。
  • developerWorks podcasts では、ソフトウェア開発者のための興味深いインタビューや議論を聞くことができます。
  • developerWorks の Technical events and webcasts で最新情報を入手してください。
  • IBM とオープンソース技術、そして製品機能を調べ、学ぶために、無料の developerWorks On demand demos をご覧ください。
  • IBM オープンソース開発者にとって関心のある、世界中で今後開催される会議や業界展示会、ウェブキャスト、その他のイベントについて調べてみてください。
  • developerWorks の Open source ゾーンをご覧ください。オープンソース技術を使った開発や、IBM 製品でオープンソース技術を使用するためのハウ・ツー情報やツール、プロジェクトの更新情報など、豊富な情報が用意されています。

製品や技術を入手するために

議論するために

  • IRC で他の Eclipse 開発者やコミッターとチャットしてみてください。
  • Eclipse に関する質問を議論するための最初の場所として、Eclipse Platform newsgroups があります (このリンクをクリックすると、デフォルトの Usenet ニュース・リーダー・アプリケーションが起動し、eclipse.platform が開きます)。
  • Eclipse newsgroupsには、Eclipse を利用し、拡張することに関心を持つ人達のために、さまざまなリソースが用意されています。
  • developerWorks blogs から developerWorks のコミュニティーに加わってください。

コメント

developerWorks: サイン・イン

必須フィールドは(*)で示されます。


IBM ID が必要ですか?
IBM IDをお忘れですか?


パスワードをお忘れですか?
パスワードの変更

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


お客様が developerWorks に初めてサインインすると、お客様のプロフィールが作成されます。会社名を非表示とする選択を行わない限り、プロフィール内の情報(名前、国/地域や会社名)は公開され、投稿するコンテンツと一緒に表示されますが、いつでもこれらの情報を更新できます。

送信されたすべての情報は安全です。

ディスプレイ・ネームを選択してください



developerWorks に初めてサインインするとプロフィールが作成されますので、その際にディスプレイ・ネームを選択する必要があります。ディスプレイ・ネームは、お客様が developerWorks に投稿するコンテンツと一緒に表示されます。

ディスプレイ・ネームは、3文字から31文字の範囲で指定し、かつ developerWorks コミュニティーでユニークである必要があります。また、プライバシー上の理由でお客様の電子メール・アドレスは使用しないでください。

必須フィールドは(*)で示されます。

3文字から31文字の範囲で指定し

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


送信されたすべての情報は安全です。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Open source
ArticleID=345969
ArticleTitle=Eclipse の API Tools の紹介
publish-date=09162008