Esta tarefa executa uma análise de API completa de um perfil de API relativo a uma linha de base - incluindo o uso da API, a compatibilidade binária e a validação do número da versão do pacote configurável. O perfil é o estado atual de um produto em desenvolvimento. O perfil é comparado a uma linha de base de API para compatibilidade binária (geralmente o release anterior de um produto).
A análise não inclui a validação da tag @since pois toda verificação é executada nos arquivos de classe binários (a origem não é analisada).
O nome da tarefa Ant é: apitooling.analysis. Para ser usado, o arquivo jar apitooling-ant.jar deve estar no caminho de classe Ant.
<apitooling.analysis baseline="..." profile="..." report="..." filters="..." excludelist="..." includelist="..." preferences="..." debug="..." eefile="..." />
| Atributo | Descrição | Necessário |
| baseline | Este atributo especifica o local da linha de base de referência.
Pode ser um arquivo .zip, .jar, .tgz, .tar.gz, ou um diretório que corresponda à pasta de instalação do Eclipse. Este é o diretório no qual se localiza o Eclipse executável. O local é especificado usando um caminho absoluto. |
Sim |
| profile | Este atributo especifica o local do produto ou perfil atual que você deseja comparar com relação à linha de base de referência.
Pode ser um arquivo .zip, .jar, .tgz, .tar.gz, ou um diretório que corresponda à pasta de instalação do Eclipse. Este é o diretório no qual se localiza o Eclipse executável. O local é especificado usando um caminho absoluto. |
Sim |
| 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 semelhante à raiz do filtro. Uma subpasta é criada para cada componente que tem problemas para ser relatado. Cada subpasta contém um arquivo chamado "report.xml". Uma pasta especial chamada "allNonApiBundles" também é criada nesta pasta que também contém um arquivo chamado "report.xml". Este arquivo lista todos os pacotes configuráveis que não estão usando a natureza de Ferramentas da API. Também há um arquivo "counts.xml" criado no diretório de relatório que contém um resumo dos problemas localizados. O local é especificado usando um caminho absoluto. |
Sim |
| filtros | Configure o diretório-raiz dos filtros de API para usar durante a análise.
O argumento é o diretório-raiz dos arquivos .api_filters que devem ser usados para filtrar problemas em potencial criados pela análise das Ferramentas da API. 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 |
| 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 DO DOCUMENTO org.eclipse.jdt.doc.isv org.eclipse.jdt.doc.user org.eclipse.pde.doc.user org.eclipse.platform.doc.isv org.eclipse.platform.doc.user # PACOTES CONFIGURÁVEIS NÃO ECLIPSE com.ibm.icu com.jcraft.jsch R:javax\..* ... |
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 DO DOCUMENTO org.eclipse.jdt.doc.isv org.eclipse.jdt.doc.user org.eclipse.pde.doc.user R:org.eclipse.platform.doc.* # PACOTES CONFIGURÁVEIS NÃO ECLIPSE com.ibm.icu com.jcraft.jsch R:javax\..* ... |
Não |
| preferences | Configure as preferências para a tarefa.
As preferências são usadas para configurar gravidades de problemas. As gravidades de problemas possuem três valores possíveis: Ignorar, Aviso ou Erro. O conjunto de problemas detectados é definido pelas chaves de preferência de problema correspondentes nas ferramentas da API. O local é especificado usando um caminho absoluto. Se o local fornecido não existir, as preferências não serão configuradas. As linhas que iniciam com '#' são ignoradas. O formato do arquivo de preferências é semelhante a este: #Thu Nov 20 17:35:06 EST 2008 ANNOTATION_ELEMENT_TYPE_ADDED_METHOD_WITHOUT_DEFAULT_VALUE=Ignore ANNOTATION_ELEMENT_TYPE_CHANGED_TYPE_CONVERSION=Ignore ANNOTATION_ELEMENT_TYPE_REMOVED_FIELD=Ignore ANNOTATION_ELEMENT_TYPE_REMOVED_METHOD=Ignore ANNOTATION_ELEMENT_TYPE_REMOVED_TYPE_MEMBER=Warning API_COMPONENT_ELEMENT_TYPE_REMOVED_API_TYPE=Ignore API_COMPONENT_ELEMENT_TYPE_REMOVED_TYPE=Ignore CLASS_ELEMENT_TYPE_ADDED_METHOD=Error CLASS_ELEMENT_TYPE_ADDED_RESTRICTIONS=Ignore CLASS_ELEMENT_TYPE_ADDED_TYPE_PARAMETER=Ignore CLASS_ELEMENT_TYPE_CHANGED_CONTRACTED_SUPERINTERFACES_SET=Ignore ...As chaves podem ser localizadas em org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes. |
Não |
| depuração | Configure o valor da depuração.
Os valores possíveis são: true, false
O padrão é false.
|
Não |
| eefile | Configure o arquivo de ambiente de execução a ser usado.
Por padrão, um arquivo de ambiente de execução correspondente a um ambiente de execução JavaSE-1.6 é usado. O formato do arquivo é descrito nesta página wiki. O arquivo é especificado usando um caminho absoluto. |
Não |
<apitooling.analysis baseline="D:\eclipse\3.4.1\eclipse" profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz" report="D:\reports\xml" filters="D:\filters" excludelist="D:\exclude_list_external.txt" preferences="D:\tests_api\org.eclipse.pde.api.tools.prefs" debug="true" />
Isto executará a tarefa ao criar arquivos report.xml dentro da pasta D:\reports\xml.
Isto usará a lista de exclusão e os arquivos .api_filter localizados em D:\exclude_list_external.txt e
D:\filters para reduzir o número de problemas a relatar.
As gravidades de problemas serão geradas conforme especificado por D:\tests_api\org.eclipse.pde.api.tools.prefs.
Como a depuração está ativada, aparecerão alguns rastreios de depuração no console Ant.

Tarefa Ant de Congelamento da API
Tarefa Ant de Geração de Arquivo
Tarefa Ant de Uso da API
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 Conversão do Relatório de Uso da API
Tarefa Ant de Reprovação da API
Tarefa Ant de Conversão do Relatório de Reprovação da API