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 中的代码的 API 使用:
org.eclipse.jdt.*
该模式必须是按此处定义的格式正确的正则表达式。
否
report 设置将生成报告的输出位置。

完成了此任务之后,就可以在此目录中使用分层结构来提供报告。 对于每个组件,如果有另一个捆绑软件引用它,就会为它创建子文件夹。 每个子文件夹中都包含一个名为“[bundlename].xml”的文件。 对于引用包含文件夹的捆绑软件的每个捆绑软件,在此文件夹中都有另一个子文件夹(名为“[referencing bundle name].xml”)。此引用捆绑软件文件夹内存在三个子文件夹之一(API、PRIVATE 或 OTHER),它们包含类型、方法或者该类型的字段引用。

已将另外三个特殊文件(即,“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 扫描期间要忽略的归档标识的逗号分隔列表。

归档标识为以下格式:[bundle id]:[path to archive]。
否
excludelist 设置排除列表位置。

排除列表位置指定将不对其进行分析的文本文件列表捆绑软件。缺省情况下,将对概要文件中的所有捆绑软件进行分析。可以使用包括和排除列表属性来有选择地包括和排除捆绑软件。包括列表确定要分析的捆绑软件集(如果省略了,那么将包括所有捆绑软件),然后应用排除列表。此文件的每一行指定下列其中一项:
  • 特定捆绑软件名称
  • 要与捆绑软件名称进行匹配的正则表达式(带有“R:”的行)
  • 注释(带有“#”的行)

使用绝对路径来指定此位置。
以下是排除列表的一个示例:
# EXCLUDED BUNDLES
R:org\.eclipse\..*\.doc\..*
...
否
includelist 设置包括列表位置。

包括列表位置指定要对其进行分析的文本文件列表捆绑软件。缺省情况下,将对概要文件中的所有捆绑软件进行分析。可以使用包括和排除列表属性来有选择地包括和排除捆绑软件。包括列表确定要分析的捆绑软件集(如果省略了,那么将包括所有捆绑软件),然后应用排除列表。此文件的每一行指定下列其中一项:
  • 特定捆绑软件名称
  • 要与捆绑软件名称进行匹配的正则表达式(带有“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 文件的任务。 此任务将在产品位置(由 .* 正则表达式定义)中搜索所有捆绑软件,搜索标识以 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 任务