Задача Ant использования API

Назначение

Эта задача выполняет полный поиск данной контрольной версии для создания отчета об использовании API.

Анализ не включает в себя комплекты, в которых не включены Инструменты API.

Формат

Описание

Именем задачи Ant является apitooling.apiuse. Для использования JAR-файла apitooling-ant.jar он должен находиться в classpath Ant.

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

Параметры

Атрибут Описание Обязательный
location Этот атрибут задает расположение текущего продукта, для которой вы хотите определить использование API.

Это может быть файл .zip, .jar, .tgz, .tar.gz или каталог, содержащий продукт или набор комплектов.

Расположение задается с помощью абсолютного пути.
Да
scopepattern Этот атрибут указывает шаблон регулярного выражения, с помощью которого можно выбрать те комплекты в расположении, в которых требуется выполнить поиск.

Например, следующее значение задает поиск использования API только в комплектах Eclipse:
org.eclipse.*
Шаблон должен быть указан в формате регулярных выражений, описание которого приведено здесь.
Нет
referencepattern Этот атрибут указывает шаблон регулярного выражения, используемый для фильтрации результатов поиск. В отчете будет показано только использование API, ссылающееся на комплект, который соответствует условию фильтра.

Например, следующее значение приведет к включению в отчет только использование, ссылающееся на код в JDT:
org.eclipse.jdt.*
Шаблон должен быть указан в формате регулярных выражений, описание которого приведено здесь.
Нет
report Установите расположение вывода, в котором будут генерироваться отчеты.

После выполнения задачи отчеты становятся доступными в этом каталоге с помощью иерархической структуры. Подпапка создается для каждого компонента, на который ссылается другой комплект. Каждая подпапка содержит файл с именем "[имя_комплекта].xml". В этой папке содержится другая подпапка (по имени "[имя ссылающегося комплекта].xml") для каждого комплекта, который ссылается на комплект содержащей папки. В папке ссылающегося комплекта находится одна из трех подпапок (API, PRIVATE или OTHER), которая содержит ссылки на тип, метод или поле этого рода.

Три других специальных файла - "counts.xml", "not_searched.xml" и "no_apidescription.xml" - записаны в каталоге отчета и соответственно содержат информацию о числе найденных ссылок, о тех комплектах из контрольной версии, для которых не производился поиск информации об использовании, и тех комплектах, которые не содержат файлов .api_description.

Расположение задается с помощью абсолютного пути.

Например:
  root
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- "counts.xml"
   +-- имя комплекта и использование
   		|
   		+--имя ссылающегося комплекта
   			|
   			+-- [API или PRIVATE или OTHER]
   				|
   				+--[type_ или method_ или field_]references.xml
Да
considerinternal Должны ли внутренние ссылки учитываться при поиске.

Значение по умолчанию - false.
Нет
considerapi Должны ли ссылки на API учитываться при поиске.

Значение по умолчанию - false.
Нет
considerillegaluse Должны ли ссылки на недопустимые API учитываться при поиске.

Значение по умолчанию - false.
Нет
apipatterns Перечисленные через запятую шаблоны имен пакетов (регулярные выражения), которые следует рассматривать как пакеты API.

По умолчанию в просмотренных комплектах применяются описания API, однако это можно изменить для переопределения или добавления пакетов API.
Нет
internalpatterns Перечисленные через запятую шаблоны имен пакетов (регулярные выражения), которые следует рассматривать как частные пакеты.

По умолчанию в просмотренных комплектах применяются описания API, однако это можно изменить для переопределения или добавления частных пакетов.
Нет
archivepatterns Список идентификаторов архивов, игнорируемых в ходе сканирования (в качестве разделителя применяется запятая).

Идентификатор архива в формате: [ИД комплекта]:[путь к архиву].
Нет
excludelist Установите расположение списка исключений.

Расположение списка исключения указывает текстовый файл, в котором перечислены комплекты, подлежащие исключению из анализа. По умолчанию анализируются все комплекты профайла. Атрибуты списка включения и списка исключения можно использовать для выборочного включения и исключения комплектов. Список включения задает набор комплектов для анализа (если не указан, включаются все комплекты), затем применяется список исключения. Каждая строка файла задает один из следующих элементов:
  • имя определенного комплекта
  • регулярное выражение для поиска совпадений с именами комплектов (строки с "R:")
  • комментарий (строки с '#')

Расположение задается с помощью абсолютного пути.
Пример списка исключения:
# EXCLUDED BUNDLES
R:org\.eclipse\..*\.doc\..*
...
Нет
includelist Задайте расположение списка включения.

Расположение списка включения указывает текстовый файл, в котором перечислены комплекты, подлежащие включению в анализ. По умолчанию анализируются все комплекты профайла. Атрибуты списка включения и списка исключения можно использовать для выборочного включения и исключения комплектов. Список включения задает набор комплектов для анализа (если не указан, включаются все комплекты), затем применяется список исключения. Каждая строка файла задает один из следующих элементов:
  • имя определенного комплекта
  • регулярное выражение для поиска совпадений с именами комплектов (строки с "R:")
  • комментарий (строки с '#')

Расположение задается с помощью абсолютного пути.
Пример списка включения:
# INCLUDED BUNDLES
R:org\.eclipse\..*
...
Нет
filters Установите корневой каталог фильтров API, используемых в процессе просмотра использования.

Аргумент - это корневой каталог файлов .api_filters, который должен использоваться для фильтрации ссылок.

Файлы .api_filters указывают, какие именно неполадки требуется игнорировать при анализе api. Во время осмотра использования фильтры неполадок будут преобразованы в список ссылок, которые должны быть отфильтрованы из результатов осмотра использования.

Корневой каталог задается с помощью абсолютного пути.
В корневом каталоге должна содержаться следующая структура:
 root
  |
  +-- имя компонента (например, 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"
	/>

Выполнится задача, создающая файлы *.xml в папке /eclipse/apiuse-both/XML. Задача выполняет поиск всех комплектов в расположении продукта (регулярное выражение .*), для того чтобы найти все ссылки на комплекты, идентификаторы которых начинаются с org.eclipse (регулярное выражение org\.eclipse.*). Будет использоваться файл списка исключения, расположенный в каталоге D:\exclude_list_external.txt, для уменьшения числа неполадок в отчете.

В ходе сканирования игнорируются все файлы классов, найденные в архиве /libs/contributed.jar из комплекта org.eclipse.test.bundle.

После включения отладки некоторая информация трассировки будет показана на консоли Ant.

Связанные ссылки

Задача Ant фиксации состояния API
Задача Ant генерации файла
Задача Ant преобразования отчета об анализе
Задача Ant преобразования отчета о фиксации состояния API
Задача Ant об устаревшем API
Задача Ant преобразования отчета об устаревшем API
Задача Ant преобразования отчета об использовании API