Tarefa Ant de Uso da API

Propósito

Esta tarefa executa uma procura completa de uma determinada linha de base para criar um relatório de uso da API.

A análise não inclui pacotes configuráveis que não são ativados por Ferramentas de API.

Uso

Descrição

O nome da tarefa Ant é: apitooling.apiuse. Para ser usado, o arquivo jar apitooling-ant.jar deve estar no caminho de classe Ant.

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

Parâmetros

Atributo Descrição Necessário
location Este atributo especifica o local do produto atual que você deseja procurar para o uso da API.

Ele pode ser um arquivo .zip, .jar, .tgz, .tar.gz ou um diretório contendo um produto ou uma coleção de pacotes configuráveis.

O local é especificado usando um caminho absoluto.
Sim
scopepattern Este atributo especifica um padrão de expressão regular usado para selecionar que pacotes configuráveis no local serão procurados.

Por exemplo, o seguinte apenas faria a varredura de uso da API em pacotes configuráveis do Eclipse:
org.eclipse.*
O padrão deve ser uma expressão regular bem formada, como definido aqui.
Não
referencepattern Este atributo especifica um padrão de expressão regular usado para filtrar os resultados da procura. Apenas o uso da API que referencia um pacote configurável correspondente ao filtro será relatado.

Por exemplo, o seguinte apenas relataria o uso que referencia o código em JDT:
org.eclipse.jdt.*
O padrão deve ser uma expressão regular bem formada, como definido aqui.
Não
report Configure o local de saída onde os relatórios serão gerados.

Depois que a tarefa for concluída, os relatórios estarão disponíveis neste diretório usando uma estrutura hierárquica. Uma subpasta é criada para cada componente que possui outro pacote configurável que faz referência a ele. Cada subpasta contém um arquivo chamado "[bundlename].xml". Dentro desta pasta há outra subpasta (denominada "[referencing bundle name].xml") para cada pacote configurável que faz referência ao pacote configurável da pasta de contenção. Dentro da pasta do pacote configurável de referência há uma de três subpastas (API, PRIVATE ou OTHER) que contêm referências de tipo, método ou campo desse tipo.

Outros três arquivos especiais são gravados no diretório do relatório, que são "counts.xml", "not_searched.xml" e "no_apidescription.xml" e contêm informações sobre o número de referências encontradas, os pacotes configuráveis a partir da linha de base nos quais não foram procuradas informações de uso e que não tinham arquivos .api_description neles, respectivamente.

O local é especificado usando um caminho absoluto.

Por exemplo:
  root
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- "counts.xml"
   +-- nome do pacote configurável com uso
   		|
   		+--nome de pacote configurável de referência
   			|
   			+-- [API ou PRIVATE ou OTHER]
   				|
   				+--[type_ ou method_ ou field_]references.xml
Sim
considerinternal Se as referências internas devem ser consideradas durante a procura.

O padrão é false.
Não
considerapi Se as referências de API devem ser consideradas durante a procura.

O padrão é false.
Não
considerillegaluse Se for ilegal, as referências de API deverão ser consideradas durante a procura.

O padrão é false.
Não
apipatterns Uma lista separada por vírgula de padrões de nomes de pacotes (expressões regulares) que serão considerados como pacotes de APIs.

Por padrão, as descrições de API são usadas nos pacotes configuráveis varridos, mas podem ser usadas para substituir ou incluir pacotes de APIs.
Não
internalpatterns Uma lista separada por vírgula de padrões de nomes de pacotes (expressões regulares) que serão considerados como pacotes privados.

Por padrão, as descrições de API são usadas nos pacotes configuráveis varridos, mas podem ser usadas para substituir ou incluir pacotes privados.
Não
archivepatterns Uma lista separada por vírgula de identificadores de archive que serão ignorados durante a varredura.

Um identificador de archive tem o formato: [id do pacote configurável]:[caminho para arquivamento].
Não
excludelist Configure o local da lista de exclusão.

O local da lista de exclusão especifica um arquivo de texto listando pacotes configuráveis a serem excluídos da análise. Pelo padrão, todos os pacotes configuráveis no perfil são analisados. Os atributos da lista de inclusão e exclusão podem ser usados para seletivamente incluir e excluir pacotes configuráveis. A lista de inclusão fornece o valor inicial do conjunto de pacotes configuráveis a ser analisado (quando omitido, todos os pacotes configuráveis são incluídos) e a lista de exclusão é então aplicada. Cada linha do arquivo especifica:
  • um nome de pacote configurável específico
  • uma expressão regular com a qual corresponder os nomes dos pacotes configuráveis (linhas com "R:")
  • um comentário (linhas com '#')

O local é especificado usando um caminho absoluto.
A seguir há um exemplo de lista de exclusão:
# PACOTES CONFIGURÁVEIS EXCLUÍDOS R:org\.eclipse\..*\.doc\..* ...
Não
includelist Configura o local da lista de inclusão.

O local da lista de inclusão especifica um arquivo de texto listando pacotes configuráveis a serem incluídos na análise. Pelo padrão, todos os pacotes configuráveis no perfil são analisados. Os atributos da lista de inclusão e exclusão podem ser usados para seletivamente incluir e excluir pacotes configuráveis. A lista de inclusão fornece o valor inicial do conjunto de pacotes configuráveis a ser analisado (quando omitido, todos os pacotes configuráveis são incluídos) e a lista de exclusão é então aplicada. Cada linha do arquivo especifica:
  • um nome de pacote configurável específico
  • uma expressão regular com a qual corresponder os nomes dos pacotes configuráveis (linhas com "R:")
  • um comentário (linhas com '#')

O local é especificado usando um caminho absoluto.
A seguir há um exemplo de lista de inclusão:
# PACOTES CONFIGURÁVEIS INCLUÍDOS R:org\.eclipse\..* ...
Não
filtros Configure o diretório-raiz dos filtros de API para usar durante a varredura de uso.

O argumento é o diretório-raiz dos arquivos .api_filters que devem ser usados para filtrar referências.

Os arquivos .api_filters determinam problemas específicos a serem ignorados durante a análise da API. Durante a varredura de uso, os filtros de problemas serão convertidos em uma lista de referências que será filtrada a partir dos resultados da varredura de uso.

A raiz é especificada usando um caminho absoluto.
A raiz precisa conter a seguinte estrutura:
 raiz
  |
  +-- nome do componente (ou seja, org.eclipse.jface)
         |
         +--- .api_filters
Não
depuração Configure o valor da depuração.

Os valores possíveis são: true, false
O padrão é false.
Não

Exemplos

	<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"
	/>

Isto executará a tarefa criando arquivos *.xml dentro da pasta /eclipse/apiuse-both/XML. A tarefa procurará todos os pacotes configuráveis no local do produto - definido pela expressão regular .* - pesquisando todas as referências para todos os pacotes configuráveis cujo identificador começa com org.eclipse (definido pela expressão regular org\.eclipse.*). Ela usará o arquivo de lista de exclusões localizado em D:\exclude_list_external.txt para reduzir o número de problemas a relatar.

Durante a varredura, todos os arquivos de classe localizados no archive /libs/contributed.jar, dentro de org.eclipse.test.bundle, serão ignorados.

Se a depuração estiver ativada, algum rastreio de depuração será exibido no console Ant.

Referência relacionada

Tarefa Ant de Congelamento da API
Tarefa Ant de Geração de Arquivo
Tarefa Ant de Conversão do Relatório de Análise
Tarefa Ant de Conversão de Relatório de Congelamento de API
Tarefa Ant de Reprovação da API
Tarefa Ant de Conversão do Relatório de Reprovação da API
Tarefa Ant de Conversão do Relatório de Uso da API