Tarefa Ant de Migração do Uso da API

Propósito

Esta tarefa obtém uma varredura do uso da API especificada e tenta resolvê-la novamente dentro de um release específico do produto candidato e informa qualquer referência não resolvida.

Uso

Descrição

O nome da tarefa Ant é: apitooling.apimigration. Para ser usado, o arquivo jar apitooling-ant.jar deve estar no caminho de classe Ant.

 <apitooling.apimigration 	candidate="..."
	usescan="..."
	scopepattern="..."
	referencepattern="..."
	excludelist="..."
	includelist="..."
	report="..."
	debug="..."
 />

Parâmetros

Atributo Descrição Necessário
candidate Este atributo especifica o produto que você deseja usar como o candidato da migração.

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.

Sim
usescan Este atributo especifica a varredura de uso do produto que você deseja comparar com o candidato da migração.

O atributo usescan é especificado usando um caminho absoluto para a raiz da varredura de uso.
Sim
scopepattern Este atributo especifica o padrão de expressão regular usado para criar o escopo dos elementos nos quais procurar referências no local do produto.

O padrão deve ser uma expressão regular bem formada, como definido aqui.
Não
referencepattern Configura o padrão de expressão regular usado para criar o escopo de elementos nos quais procurar referências no local do produto.

O padrão deve ser uma expressão regular bem formada, como definido aqui.
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:
  • um nome de pacote configurável específico
  • uma expressão regular com a qual corresponder os nomes dos pacotes configuráveis (linhas com "R:")
  • um comentário (linhas com '#')

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:
  • um nome de pacote configurável específico
  • uma expressão regular com a qual corresponder os nomes dos pacotes configuráveis (linhas com "R:")
  • um comentário (linhas com '#')

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
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.

Dois outros arquivos especiais são gravados no diretório de relatório, que são "not_searched.xml" e "no_apidescription.xml", e eles contêm informações sobre pacotes configuráveis da linha de base que não eram procura para informações de uso e os que não tinham um arquivo .api_description neles, respectivamente.

O local é especificado usando um caminho absoluto.

Por exemplo:
  raiz
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- nome do pacote configurável com uso
     |
     +--nome do pacote configurável de referência
      |
      +-- [API ou PRIVATE ou OTHER]
       |
       +--[type_ ou method_ ou field_]references.xml
Sim
depuração Configure o valor da depuração.

Os valores possíveis são: true, false
O padrão é false.
Não

Exemplos

 <apitooling.apimigration
  candidate="/eclipse/sdk3.5"
  usescan="/eclipse/scans/sdk3.4"

  scopepattern=".*"
  referencepattern="org\.eclipse.*"
  excludelist="D:\exclude_list_external.txt"
  report="/eclipse/apimigration/xml"
  debug="true"

 />

Isso executará a tarefa que criará arquivos *.xml dentro da pasta /eclipse/apimigration/xml. A tarefa resolverá novamente todas as referências no local usescan - definida pela expressão regular .* - contra o produto candidato 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.

Se a depuração estiver ativada, algum rastreio de depuração será exibido no console Ant.

Referência relacionada

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