Tarea Ant Utilización de API

Finalidad

Esta tarea ejecuta una búsqueda completa en una línea base dada para crear un informe de utilización de API.

El análisis no incluye paquetes que no están habilitados para Herramientas de API.

Utilización

Descripción

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

<apitooling.apiuse
	location="..."
	scopepattern="..."
	referencepattern="..."
	report="..."
	considerinternal="..."
	considerapi="..."
	considerillegaluse="..."
	apipatterns="..."
	internalpatterns="..."
	archivepatterns="..."
	excludelist="..."
	includelist="..."	
	debug="..."
/>

Parámetros

Atributo Descripción Necesario
location Este atributo especifica la ubicación del producto actual en el que desea buscar la utilización de API.

Puede ser un archivo .zip, .jar, .tgz, .tar.gz o un directorio que incluya un producto o una recopilación de paquetes.

La ubicación se especifica mediante una vía de acceso absoluta.
Sí
scopepattern Este atributo especifica un patrón de expresión regular que se utiliza para seleccionar en qué paquetes de la ubicación se buscará.

Por ejemplo, el siguiente solo podría explorar la utilización de API en paquetes de Eclipse:
org.eclipse.*
El patrón debe ser una expresión regular bien formada según se define aquí.
No
referencepattern Este atributo especifica un patrón de expresión regular que se utiliza para filtrar los resultados de búsqueda. Solo se notificará la utilización de API que haga referencia a un paquete que coincida con el filtro.

Por ejemplo, lo siguiente notificaría solamente la utilización que hace referencia al código en JDT:
org.eclipse.jdt.*
El patrón debe ser una expresión regular bien formada según se define aquí.
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.

Los otros archivos especiales se escriben en el directorio de informes, "counts.xml", "not_searched.xml" y "no_apidescription.xml", que contienen información sobre el número de referencias encontradas, y 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"
   +-- "counts.xml"
   +-- nombre de paquete con utilización
   		|
   		+--nombre de paquete de referencia
   			|
   			+-- [API o PRIVATE u OTHER]
   				|
   				+--[type_ or method_ or field_]references.xml
Sí
considerinternal Si las referencias internas deben tenerse en cuenta durante la búsqueda.

El valor por omisión es false.
No
considerapi Si las referencias de API deben tenerse en cuenta durante la búsqueda.

El valor por omisión es false.
No
considerillegaluse Si las referencias de utilización de API no permitidas deben tenerse en cuenta durante la búsqueda.

El valor por omisión es false.
No
apipatterns Una lista separada por comas de patrones de nombres de paquete (expresiones regulares) para tener en cuenta como paquetes de API.

De forma predeterminada, se utilizan las descripciones de API en los paquetes explorados pero esto se puede utilizar para alterar temporalmente o añadir paquetes de API.
No
internalpatterns Una lista separada por comas de patrones de nombres de paquete (expresiones regulares) para tener en cuenta como paquetes privados.

De forma predeterminada, se utilizan las descripciones de API en los paquetes explorados pero esto se puede utilizar para alterar temporalmente o añadir paquetes privados.
No
archivepatterns Una lista separada por comas de identificadores de archivador a ignorar durante la exploración.

Un identificador de archivador a menudo tiene la forma: [id de paquete]:[vía de acceso al archivador].
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
filters Establecer el directorio raíz de los filtros de API a utilizar durante la exploración de utilización.

El argumento es el directorio raíz de los archivos .api_filters que deben utilizarse para filtrar referencias.

Los archivos .api_filters especifican problemas concretos que deben ignorarse durante el análisis de API. Durante la exploración de utilización, los filtros de problemas se convertirán en una lista de referencias que se filtrará a partir de los resultados de exploración de utilización.

La raíz se especifica mediante una vía de acceso absoluta.
La raíz debe contener la estructura siguiente:
 raíz |
  +-- nombre de componente (es decir, org.eclipse.jface)
         |
         +--- .api_filters
No
debug Establecer el valor de depuración.

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

Ejemplos

	<apitooling.apiuse
		location="/eclipse/eclipse.tar.gz"
		scopepattern=".*"
		referencepattern="org\.eclipse.*"
		report="/eclipse/apiuse-both/XML"
		considerinternal="true"
		considerapi="true"
		considerillegaluse="true"
		archivepatterns="org.eclipse.test.bundle:/libs/contributed.jar"
		excludelist="D:\exclude_list_external.txt"
		debug="true"
	/>

Esto ejecutará la tarea creando archivos *.xml dentro de la carpeta /eclipse/apiuse-both/XML. La tarea buscará todos los paquetes en la ubicación del producto, definida por la expresión regular .*, buscando todas las referencias a cualesquiera paquetes cuyo identificador empiece por org.eclipse (definido por la expresión regular org\.eclipse.*). Utilizará la lista de exclusiones D:\exclude_list_external.txt para reducir el número de problemas de los que informar.

Mientras explora, se ignorarán los archivos de clase encontrados en el archivador /libs/contributed.jar, dentro de org.eclipse.test.bundle.

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

Referencia 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