API 使用マイグレーション Ant タスク

目的

このタスクでは、特定の API 使用スキャンを取り、特定の候補製品リリース内で再びその解決を試みて、未解決の参照があればそれを報告します。

使用法

説明

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

 <apitooling.apimigration
	candidate="..."
	usescan="..."
	scopepattern="..."
	referencepattern="..."
	excludelist="..."
	includelist="..."
	report="..."
	debug="..."
/>

パラメーター

属性 説明 必須
candidate この属性は、マイグレーション候補として使用する製品を指定します。

このロケーションは、.zip、.jar、.tgz、.tar.gz ファイル、または Eclipse のインストール・フォルダーに対応するディレクトリーなどになります。これは、Eclipse 実行可能プログラムが存在するディレクトリーです。

はい
usescan この属性は、マイグレーション候補との比較を行う製品使用スキャンを指定します。

usescan は、使用スキャンのルートへの絶対パスを使って指定されます。
はい
scopepattern この属性は、製品ロケーション内の参照元を検索するための要素のスコープを作成するのに使用する正規表現パターンを指定します。

このパターンは、ここで定義されるように、適切にフォーマット設定された正規表現でなければなりません。
いいえ
referencepattern 製品ロケーション内の参照先を検索するための要素のスコープを作成するのに使用する正規表現パターンを設定します。

このパターンは、ここで定義されるように、適切にフォーマット設定された正規表現でなければなりません。
いいえ
excludelist 除外リストのロケーションを設定します。

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

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

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

ロケーションは、絶対パスを使用して指定します。
インクルード・リストの例を以下に示します。
# INCLUDED BUNDLES
R:org¥.eclipse¥..*
...
いいえ
report レポートが生成される出力ロケーションを設定します。

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

そのほかに、使用情報を検索しなかったベースラインのバンドルに関する情報を含む「not_searched.xml」と、 .api_description ファイルが含まれていないバンドルに関する情報を含む「no_apidescription.xml」の 2 つの特殊ファイルが、レポート・ディレクトリーに書き込まれます。

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

例:
  root
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- bundle name with usage
     |
     +--referencing bundle name
      |
      +-- [API or PRIVATE or OTHER]
       |
       +--[type_ or method_ or field_]references.xml
はい
デバッグ デバッグ値を設定します。

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

サンプル

 <apitooling.apimigration
  candidate="/eclipse/sdk3.5"
  usescan="/eclipse/scans/sdk3.4"

  scopepattern=".*"
  referencepattern="org¥.eclipse.*"
  excludelist="D:¥exclude_list_external.txt"
  report="/eclipse/apimigration/xml"
  debug="true"

 />

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

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

関連参照

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