このタスクは、API 使用、バイナリー互換性、およびバンドル・バージョン番号の検証を含む、ベースラインに対して相対的な API プロファイルの完全な API 分析を実行します。プロファイルは、開発中の製品の現行状態です。バイナリー互換性について、プロファイルは API ベースラインと比較されます (通常、製品の前のリリース)。
すべての妥当性検査はバイナリー・クラス・ファイル上で実行される (ソースは分析されません) ので、分析には @since タグの妥当性検査は含まれません。
Ant タスクの名前は、apitooling.analysis です。
使用するには、jar ファイル apitooling-ant.jar が Ant クラスパス上になければなりません。
<apitooling.analysis baseline="..." profile="..." report="..." filters="..." excludelist="..." includelist="..." preferences="..." debug="..." eefile="..." />
| 属性 | 説明 | 必須 |
| baseline | この属性は、参照ベースラインのロケーションを指定します。 このロケーションは、.zip、.jar、.tgz、.tar.gz ファイル、または Eclipse のインストール・フォルダーに対応するディレクトリーなどになります。これは、Eclipse 実行可能プログラムが存在するディレクトリーです。 ロケーションは、絶対パスを使用して指定します。 |
はい |
| profile | この属性は、参照ベースラインに対して比較する、現行製品またはプロファイルのロケーションを指定します。 このロケーションは、.zip、.jar、.tgz、.tar.gz ファイル、または Eclipse のインストール・フォルダーに対応するディレクトリーなどになります。これは、Eclipse 実行可能プログラムが存在するディレクトリーです。 ロケーションは、絶対パスを使用して指定します。 |
はい |
| report | レポートが生成される出力ロケーションを設定します。 タスクが完了すると、このディレクトリーでフィルター・ルートと類似する構造を使用することで、レポートが使用可能になります。レポートされる問題のあるコンポーネントごとにサブフォルダーが作成されます。各サブフォルダーには、「report.xml」という名前のファイルが含まれています。 このフォルダーには、「allNonApiBundles」という名前の特別なフォルダーも作成され、そのフォルダーにも「report.xml」という名前のファイルが含まれます。このファイルには、API ツール・ネーチャーを使用していないすべてのバンドルがリストされます。 検出される問題の要約が入る「counts.xml」ファイルもレポート・ディレクトリーに作成されます。 ロケーションは、絶対パスを使用して指定します。 |
はい |
| filters | 分析中に使用する API フィルターのルート・ディレクトリーを設定します。 引数は、API ツール分析によって作成される潜在的な問題をフィルターに掛けるのに使用される .api_filters ファイルのルート・ディレクトリーです。 ルートは、絶対パスを使用して指定します。 ルートには、以下の構造が含まれている必要があります。
root
|
+-- component name (i.e. org.eclipse.jface)
|
+--- .api_filters
|
いいえ |
| excludelist | 除外リストのロケーションを設定します。 この除外リストのロケーションでは、分析から除外するバンドルをリストしたテキスト・ファイルを指定します。 デフォルトでは、プロファイルのすべてのバンドルが分析されます。インクルードおよび除外リスト属性を使用して、バンドルを選択的にインクルードしたり除外したりできます。インクルード・リストで、分析するバンドルのセットが初期化され (これを省略すると、すべてのバンドルがインクルードされる)、その後、除外リストが適用されます。 ファイルの各行は、次のうちの 1 つを指定します。
ロケーションは、絶対パスを使用して指定します。 除外リストの例を以下に示します。 # DOC BUNDLES org.eclipse.jdt.doc.isv org.eclipse.jdt.doc.user org.eclipse.pde.doc.user org.eclipse.platform.doc.isv org.eclipse.platform.doc.user # NON-ECLIPSE BUNDLES com.ibm.icu com.jcraft.jsch R:javax¥..* ... |
いいえ |
| includelist | インクルード・リストのロケーションを設定します。 インクルード・リストのロケーションは、分析に組み込むバンドルをリストするテキスト・ファイルを指定します。 デフォルトでは、プロファイルのすべてのバンドルが分析されます。インクルードおよび除外リスト属性を使用して、バンドルを選択的にインクルードしたり除外したりできます。インクルード・リストで、分析するバンドルのセットが初期化され (これを省略すると、すべてのバンドルがインクルードされる)、その後、除外リストが適用されます。 ファイルの各行は、次のうちの 1 つを指定します。
ロケーションは、絶対パスを使用して指定します。 インクルード・リストの例を以下に示します。 # DOC BUNDLES org.eclipse.jdt.doc.isv org.eclipse.jdt.doc.user org.eclipse.pde.doc.user R:org.eclipse.platform.doc.* # NON-ECLIPSE BUNDLES com.ibm.icu com.jcraft.jsch R:javax¥..* ... |
いいえ |
| preferences | タスクの設定を行います。 この設定を使用して、問題の重大度を構成します。問題の重大度には、無視、警告、またはエラーの 3 つの指定可能な値があります。検出される一連の問題は、API ツールの対応する問題設定キーによって定義されます。 ロケーションは、絶対パスを使用して指定します。指定されたロケーションが存在しない場合、設定は行われません。 「#」で始まる行は無視されます。設定ファイルのフォーマットは、次のようになります。 #Thu Nov 20 17:35:06 EST 2008 ANNOTATION_ELEMENT_TYPE_ADDED_METHOD_WITHOUT_DEFAULT_VALUE=Ignore ANNOTATION_ELEMENT_TYPE_CHANGED_TYPE_CONVERSION=Ignore ANNOTATION_ELEMENT_TYPE_REMOVED_FIELD=Ignore ANNOTATION_ELEMENT_TYPE_REMOVED_METHOD=Ignore ANNOTATION_ELEMENT_TYPE_REMOVED_TYPE_MEMBER=Warning API_COMPONENT_ELEMENT_TYPE_REMOVED_API_TYPE=Ignore API_COMPONENT_ELEMENT_TYPE_REMOVED_TYPE=Ignore CLASS_ELEMENT_TYPE_ADDED_METHOD=Error CLASS_ELEMENT_TYPE_ADDED_RESTRICTIONS=Ignore CLASS_ELEMENT_TYPE_ADDED_TYPE_PARAMETER=Ignore CLASS_ELEMENT_TYPE_CHANGED_CONTRACTED_SUPERINTERFACES_SET=Ignore ...キーは、org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes で検出できます。 |
いいえ |
| debug | デバッグ値を設定します。
指定可能な値は、 true、false です。デフォルトは false です。
|
いいえ |
| eefile | 使用する実行環境ファイルを設定します。 デフォルトでは、JavaSE-1.6 実行環境に対応する実行環境ファイルが使用されます。 ファイルのフォーマットは、この wiki ページで説明されています。 ファイルは、絶対パスを使用して指定します。 |
いいえ |
<apitooling.analysis baseline="D:¥eclipse¥3.4.1¥eclipse" profile="D:¥eclipse-SDK-I20081118-0800-linux-gtk.tar.gz" report="D:¥reports¥xml" filters="D:¥filters" excludelist="D:¥exclude_list_external.txt" preferences="D:¥tests_api¥org.eclipse.pde.api.tools.prefs" debug="true" />
これにより、フォルダー D:¥reports¥xml 内に report.xml ファイルを作成するタスクが実行されます。D:¥exclude_list_external.txt にある除外リストおよび D:¥filters にある .api_filter ファイルを使用して、レポートする問題の数を削減します。
問題の重大度は、D:¥tests_api¥org.eclipse.pde.api.tools.prefs の指定に従って生成されます。
デバッグが使用可能であるため、いくつかのデバッグ・トレースが Ant コンソールに表示されます。

API フリーズの Ant タスク
ファイル生成の Ant タスク
API 使用の Ant タスク
分析レポート変換の Ant タスク
API フリーズ・レポート変換の Ant タスク
API 使用レポート変換の Ant タスク
API 非推奨の Ant タスク
API 非推奨レポート変換の Ant タスク