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.
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="..." />
| 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:
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:
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 |
<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.

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