Tarea Ant Migración de utilización de API

Finalidad

Esta tarea toma una exploración de utilización de API dada e intenta volver a resolverla con un release de producto candidato dado e informa de referencias no resueltas.

Utilización

Descripción

El nombre de la tarea Ant es: apitooling.apimigration. Para utilizarla, el archivo jar apitooling-ant.jar debe estar en la vía de acceso de clases Ant.

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

Parámetros

Atributo Descripción Necesario
candidate Este atributo especifica el producto que desea utilizar como candidato a la migración.

Puede ser un archivo .zip, .jar, .tgz, .tar.gz o un directorio correspondiente a la carpeta de instalación de Eclipse. Se trata del directorio en el que puede encontrar el ejecutable de Eclipse.

Sí
usescan Este atributo especifica la exploración de utilización de producto que desea comparar con el candidato a la migración.

El atributo usescan se especifica mediante una vía de acceso absoluta a la raíz de la exploración de utilización.
Sí
scopepattern Este atributo especifica el patrón de expresión regular utilizado para construir el ámbito de los elementos en los que buscar "referencias de" en la ubicación del producto.

El patrón debe ser una expresión regular bien formada según se define aquí.
No
referencepattern Establecer el patrón de expresión regular utilizado para construir el ámbito de los elementos en los que buscar "referencias a" en la ubicación del producto.

El patrón debe ser una expresión regular bien formada según se define aquí.
No
excludelist Establecer la ubicación de la lista de exclusiones.

La ubicación de lista de exclusiones especifica un archivo de texto que enumera los paquetes que se excluirán del análisis. De forma predeterminada, se analizan todos los paquetes del perfil. Se pueden utilizar los atributos de lista de inclusiones y exclusiones para incluir y excluir paquetes de forma selectiva. La lista de inclusiones define el conjunto de paquetes a analizar (si se omite, se incluyen todos los paquetes) y, posteriormente, se aplica la lista de exclusiones. Cada línea del archivo especifica:
  • un nombre de paquete específico
  • una expresión regular con la que deben coincidir los nombres de paquete (líneas que empiecen con "R:")
  • un comentario (las líneas con '#')

La ubicación se especifica mediante una vía de acceso absoluta.
A continuación figura una lista de exclusiones de ejemplo:
# EXCLUDED BUNDLES
R:org\.eclipse\..*\.doc\..*
...
No
includelist Establecer la ubicación de la lista de inclusiones.

La ubicación de lista de inclusiones especifica un archivo de texto que enumera los paquetes que se incluirán en el análisis. De forma predeterminada, se analizan todos los paquetes del perfil. Se pueden utilizar los atributos de lista de inclusiones y exclusiones para incluir y excluir paquetes de forma selectiva. La lista de inclusiones define el conjunto de paquetes a analizar (si se omite, se incluyen todos los paquetes) y, posteriormente, se aplica la lista de exclusiones. Cada línea del archivo especifica:
  • un nombre de paquete específico
  • una expresión regular con la que deben coincidir los nombres de paquete (líneas que empiecen con "R:")
  • un comentario (las líneas con '#')

La ubicación se especifica mediante una vía de acceso absoluta.
A continuación figura una lista de inclusiones de ejemplo:
# INCLUDED BUNDLES
R:org\.eclipse\..*
...
No
report Establecer la ubicación de salida en la que se generarán los informes.

Una vez completada la tarea, hay informes disponibles en este directorio mediante una estructura jerárquica. Se crea una subcarpeta para cada componente que tiene otro paquete que hace referencia a aquel. Cada subcarpeta contiene un archivo llamado "[bundlename].xml". En esta carpeta hay otra subcarpeta (llamada "[nombre de paquete de referencia].xml") para cada paquete que hace referencia al paquete de la carpeta que lo contiene. Dentro de la carpeta del paquete de referencia hay una de tres subcarpetas(API, PRIVATE o OTHER) que contienen las referencias de tipo, método o campo de esa especie.

Otros dos archivos especiales se escriben en el directorio de informes, "not_searched.xml" y "no_apidescription.xml", archivos que contienen información sobre paquetes de la línea base en los que no se buscó información de utilización y sobre los que no tenían archivos .api_description dentro de ellos, respectivamente.

La ubicación se especifica mediante una vía de acceso absoluta.

Por ejemplo:
  raíz
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- nombre de paquete con utilización
     |
     +--nombre de paquete de referencia
      |
      +-- [API o PRIVATE o OTHER]
       |
       +--[type_ or method_ or field_]references.xml
Sí
debug Establecer el valor de depuración.

Los valores posibles son: true, false
El valor por omisión es false.
No

Ejemplos

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

 />

Esto ejecutará la tarea creando archivos *.xml dentro de la carpeta /eclipse/apimigration/xml. Esta tarea volverá a resolver todas las referencias en la ubicación usescan, definida por la expresión .*, contra el producto candidato cuyo identificador empieza por org.eclipse (definido por la expresión regular org\.eclipse.*). Utilizará la lista de exclusiones del archivo ubicado en D:\exclude_list_external.txt para reducir el número de problemas de los que informar.

Si la depuración está habilitada, se mostrará algún rastreo de depuración en la consola Ant.

Consulta relacionada

Tarea Ant Congelación de API
Tarea Ant Generación de archivos
Tarea Ant Conversión de informes de Análisis
Tarea Ant Conversión de informes de Congelación de API
Tarea Ant Obsolescencia de API
Tarea Ant Conversión de informes de Obsolescencia de API
Tarea Ant Conversión de informes de Utilización de API
Tarea Ant Conversión de informes de Migración de Utilización de API