Tarea Ant Problemas de exploración de utilización de API

Finalidad

Esta tarea resuelve las Exploraciones de utilización de API en un perfil relativo a una línea base. Notifica las referencias a los tipos, métodos y campos que ahora faltan del perfil.

Utilización

Descripción

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

<apitooling.apiusescanproblems
	profile="..."
	report="..."
	apiusescans="..."
	excludelist="..."
	includelist="..."
	preferences="..."
	debug="..."
/>

Parámetros

Atributo Descripción Necesario
profile Este atributo especifica la ubicación del producto o perfil actual con el que desea solucionar las exploraciones de utilización de API.

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 la ubicación de salida en la que se generarán los informes.

Una vez completada la tarea, hay informes disponibles en este directorio. Se crea una subcarpeta para cada componente con problemas de los que informar. Cada subcarpeta contiene un archivo llamado "report.xml".

La ubicación se especifica mediante una vía de acceso absoluta.
Sí
apiusescans Este atributo especifica la lista separada por comas de las ubicaciones de las Exploraciones de utilización de API en relación con las cuales desea comprobar el perfil.

Puede ser un archivo .zip o un directorio correspondiente al informe de exploración de utilización de API. Se trata del directorio en el que puede encontrar la carpeta XML en la exploración de utilización.
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. 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:
 # 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
 R:javax\..*
 ...
No
includelist Establecer la ubicación de la lista de inclusiones.

La ubicación de la 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:
 # DOC BUNDLES
 org.eclipse.jdt.doc.isv
 org.eclipse.jdt.doc.user
 org.eclipse.pde.doc.user
 R:org.eclipse.platform.doc.*
 # NON-ECLIPSE BUNDLES
 com.ibm.icu
 com.jcraft.jsch
 R:javax\..*
 ...
No
preferences Establecer las preferencias para la tarea.

Las preferencias se utilizan para configurar gravedades de problemas. Las gravedades de problemas tienen tres valores posibles: Ignorar, Aviso o Error. El conjunto de problemas detectado se define mediante las claves de preferencias de problemas correspondientes en las Herramientas de API.
La ubicación se especifica mediante una vía de acceso absoluta. Si la ubicación dada no existe, no se establecerán las preferencias.
Se ignoran las líneas que empiezan por '#'. El formato del archivo de preferencias tiene el aspecto siguiente:
 #Thu Nov 20 17:35:06 EST 2008
 API_USE_SCAN_TYPE_SEVERITY=Error
 API_USE_SCAN_METHOD_SEVERITY=Error
 API_USE_SCAN_FIELD_SEVERITY=Error
Las claves pueden encontrarse en org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes.
No
debug Establecer el valor de depuración.

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

Ejemplos

	<apitooling.apiusescanproblems
		profile="D:\eclipse\3.7\eclipse"
		report="D:\reports\xml"
		apiusescans="D:\APIUseScan\ProductOne,D:\APIUseScan\ProductTwo"
		excludelist="D:\exclude_list_external.txt"
		preferences="D:\tests_api\org.eclipse.pde.api.tools.prefs"
		debug="true"
	/>

Esto ejecutará la tarea creando archivos report.xml dentro de la carpeta D:\reports\xml. Los tipos, los métodos y los campos de las exploraciones de utilización se resolverán en el perfil en D:\eclipse\3.7\eclipse y se notificarán los que falten. Utilizará la lista de exclusiones del archivo D:\exclude_list_external.txt para reducir el número de paquetes sobre los cuales se notifican problemas.

Las gravedades de problema se generarán según se especifica en D:\tests_api\org.eclipse.pde.api.tools.prefs.

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 de API
Tarea Ant Congelación de API
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 Conversión de informes de Utilización de API
Tarea Ant Obsolescencia de API
Tarea Ant Conversión de informes de Obsolescencia de API