Tarefa ant de desactualização da API

Finalidade

Esta tarefa executa uma análise completa da API de um perfil da API relativo a uma linha de base - procurando somente membros (classes, campos, métodos) que estejam desactualizados/não desactualizados. O perfil é o estado actual de um problema em desenvolvimento. O perfil é comparado a uma linha de base da API para alterações de desactualização (normalmente, a edição anterior de um produto).

Utilização

Descrição

O nome da tarefa ant é: apitooling.apideprecation. Para ser utilizado, o ficheiro jar apitooling-ant.jar tem de estar no caminho de classes Ant.

<apitooling.apideprecation
	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 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 semelhante à raiz do filtro. É criada uma subpasta para cada componente que tem problemas para ser comunicados. Cada subpasta contém um ficheiro chamado "report.xml".

É igualmente criada nesta pasta uma pasta especial chamada "allNonApiBundles" que contém um ficheiro chamado "report.xml". Este ficheiro lista todos os lotes que não estão a utilizar a natureza das Ferramentas da API.

A localização é especificada utilizando um caminho absoluto.
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;
 # DOC BUNDLES
 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
 # NON-ECLIPSE BUNDLES
 com.ibm.icu
 com.jcraft.jsch
 javax.servlet
 javax.servlet.jsp
 ...
A lista de exclusões pode conter expressões regulares se a linha começar por "R:".
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;
 # DOC BUNDLES
 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
 # NON-ECLIPSE BUNDLES
 com.ibm.icu
 com.jcraft.jsch
 javax.servlet
 javax.servlet.jsp
 ...
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 está descrito nesta página wiki.

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

Exemplos

 <apitooling.apideprecation
  baseline="D:\eclipse\3.4.1\eclipse"
  profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz"

  report="D:\reports\xml"
  excludelist="D:\exclude_list_external.txt"
  debug="true"
 />

Isto irá executar a tarefa criando ficheiros report.xml dentro da pasta D:\reports\xml. Irá utilizar a lista de exclusão para reduzir o número de problemas para o 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 congelamento da API de Ferramentas API
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 conversão de relatórios de utilização da API
Tarefa ant de conversão de relatórios de desactualização da API