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

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