API 使用の Ant タスク

目的

このタスクは、特定のベースラインの完全な検索を実行して、API 使用のレポートを作成します。

分析には、API ツール対応ではないバンドルは含まれません。

使用法

説明

Ant タスクの名前は、apitooling.apiuse です。 使用するには、jar ファイル apitooling-ant.jar が Ant クラスパス上になければなりません。

<apitooling.apiuse
	location="..."
	scopepattern="..."
	referencepattern="..."
	report="..."
	considerinternal="..."
	considerapi="..."
	considerillegaluse="..."
	apipatterns="..."
	internalpatterns="..."
	archivepatterns="..."
	excludelist="..."
	includelist="..."	
	debug="..."
/>

パラメーター

属性 説明 必須
location この属性は、API の使用の検索先となる、現行製品のロケーションを指定します。

このロケーションは、.zip、.jar、.tgz、.tar.gz ファイル、または製品あるいはバンドル・コレクションが含まれるディレクトリーになります。

ロケーションは、絶対パスを使用して指定します。
はい
scopepattern この属性は、検索対象のロケーション内のバンドルを選択するために使用する正規表現パターンを指定します。

例えば、以下は Eclipse バンドル内の API 使用のみをスキャンします。
org.eclipse.*
このパターンは、ここで定義されるように、適切にフォーマット設定された正規表現でなければなりません。
いいえ
referencepattern この属性は、検索結果をフィルターに掛けるために使用する正規表現パターンを指定します。 フィルターと一致するバンドルを参照する API 使用だけが報告されます。

例えば、以下は JDT のコードを参照する使用だけを報告します。
org.eclipse.jdt.*
このパターンは、ここで定義されるように、適切にフォーマット設定された正規表現でなければなりません。
いいえ
report レポートが生成される出力ロケーションを設定します。

タスクが完了すると、このディレクトリーで階層構造を使用することで、レポートが使用可能になります。それを参照する別のバンドルがあるコンポーネントごとに、サブフォルダーが作成されます。各サブフォルダーには、「[bundlename].xml」という名前のファイルが含まれています。このフォルダー内には、それを含んでいるフォルダーのバンドルを参照するバンドルごとに、別のサブフォルダー (「[referencing bundle name].xml」という名前) があります。 参照側のバンドル・フォルダー内には、その種類の型、メソッド、またはフィールド参照を含む 3 つのサブフォルダー (API、PRIVATE または OTHER) のうちの 1 つがあります。

その他に、3 つの特殊ファイルがレポート・ディレクトリーに書き込まれます。つまり、見つかった参照の数に関する情報を格納する「counts.xml」、使用情報を検索しなかったベースラインのバンドルに関する情報を格納する「not_searched.xml」、および .api_description ファイルが含まれていないバンドルに関する情報を格納する「no_apidescription.xml」の 3 つです。

ロケーションは、絶対パスを使用して指定します。

以下に例を示します。
  root
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- "counts.xml"
   +-- bundle name with usage
   		|
   		+--referencing bundle name
   			|
   			+-- [API or PRIVATE or OTHER]
   				|
   				+--[type_ or method_ or field_]references.xml
はい
considerinternal 検索中に、内部参照が考慮されるかどうか。

デフォルトは false です。
いいえ
considerapi 検索中に、API 参照が考慮されるかどうか。

デフォルトは false です。
いいえ
considerillegaluse 検索中に、正しくない API 使用参照が考慮されるかどうか。

デフォルトは false です。
いいえ
apipatterns API パッケージと見なすパッケージ名パターン (正規表現) のコンマ区切りリスト。

デフォルトで API の説明はスキャン・バンドルで使用されますが、これを使用して API パッケージをオーバーライドまたは追加することができます。
いいえ
internalpatterns private パッケージと見なすパッケージ名パターン (正規表現) のコンマ区切りリスト。

デフォルトで API の説明はスキャン・バンドルで使用されますが、これを使用して private パッケージをオーバーライドまたは追加することができます。
いいえ
archivepatterns スキャン中に無視するアーカイブ ID のコンマ区切りリスト。

アーカイブ ID の形式は [bundle id]:[path to archive] です。
いいえ
excludelist 除外リストのロケーションを設定します。

この除外リストのロケーションでは、分析から除外するバンドルをリストしたテキスト・ファイルを指定します。 デフォルトでは、プロファイルのすべてのバンドルが分析されます。インクルードおよび除外リスト属性を使用して、バンドルを選択的にインクルードしたり除外したりできます。インクルード・リストで、分析するバンドルのセットが初期化され (これを省略すると、すべてのバンドルがインクルードされる)、その後、除外リストが適用されます。 ファイルの各行は、次のうちの 1 つを指定します。
  • 特定のバンドル名
  • バンドル名と突き合わせる正規表現 (行は "R:" で始まる)
  • コメント (行は '#' で始まる)

ロケーションは、絶対パスを使用して指定します。
除外リストの例を以下に示します。
# EXCLUDED BUNDLES
R:org¥.eclipse¥..*¥.doc¥..*
...
いいえ
includelist インクルード・リストのロケーションを設定します。

インクルード・リストのロケーションは、分析に組み込むバンドルをリストするテキスト・ファイルを指定します。 デフォルトでは、プロファイルのすべてのバンドルが分析されます。インクルードおよび除外リスト属性を使用して、バンドルを選択的にインクルードしたり除外したりできます。インクルード・リストで、分析するバンドルのセットが初期化され (これを省略すると、すべてのバンドルがインクルードされる)、その後、除外リストが適用されます。 ファイルの各行は、次のうちの 1 つを指定します。
  • 特定のバンドル名
  • バンドル名と突き合わせる正規表現 (行は "R:" で始まる)
  • コメント (行は '#' で始まる)

ロケーションは、絶対パスを使用して指定します。
インクルード・リストの例を以下に示します。
# INCLUDED BUNDLES
R:org¥.eclipse¥..*
...
いいえ
filters 使用スキャン中に使用する API フィルターのルート・ディレクトリーを設定します。

引数は、参照をフィルターに掛けるのに使用される .api_filters ファイルのルート・ディレクトリーです。

.api_filters ファイルは、API の分析中に無視する特定の問題を指定します。 使用スキャン中、使用スキャンの結果からフィルターに掛けられる参照のリストに問題フィルターが変換されます。

ルートは、絶対パスを使用して指定します。
ルートには、以下の構造が含まれている必要があります。
 root
  |
  +-- component name (i.e. org.eclipse.jface)
         |
         +--- .api_filters
いいえ
debug デバッグ値を設定します。

指定可能な値は、true、false です。
デフォルトは false です。
いいえ

例

	<apitooling.apiuse
		location="/eclipse/eclipse.tar.gz"
		scopepattern=".*"
		referencepattern="org¥.eclipse.*"
		report="/eclipse/apiuse-both/XML"
		considerinternal="true"
		considerapi="true"
		considerillegaluse="true"
		archivepatterns="org.eclipse.test.bundle:/libs/contributed.jar"
		excludelist="D:¥exclude_list_external.txt"
		debug="true"
	/>

これにより、フォルダー /eclipse/apiuse-both/XML 内に *.xml ファイルを作成するタスクが実行されます。タスクは、ID が org.eclipse で始まる (org¥.eclipse.* 正規表現によって定義される) バンドルへの参照を求めて、製品ロケーション (正規表現 .* によって定義される) 内のすべてのバンドルを検索します。D:¥exclude_list_external.txt にある除外リスト・ファイルを使用して、レポートする問題の数を削減します。

スキャン中、org.eclipse.test.bundle 内の /libs/contributed.jar アーカイブで見つかるクラス・ファイルはすべて無視されます。

デバッグが使用可能である場合、いくつかのデバッグ・トレースが Ant コンソールに表示されます。

関連参照

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