Tarefa ant de utilização da API

Finalidade

Esta tarefa executa uma pesquisa completa de uma linha de base fornecida para criar um relatório da utilização da API.

A análise não inclui agrupamentos que não sejam Ferramentas API activadas.

Utilização

Descrição

O nome da tarefa ant é: apitooling.apiuse. Para ser utilizada, o ficheiro jar apitooling-ant.jar tem de estar no caminho de classe de 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 a localização do produto actual que pretende pesquisar para verificar a utilização da API.

Pode ser um ficheiro .zip, .jar, .tgz, .tar.gz ou um directório que contém um produto ou colecção de lotes.

A localização é especificada utilizando um caminho absoluto.
Sim
scopepattern Este atributo especifica um padrão de expressão regular utilizado para seleccionar quais os lotes serão pesquisados na localização.

Por exemplo, o seguinte iria apenas pesquisar a utilização da API em lotes do Eclipse:
org.eclipse.*
O padrão tem de ser uma expressão regular bem formatada conforme se define aqui.
Não
referencepattern Este atributo especifica um padrão de expressão regular utilizado para filtrar os resultados da pesquisa. Apenas a utilização da API que faz referência a um lote correspondente ao filtro será registada.

Por exemplo, o seguinte iria registar apenas a utilização que faz referências a código em JDT:
org.eclipse.jdt.*
O padrão tem de ser uma expressão regular bem formatada conforme se define aqui.
Não
report Define a localização da saída de dados em que os relatórios são gerados.

Após a conclusão da tarefa, existem relatórios disponíveis no directório indicado que utilizam uma estrutura hierárquica. É criada uma subpasta para cada componente que tem outro agrupamento que o refere. Cada subpasta contém um ficheiro chamado "[bundlename].xml". Dentro dessa pasta existe outra subpasta (com o nome "[nome agrupamento referenciado].xml") para cada agrupamento que faça referência ao agrupamento da pasta que o contém. Dentro da pasta de agrupamentos referenciados está uma das subpastas de árvore (API, PRIVATE ou OTHER) que contém as referências de tipo, método ou campo dessa categoria.

No directório de relatórios são gravados três outros ficheiros especiais, 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, lotes da linha de base que não foram pesquisados ou informação de utilização e os que não tiveram ficheiros .api_description, respectivamente.

A localização é especificada utilizando um caminho absoluto.

Por exemplo:
  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
Sim
considerinternal Se as referências internas deverão ou não ser consideradas durante a pesquisa.

A predefinição é false.
Não
considerapi Se as referências da API deverão ou não ser consideradas durante a pesquisa.

A predefinição é false.
Não
considerillegaluse Se as referências de utilização da API ilegais devem ser consideradas durante a pesquisa.

A predefinição é false.
Não
apipatterns Uma lista separada por vírgulas de padrões de nomes de pacotes (expressões regulares) a considerar como pacotes da API.

Por predefinição, todas as descrições da API são utilizadas nos lotes pesquisados, mas podem ser utilizadas para substituir ou adicionar pacotes da API.
Não
internalpatterns Uma lista separada por vírgulas de padrões de nomes de pacotes (expressões regulares) a considerar como pacotes privados.

Por predefinição, todas as descrições da API são utilizadas nos lotes pesquisados, mas podem ser utilizadas para substituir ou adicionar pacotes privados.
Não
archivepatterns Uma lista separada por vírgulas de identificadores de arquivo a ignorar durante a pesquisa.

Um identificador de arquivo tem a seguinte forma: [id lote]:[caminho para arquivo].
Não
excludelist Define a localização da lista de exclusão.

A localização da lista de exclusões especifica um ficheiro de texto que lista os lotes a excluir da análise. Por predefinição, todos os lotes no perfil serão analisados. Os atributos da lista de exclusões e inclusões podem ser utilizados, de forma selectiva, para incluir e excluir lotes. A lista de inclusões dissemina o conjunto de lotes a analisar (quando omitidos, todos os lotes são incluídos), e a lista de exclusões é então aplicada. Cada linha do ficheiro especifica:
  • um nome de lote específico
  • uma expressão regular para corresponder relativamente a nomes de lotes (linhas que começam por "R:")
  • um comentário (linhas que começam por '#')

A localização é especificada utilizando um caminho absoluto.
A seguir encontra-se um exemplo de uma lista de exclusões:
# EXCLUDED BUNDLES
R:org\.eclipse\..*\.doc\..*
...
Não
includelist Defina a localização da lista de inclusões.

A localização da lista de inclusões especifica um ficheiro de texto que lista os lotes a incluir da análise. Por predefinição, todos os lotes no perfil serão analisados. Os atributos da lista de exclusões e inclusões podem ser utilizados, de forma selectiva, para incluir e excluir lotes. A lista de inclusões dissemina o conjunto de lotes a analisar (quando omitidos, todos os lotes são incluídos), e a lista de exclusões é então aplicada. Cada linha do ficheiro especifica:
  • um nome de lote específico
  • uma expressão regular para corresponder relativamente a nomes de lotes (linhas que começam por "R:")
  • um comentário (linhas que começam por '#')

A localização é especificada utilizando um caminho absoluto.
A seguir encontra-se um exemplo de uma lista de inclusões:
# INCLUDED BUNDLES
R:org\.eclipse\..*
...
Não
filtros Defina o directório de raiz dos filtros da API a utilizador durante a pesquisa de utilização.

O argumento do directório raiz dos ficheiros .api_filters devem ser utilizados para filtrar referências.

Os ficheiros .api_filters especificam problemas específicos a ignorar durante a análise da api. Durante a pesquisa de utilização, os filtros de problemas serão convertidos numa lista de referências que serão filtrados a partir dos resultados da pesquisa de utilização.

A raiz é especificada utilizando um caminho absoluto.
A raiz precisa de conter a seguinte estrutura:
 root
  |
  +-- component name (i.e. org.eclipse.jface)
         |
         +--- .api_filters
Não
debug Define o valor de depuração.

Os valores possíveis são: true, false
A predefiniçã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"
	/>

Este exemplo irá executar a tarefa criando ficheiros *.xml dentro da pasta /eclipse/apiuse-both/XML. A tarefa irá pesquisar todos os lotes na localização do produto - definida pela expressão regular .* - pesquisando todas as referências a quaisquer lotes cujo identificador começa por org.eclipse (definido pela expressão regular org\.eclipse.*). Irá utilizar o ficheiro da lista de exclusões localizado em D:\exclude_list_external.txt para reduzir o número de problemas a registar.

Ao pesquisar, quaisquer ficheiros de classe encontrados no arquivo /libs/contributed.jar dentro de org.eclipse.test.bundle serão ignorados.

Se a depuração estiver activada, aparecerá alguma indicação de rastreio na consola ant.

Referência relacionada

Tarefa ant de congelamento da API
Tarefa ant de geração de ficheiros
Tarefa ant de conversão de relatórios de análise
Tarefa ant de conversão de relatórios de congelamento da API
Tarefa ant de desactualização da API
Tarefa ant de conversão de relatórios de desactualização da API
Tarefa ant de conversão de relatórios de utilização da API