Tarefa ant de congelamento da API de Ferramentas API

Finalidade

Esta tarefa identifica API que foram adicionadas, modificadas ou removidas relativamente à linha de base da API. A tarefa tem como objectivo validar a não ocorrência de alterações da API após um congelamento da API.

Utilização

Descrição

O nome da tarefa ant é: apitooling.apifreeze. Para ser utilizada, o ficheiro jar apitooling-ant.jar tem de estar no caminho de classe de ant.

<apitooling.apifreeze
	baseline="..."
	profile="..."
	report="..."
	excludelist="..."
	includelist="..."
	debug="..."
		eefilee="..."
/>

Parâmetros

Atributo Descrição Necessário
baseline Este atributo especifica a localização da linha de base de referência.

Pode ser um ficheiro .zip, .jar, .tgz ou .tar.gz, ou um directório que corresponda a um pasta de instalação do Eclipse. Este directório é onde se encontra o executável do Eclipse.

A localização é especificada utilizando um caminho absoluto.
Sim
profile Este atributo especifica a localização do produto actual ou o perfil que pretende comparar com a linha de base de referência.

Pode ser um ficheiro .zip, .jar, .tgz ou .tar.gz, ou um directório que corresponda a um pasta de instalação do Eclipse. Este directório é onde se encontra o executável do Eclipse.

A localização é especificada utilizando um caminho absoluto.
Sim
report Define o nome do ficheiro do relatório a ser gerado.

O nome deverá ser especificado utilizando um caminho absoluto.
Tem de ser a localização de um ficheiro, não um directório.
Sim
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. Além disso, esta tarefa suporta a listagem de membros nas listas de inclusão e exclusão. A lista de inclusão dissemina o conjunto de lotes e membros a analisar (quando omitidos, todos os lotes e membros são incluídos), e a lista de exclusão é então aplicada. Cada linha do ficheiro especifica:
  • um nome de lote específico
  • um nome de membro específico
  • uma expressão regular para corresponder em relação aos nomes de lotes ou membros (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:
# ECLIPSE MEMBERS
org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object;
# ECLIPSE BUNDLES
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_ERROR
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_WARNING
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_ELCL_COLLAPSEALL
# NON-ECLIPSE BUNDLES
com.ibm.icu
R:javax\..*
...
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. Além disso, esta tarefa suporta a listagem de membros nas listas de inclusão e exclusão. A lista de inclusão dissemina o conjunto de lotes e membros a analisar (quando omitidos, todos os lotes e membros são incluídos), e a lista de exclusão é então aplicada. Cada linha do ficheiro especifica:
  • um nome de lote específico
  • um nome de membro específico
  • uma expressão regular para corresponder em relação aos nomes de lotes ou membros (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:
# ECLIPSE MEMBERS
org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object;
# ECLIPSE BUNDLES
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_ERROR
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_WARNING
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_ELCL_COLLAPSEALL
# NON-ECLIPSE BUNDLES
com.ibm.icu
R:javax\..*
...
Não
debug Define o valor de depuração.

Os valores possíveis são: true, false
A predefinição é false.
Não
eefile Define o ficheiro do ambiente de execução a ser utilizado.

Por predefinição, é utilizado um ficheiro de ambiente de execução que corresponde a um ambiente de execução Java SE-1.6.

O formato do ficheiro é descrito na página wiki .

O ficheiro é especificado utilizando um caminho absoluto.
Não

Exemplos

	<apitooling.apifreeze
		baseline="D:\eclipse\3.4.1\eclipse"
		profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz"
		report="D:\report\report.xml"
		excludelist="D:\exclude_list.txt"
		debug="true"
	/>

Isto irá executar a tarefa criando report.xml dentro da pasta D:\report. Irá utilizar a lista de exclusão D:\exclude_list_external.txt para reduzir o número de problemas do relatório.

Uma vez que a depuração está activada, aparecerá alguma indicação de rastreio na consola ant.

Referência relacionada

Tarefa ant de análise
Tarefa ant de geração de ficheiros
Tarefa ant de utilização da API
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