這項作業對給定的基準線執行完整搜尋,以建立一份 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")。 有三個子資料夾(API、PRIVATE 或 OTHER)包含那一種的類型、方法或欄位參照,它們其中之一會在參照的軟體組資料夾內。 另外還有三個特殊檔案會寫入 report 目錄中,它們是 "counts.xml"、"not_searched.xml" 和 "no_apidescription.xml",其中分別包含找到的參照數目、基準線中未搜尋用法資訊的軟體組,以及其中沒有 .api_description 檔之軟體組等相關資訊。 這個位置是使用絕對路徑指定的。 例如: 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 | 一份逗點區隔清單,列出要視為專用套件的套件名稱型樣(正規表示式)。
依預設,會在掃描的軟體組中使用 API 說明,但這可用來置換或新增專用套件。 |
否 |
| archivepatterns | 一份逗點區隔清單,列出掃描期間所要忽略的保存檔 ID。
保存檔 ID 的格式如下: [bundle id]:[path to archive]。 |
否 |
| excludelist |
設定排除清單位置。
排除清單位置指定一個文字檔,列出要從分析中排除的軟體組。 依預設,會分析設定檔中的所有軟體組。 您可以利用併入及排除清單屬性來選擇性地併入及排除軟體組。 併入清單會植入一組要分析的軟體組(省略的話,就會併入所有軟體組),然後再套用排除清單。 檔案中的每一行指定下列項目之一:
這個位置是使用絕對路徑指定的。 以下是一份範例排除清單: # EXCLUDED BUNDLES R:org\.eclipse\..*\.doc\..* ... |
否 |
| includelist |
設定併入清單位置。
併入清單位置指定一個文字檔,列出要併入分析中的軟體組。 依預設,會分析設定檔中的所有軟體組。 您可以利用併入及排除清單屬性來選擇性地併入及排除軟體組。 併入清單會植入一組要分析的軟體組(省略的話,就會併入所有軟體組),然後再套用排除清單。 檔案中的每一行指定下列項目之一:
這個位置是使用絕對路徑指定的。 以下是一份範例併入清單: # 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 作業