API 淘汰 Ant 作業

目的

這項作業會執行 API 設定檔相對於基準線的完整 API 分析 - 僅尋找已淘汰 / 未淘汰的成員(類別、欄位、方法)。此設定檔是開發中產品的現行狀態。此設定檔會與 API 基準線做比較,以瞭解淘汰方面的變更(通常是產品的舊版)。

用法

說明

Ant 作業的名稱為:apitooling.apideprecation。如果要能夠使用,JAR 檔 apitooling-ant.jar 必須在 Ant 類別路徑上。

<apitooling.apideprecation
	baseline="..."
	profile="..."
	report="..."
	excludelist="..."
	includelist="..."
	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 工具」本質的所有軟體組。

這個位置是使用絕對路徑指定的。
是
excludelist 設定排除清單位置。

排除清單位置指定一個文字檔,列出要從分析中排除的軟體組。 依預設,會分析設定檔中的所有軟體組。 您可以利用併入及排除清單屬性來選擇性地併入及排除軟體組。 另外,這項作業還支援列出併入及排除清單中的成員。 併入清單會植入一組要分析的軟體組和成員(省略的話,就會併入所有軟體組和成員),然後再套用排除清單。 檔案中的每一行指定下列項目之一:
  • 特定的軟體組名稱
  • 特定成員名稱
  • 用來比對軟體組或成員名稱的正規表示式(行首是 "R:")
  • 註解(行首是 '#')

這個位置是使用絕對路徑指定的。
以下是一份範例排除清單:
 # ECLIPSE MEMBERS
 org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object;
 # 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
 javax.servlet
 javax.servlet.jsp
 ...
如果行首是 "R:",排除清單可以包含正規表示式。
否
includelist 設定併入清單位置。

併入清單位置指定一個文字檔,列出要併入分析中的軟體組。 依預設,會分析設定檔中的所有軟體組。 您可以利用併入及排除清單屬性來選擇性地併入及排除軟體組。 另外,這項作業還支援列出併入及排除清單中的成員。 併入清單會植入一組要分析的軟體組和成員(省略的話,就會併入所有軟體組和成員),然後再套用排除清單。 檔案中的每一行指定下列項目之一:
  • 特定的軟體組名稱
  • 特定成員名稱
  • 用來比對軟體組或成員名稱的正規表示式(行首是 "R:")
  • 註解(行首是 '#')

這個位置是使用絕對路徑指定的。
以下是一份範例併入清單:
 # ECLIPSE MEMBERS
 org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object;
 # 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
 javax.servlet
 javax.servlet.jsp
 ...
否
除錯 設定除錯值。

可能的值為:true、false
預設值是 false。
否
eefile 設定要使用的環境檔案。

依預設,會使用對應於 JavaSE-1.6 執行環境的執行環境檔案。

檔案的格式說明於這個 Wiki 網頁上。

這個檔案是使用絕對路徑指定的。
否

範例

 <apitooling.apideprecation
  baseline="D:\eclipse\3.4.1\eclipse"
  profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz"

  report="D:\reports\xml"
  excludelist="D:\exclude_list_external.txt"
  debug="true"
 />

這個範例將在 D:\reports\xml 資料夾內執行建立 report.xml 檔案的作業。 它將使用排除清單來減少要報告的問題數目。

由於已啟用除錯,部分除錯追蹤將顯示在 Ant 主控台上。

相關參照

API 凍結 Ant 作業
檔案產生 Ant 作業
API 用法 Ant 作業
分析報告轉換 Ant 作業
API 凍結報告轉換 Ant 作業
API 用法報告轉換 Ant 作業
API 淘汰報告轉換 Ant 作業