Eclipse プラットフォーム
API 使用規則

バージョン 0.15 - 改訂 12:00 May 30, 2001

Eclipse プラットフォーム API (およびその他コンポーネント) のクライアントの使用規則を以下に示します。

API とは?

Eclipse プラットフォームは、クライアント (プラグインを作成する ISV) が使用する API エレメントを定義します。 また、これらのプラグインも、クライアントに対し API エレメントなどを定義することができます。 API エレメントは、パブリック・フェースです。つまり、それらの動作や使用目的に関する仕様を含んでいます。 API エレメントは、サポートの対象となります。Eclipse プラットフォームのチームは、 指定の動作から逸脱しているような実装上のバグを修正します。 API の大幅な変更に伴うコストは高くつくことが多いため、 Eclipse プラットフォーム・チームは、メジャー・リリースを継続的に行い、API エレメントを引き続き発展させていく予定です。

API と非 API の区別

API エレメントは、その性質上、文書化されて仕様を持つものです。 一方、内部的な実装の詳細である非 API エレメントは、通常、 パブリッシュされたドキュメンテーションや仕様を持ちません。 したがって、対象についてのドキュメンテーションが見つからない場合、 これは、通常、API ではないものと見なすことができます。

より明確に区別をするならば、プラットフォームのコード・ベースは API と非 API パッケージに分離されており、 すべての API エレメントは、専用の API パッケージに宣言されています。

これら以外はすべて内部の実装の詳細と見なされ、いずれのクライアントからも使用することはできません。 クライアント・コードが非 API エレメントの名前を参照することがあってはなりません (Java リフレクションを使用する場合でも)。 場合によっては、Java 言語の名前アクセス規則が、不当な参照を拒否するのに使用されます。 ただし、これが不可能である場合が多くあります。 この単純な規則を 1 つ守ることにより、問題を完全に回避することができます。

一般規則

API エレメントの仕様は、エレメントの Java ソース・コード内の Javadoc コメントから生成されます。 一部のタイプのエレメントについては、仕様は規約の形式をとっています。 例えば、メソッドの場合、二者 (メソッドの呼び出し元とメソッドのインプリメント担当) 間の規約となります。 基本的な規則は次のとおりです。 API 規約中で用いられている "must" は、条件を必ず満たすことの確認が義務とされることを意味します。 これを怠った場合、仕様外の (おそらくは予期しない) 結果をもたらすプログラミング・エラーと見なされます。 その他の一般的な規則

public API メソッドの呼び出し

ほとんどのクライアントでは、クライアントが適切な呼び出しを行った場合は、 多くの Eclipse API は、API インターフェースまたはクラスにおける public メソッドの形をとります。

プラットフォーム API クラスのインスタンス化

すべての具象 API クラスは、誰でもインスタンス化することができるわけではありません。 API クラスには、インスタンスの作成が許可される条件を記したインスタンス化の規約があります。 この規約は、その他初期化に関する責任 (例、インスタンスが完全にアクティブになる前の特定のプロパティーの構成など)、 および関連するライフ・サイクルに関する責任 (例、dispose() を呼び出し、インスタンスに依存する OS リソースを解放する) なども対象としています。 クライアントによってインスタンス化されるよう設計されているクラスは、 Javadoc のクラス・コメント中に、明示的にフラグが付けられています ("Clients may instantiate" など)。

プラットフォーム API クラスのサブクラス化

API クラスのサブセットのみ、サブクラス化されるよう設計されています。 API クラスには、サブクラス化の宣言が許可される条件を記したサブクラス化の規約があります。 この規約は、初期化やライフ・サイクルに関する責任についても対象としています。 クライアントによってサブクラス化されるよう設計されているクラスは、 Javadoc のクラス・コメント中に、明示的にフラグが付けられています ("Clients may subclass" など)。

protected API メソッドの呼び出し

通常、継承された protected および public メソッドをサブクラス内から呼び出すことができます。 ただし、階層の外部から public メソッドを呼び出す場合に比べて注意が必要です。

API メソッドのオーバーライド

public および protected API メソッドのサブセットのみ、オーバーライドされるよう設計されています。 各 API メソッドには、サブクラスのオーバーライドが許可される条件を記したサブクラスの規約があります。 デフォルトでは、オーバーライドは許可されません。 実際のメソッドの実装をオーバーライドするには、そのサブクラスの規約を確認することが重要です。 メソッドをオーバーライドする際、サブクラス規約の内容は自動的には受け渡されません。

プラットフォーム API インターフェースのインプリメント

API インターフェースのサブセットのみ、クライアントによりインプリメントされるよう設計されています。 API インターフェースには、インプリメントが許可される条件を記した規約があります。 クライアントによってインプリメントされるよう設計されているインターフェースは、 Javadoc のクラス・コメント中に、明示的にフラグが付けられています ("Clients may implement" など)。 クライアントは、インプリメントを許可されている場合にのみ、 API インターフェースのサブインターフェースを宣言することができます。

public API メソッドのインプリメント

「API メソッドのオーバーライド」を参照。

API クラスおよびインターフェースのフィールドへのアクセス

クライアントは、API フィールドを読み取ることができ、そのほとんどは、final です。 構造体のようなオブジェクトには、非 final の public フィールドを持つものがあり、 特に指定がない場合、クライアントはその読み取りと書き込みが可能です。

既知の API タイプのオブジェクトのキャスト

既知の API タイプのオブジェクトは、API で明示的に許可されている場合、 異なる API タイプにのみキャスト (または instanceof を使用し条件付きでキャスト) することができます。 また、いずれのオブジェクトも非 API クラスまたはインターフェースにキャストすることは妥当ではありません。

規則に従わない場合

故意であるかどうかにかかわらず、規則に従わない場合には影響があります。 API 規則に従わない場合に警告を与えることができれば、関係者全員にとって事態は容易になります。 ただし、それはあり得ません。 多くの場合、API 適合が自主管理制度として機能し、 クライアントがそれぞれ規則を熟知しこれに従う責任を負います。

API エレメントにおける規約は、サポートされ認可された振る舞いの範囲を定めています。 Eclipse プラットフォームの機能の充実・改良が進むにあたり、その開発内容を示すことは API 規約の役割となります。 この規約の範囲外の内容は、いずれもサポートの対象外であり、 時期を定めず (リリース途中、または各種 OS プラットフォーム間でも) 通知なしに変更される場合があります。 上記規則に従わないクライアント・コードは、異なるバージョンやパッチ・レベルのプラットフォーム、異なる OS、 共存するプラグインの各種組み合わせ、または異なるワークベンチ・パースペクティブで実行した場合に失敗する可能性があります。 実際に、違反を犯した結果がどうなるかを試してみようとは誰も思わないでしょう。 規則を無視した場合に、警告がなかったと弁解することはできません。 「既に通知済み」のことです。

一方、規則に従ったクライアントのプラグイン・コードは、 バージョンやパッチ・レベルの異なるプラットフォーム、異なる OS での動作が可能であり、 他のプラグインとの共存も問題ありません。 関係者全員が規則を順守することにより、Eclipse プラットフォームは 新製品を開発するための安定したサポートを提供する基盤となります。