Tarea Ant Congelación de API

Finalidad

Esta tarea identifica las API que se han añadido, modificado o eliminado relativas a una línea base de API. Esta tarea está pensada para validar que no se produzcan cambios de API después de una congelación de API.

Utilización

Descripción

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

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

Parámetros

Atributo Descripción Necesario
baseline Este atributo especifica la ubicación de la línea base de referencia.

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.

La ubicación se especifica mediante una vía de acceso absoluta.
Sí
profile Este atributo especifica la ubicación del producto o perfil actual que desea comparar con la línea base de referencia.

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.

La ubicación se especifica mediante una vía de acceso absoluta.
Sí
report Establecer el nombre del archivo de informe a generar.

Debe especificarse mediante una vía de acceso absoluta.
Esta debe ser una ubicación de archivo, no un directorio.
Sí
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. Además, esta tarea admite la enumeración de miembros en las listas de inclusiones y exclusiones. La lista de inclusiones define el conjunto de paquetes y miembros 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
  • un nombre de miembro específico
  • una expresión regular con la que deben coincidir los nombres de miembro o 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:
# 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\..*
...
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. Además, esta tarea admite la enumeración de miembros en las listas de inclusiones y exclusiones. La lista de inclusiones define el conjunto de paquetes y miembros 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
  • un nombre de miembro específico
  • una expresión regular con la que deben coincidir los nombres de miembro o 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:
# 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\..*
...
No
debug Establecer el valor de depuración.

Los valores posibles son: true, false
El valor por omisión es false.
No
eefile Establezca el archivo de entorno de ejecución a utilizar.

De forma predeterminada, se utiliza un archivo de entorno de ejecución que corresponde a un entorno de ejecución JavaSE-1.6.

El formato del archivo se describe en esta página wiki.

El archivo se especifica mediante una vía de acceso absoluta.
No

Ejemplos

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

Esto ejecutará la tarea creando archivos report.xml dentro de la carpeta D:\report. Utilizará la lista de exclusiones D:\exclude_list_external.txt para reducir el número de problemas de los que informar.

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

Referencia relacionada

Tarea Ant Análisis
Tarea Ant Generación de archivos
Tarea Ant Utilización de API
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