Apache Ant

Construyendo aplicaciones con Apache Ant

Ttulo: Autor: Versin: Curso: Lugar:

Construyendo aplicaciones con Apache Ant Miguel ngel Rodrguez Manzano <mrnet@ono.com> 1.4 (Martes 20 de Febrero de 2007) Arquitecto Java en Tecnologa J2EE (2006-2007) Forman <info@forman.es> Centro de formacin e innovacin de Andaluca Parque Tecnolgico de Andaluca C/ Severo Ochoa, 30 29590 Campanillas (Mlaga)

-1-

NDICE DE CONTENIDOS 1.- INTRODUCCIN.............................................................................3 1.1.- Qu es Ant?.................................................................................3 1.2.- Un poco de historia......................................................................3 1.3.- Por qu Ant?...............................................................................4 2.- INSTALACIN................................................................................5 2.1.- Descarga.......................................................................................5 2.2.- Estructura de Ant.........................................................................5 2.3.- Instalacin...................................................................................5 2.4.- Variables de entorno...................................................................6 3.- CONCEPTOS BSICOS....................................................................7 3.1.- Tareas..........................................................................................7 3.2.- Propiedades.................................................................................8 3.3.- Targets.........................................................................................10 3.4.- Dependencias..............................................................................11 3.5.- Referencias..................................................................................12 3.6.- Rutas...........................................................................................13 3.7.- Recursos......................................................................................15 4.- EL ARCHIVO DE CONSTRUCCIN.................................................18 4.1.- Proyecto <project>.......................................................................18 4.2.- Propiedad <property>.................................................................19 4.3.- Target <target>............................................................................21 4.4.- Nuestro primer archivo de construccin.....................................22 5.- TAREAS..........................................................................................26 5.1.- Tareas segn su funcionalidad.....................................................27 5.2.- Tareas bsicas..............................................................................33 5.3.- Tareas opcionales........................................................................60 6.- EJEMPLOS.....................................................................................67 6.1.- Aplicacin HolaMundo bsica..................................................67 6.2.- Aplicacin HolaMundo, usando JUnit 4...................................67 6.3.- Servlet HolaMundo desplegable...............................................67 7.- RECURSOS ADICIONALES.............................................................68 7.1.- Tutoriales.....................................................................................68 7.2.- Pginas web.................................................................................69 7.3.- Libros...........................................................................................71 8.- FUENTES........................................................................................73 9.- HISTORIAL.....................................................................................75 -2-

1.- INTRODUCCIN. 1.1.- Qu es Ant?

Apache Ant es una herramienta software pensada para automatizar todos los repetitivos procesos que habitualmente han de llevarse a cabo entorno al desarrollo genrico de cualquier aplicacin: la compilacin, construccin (build en ingls) y prueba de aplicaciones software desarrolladas, fundamentalmente, usando el lenguaje de programacin Java. Ant es similar en concepto al clsico make caracterstico de ciertos entornos de desarrollo, pero est escrito en lenguaje Java y, por tanto, hace uso de la plataforma Java y se adecua mejor que este ltimo a la construccin de proyectos de software de aplicaciones Java. La diferencia ms notoria entre Ant y make es que Ant usa XML para describir los procesos de construccin y sus dependencias, mientras que make tiene su propio formato para escribir un makefile. Apache Ant es un proyecto de la Fundacin Apache Software y, por tanto, de cdigo-abierto (open-source en ingls) y libre distribucin, bajo los trminos generales dispuestos en la licencia Apache Software License.

1.2.- Un poco de historia.

Ant fue concebido por James Duncan Davidson, durante el proceso de conversin de un producto de Sun en un proyecto de cdigo-abierto. Este producto, el motor (engine) de implementacin de referencia de la especificacin JSP/Servlet (que ms tarde sera conocido como Apache Tomcat). La herramienta make, de cdigo cerrado, era la que por aquellos entonces se usaba en el proyecto para compilarlo en el sistema operativo Solaris. No obstante, en el frondoso mundillo de la comunidad open-source no haba forma posible de controlar en qu plataformas se compilaba el proyecto Ant fue creada como una herramienta simple e independiente de la plataforma para compilar dicho proyecto siguiendo una serie de directivas bsicas dadas en un fichero de construccin (build file) escrito en XML, que, por defecto, tiene el nombre build.xml. La versin 1.1 de Ant fue oficialmente liberada al pblico como una herramienta independiente propiamente dicha el 19 de Julio de 2000. Desde estos humildes comienzos, la herramienta no ha parado de crecer en funcionalidades y popularidad, hasta alcanzar y quizs, incluso superar al propio Tomcat. Para terminar, se dice que su nombre viene de un acrnimo que vendra a significar algo como Another neat tool (Otra herramienta guay en ingls). As mismo, es una curiosa coincidencia que la palabra ant (hormiga en ingls) apareciera en el artculo Recursive make considered harmful (El make recursivo considerado peligroso) de Peter Miller (un artculo que describa los problemas de construccin de la herramienta make que ms tarde Ant se propondra resolver) como nombre en algunas estructuras de los proyectos que, a modo de ejemplo, se utilizaban en dicho artculo. -3-

1.3.- Por qu Ant?

Una buena pregunta, desde luego. A lo largo de estos ltimos aos, Ant se ha convertido en uno de los iconos del mundillo open-source Java. Para una inmensa mayora de los desarrolladores, ya es un hecho comn el ver un fichero build.xml acompaando a todo proyecto software que se precie Existen otras herramientas para la compilacin y construccin de aplicaciones software basadas en tecnologas Java, como, por ejemplo, la emergente Apache Maven o JavaMake, entre otras. Entonces, por qu elegir Ant?

Independencia de la plataforma
Uno de los factores fundamentales para la consecucin de este enorme xito y para los que Ant fue ideado en un principio es, sin duda alguna, la independencia prcticamente absoluta de la plataforma de desarrollo que, gracias a las tecnologas Java y XML, puede ofrecer Ant. Desde que Ant estuvo disponible, ya no fue necesario tener que usar confusos makefiles con comandos Unix o tener que escribir engorrosos scripts o archivos de procesado por lotes (aquellos socorridos .BAT) en Windows para poder construir nuestras aplicaciones. Tampoco era ya necesario distinguir entre la barra / de Unix y la barra invertida \ de Windows para especificar las rutas de ficheros, puesto que Ant permita al desarrollador usar su convencin favorita y la adaptaba.

Estandarizacin del proceso de construccin

Para la construccin de nuestras aplicaciones ahora slo es necesaria una nica herramienta, que sabemos que funciona siempre de la misma forma (escribiendo ant y el target deseado) y que podemos analizar y modificar fcilmente su comportamiento (a travs del archivo de construccin) para adaptarlo a nuestras necesidades.

Sencilla integracin con JUnit

Adems de eso, Ant hace gala de otras caractersticas importantes y de gran valor a la hora de afrontar el desarrollo de proyectos de software serios haciendo uso de herramientas libres. Por ejemplo: una de las ms importantes es la facilidad de Ant para integrar pruebas de unidad JUnit en el proceso de construccin de nuestras aplicaciones. Esto ha provocado el que Ant haya impulsado a muchos desarrolladores a adoptar modelos de desarrollo conducidos segn las pruebas (test-driven), o programacin extrema.

Extensiones: hasta el infinito y ms all

Se te quedan cortas las potentes capacidades que te ofrece Ant? Quieres personalizar an ms ciertos procesos para tus proyectos? No hay problema. Ant, proporcionando una API propia sobre la que trabajar, permite la definicin de tareas y procesos personalizados al mximo que ponen a disposicin de los desarrolladores capacidades extraordinarias. Por nombrar someramente algunas de las ms importantes: pruebas JUnit, compilacin .NET (existen libreras, as como una versin especfica de Ant para .NET, llamada NAnt), salida JSP, EJB, JavaCC, cabeceras C para JNI, validacin XML, as como facilidades de comunicaciones como FTP, multimedia con imgenes y sonido, o ejecucin de todo tipo de comandos y scripts. -4-

2.- INSTALACIN. 2.1.- Descarga.

Vamos a proceder a instalar Ant en nuestra mquina. Para ello, en primer lugar, acudimos a la pgina oficial del proyecto, ubicada en la siguiente URL: http://ant.apache.org Acudimos a la seccin de descargas de la pgina web (haciendo clic en Download / Binary distributions) y bajamos un fichero que tendr un nombre similar a apache-ant1.7.0-bin, donde 1.7.0, o la que corresponda en su caso, es la versin de la herramienta.

2.2.- Estructura de Ant.

Una vez descargada la herramienta, descomprimimos sus ficheros en el disco duro y nos encontramos con la siguiente estructura: ant | +--- bin | +--- lib | +--- docs | +--- etc Diversos ficheros de texto, sobre todo con informacin bsica Scripts para el lanzamiento de la aplicacin Contiene libreras jar de Ant, y otras para dependencias Contiene la documentacin de Ant (de obligada lectura ;-) Contiene otros archivos (xsl para generar informes, ...)

Los directorios que ms habremos de visitar sern normalmente lib, para aadir libreras requeridas por ciertas tareas adicionales que queramos usar y que tengas otras libreras no incluidas con la distribucin de Ant como dependencia, o, de vez en cuando, el directorio docs, cuando necesitemos consultar la documentacin del proyecto.

2.3.- Instalacin.
La instalacin de la aplicacin es tan sencilla como simplemente descomprimir la herramienta en el disco duro, renombrando el directorio llamado apache-ant-1.7.0 a simplemente ant, por comodidad. Ant, siendo prcticamente independiente de la plataforma en que es usado, no usa ninguna estructura de datos de ningn sistema operativo para almacenar datos de configuracin propios, salvo algunas variables de entorno que, a continuacin, en las siguientes lneas, pasaremos a establecer.

-5-

2.4.- Variables de entorno.

Ant slo requiere para su funcionamiento del establecimiento de unas pocas variables de entorno en nuestro sistema operativo, bsicamente para localizar la ruta de la herramienta. Son las siguientes:
Variable Contenido

ANT_HOME PATH JAVA_HOME

Ruta donde est instalado Ant. Hay que aadirle el directorio bin de Ant. Ruta donde est instalado el JDK de Java.

La variable JAVA_HOME es posible que ya la tengamos establecida correctamente si previamente hemos instalado el Kit de Desarrollo Java (Java Development Kit, o ms escuetamente, JDK) en nuestro sistema. La variable de entorno PATH es bastante comn en muchos sistemas operativos. Se usa para comunicar al sistema operativo en cuestin rutas del disco donde se ubican aplicaciones que queremos que estn alcanzables desde cualquier parte del rbol de directorios del sistema. A continuacin, vamos a sugerir como hacer esta mnima configuracin para los sistemas operativos ms comunes:

Microsoft Windows y OS/2

Encontrndonos en el intrprete de comandos, y asumiendo que tenemos Ant instalado en el directorio C:\ant y el JDK de Java en C:\jdk, habremos de usar el comando set para instanciar las variables de entorno de la siguiente manera: set ANT_HOME=c:\ant set PATH=%PATH%;%ANT_HOME%\bin set JAVA_HOME=c:\jdk

Linux/Unix (bash)
Suponiendo que Ant est instalado en /usr/local/ant y el JDK en /usr/local/jdk export ANT_HOME=/usr/local/ant export JAVA_HOME=/usr/local/jdk export PATH=${PATH}:${ANT_HOME}/bin

Linux/Unix (csh)
setenv ANT_HOME /usr/local/ant setenv JAVA_HOME /usr/local/jdk set path=( $path $ANT_HOME/bin ) Tener un enlace simblico o, en este caso, una variable de entorno que apunte a la ltima versin del JDK hace ms fcil las actualizaciones a nuevas versiones del mismo.

-6-

3.- CONCEPTOS BSICOS.

A continuacin, vamos a explicar ciertos conceptos bsicos que conviene conocer previamente al uso de la herramienta. Estos conceptos bsicos, tales como target o dependencia pueden resultarte familiares si ya has lidiado con el clsico make u otras herramientas de construccin. No obstante, conviene saber cmo estn definidas en Ant. Adems de esto, Ant aade otros conceptos bsicos propios muy importantes, como son las tareas, propiedades, targets, dependencias, referencias, o los recursos.

3.1.- Tareas.
Una tarea es una etiqueta XML vlida que puede aparecer en el archivo build.xml. Una tarea equivale a algn proceso que Ant puede llevar a cabo por nosotros: borrar o renombrar ficheros, comprimirlos, compilar cdigo fuente, ejecutar pruebas, etc, etc Las tareas Ant (como etiquetas XML del archivo de construccin que son) pueden tener atributos, as como, en su caso, elementos anidados.
<tarea atributo1="valor.atributo1" atributo2="valor.atributo2" ... atributoN="valor.atributoN" > <tarea-anidada1 atributo11="valor.atributo11" atributo12="valor.atributo12" ... atributo1N="valor.atributo1N" >

</tarea-anidada1> ... <tarea-anidadaN

atributoN1="valor.atributoN1" atributoN2="valor.atributoN2" ... atributoNM="valor.atributoNM" >

</tarea>

</tarea-anidadaN>

Ms adelante, entraremos en ms detalle del funcionamiento de las tareas, enunciando listados de las tareas de Ant atendiendo a diversos criterios, y pasaremos a explicar con relativo nivel de detalle las tareas ms importantes. Las tareas ms bsicas y comnmente usadas, estn agrupadas en la documentacin de Ant bajo el nombre de core tasks (tareas del ncleo de la herramienta). Adems de estas tareas bsicas predefinidas e incluidas con Ant, que forman el corpus primordial de funcionalidades que necesitaremos habitualmente, existen tareas opcionales, optional tasks. Para usarlas, normalmente slo habr que importar una serie de libreras en los directorios necesarios de Ant. Finalmente, para los ms inquietos, Ant tambin proporciona una completa API repleta de todo tipo de funcionalidades de la que podemos hacer uso para crear nuestras propias tareas personalizadas para los ficheros de construccin de nuestros proyectos. -7-

3.2.- Propiedades.
Las propiedades son una serie de datos guardados, similares a variables, que se definen mediante una etiqueta especial vlida en el archivo de construccin: la etiqueta property, aunque tambin pueden establecerse a travs de un fichero externo. Una propiedad tiene un nombre y un valor; el nombre es sensible a maysculas y minsculas. Una propiedad puede aparecer como valor en los atributos de cualquier tarea. La forma habitual de definir el nombre y valor de una propiedad tiene esta estructura: <property name="nombre.propiedad" value="valor.propiedad"/> Para referenciar su valor donde sea necesario, habremos de escribir el nombre de la propiedad entre llaves empezando por un smbolo de dlar: ${nombre.propiedad} En una propiedad podemos guardar, por ejemplo, el nombre de los directorios por defecto de compilacin, valores de entorno, directorio de salida javadoc, etc Por ejemplo, la siguiente lnea define una propiedad src.dir, que mantendra guardada la ruta relativa al proyecto donde encontrar las clases de la aplicacin: <property name="src.dir" value="src"/> Tras esto, cada vez que queramos referenciar el directorio donde se alojan las clases de la aplicacin, slo tendremos que escribir ${src.dir}. Esto facilita el mantenimiento del archivo de construccin y una mayor flexibilidad a la hora de afrontar cambios en cualquiera de los procesos de la construccin de la aplicacin. As pues, las propiedades nos ayudan a establecer, controlar y parametrizar la lgica del proceso de construccin. No obstante, no podemos comprobar o comparar el valor de una propiedad, slo podemos consultar si una propiedad est establecida o no. Para poder comprobar condiciones ms complejas, se recomienda crear targets especficos de comprobacin, normalmente etiquetados en su nombre con el sufijo check. Por ejemplo, la siguiente lnea define una tarea que comprueba la existencia de la clase TestCase del framework JUnit necesaria para llevar a cabo las pruebas de unidad de la aplicacin, y establece la propiedad junit.instalado segn proceda:
<target name="junit.check"> <available property="junit.instalado" classname="junit.framework.TestCase"/> </target>

-8-

Finalmente, hay que comentar que las propiedades pueden establecerse en archivos de construccin, pero tambin a travs de un fichero externo con: <property file="build.properties"/> En el archivo de propiedades, podemos establecer los valores para algunas propiedades predeterminadas de Ant o establecer las nuestras propias para configurar el proceso de construccin para que se ajuste al mximo a nuestras necesidades siendo adems de fcil modificacin ante posibles cambios (simplemente editando algunas lneas de un fichero de texto). Un extracto de un fichero build.properties relativamente comn en cualquier proyecto podra ser el siguiente:
build.properties # # Base build properties # #javac options # http://ant.apache.org/manual/CoreTasks/javac.html # sun javac build.compiler=javac # jikes compiler #build.compiler=jikes # generic compiler options build.verbose=false build.fork=true build.deprecation=false build.nowarn=true # optimize only works with a few compilers build.optimize=true # Change this var to build to a different Java version java.target_version=1.5

Como puede observarse, es muy comn definir todo tipo de propiedades entorno a las opciones de compilacin del cdigo fuente, empezando incluso por el propio compilador a usar (cada vez es mayor el nmero de alternativas al compilador de Sun), opciones de compilacin, y diversas rutas de directorio, tanto para la localizacin de ciertas libreras, ficheros fuente o rutas de salida para los productos del proceso de construccin.

-9-

3.3.- Targets.
Un target u objetivo (de construccin) no es ms que es un conjunto de tareas referenciadas bajo un nombre representativo, que debera ilustrar el objetivo (nunca mejor dicho) a conseguir al que estn enfocada la ejecucin de dicho target. La definicin habitual de un target tiene el siguiente aspecto general: <target name="nombre.target"> ... definicin del target ... </target> Normalmente, siguiendo una convencin no escrita, los nombres de objetivos ms habituales que los desarrolladores suelen escribir para Ant son:
Nombre del target Objetivo a realizar

main, default, all... init clean prepare compile test, junit... jar javadoc

Objetivo por defecto: suele ejecutar todos los dems targets. Procesos varios de inicializacin para la construccin. Borra los archivos de bytecode (*.class) de la aplicacin. Crea la estructura de directorios apropiada en el disco. Compila el cdigo fuente de la aplicacin. Realiza las pruebas internas o JUnit de la aplicacin. Empaqueta la aplicacin en un Java ARchive. Genera la documentacin de nuestra aplicacin con javadoc.

Nota, por supuesto, que estos objetivos no estn predefinidos en Ant, sino que el desarrollador tiene que escribirlos adecuadamente en el fichero build.xml para cada aplicacin. Evidentemente, cada desarrollador puede llamar a la tarea con un nombre a su eleccin (por poner un ejemplo relativamente habitual, usando su lengua verncula: quedando compile como compilar en castellano, o kompilieren en alemn). No obstante, estos nombres aqu enumerados suelen ser los ms habituales. Se muestran adems como referencia, puesto que nosotros, en mayor o menor medida, siempre vamos a tener que definir targets muy similares a esos. Como mnimo, siempre habremos de definir un target para poder compilar nuestro cdigo fuente, aunque ser habitual definir algunos ms a poco que nuestro proyecto sea de una cierta envergadura. A veces, pueden aparecer targets con nombres que incluyen un guin como -init. Esto suele ser una convencin que indica que dicho target no ha de llamarse desde la lnea de comandos, sino que es para uso interno del proceso de construccin.

- 10 -

3.4.- Dependencias.
Una dependencia es una relacin de anterioridad en el tiempo o en secuencia entre los targets. Por la propia naturaleza del proceso de construccin de una aplicacin, ciertos pasos, targets u objetivos tienen que ir antes que otros. El ejemplo tpico de dependencia es el que se da siempre entre los targets compilar y empaquetar en un archivo jar: no tiene sentido empaquetar primero y compilar despus, puesto que empaquetaremos los archivos de bytecode generados anteriormente y no los actualizados. Es necesario que cualquier herramienta de construccin que defina targets proporcione algn medio de definir las dependencias entre ellos. En el caso de Ant, las dependencias se enumeran en el atributo depends de la etiqueta target. Por ejemplo: <target name="compile" depends="junit, prepare"> ... definicin del target ... </target> En la expresin anterior tenemos un bloque de definicin de un target llamado compile (que compilar nuestro cdigo fuente y generar los archivos bytecode *.class), que, para que pueda ser ejecutado, habrn de ejecutarse previamente los targets junit (pruebas de unidad JUnit) y prepare (creacin de la estructura de directorios de salida). El atributo depends de Ant slo especifica el orden en el que los targets deberan ser ejecutados, no especifican una necesidad de que los targets previos tengan que ejecutarse y acabar bien. As pues, un target podr ejecutarse incluso si todos los targets de los que depende se hayan ejecutado con errores o hayan fallado. Ant intenta ejecutar dichos targets en el orden en el que aparecen en el atributo depends (de izquierda a derecha), pero no necesariamente ocurrir as. Todo depender de las dependencias concretas que haya establecidas en cada caso particular. Supongamos que tenemos el siguiente ejemplo de targets con dependencias: <target <target <target <target name="A"/> name="B" depends="A"/> name="C" depends="B"/> name="D" depends="C,B,A"/>

Si ejecutamos el target D, podra pensarse que, segn el orden especificado, el primer target en ejecutarse ser el C, seguido del B y el A Pero, no es as! Como podemos ver en el propio cdigo, C depende de B, y B depende de A, as que el primero en ejecutarse es A (que no tiene ninguna dependencia), luego B, C y, finalmente, D. Todos los targets, independientemente de en el nmero de otros targets en los que aparezcan como dependencia, se ejecutarn una nica vez. Es decir, si en el ejemplo anterior se ejecuta el target A, despus, al ejecutarse el B, aunque B dependa de A, como A ya se ha ejecutado, no es necesario que A vuelva a ejecutarse.

- 11 -

3.5.- Referencias.
A algunos elementos del fichero de construccin se le puede asignar una referencia identificativa para poder reutilizarlo posteriormente. Esta posibilidad es muy til a la hora de definir elementos repetitivos con ciertos valores concretos o trozos de cdigo XML que necesitamos usar un nmero muy grande de veces a lo largo del fichero de construccin. As pues, las referencias posibilitan la reutilizacin de cdigo y facilitan un muy rpido mantenimiento de los ficheros de construccin frente a posibles cambios. Slo hemos de incluir un atributo id con el nombre de referencia en la definicin y luego referenciarlo usando mismo nombre cuando lo necesitemos a travs del atributo refid. Por ejemplo, imaginemos que tenemos el siguiente trozo de cdigo:
<project...> <target name="miTarget1"> <condition...> <classpath> <pathelement <pathelement <pathelement </classpath> </condition> </target> <target name="miTarget2"> <condition...> <classpath> <pathelement <pathelement <pathelement </classpath> </condition> </target> </project>

location="lib/"/> path="libreria1.jar;libreria2.jar"/> path="${ruta.adicional}"/>

location="lib/"/> path="libreria1.jar;libreria2.jar"/> path="${ruta.adicional}"/>

Si definimos por separado un elemento que agrupe las rutas que se incluyen en el elemento classpath y le asignamos un nombre de referencia, como, por ejemplo, classpath.aplicacion, podremos reescribir el cdigo anterior de la siguiente manera:
<project...> <path id="classpath.aplicacion"> <pathelement location="lib/"/> <pathelement path="libreria1.jar;libreria2.jar"/> <pathelement path="${ruta.adicional}"/> </path> <target name="miTarget1"> <condition...> <classpath refid="classpath.aplicacion"/> </condition> </target> <target name="miTarget2"> <condition...> <classpath refid="classpath.aplicacion"/> </condition> </target> </project>

- 12 -

3.6.- Rutas.
Ant define instrumentos muy convenientes para poder especificar rutas de ficheros o directorios, para que, posteriormente, puedan ser manejados por las dems entidades del archivo de construccin.

Elementos de ruta locales a una tarea <classpath>

En Ant, para definir y agrupar informacin de rutas que queremos aplicar en la tarea local, se usa el elemento <classpath>, que tiene dos atributos: location y path, que, a su vez, pueden especificarse alternativamente como atributos del mismo nombre de un elemento anidado <pathelement>.
Atributo Descripcin

location path
Elemento anidado

Especifica una ruta nica (absoluta o relativa) de un fichero o directorio. Lista de rutas separadas por ; o :. Este atributo est pensado con la idea de especificar rutas predefinidas, en otro caso, debera optarse por usar mltiples elementos anidados <pathelement> con atributos location.
Descripcin
Atributo Descripcin

pathelement

location path

Idntico al atributo location. Idntico al atributo path.

Hay que comentar, adems, que dentro de la etiqueta <classpath> pueden colocarse una o ms colecciones de recursos (los recursos y colecciones de recursos se explican un poco ms adelante) como elementos anidados para aadir ms rutas. Evidentemente, estas colecciones habrn de contener recursos de un tipo apropiado (rutas o ficheros). Dichos recursos se aaden en el orden en que se especifican en el archivo de construccin, aunque colecciones como <fileset>, <dirset>, y <files> no tienen especificada una relacin de orden. Para ms detalles, acude al apartado dedicado a los recursos y colecciones de recursos.
Ejemplos:

Si tenemos una propiedad classpath ya definida, especificar dicha propiedad para usar dentro de la tarea actual es tan sencillo como: <classpath> <pathelement path="${classpath}"/> </classpath> Este mismo ejemplo puede abreviarse usando el atributo path propio: <classpath path="${classpath}"/> Un ejemplo tambin habitual es el que enumera una lista de archivos de librera: <classpath> <pathelement path="lib/junit.jar;lib/servlet-api.jar"/> </classpath> - 13 -

Elementos de ruta globales <path>

Si queremos definir una estructura que contenga rutas de fichero que podamos reutilizar un nmero indeterminado de veces, usaremos un elemento <path> al mismo nivel que los targets con un cierto nombre de referencia, que usaremos para acceder a l. Esta funcionalidad es fundamental para poder mantener nuestros archivos de construccin (sobre todo en el caso de aplicaciones complejas o grandes proyectos) de forma fcil, ordenada, potente y, no menos importante, gil a la hora de su mantenimiento. Los atributos y elementos anidados de <path> son exactamente los mismos que los de <classpath>. No obstante, los volvemos a reproducir aqu como referencia:
Atributo Descripcin

location path
Elemento anidado

Especifica una ruta nica (absoluta o relativa) de un fichero o directorio. Lista de rutas separadas por ; o :. Este atributo est pensado con la idea de especificar rutas predefinidas, en otro caso, debera optarse por usar mltiples elementos anidados <pathelement> con atributos location.
Descripcin
Atributo Descripcin

pathelement

location path

Idntico al atributo location. Idntico al atributo path.

Dentro de la etiqueta <path>, igual que ocurra con <classpath>, pueden colocarse una o ms colecciones de recursos (los recursos y colecciones de recursos se explican un poco ms adelante) como elementos anidados para potenciar las facilidades de especificacin de rutas. Por supuesto, estas colecciones habrn de contener recursos de un tipo apropiado (rutas o ficheros). Como siempre, dichos recursos se aaden en el orden en que se especifican en el archivo de construccin, aunque colecciones como <fileset>, <dirset>, y <files> no tienen especificada una relacin de orden. Como veremos ms adelante, <path> define una coleccin de recursos implcita, por tanto, dentro de un elemento <path> pueden anidarse, a su vez, otros elementos <path>.
Ejemplos:

Forma habitual de uso del elemento <path>, con y sin elementos anidados: <path id="ruta.base"> <pathelement path="${classpath}"/> </path> <path id="ruta.base" path="${classpath}"/> Definicin un <path> formado por una ruta predefinida (que consta de una lista de dos libreras, separas por un punto y coma ;) y un archivo suelto adicional: <path> <pathelement path="lib/junit.jar;lib/servlet-api.jar"/> <pathelement location="/una/ruta/cualquiera/libreria.jar"/> - 14 -

</path>

- 15 -

3.7.- Recursos.
Los recursos son entidades abstractas con capacidades de lectura y escritura de datos y propiedades, a la manera de los ficheros. Para manejar el acceso a sus atributos, la implementacin de un recurso deber proporcionar los medios para leer y/o escribir contenido de dicho recurso. Aunque el concepto de recurso en Ant data de la versin 1.5.2 de la herramienta, el uso explcito de los mismos es mucho ms reciente, de la versin 1.7, as que es posible que no se vean mucho an en la mayora de ficheros de construccin, pero su enorme potencial asegura que sern adoptados masivamente por los desarrolladores.

Recursos predefinidos
Recurso Descripcin

resource file url string propertyresource javaresource zipentry tarentry gzipresource bzip2resource
Ejemplos:

Recurso bsico. Todos los dems tipos de recurso derivan de este tipo. Un archivo accesible desde el sistema de ficheros local. Una URL de un recurso accesible desde un sistema remoto. Una cadena de texto Java del tipo String. Es de slo lectura. Representa una propiedad de Ant. Representa un recurso Java cargable a travs del Java classloader. Representa una entrada de un archivo ZIP. Representa una entrada de un archivo TAR. Da soporte GZip a una coleccin de recursos anidada en su interior. Da soporte Bzip2 a una coleccin de recursos anidada en su interior.

As pues, por ejemplo, si queremos definir cierto fichero de nuestra aplicacin como un recurso para poder acceder a l en la definicin de nuestro fichero de construccin, podramos hacer: <file file="fichero.txt" basedir="."/> Otros ejemplos:
<url url="http://heanet.dl.sourceforge.net/sourceforge/junit/junit4.1.zip"/> <string value="Entorno de pruebas JUnit instalado."/> <propertyresource name="junit.instalado"/> <javaresource name="junit.framework.TestCase" classpath="${ruta.librerias}"/> <zipentry archive="${ruta.proyecto}\recursos.zip" name="logo.gif"/> <tarentry archive="${ruta.proyecto}\recursos.tar" name="logo.gif"/> <gzipresource> <url url="http://www.ejemplo.org/archivo.gz"/> </gzipresource> <bzip2resource> <file file="${ruta.proyecto}\archivo.bz2"/> </bzip2resource>

Con estos recursos bsicos tenemos la suficiente funcionalidad para hacer uso de prcticamente cualquier recurso que necesitemos para la construccin de nuestras aplicaciones, pero slo podemos cargarlos de uno en uno. Imaginemos que necesitamos especificar cientos o miles de recursos; la tarea se hara muy tediosa. Para facilitarnos la vida en ese caso, Ant soporta tambin colecciones de recursos. - 16 -

Colecciones de recursos
Las colecciones de recursos son entidades abstractas que pueden agrupar un nmero indeterminado de recursos individuales para facilitar su gestin. Algunos de los tipos de datos clsicos de Ant han sido rediseados para comportarse como colecciones de recursos. Este es el caso de todos los tipos de datos relacionados con conjuntos de ficheros y propiedades:
Coleccin Descripcin

fileset, dirset, filelist, path y sus derivados tarfileset zipfileset propertyset

Colecciones bsicas para el manejo de grupos de ficheros. Todas ellas contienen mltiples referencias a recursos de tipo file. Puede contener recursos file o tarentry segn la configuracin. Puede contener recursos file o zipentry segn la configuracin. Contiene un conjunto de recursos propertyresource.

Adems de estas, se aaden una nueva serie de colecciones predefinidas:

Coleccin Descripcin

resources files restrict sort first tokens union intersect difference

Coleccin de recursos genrica. Coleccin de archivos similar a fileset. Filtra una coleccin de archivos a los que cumplen ciertos criterios. Coleccin de recursos ordenada segn algn criterio. Selecciona los n primeros elementos de la coleccin anidada. Tokens de cadenas de caracteres (recursos string) recogidos de la coleccin de recursos anidada. Conjunto unin de las colecciones de recursos anidadas. Interseccin de las colecciones de recursos anidadas. Diferencia de las colecciones de recursos anidadas.

Las colecciones de recursos permiten a los usuarios de Ant especificar referencias a una gran variedad de tipos de recursos, de forma ms cmoda y potente. Esto facilita el diseo de los archivos de construccin, puesto que cierto conjunto de ficheros se puede conseguir de muchas formas distintas, y cada desarrollador puede elegir la forma con la que se sienta ms cmodo.

- 17 -

Ejemplos:

Definicin de un classpath local <classpath> a una tarea en la que usamos colecciones de recursos para incluir y excluir ficheros y directorios concretos. El siguiente cdigo construye un elemento classpath que contiene el valor de la propiedad classpath, seguido de una lista de todos los archivos con extensin jar del directorio lib, el directorio classes, todos los directorios classes (el patrn de ruta ** encaja con cualquier cadena de ruta de longitud variable) bajo el directorio apps (excluyendo aquellos que incluyan la cadena Test en su nombre), y, finalmente, los archivos especificados por el <filelist> referenciado. <classpath> <pathelement path="${classpath}"/> <fileset dir="lib"> <include name="**/*.jar"/> </fileset> <pathelement location="classes"/> <dirset dir="${build.dir}"> <include name="apps/**/classes"/> <exclude name="apps/**/*Test*"/> </dirset> <filelist refid="jars.externos"/> </classpath> Ejemplo importante. Definicin de un elemento <path> global con un nombre de referencia ruta.base con la ruta bsica de bsqueda de clases de la aplicacin, que incluye: las rutas guardadas en la propiedad classpath, todos los archivos jar de librera del directorio lib, as como todas las clases alojadas en el directorio classes. Ntese que, a diferencia de los ejemplos de cdigo anteriores (que estaban ubicados en el interior de alguna tarea), este ejemplo est fuera de cualquier tarea y target, de hecho, al mismo nivel que los targets del archivo de construccin. <path id="ruta.base"> <pathelement path="${classpath}"/> <fileset dir="lib"> <include name="**/*.jar"/> </fileset> <pathelement location="classes"/> </path> Suponiendo que tenemos definido el ejemplo anterior, podemos referenciar al elemento <path> de nombre ruta.base desde dentro incluso de otro <path>: <path id="ruta.tests"> <path refid="ruta.base"/> <pathelement location="testclasses"/> </path>

- 18 -

4.- EL ARCHIVO DE CONSTRUCCIN.

El archivo de construccin, normalmente llamado build.xml, es el elemento fundamental de informacin sobre el que se sustenta Ant para guiar el proceso de construccin de nuestra aplicacin. En el archivo de construccin el desarrollador puede definir con todo detalle las opciones, funcionalidades, la secuencia y el comportamiento del proceso de construccin. Tras instalar Ant en nuestra mquina, deberemos proceder a escribir nuestro propio fichero de construccin para poder construir nuestra aplicacin. En la siguiente seccin procederemos a explicar ms detalladamente las tareas bsicas del mismo. Para cada tarea, describiremos su funcin, explicaremos sus atributos y mostraremos una serie de ejemplos relevantes para la ocasin.

4.1.- Proyecto <project>.

El proyecto es la estructura de mayor alto nivel en la jerarqua de Ant. Todo archivo de construccin build.xml ha de tener uno y slo un proyecto. En esta etiqueta se contendr informacin bsica para la especificacin del proceso de construccin. Veamos:
Atributo Descripcin

name basedir default

Nombre de nuestro proyecto. Generalmente, el nombre de la aplicacin. Directorio base. La ruta del disco raz del proyecto. Se puede especificar de antemano tambin mediante la propiedad basedir. Si no se especifica, por defecto se usa el directorio base donde se encuentra el fichero build.xml. Target por defecto. Si no se especifica este atributo, Ant generar un target por defecto que ejecutar todas las tareas de ms alto nivel.

As pues, si queremos especificar un proyecto para nuestra aplicacin, llamada Formanager y situada en la ruta C:\Proyectos\Formanager, escribiramos:
<?xml version="1.0"?> <project name="Formanager" basedir="C:\Proyectos\Formanager" default="todo"> ... definicin del proyecto ... </project>

No obstante, si el archivo build.xml va a estar colocado en el mismo directorio base que se indica (lo ms habitual), para una mayor generalidad, se recomienda usar . (referencia local al directorio actual) como directorio base. As pues, quedara: <?xml version="1.0"?> <project name="Formanager" basedir="." default="todo"> ... definicin del proyecto ... </project> Recordemos que el archivo de construccin es un fichero XML y debe contener en su primera lnea la cabecera de todo archivo XML. De ah la primera lnea del ejemplo.

- 19 -

4.2.- Propiedad <property>.

Mediante la etiqueta property (en realidad es una tarea, pero es tan bsica que hemos preferido explicarla fuera de la seccin dedicada a las tareas) podemos guardar informacin para el control del flujo del proceso de construccin en una propiedad, o un conjunto de propiedades, que se podrn establecer explcitamente desde la propia etiqueta, o bien que se leern desde un archivo o un recurso externo. Las propiedades tienen un nombre y pueden tener un valor, siempre sensibles al caso (es decir, que se distinguen maysculas/minsculas). Una propiedad puede tener valor o no (en cuyo caso se dice que la propiedad no est establecida, en ingls is not set), y eso es lo nico que vamos a poder comprobar de las mismas: si una propiedad est establecida o no; no podemos comprobar el valor concreto de una propiedad. Las propiedades, adems, son inmutables. Es decir, que una propiedad que recibe un valor (queda establecida a cierto valor) ya no puede cambiar de valor durante el resto del proceso de construccin. Visto as, las propiedades se comportan de una forma ms similar a las constantes que a las variables.
Atributo Descripcin

Nombre que queremos darle a la propiedad. Valor de la propiedad. Establece la propiedad a la ruta absoluta/relativa al basedir del proyecto. Nombre de referencia de un objeto (p. ej., de un <path> u otra propiedad). El nombre de recurso del archivo de propiedades. El nombre de archivo del archivo de propiedades. Una URL desde la cual leer las propiedades. El prefijo a anteponer ante variables de entorno. Si especificamos environment=entorno, podremos acceder a las propiedades del sistema environment operativo con entorno + . + nombre variable. P. ej., para la variable PATH sera entorno.PATH, y para acceder a su valor ${entorno.PATH}. Ntese que se distinguen maysculas y minsculas: es PATH y no Path. classpath El classpath en el que buscar el recurso. classpathref El classpath dado como referencia a un <path> definido donde sea. Prefijo que se le aplicar a las propiedades usando file o resource. Se le prefix anexa un punto . al final del prefijo si no se especifica. Es decir, con prefix=forman, las propiedades se llamarn forman.nombrepropiedad. Viendo esto, podemos darnos cuenta de que hay 6 formas de establecer valores para las propiedades de nuestra aplicacin: 1) Proporcionando su nombre (name) y un valor (value). 2) Proporcionando su nombre (name) y una referencia (refid) a otra propiedad. 3) Proporcionando un nombre de archivo (file) del archivo de propiedades desde el cual cargar las propiedades. Este archivo de propiedades tiene el mismo formato definido por el fichero utilizado en la clase java.util.Properties. 4) Proporcionando una URL (url) apuntando a un fichero de propiedades vlido. 5) Proporcionando el nombre de un recurso (resource) que contenga el fichero de propiedades a utilizar. 6) Estableciendo el atributo environment con un prefijo. Se le podr dar valor a las propiedades anteponiendo el prefijo dado y un punto al nombre de la variable. - 20 -

name value location refid resource file url

Aunque es posible utilizar combinaciones de estas formas, no se recomienda hacerlo. Debera usarse una nica forma de establecer cada una de las propiedades, ya que, por ejemplo, podran producirse errores si las propiedades no se establecen en el orden esperado. El atributo valor de las propiedades puede perfectamente contener referencias a otras propiedades. Dichas referencias se resolvern en el justo momento en que la propiedad es establecida. Esto tambin es as para las propiedades cargadas desde fichero.

Propiedades predefinidas
Adems de las propiedades que podemos definir nosotros, Ant define una serie de propiedades predefinidas para su funcionamiento interno que puede convenirnos conocer para consultarlas y hacer uso de ellas en ciertos momentos.
Propiedad Descripcin

La ruta absoluta del directorio base del proyecto, tal cual se estableci en el atributo basedir de la etiqueta <project>. ant.file La ruta absoluta del fichero de construccin usado. ant.version La versin de Ant. El nombre del proyecto que estamos construyendo, tal cual se ant.project.name estableci en el atributo name de la etiqueta <project>. La versin de la JMV (Mquina Virtual Java) que ha detectado Ant. ant.java.version Actualmente puede contener los valores 1.2, 1.3, 1.4 y 1.5. Directorio raz de Ant. NOTA: Esta propiedad es establecida por el ant.home script lanzador de Ant, y podra no tener valor en entornos integrados de desarrollo (o IDEs), como Eclipse o NetBeans, que hagan uso de Ant. basedir

- 21 -

4.3.- Target <target>.

Mediante la etiqueta target modelaremos las funcionalidades de los procesos de nuestro fichero de construccin. De un target hemos de especificar obligatoriamente su nombre, y, a partir de ah, posibles dependencias con otros targets o alguna propiedad que habr de estar establecida (o no) para que dicho target sea ejecutado.
Atributo Descripcin

name depends if unless description

Nombre del target. Atributo obligatorio. Lista de nombres de targets separados por comas de los que este depende. Nombre de una propiedad que debe estar establecida (tener algn valor) para que este target sea ejecutado. Nombre de una propiedad que no debe estar establecida (es decir, que an no se le haya dado ningn valor) para que este target sea ejecutado. Breve descripcin textual de la funcin del target.

As pues, la forma general de un target se parecer a la siguiente:

<target name="compilar" description="Compila las clases de la aplicacin"> ... definicin del target ... </target>

Si tenemos un target que slo queremos que se ejecute solamente cuando se den ciertas condiciones, podemos definir targets de comprobacin, como mencionbamos en el apartado que dedicamos a las propiedades. Podemos usar la tarea condition para comprobar cierta condicin y, en base a ello, establecer o no una propiedad a algn valor. Por ejemplo, si queremos comprobar la existencia de ciertos ficheros antes de ejecutar un target, podramos definir algo similar a lo siguiente:
<target name="miTarget" depends="miTarget.check" if="miTarget.run"> </target>
<echo>INFO: Los archivos historial.txt y changelog.txt estn presentes.</echo>

<target name="miTarget.check"> <condition property="miTarget.run"> <and> <available file="historial.txt"/> <available file="changelog.txt"/> </and> </condition> </target>

Como podemos ver, lo que realmente hacemos es crear un target de comprobacin del que depender el target principal y en el que comprobaremos la condicin que nos interesa. Es una buena opcin tener un target genrico de comprobacin de mltiples propiedades, que, adems, sea ejecutado, siempre que sea posible, al principio del flujo de la construccin del proyecto.

- 22 -

4.4.- Nuestro primer archivo de construccin.

Despus de haber comprendido los conceptos bsicos de la herramienta, as como sus tareas ms fundamentales, estamos en condiciones ya de ir poniendo en prctica todos nuestros recin adquiridos conocimientos realizando un primer ejemplo de archivo de construccin. Para ello, vamos a ir desarrollando un ejemplo bsico de fichero de construccin ambientado en unas condiciones lo ms generales posibles, yendo paso a paso, y explicando en detalle cada una de nuestras acciones. 1) Creamos un archivo de construccin para nuestro proyecto, preferiblemente llamado build.xml. Puedes crearlo con tu editor de textos favorito, aunque, para mayor comodidad y productividad, se recomienda un editor especfico de archivos XML. NOTA: si usamos un editor de textos que no codifique el archivo de texto de salida con una codificacin Unicode UTF-8 podemos tener problemas. Ant rechazar, arrojando un error en dicho caso, cualquier archivo que no pueda leer correctamente. Especialmente problemticos (estas cosas se dicen por experiencia propia) pueden ser caracteres como las tildes () que puedan contener los comentarios de nuestro archivo de construccin. 2) Aadimos la cabecera XML bsica al archivo. <?xml version="1.0"?> 3) Definimos nuestro proyecto de construccin: tendr el nombre (name) de, por ejemplo, HolaMundo, su directorio base (basedir) ser el mismo en el que est colocado el archivo de construccin (por tanto, el directorio actual o .) y su target por defecto ser el target todo, que ejecutar todos los targets disponibles. <project name="HolaMundo" basedir="." default="todo"> ... definicin del proyecto ... </project> 4) Una vez definido nuestro proyecto, seguimos escribiendo ya dentro de su bloque. Definimos las propiedades generales del proyecto. Conviene definir unas cuantas propiedades bsicas, segn nuestro propio criterio, con (al menos) rutas para la localizacin de nuestros archivos, as como para guardar los archivos compilados de bytecode, o la ruta de salida de la documentacin generada por javadoc, entre otras. <property <property <property <property name="dir.fuentes" name="dir.clases" name="dir.jar" name="dir.javadoc" value="${basedir}\src"/> value="${basedir}\classes"/> value="${basedir}\jar"/> value="${basedir}\javadoc"/>

Como podemos ver, estamos generando una serie de propiedades para hacer referencia a ciertas rutas de nuestro proyecto usando una de las propiedades predefinidas de Ant, basedir, que ya hemos establecido anteriormente al definir nuestro proyecto.

- 23 -

5) Vamos definiendo uno por uno todos los targets que vamos a necesitar. Primeramente, definiremos el target por defecto todo, que estar vaco y que lo ms importante a tener en cuenta es que tendr en su atributo depends los nombres de todos los dems targets que queramos que se ejecuten cuando se ejecute el target por defecto. Esto forzar a Ant a ejecutar todos esos targets del archivo de construccin que han sido especificados en el depends, luego ejecutar el target todo (vaco) y terminar. <target name="todo" depends="compilar, empaquetar, documentar"/> 6) Definimos el resto de targets. Lo ms habitual es definir los targets segn el orden lgico en el que van a ejecutarse habitualmente, es decir, si lo primero que se va a hacer generalmente es compilar el cdigo fuente, lo ms intuitivo es definir el target compilar en primer lugar, y as sucesivamente. <target name="compilar"> <javac srcdir="${dir.fuentes}" destdir="${dir.classes}"/> </target> Como podemos ver, el target compilar no depende de ningn otro, as que es candidato para ser ejecutado el primero de todos. Adems, podemos observar que se ha usado una tarea que an no hemos visto: <javac>. Esta tarea es una de las tareas bsicas (Core tasks) de Ant, que nos permite compilar un rbol de archivos Java. En el atributo srcdir le indicamos la localizacin de la raz de nuestro rbol de archivos de cdigo fuente Java (localizacin que ya definimos en la propiedad dir.fuentes) y en el atributo destdir le indicamos el directorio raz al cual copiar los archivos de bytecode generados tras la compilacin (esta ruta tambin la guardamos en la propiedad dir.clases). Para ms informacin sobre la tarea <javac>, puedes consultar la seccin Tareas bsicas de este mismo documento, o acudir a la documentacin oficial de Ant. <target name="empaquetar" depends="compilar"> <jar destfile="${dir.jar}\${ant.project.name}.jar" basedir="${dir.classes}" manifest="${dir.fuentes}\META-INF\MANIFEST.MF" /> </target> El target empaquetar, que depende de la ejecucin previa de compilar, ejecuta una tarea <jar>, que se encargar de empaquetar nuestra aplicacin en un archivo JAR ejecutable (se incluye para ello una referencia al archivo de manifiesto en el atributo manifest). Como podemos observar, la ruta del archivo de salida (destfile) ser el subdirectorio jar, contenido en la propiedad dir.jar y el archivo se llamar como el nombre del proyecto, haciendo uso de la propiedad predefinida ant.project.name. Los archivos incluidos sern todos aquellos que se encuentren en el directorio dado por el atributo basedir.

- 24 -

<target name="documentar"> <javadoc sourcepath="${dir.fuentes}" destdir="${dir.javadoc}" /> </target> El target documentar, que no depende de la ejecucin previa de ningn otro para ejecutarse, lleva a cabo una tarea <javadoc>, que se encarga de generar la documentacin de nuestra aplicacin a partir de su cdigo fuente usando la herramienta javadoc de Sun, proporcionada como parte del JDK (Kit de Desarrollo Java). Para ms informacin sobre dicha herramienta y su uso, acuda a la documentacin oficial de Sun Microsystems. 7) Cerramos el bloque de proyecto y revisamos nuestro cdigo. Una vez que hemos definido todos los targets de nuestro fichero de construccin, ya hemos terminado. Lo nico que nos queda por hacer es cerrar el bloque del proyecto con </project> (que es siempre la ltima lnea de cualquier fichero de construccin de Ant) y, despus, siempre viene bien revisar nuestro cdigo para repasar lo que estamos haciendo y buscar cualquier errata.

- 25 -

Nuestro primer archivo de construccin: cdigo completo

Una vez que hayamos terminado con todos los pasos necesarios para escribir el archivo de construccin, nos habr quedado algo similar a lo siguiente:
build.xml

<?xml version="1.0"?> <!-- definicion del proyecto --> <project name="HolaMundo" basedir="." default="todo"> <!-- propiedades del proyecto --> <property <property <property <property name="dir.fuentes" name="dir.clases" name="dir.jar" name="dir.javadoc" value="${basedir}\src" /> value="${basedir}\classes" /> value="${basedir}\jar" /> value="${basedir}\javadoc" />

<!-- target por defecto --> <target name="todo" depends="compilar, empaquetar, documentar"> <echo>Target por defecto completado.</echo> </target> <!-- otros targets --> <target name="compilar"> <javac srcdir="${dir.fuentes}" destdir="${dir.clases}" /> </target> <target name="empaquetar" depends="compilar"> <jar destfile="${dir.jar}\${ant.project.name}.jar" basedir="${dir.clases}" manifest="${dir.fuentes}\META-INF\MANIFEST.MF" /> </target> <target name="documentar"> <javadoc sourcepath="${dir.fuentes}" destdir="${dir.javadoc}" /> </target> </project>

- 26 -

5.- TAREAS.
En la siguiente seccin vamos a hablar con relativa profundidad de unas cuantas tareas que podemos usar en Ant para poder sacar adelante los procesos de construccin personalizados de nuestras aplicaciones. Dejaremos fuera de este documento todas aquellas tareas que se salgan de nuestro entorno de trabajo ms habitual: el proceso de desarrollo de aplicaciones Java J2SE/J2EE robustas, su documentacin, prueba, empaquetado y, finalmente, su despliegue en un servidor de aplicaciones. Las tareas ms sencillas se explicarn en detalle. Sin embargo, en las tareas ms complejas slo entraremos en un nivel de detalle suficiente para explicar el uso ms general y facilitar la comprensin de las mismas. Obviamente, no tiene sentido referenciar todas las posibilidades de la seleccin completa de las tareas Ant en este documento, ya que excedera en demasa de su carcter docente y de introduccin. Para poder consultar el funcionamiento y uso de todas las tareas de que dispone Ant, con una descripcin completa y en detalle, lo mejor es acudir a su excelente manual, a la seccin Ant Tasks (Tareas Ant), donde puede consultarse informacin tanto de tareas bsicas como opcionales. El manual de Ant viene ya incluido de serie con el archivo de distribucin de la herramienta, as como tambin est disponible actualizado en su pgina web oficial a travs de la siguiente direccin: http://ant.apache.org/manual/ Como ya habamos mencionado anteriormente, una tarea Ant se corresponde en el fichero de construccin con una etiqueta XML, que puede tener atributos (llamados parmetros en la terminologa de Ant) y elementos anidados, que son ciertas etiquetas interiores que nos servirn para especificar diversas opciones de la tarea concreta. Siempre que sea importante detallar estos elementos para comprender el funcionamiento de una determinada tarea, se incluir una explicacin concisa sobre su funcin. El aspecto de una tarea habitual con elementos anidados tiene el siguiente aspecto: <tarea atributo1=valor1 atributo2=valor2> <elemento-anidado1 atributo11=valor11/> <elemento-anidado2 atributo21=valor21> <elemento-anidado21 atributo211=valor211/> </elemento-anidado2> </tarea> Hay que comentar tambin que hay algunos tipos especiales de tareas con ciertas caractersticas, como las tareas que heredan de MatchingTask, y que tienen una serie de atributos adicionales. A continuacin, sigue una explicacin someras de tareas que, ya sean bsicas u opcionales, nos convendr conocer en nuestro entorno habitual de trabajo y desarrollo. Happy Ant-ing! - 27 -

5.1.- Tareas segn su funcionalidad.

Las tareas de Ant pueden reunirse en diversos grupos atendiendo a su funcionalidad. Para disponer de una referencia rpida de las mismas, y facilitar su localizacin cuando necesitemos consultar si Ant dispone de cierta tarea, aqu sigue una enumeracin de todas las tareas de Ant agrupadas segn su tipo de funcionalidad. Puedes consultar esta informacin totalmente actualizada acudiendo tambin al manual oficial de Ant, en su apartado Overview of Ant Tasks, del que esta seccin supone una mera traduccin y adaptacin al castellano. Se ha decidido incluir este apartado del manual casi tal cual porque es una forma muy rpida y clarificadora de comprender la divisin de las tareas de Ant, y como referencia nos ser muy valiosa.

Listado (no exhaustivo) de tareas segn su funcionalidad

(Ant versin 1.7)

Archive Tasks
Tarea Descripcin

bunzip2 bzip2 cab ear gunzip gzip jar manifest rpm signjar tar unjar untar unwar unzip war zip

Descomprime un archivo comprimido con GZip o BZip2. Comprime un archivo usando el algoritmo GZip o BZip2. Crea un archivo CAB de Microsoft. Extensin de la tarea <jar> para facilitar la creacin de archivos EAR. Descomprime un archivo GZip. Comprime en GZip un conjunto de archivos. Empaqueta en JAR un conjunto de archivos. Crea un archivo de manifiesto. Tarea slo vlida para Unix que invoca al manejador de paquetes rpm. Firma un archivo JAR o ZIP con la herramienta javasign del JDK. Empaqueta una serie de archivos en un TAR. Desempaqueta un archivo JAR. Desempaqueta un archivo TAR. Desempaqueta un archivo WAR. Descomprime un archivo ZIP. Una extensin de la tarea <jar> para facilitar la creacin de archivos WAR. Crea un archivo ZIP.

Audit/Coverage Tasks
Tarea Descripcin

jdepend

Invoca al parser JDepend, que analiza una serie de directorios de cdigo Java y genera mtricas de calidad del diseo para cada clase Java.

- 28 -

Compile Tasks
Tarea Descripcin

depend javac apt

jspc netrexxc rmic wljspc

Determina qu archivos de clase estn desactualizados con respecto a su cdigo fuente, eliminando los archivos de clase que dependan de cualquier clase desactualizada y forzando su recompilacin. Usada junto a <javac>. Compila los archivos de cdigo fuente Java especificados. Ejecuta el annotation processor tool (apt) y opcionalmente compila el cdigo fuente original, y cualquier cdigo generado. Ejecuta el compilador JSP. Puede usarse para precompilar pginas JSP para una rpida invocacin inicial de pginas JSP, el despliegue en un servidor sin toda la JDK instalada, o simplemente comprobacin de la sintaxis de las pginas sin desplegarlas. Luego puede usarse la tarea <javac> para compilar el cdigo Java. Compila un rbol de cdigo fuente NetRexx. Ejecuta el compilador RMI sobre los ficheros especificados. Compila pginas JSP usando el compilador JSP de Weblogic, weblogic.jspc. Para compilar con un compilador que no sea de Weblogic, usar <jspc>.

Deployment Tasks
Tarea Descripcin

Tarea para ejecutar una herramienta de despliegue en caliente para un serverdeploy servidor J2EE de un fabricante especfico.

Documentation Tasks
Tarea Descripcin

javadoc stylebook

Genera documentacin del proyecto usando la herramienta javadoc. Ejecuta el generador de documentacin Apache Stylebook. Al contrario que con la versin de lnea de comandos de esta herramienta, todos los tres argumentos son obligatorios para ejecutar esta tarea.

EJB Tasks
Tarea Descripcin

blgclient ddcreator iplanet-ejbc

Borland Application Server versin 4 y 5 Weblogic 4.5.1 iPlanet Application Server 6.0
Elemento anidado de <ejbjar> Descripcin

ejbjar

wlrun wlstop

borland iPlanet jboss jonas weblogic websphere Weblogic 4.5.1 a 7.0 Weblogic 4.5.1 a 7.0

Borland Application Server versin 4 y 5 iPlanet Application Server 6.0 JBoss JOnAS 2.4.x y 2.5 Weblogic 5.1 a 7.0 IBM WebSphere 4.0

- 29 -

Execution Tasks
Tarea Descripcin

ant antcall apply dependset exec java parallel sequential sleep subant waitfor

Ejecuta Ant con un nuevo archivo de construccin, opcionalmente adems con la posibilidad de pasar propiedades con nuevos valores. Esta tarea puede usarse para construir sub-proyectos. Ejecuta un target dentro del mismo archivo de construccin, con la posibilidad de pasar propiedades con nuevos valores. Ejecuta un comando de sistema sobre un conjunto de ficheros. Compara un conjunto de archivos de cdigo fuente con un conjunto de archivos de destino. Si cualquiera de los archivos de cdigo fuente es ms nuevo que cualquiera de los de destino, todos los de destino son borrados. Ejecuta un comando. Similar a <apply>, pero sin conjuntos de ficheros. Ejecuta una clase Java en la mquina virtual Java de Ant o en otra aparte. Una tarea contenedora. Todas las tareas anidadas dentro de ella se ejecutarn en paralelo en su propio thread independiente. Una tarea contenedora. Todas las tareas anidadas dentro de ella se ejecutan en secuencia. Su principal uso es agrupar subconjuntos de tareas que han de ejecutarse secuencialmente dentro de la tarea <parallel>. Suspende la ejecucin de Ant por un periodo de tiempo (dado en mseg). Esta tarea es til cuando la construccin o el despliegue requiere de un intervalo de tiempo entre tareas. Llama a cierto target para todos los subproyectos definidos. Bloquea la ejecucin hasta que se cumplan ciertas condiciones. Esta tarea est orientada a sincronizar distintos procesos en paralelo de <parallel>.

File Tasks
Tarea Descripcin

attrib checksum chgrp chmod chown concat copy delete filter fixcrlf get mkdir move patch

Cambia los permisos y/o atributos de un fichero o ficheros dentro de los directorios especificados. Actualmente, slo tiene efecto bajo Windows. Genera un checksum para un fichero o conjunto de ficheros. Cambia el grupo al que pertenece un fichero o conjunto de ficheros. Actualmente, esta tarea slo tiene efecto en sistemas UNIX. Cambia los permisos de un fichero o grupo de ficheros dentro de los directorios especificados. Los permisos se establecen siguiendo el estilo habitual de UNIX. Actualmente, slo tiene efecto en sistemas UNIX. Cambia el usuario al que pertenece un fichero o conjunto de ficheros. Actualmente, esta tarea slo tiene efecto en sistemas UNIX. Concatena mltiples ficheros en uno solo, o en el registro de salida de Ant. Copia un fichero o conjunto de ficheros a un nuevo fichero o directorio. Borra ficheros sueltos, todos los ficheros y subdirectorios de un directorio dado, o un conjunto de ficheros dado por uno o ms <fileset>. Establece un filtro de tokens, o lee varios filtros de un fichero especificado. Los tokens de filtrado se usan en todas las tareas de copiado de archivos. Modifica un fichero para aadir o eliminar tabuladores, saltos de pgina, retornos de carro o marcas EOF de fin de fichero. Descarga un fichero desde una URL. Crea un directorio. Se crean los directorios padres que no existan. Mueve un fichero o conjunto de ficheros a un directorio. Aplica un parche diferencial de cdigo diff a un archivo. - 30 -

replace
replaceregexp

sync tempfile touch

Reemplaza las ocurrencias de una cadena de texto por otra en un fichero. Reemplaza una expresin regular por un patrn de sustitucin. Sincroniza dos rboles de directorios. Genera un nombre para un archivo temporal y establece una propiedad. Cambia la fecha de modificacin de un fichero, crendolo si no existe.

Java2 Extensions Tasks

Tarea jarlib-available Descripcin

Comprueba si una extensin est presente en un fileset o en un extensionset. Si est presente, establece una propiedad. Muestra la informacin contenida en los atributos Optional Package y jarlib-display Package Specification de los archivos JAR especificados. Tarea para generar un manifiesto que declara todas las dependencias del manifiesto. Las dependencias se determinan mirando la ruta especificada y jarlib-manifest buscando a ver si hay especificaciones Extension/Optional Package en los manifiestos del los archivos JAR. Intenta localizar un JAR que satisfaga una extensin, y coloca su ruta en la jarlib-resolve propiedad especificada.

Logging Tasks
Tarea Descripcin

record

Lanza un listener que graba la salida del proceso de construccin a un fichero. Se permiten varios recorders simultneos con distintos ficheros.

Mail Tasks
Tarea Descripcin

mail

Enva un correo electrnico saliente usando SMTP.

Miscellaneous Tasks
Tarea defaultexcludes Descripcin

echo fail genkey input script sound splash sql taskdef tstamp typedef xmlvalidate

Modifica la lista por defecto de patrones de exclusin de ficheros de Ant. Enva texto a la consola del sistema (System.out) o a un fichero. Fuerza salir del proceso de construccin arrojando una BuildException, y, opcionalmente, muestra un mensaje con informacin adicional. Genera una clave (key) dentro de un almacn de claves (keystore). Permite la interaccin de los usuarios durante el proceso de construccin mostrando un mensaje y leyendo una lnea de entrada desde la consola. Ejecuta un script en un lenguaje que soporte Apache BSF. Reproduce un sonido al final del proceso de construccin. El sonido ser uno u otro segn la construccin concluya con xito o con un fallo. Muestra una pantalla de presentacin momentnea (splash screen). Ejecuta una serie de sentencias SQL en una base de datos usando JDBC. Aade una nueva definicin de tarea para usarla en el proyecto actual. Establece las propiedades DSTAMP, TSTAMP y TODAY del proyecto. Aade una definicin de tipo para poder usarlo en el proyecto actual. Comprueba si ciertos ficheros XML son vlidos (o bien formados). - 31 -

.NET Tasks
Tarea Descripcin

Compila cdigo fuente C#. Compila cdigo fuente Visual Basic .NET. Compila cdigo fuente J#. Desensambla ejecutables y libreras .NET. wsdltodotnet Genera cdigo .NET (C# o Visual Basic) desde un archivo WSDL. importtypelib Importa una librera de tipo COM a .NET.

csc vbc jsharpc ildasm

Pre-process Tasks
Tarea Descripcin

Invoca el generador de traductores ANTLR sobre un archivo de gramtica. Genera un DTD para los archivos de construccin que contiene diversa antstructure informacin sobre todas las tareas reconocidas en ese momento por Ant. Importa otro archivo de construccin y potencialmente sobrescribe los import targets del mismo con los del archivo de construccin actual. javacc Invoca el compilador-compilador JavaCC sobre un archivo de gramtica. javah Genera cabeceras JNI a partir de una clase Java. jjdoc Invoca al generador de documentacin JJDoc para JavaCC. jjtree Invoca el preprocesador JJTree para JavaCC. macrodef Define una nueva tarea como una macro. Convierte ficheros desde su codificacin de caracteres nativa a ASCII usando Unicode. Se usa habitualmente para convertir archivos de cdigo native2ascii fuente mantenidos en una codificacin nativa de sistema operativo a ASCII como paso previo a la compilacin de dicho cdigo. Define una nueva tarea utilizando una tarea ya existente con valores por presetdef defecto preestablecidos para sus atributos o elementos anidados. Identifica claves en ficheros, delimitados por tokens especiales, y los translate traduce a valores ledos desde otros ficheros de recurso (resource bundles). typedef Aade una definicin de tipo para poder usarlo en el proyecto actual. xslt Procesa un conjunto de documentos por el transformador XSLT.

antlr

Property Tasks
Tarea Descripcin

Establece una propiedad si cierto recurso existe en tiempo de ejecucin. Establece una propiedad al ltimo elemento de una ruta especificada. buildnumber Puede usarse para hacer un seguimiento del nmero de construccin. condition Establece una propiedad si se dan ciertas condiciones. dirname Establece una propiedad a la ruta del ltimo directorio de una ruta dada. echoproperties Lista las propiedades actuales del proyecto. loadfile Carga un fichero en una propiedad. loadproperties Carga propiedades Ant desde un archivo externo. makeurl Crea una URL o una lista de URLs a partir de uno o varios ficheros. Convierte un conjunto de rutas ficheros a una lista separada por el pathconvert separador especificado y la guarda en una determinada propiedad. property Establece una propiedad (dando nombre y valor) o varias (va fichero). propertyfile Crea o modifica archivos de propiedades. - 32 -

available basename

Establece una propiedad si un cjto de ficheros es ms reciente que otro. Encuentra una determinada clase o recurso. xmlproperty Carga valores de propiedades desde un archivo XML bien formado.
whichresource

uptodate

Remote Tasks
Tarea Descripcin

ftp rexec scp setproxy sshexec telnet

Implementa un cliente FTP bsico que puede enviar, recibir, listar y borrar ficheros y directorios en un servidor FTP remoto. Tarea para automatizar una sesin rexec remota. Copia ficheros hacia o desde un servidor remoto usando SSH. Establece las propiedades del Proxy web de Java, para que las tareas y el cdigo que estn ejecutndose en la misma mquina virtual Java puedan tener acceso externo a travs del firewall a sitios web remotos. Ejecuta un comando en un servidor remoto usando SSH. Automatiza una sesin remota de Telnet.

SCM (Source Configuration Management) Tasks

Tarea Descripcin

cvs
cvschangelog

cvspass cvstagdiff cc******* ccm***** vss****** p4****** pvcs sos****** st*******

Administra paquetes/mdulos recibidos desde un repositorio CVS. Genera un informe XML de los cambios guardados en un repositorio CVS. Aade entradas a un archivo .cvspass. Aadir entradas a este fichero tiene el mismo efecto que la ejecucin de un comando cvs login. Genera un informe XML de cambios diferenciales entre dos tags o fechas. Tarea que puede realizar acciones de la herramienta ClearCase: cccheckin, cccheckout, ccuncheckout, etc Consulta el manual para ms detalles. Tarea que puede realizar acciones de la herramienta Synergy, antigua Continuus: ccmcheckin, etc Consulta el manual de Ant para ms detalles. Tarea que puede realizar acciones de la herramienta Visual SourceSafe de Microsoft: vsscheckin, etc Consulta el manual de Ant para ms detalles. Tarea que puede realizar acciones de la herramienta Perforce: p4sync, p4change, p4edit, p4submit, etc Consulta el manual para ms detalles. Permite al usuario extraer la ltima revisin del cdigo fuente de una aplicacin desde un repositorio PVCS. Consulta el manual para detalles. Tarea que puede realizar acciones de la herramienta SourceOffSite: sosget, soslabel, soscheckin, etc Consulta el manual de Ant para ms detalles. Tarea que puede realizar acciones de la herramienta StarTeam: stcheckin, stcheckuot, stlabel, y stlist. Consulta el manual de Ant para ms detalles.

Testing Tasks
Tarea Descripcin

junit junitreport

Ejecuta las pruebas del framework JUnit de pruebas de unidad. Mezcla los archivos XML generados individualmente por la tarea <junit> y genera una salida HTML, aplicndole una hoja de estilo para crear un informe de los resultados de las pruebas visible a travs de un navegador.

- 33 -

5.2.- Tareas bsicas.

Las tareas bsicas son aquellas que estn incluidas en el ncleo de Ant per se, sin necesidad de incluir libreras adicionales, y que proporcionan las capacidades ms fundamentales de la herramienta. Son el conjunto mnimo de tareas que el equipo de desarrollo de Ant ha acordado que van a necesitarse en el orden del da de nuestro trabajo. Enumeraremos mediante una tabla la lista completa de todas las tareas bsicas de Ant a modo de referencia, y despus pasaremos a explicar brevemente las ms importantes y comnmente usadas en nuestro escenario habitual de trabajo.

Listado completo de tareas bsicas (Ant versin 1.7)

Tarea Descripcin

ant antcall antstructure apply apt available basename buildnumber bunzip2 bzip2 checksum chmod concat condition copy cvs cvschangelog cvsversion cvspass cvstagdiff defaultexludes delete dependset diagnostics dirname ear echo echoxml exec fail

Lanza la construccin de un subproyecto. Lanza la ejecucin de un target dentro de un mismo proyecto. Genera un DTD informativo para los ficheros de construccin de Ant. Ejecuta un comando en el sistema sobre un conjunto de ficheros. Lanza el annotation processor tool (apt), y, opcionalmente, compila el cdigo original, as como cualquier cdigo fuente generado. Establece una propiedad si existe cierto recurso en tiempo de ejecucin. Determina el nombre del fichero de una ruta absoluta o relativa. Tarea bsica para ir registrando un nmero de construccin. Descomprime un recurso comprimido con BZip2. Comprime un recurso a un archivo de salida usando el algoritmo BZip2. Genera checksums. Esta tarea puede usarse para verificar ficheros. Cambia permisos de acceso de ficheros. Slo tiene efecto en UNIX. Concatena uno o ms recursos a un nico fichero de salida o la consola. Establece una propiedad si se cumple cierta condicin. Copia archivos o coleccin de recursos a un nuevo archivo o directorio. Administra paquetes recibidos desde un repositorio CVS. Genera un fichero XML con el log de cambios grabados en un CVS. Tarea que permite obtener la versin del cliente y el servidor CVS. Aade entradas a un archivo .cvspass, con el mismo efecto que cvslogin. Genera un fichero XML con los cambios entre dos tags o fechas. Altera los archivos que son excluidos por Ant por defecto. Borra una serie de ficheros y/o directorios. Maneja dependencias adicionales arbitrarias entre ficheros. Ejecuta el modo diagnstico desde dentro de Ant. til si se quiere lanzar su modo de diagnstico desde dentro de un entorno de desarrollo (IDE). Establece una propiedad con el directorio padre de una ruta de fichero. Extensin de la tarea jar con opciones de tratamiento especiales para archivos EAR (Enterprise Application Archive). Escribe un mensaje a los logres y listeners del proyecto, que por defecto ser la salida del sistema (System.out) si no se especifica lo contrario. Tarea que pasa al dispositivo de salida o a un fichero los elementos XML que estn incluidos en su bloque. Ejecuta un comando de sistema. Similar a apply, pero sin ficheros. Provoca un fallo en el proceso de construccin, arrojando una excepcin - 34 -

filter fixcrlf genkey get gunzip gzip import input jar java javac javadoc length loadfile loadproperties loadresource makeurl mail macrodef manifest
manifestclasspath

mkdir move nice parallel patch pathconvert presetdef property record replace resourcecount rmic sequential signjar sleep sql subant sync tar taskdef tempfile

BuildException con un mensaje informativo. Establece tokens de cadenas de caracteres para filtrado de ficheros. Ajusta las convenciones locales de salto de lnea y retorno de carro. Genera una clave cifrada de firma en un almacn de claves (keystore). Descarga un fichero desde URL (podemos usar http:, ftp:, jar:, https:). Descomprime un recurso usando GZip. Comprime un recurso usando el algoritmo GZip. Importa un fichero de construccin externo completo al proyecto actual. Permite la interaccin del usuario durante el proceso de construccin. Empaqueta en JAR un conjunto dado de ficheros. Ejecuta una clase Java en la mquina virtual. Compila un rbol de cdigo fuente Java. Genera la documentacin del proyecto usando la herramienta javadoc. Muestra o establece una propiedad con la longitud de fichero o cadena. Especializacin de loadresource para ficheros. Carga los contenidos de cierto fichero como propiedades de Ant. Carga un recurso textual y lo almacena en una propiedad. Convierte rutas de fichero en URLs tipo file: Enva un correo electrnico saliente va SMTP. Define una nueva tarea usando los elementos anidados <sequential>. Crea un archivo de manifiesto para poder incluirlo en un archivo JAR. Convierte un recurso path en una propiedad vlida que pueda usarse para establecer el atributo Class-Path de un manifiesto. Crea un directorio (y todos sus padres, hasta la rama final), si no existe. Mueve ficheros a un nuevo directorio. Consulta o establece la prioridad de la hebra actual de ejecucin de Ant. Tarea contenedora (puede contener otras tareas). Todas las tareas contenidas dentro de esta tarea corrern paralelamente en su thread. Aplica un parche diferencial (diff) a un archivo. Convierte una coleccin de recursos en una lista de nombres de archivo. Permite definir nuestras propias tareas en un archivo de construccin. Usando esta tarea podemos definir nuestras propias tareas. Establece una propiedad (dados su nombre y valor) o un conjunto de las mismas a travs de un fichero externo de propiedades. Define un recorder, es decir, un listener que guarda la salida generada por el proceso de construccin a un fichero. Reemplaza en un conjunto de ficheros una cadena de texto por otra. Sirve para consultar el tamao de colecciones de recursos o establecer propiedades con dicho nmero. Puede usarse como condicin. Compila clases en el rmic (Java RMI stub compiler) del JDK. Tarea contenedora. Las tareas anidadas son ejecutadas en secuencia. La funcin de esta tarea es agrupar tareas secuenciales en <parallel>. Firma archivos JAR usando la herramienta jarsigner del JDK. Detiene (o duerme) Ant durante un breve periodo de tiempo. til si el proceso de construccin o despliegue requiere una pausa entre tareas. Ejecuta una serie de sentencias SQL en una base de datos usando JDBC. Llama a un target dado para todos los subproyectos definidos. Sincroniza un directorio con los ficheros definidos en una coleccin. Crea un archivo TAR para agrupar colecciones de ficheros. Aade una definicin de tarea al proyecto actual para que pueda usarse. Crea un archivo temporal que es asignado a una propiedad. - 35 -

touch tstamp typedef unjar untar unwar unzip uptodate waitfor whichresource war xmlproperty xslt zip

Cambia fecha de ltima modificacin de un fichero. Si no existe, lo crea. Establece las propiedades DSTAMP, TSTAMP y TODAY del proyecto. Aade la definicin de una tarea o tipo de datos al proyecto para que pueda ser usado en l. <taskdef> es una generalizacin de esta. Descomprime un archivo JAR. Desempaqueta un archivo TAR. Despliega un archivo WAR. Descomprime un archivo ZIP. Establece una propiedad si una serie de archivos de destino son ms recientes que otra serie de archivos fuente. Bloquea la ejecucin hasta que se dan una serie de condiciones. Esta tarea est enfocada a sincronizar una serie de procesos que se estn ejecutando en paralelo dentro de una tarea <parallel>. Busca una clase o recurso y establece una propiedad con su URL si el recurso o fichero en cuestin es encontrado. Una extensin de la tarea <tar> para manejar las caractersticas especiales de los ficheros WAR (directorio WEB-INF, web.xml, etc). Carga valores de propiedades desde un archivo XML bien formado. Pasa un conjunto de documentos a travs de un procesador XSLT. Crea un archivo comprimido en ZIP a partir de un conjunto de ficheros.

- 36 -

Tareas bsicas ms importantes <ant>

Descripcin:

Lanza la construccin de un subproyecto con su propio archivo de construccin.

Atributos: Atributo Descripcin

antfile dir target inheritAll inheritRef output

Nombre del archivo a utilizar. Por defecto: build.xml. El directorio base del subproyecto. Por defecto: el basedir del proyecto. Nombre del target a ejecutar en el subproyecto. Por defecto: target defecto. Si el subproyecto hereda las propiedades del proyecto padre. Defecto: true. Si el subproyecto hereda las referencias del padre. Defecto: false. Nombre del archivo donde volcar la salida.

Elementos anidados: Elemento anidado Descripcin

property reference target

Ejemplos:

Nombre de una propiedad que queremos propagar al subproyecto. Para ms informacin, consulta la sintaxis de la tarea property. Referencia identificativa de un tipo de datos que queramos propagar. Mediante elementos anidados se soporta la llamada de mltiples targets.

Lanza Ant sobre un subproyecto, unicado en el subdirectorio subproyecto: <ant dir="subproyecto"/> Como el ejemplo anterior, lanza Ant sobre un subproyecto, unicado en el subdirectorio subproyecto, pero se especifica un nombre de archivo de construccin subbuild.xml diferente al nombre por defecto, y, en lugar del target por defecto, invoca a compilar: <ant antfile="subproyecto/subbuild.xml" target="compilar"/> Como el ejemplo anterior, pero pasando atributos al subproyecto a travs de una propiedad individual y de un fichero de propiedades externo: <ant antfile="subproyecto/subbuild.xml"> <property name="parametro1" value="version 1.x"/> <property file="config/subproyecto/propiedades.conf"/> </ant>

- 37 -

<antcall>
Lanza la ejecucin de un target dentro de un mismo proyecto.
Atributo Descripcin

target inheritAll inheritRef

Elemento anidado

Nombre del target a ejecutar en el subproyecto. Por defecto: target defecto. Si el nuevo proyecto hereda las propiedades del actual. Por defecto: true. Si el nuevo proyecto hereda las referencias del actual. Por defecto: false.
Descripcin

property reference target

Ejemplos:

Nombre de una propiedad que queremos propagar al target invocado. Referencia identificativa de un tipo de datos que queramos propagar. Mediante elementos anidados se soporta la llamada de mltiples targets.

En el siguiente cdigo, desde el target un-target-cualquiera se invoca a otro target imprimir-mensaje: <target name="un-target-cualquiera"> <antcall target="imprimir-mensaje"> <param name="mensaje" value="Hola, soy un mensaje."/> </antcall> </target> <target name="imprimir-mensaje"> <echo message="${mensaje}"/>
</target>

<apply>
Ejecuta un comando en el sistema, con un conjunto de ficheros como argumento. Es una de las tareas ms potentes de entre las que proporciona Ant.
Atributo Descripcin

executable dir dest

spawn relative forwardslash type

Nombre del comando a ejecutar, sin argumentos. Directorio de trabajo donde el comando debera ejecutarse. Directorio donde esperamos que el comando guarde los ficheros de salida. Atributo slo vlido si se usa un mapeador anidado. Si se omite, Ant interpretar las rutas de salida del mapeador como rutas absolutas. Si el comando debe ejecutarse en una hebra independiente de Ant. Si se lanza un comando independiente, Ant no puede hacer un log de la salida del comando, ni estarn activas las propiedades input, output, error y result del proyecto. Por defecto: false. Si los nombres de fichero que se pasan al comando son rutas relativas. Si los nombres de fichero deberan pasarse al comando usando barras /, incluso si el sistema operativo requiere otro separador, como la invertida. Indica el tipo de rutas que se pasan al comando: si slo se consideran las rutas de archivo (file), directorio (dir) o ambos (both). Defecto: file. - 38 -

addsourcefile os osfamily input inputstring output error logError

outputproperty errorproperty resultproperty

parallel maxparallel append timeout failonerror

failifexecutionfails

skipemptyfilesets newenvironment

vmlauncher
resolveExecutable

verbose
ignoremissing

force
Elemento anidado

Si los nombres de fichero se aaden automticamente. Defecto: true. Lista de sistemas operativos en los que el comando puede ser ejecutado. Familia del sistema operativo, tal y como se usa en la condicin <os>. Un archivo desde el que se recoger la entrada estndar hacia el comando. Una cadena que hace de flujo de entrada al comando. Exclusivo con input. Fichero al que volcar la salida de la ejecucin del comando. Fichero al que volcar la salida de error de la ejecucin del comando. Atributo para poder ver la salida de error del comando por el log de Ant. La propiedad en la que volcar la salida del comando. Alternativa al fichero. La propiedad en la que volcar el error del comando. Alternativa al fichero. La propiedad en la que se almacenar el cdigo de retorno del comando. Ejecuta el comando una sola vez, con todos los ficheros como argumento del comando. Si est a false, se ejecuta el comando una vez por archivo. Limita la cantidad de paralelismo a un cierto nmero de ficheros en cada momento. Si se usa un valor <= 0, se deja ilimitado. Por defecto: ilimitado. Si se sobrescriben o anexan las salidas de ejecucin de los comandos en un fichero. Si parallel fue establecido a false, habr que ponerlo a true. Detiene el comando si no termina en un periodo de tiempo (dado en mseg). Detiene el proceso de construccin si el comando devuelve un cdigo != 0. Detiene el proceso de construccin si no puede ejecutarse el comando. No ejecuta el comando si no se le pasan ficheros al comando o si todos los que se les pasa son ms viejos que los ficheros objetivo. No propagar las variables de entorno anteriores entorno cuando se especifican nuevas variables de entorno. Por defecto: false. Ejecuta el comando usando las facilidades de la JVM cuando sea posible. Cuando este atributo se establece a true, el nombre del ejecutable se resuelve primeramente en el basedir del proyecto y luego en el directorio elegido para la ejecucin del comando. Imprimir un resumen tras la ejecucin del comando. Por defecto: false. Ignorar los ficheros especificados no existentes. Por defecto: true. Fuerza la sobreescritura de ficheros saltndose la comparacin, aunque los ficheros de destino sean ms nuevos que los de origen. Por defecto: false.
Descripcin

Coleccin de recursos mapper arg srcfile

targetfile env redirector

Podemos pasarle a la tarea cualquier coleccin de recursos con la lista de rutas de los recursos a ejecutar: fileset, filelist, dirset, etc. Un mapper especifica los archivos relativos al atributo dest para comprobacin de dependencias. Argumento de lnea de comandos para pasar al comando. Por defecto, los nombres de los archivos a ejecutar sern aadidos al final de la lnea de comandos (a menos que se establezca addsourcefile a false). Si es necesario colocar los nombres de archivo en otro lugar diferente, se usa este elemento entre las etiquetas <arg> para marcar el punto exacto de insercin donde irn esos nombres de fichero. Similar a srcfile, pero marca la colocacin del archivo objetivo. Este elemento slo puede especificarse si se define un mapper anidado. Especifica variables de entorno para pasar al comando en <env> anidados. Redirector de E/S anidado. Permite recibir entrada desde y enviar salida hacia ficheros diferentes para cada archivo fuente a enviar al comando. - 39 -

Ejemplos:

El cdigo del siguiente ejemplo invoca: comando argumento1 NOMBREFICHEROFUENTE argumento2 para todos los ficheros del directorio /tmp, reemplazando NOMBREFICHEROFUENTE con la ruta absoluta de cada fichero. Si parallel se puso a true, NOMBREFICHEROFUENTE ser reemplazado con los nombres de fichero absolutos de todos los ficheros, separados por espacios. <apply executable="comando" parallel="false"> <arg value="argumento1"/> <srcfile/> <arg value="argumento2"/> <fileset dir="/tmp"/> </apply> El cdigo siguiente aplica el comando ejecutable ficticio a todos los ficheros que encajen en el patrn *.file del directorio src. El <mapper> llamado out coger todos esos archivos *.file y los renombrar a *.out, y luego se usa para especificar los ficheros sobre los que ser ejecutado el comando para la tarea <apply>. Finalmente, dentro de una etiqueta <redirector> introducimos una referencia a out como un <outmapper>, que nos permitir realizar una comprobacin de dependencia de los archivos de salida con los de entrada. <mapper id="out" type="glob" from="src/*.file" to="dest/*.out"

/> <apply executable="comando" dest="dest"> <fileset dir="src" includes="*.file"/> <mapper refid="out"/> <redirector> <outputmapper refid="out"/> </redirector> </apply>

- 40 -

<available>
Establece una propiedad si est disponible (available, en ingls) cierto recurso en tiempo de ejecucin. Este recurso puede ser una clase dentro del classpath del proyecto, un fichero, un directorio u otro recurso dentro de la mquina virtual Java del sistema. Si el recurso est presente, la propiedad se establece por defecto a true; de otro modo, no se establece dicha propiedad. Puede establecerse la propiedad a cualquier otro valor usando el atributo value. Esta tarea puede usarse para implementar control de flujo bsico sobre el proceso de construccin en base a la existencia o no de ciertos recursos.
Atributo Descripcin

property value classname file resource classpath classpathref filepath type

ignoresystemclasses

searchparents Elemento anidado

Nombre de la propiedad que queremos usar. El valor a establecer en la propiedad. Por defecto: true. El nombre de la clase a buscar dentro del classpath del proyecto. El nombre del fichero a buscar. El nombre del recurso a buscar en la mquina virtual Java. El classpath a usar cuando busquemos por classname o resource. El classpath, dado como una referencia a una ruta previamente definida. La ruta en la que buscar el fichero dado por file. El tipo del fichero file que buscamos. file si es un archivo o dir si es directorio. Si no se especifica, la propiedad se establecer si el nombre dado por file existe, tanto si es un fichero como si es un directorio. Ignora las clases de Ant al buscar un classname. Por defecto: false. Si, cuando se busca un fichero, se ha de buscar en los directorios padre de los directorios especificados para la bsqueda. Por defecto: false.
Descripcin

classpath filepath
Ejemplos:

Classpath donde buscar una clase o un recurso. Ruta de archivo donde buscar un fichero.

Comprobacin de si est disponible la clase principal de una aplicacin y establece la propiedad main.presente si es as. <available classname="aplicacion.Main" property="main.presente"/> Busca en el classpath cuya referencia es ruta.jaxp la clase Transformer del paquete java.xml.transform, estableciendo jaxp.presente si la clase est disponible. <property name="ruta.jaxp.jar" value="./lib/jaxp11/jaxp.jar" /> <path id="ruta.jaxp" location="${ruta.jaxp.jar}" /> <target ...> <available classname="javax.xml.transform.Transformer" classpathref="ruta.jaxp" property="jaxp.presente" /> </target> - 41 -

<condition>
Establece una propiedad si se da cierta condicin. Esta tarea es una generalizacin de las tareas <available> y <uptodate>. Las condiciones se especifican mediante elementos anidados especiales dentro esta tarea y de la tarea <waitfor>. La lista de elementos anidados de la tabla correspondiente supone una seleccin bsica con los ms utilizados. Para una lista exhaustiva y detallada, acude al manual de Ant, a la seccin Conditions Task.
Atributo Descripcin

property value else

Elemento anidado

Nombre de la propiedad que queremos usar. El valor a establecer en la propiedad si se da la condicin. Defecto: true. El valor a establecer en la propiedad si no se da la condicin. Por defecto, si no se da la condicin, no se establece la propiedad.
Descripcin

Niega mediante un not lgico la condicin que contenga anidada. not Realiza un and lgico entre sus elementos anidados. and Realiza un or lgico entre sus elementos anidados. or Realiza un xor lgico entre sus elementos anidados. xor Idntica a la tarea <available>. available Idntica a la tarea <uptodate>. uptodate NOTA: Todos los dems elementos anidados que pueden usarse dentro de <condition> tienen atributos propios, son ms complejos y menos comnmente usados. Ant pone a disposicin de sus usuarios un completo conjunto de elementos de comprobacin de condiciones. Para ms detalles, como ya se ha mencionado antes, acude al manual de Ant.
Ejemplos:

Comprueba que estn disponibles en el classpath del proyecto las clases DataHandler y Transport, ambas. Y, si es as, establece a true la propiedad javamail.completo. <condition property="javamail.completo"> <and> <available classname="javax.activation.DataHandler"/> <available classname="javax.mail.Transport"/> </and> </condition>

- 42 -

<copy>
Copia un fichero o una coleccin de recursos a un nuevo fichero o directorio. Por defecto, los ficheros slo se copian si los ficheros que quieren copiarse son ms nuevos que los que, en su caso, ya existan. No obstante, podemos elegir sobrescribir siempre los mismos poniendo el atributo overwrite a true. Si queremos copiar un grupo de ficheros, habremos de usar una coleccin de recursos y proporcionar un directorio de destino a travs del atributo todir.
Atributo Descripcin

El archivo a copiar. Da a los archivos copiados la misma fecha de ltima modificacin preservelastmodified que tenan los ficheros originales. tofile El nombre de archivo al que copiar. todir El directorio al que copiar. overwrite Sobrescribir los archivos aunque los de destino sean ms nuevos. Indica si se debera llevar a cabo filtrado de tokens usando los filtering filtros del archivo de construccin global durante la copia. Ignora la estructura de los archivos de origen, y copia todos los flatten archivos al directorio especificado por el atributo todir. Copia los posibles directorios vacos. Por defecto: true. includeEmptyDirs Si es establecida a true, cuando los ficheros de origen o el failonerror directorio de destino no existen, se arroja un aviso, pero el proceso de construccin no se detiene. Por defecto: true. verbose Para que la tarea escriba un mensaje con los ficheros copiados. encoding El sistema de codificacin a usar cuando se filtren los ficheros. outputencoding El sistema de codificacin a usar cuando se escriban los ficheros. Si se establece a true, la tarea procesar todos los mapeados para una ruta fuente dada. Si se establece a false, la tarea slo enablemultiplemappings procesar el primer archivo o directorio. Este atributo es relevante slo si se ha especificado un subelemento mapper. El nmero de milisegundos de margen antes de decidir que un archivo no est actualizado. Este atributo es necesario porque no todos los sistemas de ficheros soportan la comprobacin de la fecha granularity de ltima modificacin al nivel de milisegundos. Por defecto, es 1 segundo, o 2 segundos en sistemas DOS. Este atributo puede ser til si los archivos fuente y destino estn en mquinas distintas con relojes no sincronizados.

file

- 43 -

Elemento anidado

Descripcin

Coleccin de recursos mapper filterset filterchain targetfile env redirector

Ejemplos:

Podemos pasarle a la tarea cualquier coleccin de recursos con la lista de rutas de los recursos a copiar: fileset, filelist, dirset, etc. Un mapper para realizar transformaciones de las rutas de los ficheros copiados. Por defecto, la tarea copy utiliza un identity mapper. Usado para reemplazar tokens en los ficheros copiados. Las cadenas de filtrado son un grupo de filtros de lectura segn un orden. Los usuarios pueden definir las suyas propias. Se procesarn antes de los filtersets definidos. Consulta el manual de Ant para ms informacin. Similar a srcfile, pero marca la colocacin del archivo objetivo. Este elemento slo puede especificarse si se define un mapper anidado. Especifica variables de entorno para pasar al comando en <env> anidados. Redirector de E/S anidado. Permite recibir entrada desde y enviar salida hacia ficheros diferentes para cada archivo fuente a enviar al comando.

Copia un nico fichero: <copy file="fichero.txt" tofile="copia.txt"/> Copia un nico fichero a un directorio: <copy file="fichero.txt" todir="../algun/directorio"/> Copiar un directorio a otro directorio: <copy todir="../directorio/destino"> <fileset dir="directorio/origen"/> </copy> Copia un conjunto de ficheros a un directorio (2 formas distintas de hacerlo): <copy todir="../directorio/destino"> <fileset dir="directorio/origen"> <exclude name="**/*.java"/> </fileset> </copy> <copy todir="../directorio/destino"> <fileset dir="directorio_origen" excludes="**/*.java"/> </copy> Copia un conjunto de ficheros a un directorio, anexando .bak al nombre de los ficheros: <copy todir="../directorio/backup"> <fileset dir="directorio_fuente"/> <globmapper from="*" to="*.bak"/> </copy>

- 44 -

<delete>
Borra un fichero, un directorio y todos sus subdirectorios, o un conjunto de ficheros dados por una o ms colecciones de recursos. NOTA: Si se usa esta tarea para borrar directorios con archivos temporales y parece que no funciona, hay que tener en cuenta que todas las tareas basadas en directorios tienen una lista de exclusin implcita de archivos por defecto. Si queremos que la tarea <delete> o cualquier otra afecte a todos los ficheros del directorio, habremos de establecer el atributo defaultexcludes a false (por defecto es true). Si, en cambio, lo que nos interesa es definir nuestra propia lista de exclusin, podemos usar la tarea <defaultexcludes> para indicar mediante colecciones anidadas de recursos los ficheros a excluir por defecto.
Atributo Descripcin

El nombre del fichero a borrar, dado como una ruta absoluta o relativa. El directorio que deseamos borrar, incluyendo sus subdirectorios. Si se pone a true, se nos muestran los nombres de los archivos borrados. Modo silencioso. Si el archivo o directorio especificado no existe o no es posible borrarlo, Ant no muestra ningn mensaje de diagnstico (a no ser que se haya lanzado con las opciones -verbose o -debug), ni modifica el quiet status de la salida para reflejar un error. Esta configuracin emula a la opcin f del comando rm de UNIX. Activar esta opcin, implica poner el atributo failonerror a false. Por defecto: false. Controla si un error (como, por ejemplo, un fallo al intentar borrar un failonerror fichero) detiene el proceso de construccin, o si simplemente sale en el log del proyecto sin ms. Slo es relevante si quiet es false. Defecto: true. includeemptydirs Indica si hay que borrar los directorios vacos cuando se usan filesets. defaultexcludes Indica si hay que usar o no la lista por defecto de exclusin de archivos. Indica si usar el mtodo deleteOnExit() de la clase File si hay un fallo deleteonexit al intentar borrar un fichero. Esto provoca que la mquina virtual Java intente borrar el fichero cuando su proceso est terminando. Defecto: false.
Elemento anidado Descripcin

file dir verbose

Coleccin de Podemos pasarle a la tarea cualquier coleccin de recursos (fileset, recursos filelist, dirset, etc) para especificar archivos a incluir o excluir. Podemos usar esta tarea con colecciones anidadas de recursos para defaultexcludes especificar nosotros la lista de exclusin de archivos por defecto.
Ejemplos:

Borrado de un fichero y de un directorio: <delete file="/lib/ant.jar"/> <delete dir="lib"/> Borrado de todos los archivos de extensin .bak del directorio actual: <delete> <fileset dir="." includes="**/*.bak"/> </delete> - 45 -

<ear>
Extensin de la tarea <jar> con opciones especiales que simplifican la creacin de archivos EAR (Enterprise application ARchive).
NOTA: El formato ZIP que varios archivos con la misma ruta puedan existir en un mismo archivo. Esto puede crear problemas en ciertas condiciones, y desconcertar a los desarrolladores que no estn al tanto de ello. Si se desea evitar esto, establezca el atributo duplicate a un valor distinto de add (por defecto). Atributo Descripcin

Nombre del archivo EAR a crear. Descriptor de despliegue a usar (META-INF/application.xml). El directorio desde el cual buscar los ficheros a archivar/empaquetar. Indica si se han de comprimir los datos, adems de empaquetarlos. Por defecto es true. A menos que el atributo keepcompression sea false, compress esta opcin se aplicar al archivo entero, y no slo a los archivos aadidos. Para ficheros existentes, conservar la compresin como estaba inicialmente keepcompression e ignorar el valor del atributo compress. Por defecto: false. Codificacin de caracteres para los nombres de fichero dentro del archivo. encoding Por defecto: UTF-8. IMPORTANTE: No se recomienda cambiar este valor en ningn caso, ya que el archivo dejar de ser legible para Java. Almacena en el archivo slo entradas de ficheros. Por defecto: false. filesonly Lista separada por comas o espacios de patrones de nombres de fichero que includes deben incluirse en el archivo. Por defecto: se incluyen todos los ficheros. Nombre de un fichero que incluye patrones de nombres de ficheros a includesfile incluir. Cada lnea del fichero se toma como un patrn de inclusin. Lista separada por comas o espacios de patrones de nombres de fichero que excludes se excluirn del archivo. Por defecto: se excluyen slo los default excludes. Nombre de un fichero que incluye patrones de nombres de ficheros a excludesfile excluir. Cada lnea del fichero se toma como un patrn de exclusin. defaultexcludes Usar los patrones de exclusin por defecto de Ant. Por defecto: false. manifest Nombre del archivo de manifiesto a usar. Indica si hay que actualizar, o bien sobrescribir (valor a false) el archivo update de destino si este ya existe de antes. Por defecto: false. Indica el comportamiento de la tarea cuando se encuentra un fichero duplicado. Valores vlidos para este atributo son: add (se aade una duplicate entrada adicional - peligroso), preserve, y fail. Por defecto: add. Indica si el tiempo de modificacin de los ficheros ha de redondearse al siguiente nmero par (es decir, un redondeo por arriba). Los archivos ZIP almacenan la fecha de ltima modificacin de sus ficheros con una roundup granularidad de 2 segundos, y a veces se redondear por arriba y otras por abajo. Si se redondea por abajo, el archivo siempre se tomar como desactualizado la siguiente vez que se ejecute la tarea. Por defecto: true. Nivel de compresin: 0 (sin compresin) 9 (mxima compresin). level
Ejemplo:

destfile appxml basedir

<ear destfile="appl.ear" appxml="src/metadata/application.xml"> <fileset dir="build" includes="*.jar,*.war" /> </ear>

- 46 -

<exec>
Ejecuta un comando en el sistema, con un conjunto de ficheros como argumento. No se puede interactuar con el comando; la nica forma en enviar flujo de entrada es a travs de los atributos input e inputstring.
Atributo Descripcin

executable dir dest spawn os osfamily input inputstring output error logError
outputproperty errorproperty resultproperty

append timeout failonerror

failifexecutionfails

newenvironment

vmlauncher
resolveExecutable

searchpath
Elemento anidado

Nombre del comando a ejecutar, sin argumentos. Directorio de trabajo donde el comando debera ejecutarse. Directorio donde esperamos que el comando guarde los ficheros de salida. Atributo slo vlido si se usa un mapeador anidado. Si se omite, Ant interpretar las rutas de salida del mapeador como rutas absolutas. Si el comando debe ejecutarse en una hebra independiente de Ant. Si es as, Ant no podr capturar de la salida del comando, ni estarn activas las propiedades input, output, error y result del proyecto. Por defecto: false. Lista de sistemas operativos en los que el comando puede ser ejecutado. Familia del sistema operativo, tal y como se usa en la condicin <os>. Un archivo desde el que se recoger la entrada estndar hacia el comando. Una cadena que hace de flujo de entrada al comando. Exclusivo con input. Fichero al que volcar la salida de la ejecucin del comando. Fichero al que volcar la salida de error de la ejecucin del comando. Atributo para poder ver la salida de error del comando por el log de Ant. La propiedad en la que volcar la salida del comando. Alternativa al fichero. La propiedad en la que volcar el error del comando. Alternativa al fichero. La propiedad en la que se almacenar el cdigo de retorno del comando. Indica si se sobrescriben (valor a false) o anexan las salidas de ejecucin de los comandos a los ficheros de salida y error. Por defecto: false. Detiene el comando si no termina en un periodo de tiempo (dado en mseg). Detiene Ant si el comando devuelve un cdigo != 0. Por defecto: false. Detiene Ant si no puede ejecutarse el comando. Por defecto: true. No propagar las variables de entorno anteriores entorno cuando se especifican nuevas variables de entorno. Por defecto: false. Ejecuta el comando usando las facilidades de la JVM cuando sea posible. Cuando este atributo es true, el nombre del ejecutable se resuelve de inicio en el basedir del proyecto y luego en el de ejecucin del comando. Indica si se deben usar las variables de entorno del sistema a la hora de resolver la ruta del ejecutable. Por defecto: false.
Descripcin

arg env redirector

Ejemplos:

Argumento de lnea de comandos para pasar al comando. Especifica variables de entorno para pasar al comando en <env> anidados. Redirector de E/S anidado. Consulte la documentacin para ms detalles.

Abre en el navegador Firefox la pgina inicial del manual de Ant: <exec executable="C:\Firefox\firefox.exe" spawn="true"> <arg value="${ant.home}/ant/docs/manual/index.html"/> </exec> - 47 -

<jar>
Empaqueta una serie de ficheros en un archivo JAR (Java ARchive). Por defecto, se usa el directorio base del proyecto como raz de los ficheros a incluir en el archivo de empaquetado. No se almacenarn los permisos de los archivos en el JAR. Si no se proporciona ningn archivo de manifiesto, Ant generar uno bsico.
NOTA: El formato ZIP que varios archivos con la misma ruta puedan existir en un mismo archivo. Esto puede crear problemas en ciertas condiciones, y desconcertar a los desarrolladores que no estn al tanto de ello. Si se desea evitar esto, establezca el atributo duplicate a un valor distinto de add (por defecto). Atributo Descripcin

destfile basedir compress

keepcompression

encoding filesonly includes includesfile excludes excludesfile

defaultexcludes

manifest
filtersetmanifest

update
whenmanifestonly

duplicate index

Nombre del archivo JAR a crear. El directorio desde el cual buscar los ficheros a archivar/empaquetar. Indica si se han de comprimir los datos, adems de empaquetarlos. Por defecto es true. A menos que el atributo keepcompression sea false, esta opcin se aplicar al archivo entero, y no slo a los archivos aadidos. Para ficheros existentes, conservar la compresin como estaba inicialmente e ignorar el valor del atributo compress. Por defecto: false. Codificacin de caracteres para los nombres de fichero dentro del archivo. Por defecto: UTF-8. IMPORTANTE: No se recomienda cambiar este valor en ningn caso, ya que el archivo dejar de ser legible para Java. Almacena en el archivo slo entradas de ficheros. Por defecto: false. Lista separada por comas o espacios de patrones de nombres de fichero que deben incluirse en el archivo. Por defecto: se incluyen todos los ficheros. Nombre de un fichero que incluye patrones de nombres de ficheros a incluir. Cada lnea del fichero se toma como un patrn de inclusin. Lista separada por comas o espacios de patrones de nombres de fichero que se excluirn del archivo. Por defecto: se excluyen slo los default excludes. Nombre de un fichero que incluye patrones de nombres de ficheros a excluir. Cada lnea del fichero se toma como un patrn de exclusin. Indica si se han de usar o no los patrones de exclusin de nombres de fichero por defecto de Ant a la hora del empaquetado. Por defecto: false. Nombre del archivo de manifiesto a usar. Comportamiento si se encuentran archivos de manifiesto adicionales en colecciones zipfileset o zipgroupfileset. Valores vlidos: skip (saltrselos), merge (mezclarlos) o mergewithoutmain (mezclarlos ignorando la seccin Main-Class). Por defecto: skip. Indica si hay que actualizar, o bien sobrescribir (valor a false) el archivo de destino si este ya existe de antes. Por defecto: false. Indica qu hacer si no hay ficheros que incluir en el JAR. Valores vlidos: fail (detiene Ant), skip (no se crea ningn JAR), y create (crea el JAR vaco slo con el manifiesto dentro). Por defecto: create. Indica el comportamiento de la tarea cuando se encuentra un fichero duplicado. Valores vlidos para este atributo son: add (se aade una entrada adicional - peligroso), preserve, y fail. Por defecto: add. Indica si la tarea debe crear un ndice para acelerar la carga de clases. Esta es una caracterstica especfica del JDK v1.3+. A menos que se especifiquen - 48 -

manifestencoding

roundup

level
Elemento anidado

archivos jar con elementos indexjars anidados, en el ndice slo se incluirn los ficheros del jar actual. Por defecto: false. La codificacin de caracteres usada para leer el manifiesto JAR, cuando se especifica un archivo de manifiesto externo. Indica si el tiempo de modificacin de los ficheros ha de redondearse al siguiente nmero par (es decir, un redondeo por arriba). Los archivos ZIP almacenan la fecha de ltima modificacin de sus ficheros con una granularidad de 2 segundos, y a veces se redondear por arriba y otras por abajo. Si se redondea por abajo, el archivo siempre se tomar como desactualizado la siguiente vez que se ejecute la tarea. Por defecto: true. Nivel de compresin: 0 (sin compresin) 9 (mxima compresin).
Descripcin

metainf manifest

indexjars service
Ejemplos:

Especifica un fileset con todos los ficheros que han de incluirse en el directorio META-INF del archivo JAR. Este elemento es una tarea <manifest> anidada que permite crear desde el archivo de construccin un manifiesto a medida. Este elemento especifica una estructura de rutas en las que se encuentran ficheros JAR a los que se les construirn ndices. Este elemento slo se tiene en cuenta si el atributo index se estableci a true. Esta tarea no crear entradas de ndice para archivos vacos o que slo contengan ficheros en el directorio META-INF. Especifica un servicio. Consulte la documentacin de Ant para ms detalles.

Empaquetar los ficheros de ${build}/classes en el archivo aplicacion.jar: <jar destfile="aplicacion.jar" basedir="${build}/classes"/> Empaquetar los ficheros de ${build}/classes a un archivo aplicacion.jar. Slo se empaquetan los ficheros bajo el directorio paquete/test, excluyendo los ficheros (en cualquier subdirectorio a partir de esa raz) que se llamen Test.class: <jar destfile="aplicacion.jar" basedir="${build}/classes" includes="paquete/test/**" excludes="**/Test.class" /> Creacin de un archivo JAR especificando un servicio con dos implementaciones distintas del interfaz de scripting de la versin 6 del JDK: <jar jarfile="scriptImplementaciones.jar"> <fileset dir="classes"/> <service type="javax.script.ScriptEngineFactory"> <provider classname="es.forman.script.LenguajeScriptA"/> <provider classname="es.forman.script.LenguajeScriptB"/> </service> </jar> - 49 -

<java>
Ejecuta una clase en la mquina virtual de Java actual (la de Ant) o en otra aparte si se establece el atributo fork a true.
Atributo Descripcin

Nombre de la clase a ejecutar. Localizacin del archivo JAR que queremos ejecutar (por supuesto, debe tener una entrada Main-Class vlida en el manifiesto). El atributo fork jar debe estar establecido a true para ejecutar un archivo JAR. classpath El classpath a utilizar. classpathref El classpath, dado como referencia a un <path> definido en el proyecto. Ejecuta la clase en otra instancia de la mquina virtual Java distinta fork (independiente) a la de Ant. Por defecto: false. Permite que un proceso contine vivo despus de que Ant termine. Requiere que fork est a true, y no es compatible con los atributos spawn input, output, error y result (estarn desactivados por defecto). El comando usado para invocar la mquina virtual Java, por defecto es java. El comando se resuelve usando java.lang.Runtime.exec(). jvm Se ignora si fork est desactivado. Mxima cantidad de memoria que puede reservar la mquina virtual maxmemory separada. Se ignora si fork est desactivado. Detiene el proceso de construccin si el comando termina con un cdigo de failonerror retorno distinto de 0. Por defecto: false. El nombre de una propiedad en la que guardar el cdigo de retorno. Slo es resultproperty de inters si failonerror es false y fork es true. Directorio en el que invocar la mquina virtual. Ignorado si fork es false. dir Fichero al que volcar la salida. Si la salida de error no es redirigida tambin output a algn fichero o propiedad, saldr por esta salida. error Fichero al que volcar la salida de error. Este atributo se usa si se desea ver la salida de error en el registro de Ant y logError se est redirigiendo la salida a algn archivo o propiedad. Indica si los ficheros de salida y error deberan ser anexados o sobrescritos. append Defecto: false, as que los ficheros se sobrescribirn en cada ejecucin. El nombre de la propiedad en la que almacenar la salida del comando. Si outputproperty no se redirige la salida de error, esta propiedad incluir la salida de error. errorproperty El nombre de una propiedad a la que volcar la salida de error. Un archivo desde el cual el comando coger su entrada estndar. Este input atributo es mutuamente exclusivo con el atributo inputstring. Una cadena que sirve como flujo de entrada para el comando a ejecutar. inputstring Este atributo es mutuamente exclusivo con el atributo input. No propaga el nuevo entorno cuando se especifican nuevas variables de newenvironment entorno. Se ignora si fork es false. Por defecto: false. Detiene el comando si no termina en tiempo especificado (dado en mseg). timeout Se recomienda usar esta opcin si y slo si fork est activado. Si est a true, todas las propiedades de sistema y el classpath de arranque (bootclasspath) de la mquina virtual separada sern las mismas que las de clonevm la MV de Ant. Se ignora si fork est desactivado. Por defecto: false.

classname

- 50 -

Elemento anidado

Descripcin

Pueden usarse elementos anidados <arg> y <jvmarg> para especificar argumentos para la clase y la mquina virtual separada respectivamente. Especifica propiedades de sistema requeridos por la clase. syspropertyset Especifica un conjunto de propiedades de sistema. classpath Un conjunto de rutas o archivos que formen el classpath de la aplicacin. Conjunto de rutas y archivos que forman el classpath de arranque del bootclasspath comando a ejecutar. Se ignora si fork no es true. Especifica variables de entorno para pasar a la mquina virtual separada. env Consulta la tarea exec en el manual de Ant para ms detalles. Permite conceder y revocar permisos durante la ejecucin de una clase. permissions Para ms informacin, consulta el apartado Permissions del manual. assertions Controla la activacin o no de las aserciones de Java 1.4. Para especificar un redireccionador de E/S. redirector Para ms informacin sobre este atributo, consulta el manual de Ant. NOTA: Por defecto, se ignora el cdigo de retorno de una tarea <java>. No obstante, se puede guardar dicho cdigo en una propiedad usando el atributo resultproperty. Cuando se establece failonerror a true, el nico valor posible para resultproperty es 0. Cualquier otra respuesta se considerar un error y se interrumpir la construccin. De forma anloga, si failonerror=false y fork=false, tambin la propia tarea <java> debe devolver 0, o se interrumpir el proceso de construccin.
Ejemplos:

arg jvmarg sysproperty

Ejecucin de una clase en la mquina virtual de Ant con un classpath que incluye un JAR: <java classname="aplicacion.Main"> <arg value="-h"/> <classpath> <pathelement location="./lib/libreria.jar"/> <pathelement path="${java.classpath}"/> </classpath> </java> Ejecuta aplicacion.jar en una mquina virtual separada (con fork a true, como se requiere para ejecutar archivos JAR) con un mximo de 128MB de memoria. Al especificar failonerror a true, un cdigo de retorno distinto de 0 interrumpe la construccin. <java jar="aplicacion.jar" fork="true" failonerror="true" maxmemory="128m" > <arg value="-h"/> <classpath> <pathelement location="aplicacion.jar"/> <pathelement path="${java.classpath}"/> </classpath> </java> - 51 -

<javac>
Compila un rbol de directorios de cdigo fuente Java. Escanea recursivamente un directorio en busca de cdigo fuente Java. Se deben de seguir las convenciones genricas de Java en cuanto a la colocacin de los archivos de la aplicacin, mapeando la jerarqua del paquete como directorios en el disco. Se pueden incluir y excluir explcitamente ficheros para refinar el conjunto de archivos que deben compilarse, usando los atributos includes, includesfile, excludes y excludesfile. En ambos casos, la lista de archivos puede especificarse como rutas relativas al atributo srcdir o con elementos anidados <src>. Esta tarea puede usarse con diversos compiladores Java (hay muchas alternativas), estableciendo la propiedad global build.properties (con lo cual se afectar a todas las tareas <javac> de un proyecto) o el atributo compiler de una tarea <javac> concreta. Los valores vlidos para estas propiedades son los siguientes:
Valor Descripcin

classic javac1.1 javac1.2

modern javac1.3 javac1.4 javac1.5 javac1.6

jikes gcj jvc microsoft kcj sj symantec extJavac

Con todos estos valores, se usar el compilador estndar del JDK v1.1/v1.2 de Sun Microsystems. Cualquiera de los tres valores es vlido. classic es el valor ms habitual, pero javac1.1 y javac1.2 son alias vlidos. Todos estos valores sirven para usar el compilador estndar moderno del JDK de las ltimas versiones v1.3 / v1.4 / v1.5 / v1.6 de Sun Microsystems, con soporte para las ltimas y ms modernas caractersticas del lenguaje Java en el cdigo fuente. Los otros valores son alias alternativos a modern. Compilador open-source Jikes. Una opcin a tener en cuenta. Compilador gcj, parte del proyecto GCC (GNU Compiler Collection). Compilador de lnea de comandos del JDK de Microsoft para Visual J++. Puede usarse microsoft como alias para especificar este compilador. Compilador kopi, que pas a formar parte del proyecto open-source Kaffe. Compilador Java propietario de Symantec, el Symantec JIT, que formaba parte del IDE Visual Caf, y que finalmente fue incorporado a JBuilder. Ejecuta el compilador oficial de Sun en una mquina virtual propia.

NOTA: En Windows, cuando el compilador moderno se usa en modo no separado (es decir, con fork a false), bloquea los ficheros de classpath de la tarea <javac> y no los libera. El efecto lateral que provoca este comportamiento es que no se podrn borrar o mover dichos archivos despus de ejecutar la tarea <javac>, y no se liberarn hasta que haya terminado completamente el proceso de construccin, cuando Ant haya terminado. El atajo para esquivar este problema es simplemente ejecutar la tarea de compilacin en una mquina virtual separada (con fork a true). La tarea <javac>, como puede suponer el lector, es una de las ms importantes y trascendentales de Ant, dada su importancia con respecto al proceso de construccin. Por eso, aqu se le dedican varias pginas a describir con relativo detalle todas sus principales caractersticas. No obstante, por supuesto, se insta al lector a consultar profusamente toda la documentacin recogida en el apartado dedicado a esta importante tarea en el manual oficial de Ant.

- 52 -

Atributo

Descripcin

- 53 -

Localizacin de los ficheros de cdigo fuente Java a compilar. Directorio donde almacenar las clases resultantes de la compilacin. Lista de ficheros (separados por comas o espacios) a compilar. Pueden includes usarse patrones. Por defecto, se incluirn todos los ficheros **.java. El nombre de un fichero que contiene una lista de ficheros a incluir. includesfile Tambin pueden incluirse patrones de rutas en este fichero. Lista de ficheros (separados por comas o espacios) a excluir del proceso de excludes compilacin. Pueden usarse patrones. Por defecto, no se excluir ningn fichero, salvo los archivos de exclusin por defecto de Ant. El nombre de un fichero que contiene una lista de ficheros a excluir. excludesfile Tambin pueden incluirse patrones de rutas en este fichero. classpath El classpath a utilizar en la compilacin. La ruta raz a usar en la compilacin. Por defecto, ser el valor dado por el atributo srcdir, o elementos anidados <src>. Si en algn momento se sourcepath quiere suprimir la opcin sourcepath, se puede hacer sourcepath=. bootclasspath Localizacin de las clases de arranque (bootstrap). classpathref El classpath a utilizar, como referencia a un elemento <path> ya definido. sourcepathref El sourcepath a usar, como referencia a un elemento <path> ya definido. bootclasspathref El bootclasspath, dado como referencia a un elemento <path> ya definido. extdirs Localizacin de las extensiones instaladas. Codificacin de caracteres de los ficheros fuente. encoding NOTA: el compilador gcj an no soporta esta opcin. Indica si hay que pasar la opcin nowarn al compilador. Defecto: off. nowarn Indica si el compilador generar informacin de depuracin. Defecto: off. debug Cadena clave a pasar junto a la opcin de depuracin (-g) que indica el nivel de informacin de depuracin que se quiere recibir. Actualmente, esta opcin est soportada por el compilador oficial de Sun, a partir de la versin 1.2, as como por jikes. Los compiladores que no implementen esta opcin la ignorarn. Valores vlidos son: none, o una lista separada por debuglevel comas de las claves lines, vars y source. Si se especifica el uso de salida de depuracin con debug a on, pero no se especifica nada en el debuglevel, no se le anexar ninguna cadena al g. Por supuesto, si el atributo debug no est activado, este atributo es ignorado. Indica si el compilador deber aplicar tcnicas de optimizacin al cdigo fuente que genera. Por defecto: off. NOTA: Esta opcin es ignorada por el optimize compilador de Sun a partir de la versin 1.3, ya que se hizo innecesaria la optimizacin en tiempo de compilacin. Indica si el compilador debera arrojar informacin sobre la antigedad o deprecation la condicin de obsoletos de ciertas clases o mtodos. Por defecto: off. Genera archivos de clase con bytecode para una versin especfica de la mquina virtual Java. NOTA: el valor por defecto depender de la versin de la mquina virtual sobre la que est ejecutndose Ant. En particular, si se usa un JDK v1.4+, las clases generadas no sern compatibles con una target mquina virtual v1.1, a menos que se establezca este atributo a 1.1 (valor por defecto para el JDK v1.1 a v1.3). Se recomienda encarecidamente especificar esta opcin SIEMPRE. Se puede especificar un valor por defecto para este atributo con la propiedad ant.build.javac.target. Activa una salida ms verbosa en el compilador. Por defecto: no. verbose Activa la traza de dependencias para los compiladores que soporten esta depend opcin (en este caso, classic y jikes). includeAntRuntime Si incluir las libreras de ejecucin de Ant en el classpath. Por defecto: yes. - 54 -

srcdir destdir

includeJavaRuntime

fork executable

memoryInitialSize

memoryMaximumSize

failonerror

source

compiler

listfiles

tempdir

Si incluir las libreras de ejecucin de MVs en el classpath. Por defecto: no. Ejecutar javac usando el compilador del JDK externamente. Defecto: no. Ruta completa del ejecutable al compilador en caso de fork=yes (se ignora si fork=no). Puede usarse para especificar la ruta donde se encuentra alguno de los compiladores alternativos (jikes, gcj, jvc o sj). Por defecto: compilador del JDK en el cual est ejecutndose Ant. Tamao inicial de la memoria de la mquina virtual si javac se ejecuta externamente (se ignora si no es as). Puede especificarse en bytes o usando unidades ms grandes, por ejemplo: 83886080, 81920k o 80m. Por defecto: tamao por defecto asignado por la implementacin de MV. Igual a memoryInitialSize, pero para el tamao mximo de la MV. Si los errores de compilacin detendr la construccin. Por defecto: true. Valor de la opcin de lnea de comandos source; ser ignorado por todas las implementaciones previas a javac1.4 (o modern cuando Ant no est ejecutndose en una mquina virtual v1.3), as como por jikes. Si se usa este atributo con jikes, se debe estar seguro de que dicha versin de jikes soporte la opcin source. Por defecto: no se pasa source al compilador. NOTA: el valor por defecto de este atributo depender de la versin de la mquina virtual en la que est ejecutndose Ant. Se recomienda encarecidamente especificar esta opcin SIEMPRE. Se puede especificar un valor por defecto para este atributo a travs de la propiedad ant.build.javac.source. El compilador a usar. Si no se especifica valor para este atributo, por defecto se usar el valor de la propiedad build.compiler, si est establecida, o, si no es as, el compilador por defecto de la mquina virtual actual. La lista de valores vlidos es la que se menciona en la tabla anterior. Si han de listarse por pantalla los nombres de los archivos de cdigo fuente que entren al proceso de compilacin. Puede ser interesante si no estamos seguros de qu ficheros exactamente le llegan al compilador. Defecto: no. Directorio donde Ant debera colocar los archivos temporales. Este atributo slo se usa si la tarea se enva a una mquina virtual separada y, adems, los argumentos de lnea de comandos pasan de 4KB de longitud. Por defecto: directorio dado por la propiedad java.io.tmpdir de Ant.

- 55 -

Elemento anidado

Descripcin

classpath sourcepath bootclasspath extdirs src

Pueden usarse todos elementos anidados (en lugar de atributos) para especificar las rutas de ficheros y/o directorios para estos conceptos. Por tanto, podemos dejar de especificar dichos atributos y establecer los valores de dichos conceptos usando elementos anidados, por otra parte, mucho ms potentes y expresivos (los atributos, por ejemplo, no pueden contener espacios) que los simples atributos de la cabecera de la tarea. A diferencia de los anteriores elementos anidados, <src> no tiene el mismo nombre que el correspondiente atributo de la tarea. El elemento anidado <src> se corresponde con el atributo srcdir de la tarea. Este elemento anidado es la va que proporciona Ant para personalizar las opciones de compilacin para pasarle a compiladores concretos. Se puede especificar un argumento acompaado del compilador para el que sirve.
Atributos Descripcin

compilerarg

value line file path compiler

Un argumento sencillo. Puede contener espacios. Una lista de argumentos separada por espacios. El nombre de un fichero. Se pasar su ruta absoluta. Una ruta. Se puede usar ; o : como separador. Ant los convertir a la convencin de la plataforma. El argumento especificado slo se pasa si se trata del compilador que dicta este atributo. As controlamos el no pasarle a los compiladores comandos irreconocibles.

Ejemplos:

Compilacin de todos los archivos *.java del directorio dado por la propiedad src. Las clases generadas por la compilacin se guardan en el directorio dado por la propiedad build. Se usa el classpath por defecto. Esta es la forma ms bsica de usar esta tarea. <javac /> Idem al anterior, pero incluyendo el archivo xyz.jar en el classpath y excluyendo de la compilacin todos los archivos de cdigo fuente que terminen en Ejemplo.java. Adems, se pide al compilador que proporcione salida de depuracin. Tambin se especifica que el cdigo fuente est escrito con las capacidades de la versin 1.4 de Java, es decir que, por ejemplo, podemos usar aserciones, pero no clases genricas (la genericidad se introdujo en la v1.5). <javac srcdir="${src}" destdir="${build}" classpath="xyz.jar" debug="on" source="1.4" > <include name="**/*.java"/> <exclude name="**/Ejemplo.java"/> srcdir="${src}" destdir="${build}"

</javac>

- 56 -

<javadoc>
Genera documentacin del cdigo fuente usando la herramienta javatool. Escanea recursivamente un directorio en busca de cdigo fuente Java que encaje con los patrones de inclusin y que no lo haga con los de exclusin. Esta tarea no controla cuales son los archivos cambiados desde la ltima compilacin, as que siempre generar la documentacin de todas las clases. NOTA: la tarea <javadoc> llama a System.exit(), por lo que no puede ser ejecutada en la misma mquina virtual que Ant sin interferir su ejecucin. Por tanto, esta tarea se ejecuta siempre en una mquina virtual separada.
Atributo Descripcin

sourcepath sourcepathref sourcefiles destdir maxmemory

packagenames

packageList classpath bootclasspath classpathref

bootclasspathref

extdirs overview access public protected package private old verbose locale encoding version use author splitindex windowtitle doctitle header footer

Especifica la ruta de los archivos de cdigo fuente. Ruta del cdigo fuente, dada como una referencia a un elemento <path>. Lista de archivos de cdigo fuente separados por comas. Para especificar archivos sueltos a compilar puede usarse el elemento anidado <source>. Directorio de destino para los ficheros generados. Mxima memoria reservable para la mquina virtual de javadoc. Lista de paquetes separados por comas (terminando en *). Para especificar nombres de paquetes puede usarse el elemento anidado <package>. El nombre de un archivo con una lista de los paquetes a incluir. Especifica donde encontrar los archivos de clases para esta tarea. Especifica la ruta de los archivos de clase de arranque (bootclasspath). El classpath a utilizar, como referencia a un elemento <path> ya definido. El bootclasspath, dado como referencia a un elemento <path> definido. Localizacin de las extensiones instaladas. Resumen de la documentacin en un archivo HTML. Modo de acceso: public, protected, package, o private. Por defecto: protected. Muestra en la documentacin slo miembros y clases pblicos. Muestra en la documentacin miembros y clases pblicos o protegidos. Muestra en la documentacin generada miembros y clases de visibilidad pblica, protegida o con una visibilidad de mbito de paquete. Muestra en la documentacin todos los miembros y clases, incluyendo todos aquellos de visibilidad privada. Genera la salida usando el doclet de emulacin del JDK v1.1. Disponible a partir de la versin 1.2 del JDK. Muestra mensajes de salida sobre la actividad de javadoc. Cadena de localizacin a utilizar, por ejemplo: en_US, en_US_WIN, etc. Codificacin de caracteres de los archivos de cdigo fuente. Incluye prrafos @version. Por defecto: true. Crea pginas sobre el uso de paquetes y clases. Incluye prrafos @autor. Por defecto: true. Divide el ndice en un fichero por letra. Por defecto: false. Ttulo de la pgina de ndice que se mostrar en el navegador (texto). Ttulo a incluir en la pgina de ndice (cdigo HTML). Texto a incluir en la cabecera de todas las pginas generadas (HTML). Texto a incluir en el pie de pgina de todas las pginas generadas (HTML). - 57 -

Texto a incluir en la parte de abajo de las pginas generadas (HTML). Enlaza a la salida javadoc de una URL. Ver elemento anidado <link>. Enlaza a documentos en una <url> usando la lista de paquetes de linkoffline <url2>. Separa las URLs con espacios. Vase elemento anidado <link>. Define un grupo de paquetes que han de estar agrupados en la pgina inicial de resumen. Vase tambin el elemento anidado <group>. Los argumentos estn separados por comas, y cada argumento son dos group cadenas de caracteres separadas por un espacio: el primero es el ttulo del grupo y el segundo una lista de paquetes separadas por :. Si se necesita especificar ms de un grupo, o un grupo cuyo ttulo contiene una coma o un espacio, se recomienda usar un elemento anidado <group>. nodeprecated No incluir la informacin de las etiquetas @deprecated. notree No generar la jerarqua de clases. noindex No generar ningn ndice. nohelp No generar ningn enlace de ayuda. nonavbar No generar la barra de navegacin. Generar avisos referidos a la etiqueta @serial. serialwarn helpfile Especifica el archivo de ayuda que queremos usar. stylesheetfile Especifica la hoja de estilo CSS que queremos usar. charset Juego de caracteres para la visualizacin en otras plataformas. docencoding Codificacin de caracteres de los archivos generados. Especifica el archivo de clase que arranca el doclet que queremos usar para doclet generar nuestra documentacin. Vase el elemento anidado <doclet>. Ruta del archivo de clase del doclet que suele especificarse normalmente docletpath en la herramienta javadoc con la opcin doclet. docletpathref Ruta del archivo de clase del doclet, como una referencia a un <path>. Permite aadir parmetros adicionales a la lnea de comandos javadoc. additionalparam til para doclets. Los parmetros que contengan espacios han de ser marcados con &quot; Vase tambin el elemento anidado <param>. Detiene el proceso de construccin si el comando no retorna un 0. failonerror Lista de nombres de paquetes (separados por comas) para los que no excludepackagenames queremos que se genere documentacin. Vase tambin el elemento anidado <excludepackage>. defaultexludes Indica si deberan tenerse en cuenta los patrones de exclusin por defecto. Indica si el nombre del fichero fuente especificado en sourcefiles o como elementos anidados <source> deberan escribirse en un archivo temporal useexternalfile para hacer ms corta la orden de lnea de comandos. Esto tambin se aplica a los nombres de paquetes especificados a travs del atributo packagenames o con elementos anidados <package>. Por defecto: no. Este atributo es necesario para permitir a javadoc para manejar aserciones, presentes a partir de la v1.4 del J2SE. Establece este atributo a source "1.4" con cdigo fuente que se compilara usando javac source 1.4. Esta opcin est disponible desde la versin 1.4 del JDK. Genera hipervnculos a archivos de cdigo fuente. Por defecto: no. linksource Esta opcin est disponible desde la versin 1.4 del JDK. Usa el nuevo algoritmo breakiterator. Por defecto: no. breakiterator Esta opcin est disponible desde la versin 1.4 del JDK. Activa el argumento noqualifier. Valores vlidos: all o una lista de noqualifier nombres de paquetes separados por comas. includenoSi includenosourcepackages est a true, documenta tambin los
sourcepackages

bottom link

- 58 -

executable
Elemento anidado

paquetes que no contienen cdigo fuente Java, slo un package.html. Especifica un ejecutable javadoc concreto que usar en lugar del binario por defecto (el javadoc del JDK en el que est ejecutndose Ant).
Descripcin

Los atributos correspondientes a las rutas de los archivos de cdigo fuente a documentar (sourcepath), las rutas de las clases necesarias para la sourcepath documentacin externa de la aplicacin o las pertenecientes a libreras classpath (classpath), o las clases bsicas de arranque para la mquina virtual bootclasspath (bootclasspath), pueden especificarse tambin de forma ms flexible usando elementos anidados en lugar de sus correspondientes atributos. Un conjunto de directorios, dado por un elemento <dirset>, que se le pasarn a javadoc como nombres de paquetes. Ant supone que el directorio base del packageset apunta a la raz de la jerarqua de paquetes. Los packageset atributos packagenames, excludepackagenames y defaultexcludes no tienen efecto alguno sobre los elementos anidados <packageset>. Todos los archivos indicados en este elemento anidado son enviados a javadoc como archivos de cdigo fuente. Ant automticamente incluye el patrn **/*.java (y **/package.html si includenosourcepackage es true) en este conjunto de ficheros. Este elemento anidado puede usarse fileset para documentar archivos fuente que estn en el paquete por defecto, o si se quiere excluir ciertos ficheros de la documentacin. Los atributos packagenames, excludepackagenames y defaultexcludes no tienen efecto alguno sobre los elementos anidados <packageset>. Un contenedor para colecciones de recursos. Todos los archivos contenidos sourcefiles en dichas colecciones se pasarn a javadoc como archivos de cdigo fuente. Igual a una entrada individual de la lista dada por packagenames. Atributo Descripcin package name Nombre del paquete a incluir (puede ser un *). Igual a una entrada individual de la lista dada por excludepackagenames.
excludepackage
Atributo Descripcin

source doctitle header footer botton link

name Nombre del paquete a excluir (puede ser un *). Igual a una entrada individual de la lista dada por sourcefiles.
Atributo Descripcin

file El archivo de cdigo fuente a documentar. Igual al atributo doctitle, pero puede anidarse texto en su interior. Igual al atributo header, pero con texto anidado en su interior. Igual al atributo footer, pero puede anidarse texto en su interior. Igual al atributo bottom, pero puede anidarse texto en su interior. Crea un enlace a la URL dada de salida de javadoc. Sirve para lo mismo que los atributos link y linkoffline, pero cuentan con la flexibilidad que proporcionan los elementos anidados.
Atributos Descripcin

href offline packageListLoc resolveLink

La URL de la documentacin interna a enlazar. Puede ser una URL absoluta o relativa, o apuntar a un fichero. Indica si este enlace no est disponible online en el momento de generar la documentacin. Directorio que contiene un archivo lista de paquetes para documentacin externa. Es necesario especificar este atributo slo si offline se especific a true. Si el atributo es un nombre de fichero relativo, Ant - 59 -

group

intentar primero localizar el archivo como ruta relativa al directorio base del proyecto, y si encuentra un fichero usa una URL absoluta para el atributo link. De otro modo, se pasar el nombre del fichero sin ms. Rene paquetes en grupos en la pgina de resumen. Cada grupo estar en una tabla. Sirve para lo mismo que el atributo group. No obstante, con elementos anidados se pueden especificar varios grupos. NOTA: los atributos de este elemento anidado son a su vez elementos anidados.
Atributo Descripcin

doclet

title Ttulo del grupo. packages Lista de paquetes del grupo, separados por :. Se utiliza para especificar el doclet que javadoc usar para procesar los archivos de cdigo fuente. Un buen nmero de los argumentos de la tarea <javadoc> son en realidad argumentos para el doclet por defecto. Si alguno de estos atributos es especificado (slo deberan especificarse si pueden ser interpretados por el doclet en uso), se le pasar al doclet por defecto usando precisamente elementos <doclet> anidados. Si el doclet requiere parmetros adicionales, pueden pasarse a travs de elementos anidados <param> (slo se pueden pasar cadenas de caracteres). Ejemplo:
<javadoc ... > <doclet name="elDoclet" path="ruta/hasta/elDoclet"> <param name="-foo" value="valorfoo"/> <param name="-bar" value="valorbar"/> </doclet> </javadoc>

Sirve para especificar tags (etiquetas) personalizados. Esta opcin slo est disponible con la versin 1.4 de Java. Si se quiere especificar una etiqueta estndar usando un elemento anidado para determinar el orden en el que las etiquetas se procesan, no deber establecerse una descripcin para dichos tags.
Atributos Descripcin

name description enabled scope tag

dir

Nombre del tag. Descripcin del tag (por ejemplo: To do:). Si el tag est activado o no. Por defecto: true. mbito para el tag: los elementos en los que puede ser usado el tag. Es una lista de elementos separados por comas de alguno de los siguientes valores: overview, packages, types, constructors, methods, fields, o tambin all. Por defecto: all. Si se especifica este atributo, este elemento se comportar como un <fileset> implcito. Los archivos incluidos en dicho fileset deberan contener cada definicin de un tag en una lnea separada, tal y como se menciona en la gua de referencia de Javadoc: ejb.bean:t:XDoclet EJB Tag todo:a:To Do NOTA1: En la gua de referencia de Javadoc, la descripcin est entre comillas. Esto no funcionar cuando se use desde fichero, ya que la descripcin se pasa entre comillas cuando se enva a javadoc. NOTA2: Si se especifica este atributo, todos los dems atributos de este elemento son ignorados. - 60 -

Este elemento anidado se usa para especificar taglets personalizados. Esta opcin slo est disponible con la versin 1.4 de Java.
Atributo Descripcin

taglet

El nombre de la clase taglet. name Por ejemplo: com.sun.tools.doclets.ToDoTaglet. Una ruta especificando la ruta de la clase taglet, como, por ejemplo, /home/taglets. Esta informacin puede path proporcionarse a travs de un elemento anidado <path>. Especifica argumentos adicionales. Los atributos que se presentan aqu son los atributos habituales que define Ant en su manual en el apartado Command-line Arguments para definir argumentos de lnea de comandos.
Atributo Descripcin

arg

value file path pathref line

Un argumento sencillo. Puede contener espacios. El nombre de un fichero. Se pasar su ruta absoluta. Una ruta. Se puede usar ; o : como separador. Ant los convertir a la convencin de la plataforma. Una ruta, dada como referencia a un elemento <path>. Una lista de argumentos separada por espacios.

Ejemplos:

El siguiente ejemplo es el ms bsico y habitual: genera la documentacin de los archivos a partir de los archivos de cdigo fuente ubicados en el directorio dado por la propiedad dir.fuentes, y almacena la documentacin generada en el directorio dir.javadoc. <javadoc sourcepath="${dir.fuentes}" destdir="${dir.javadoc}"/> El siguiente cdigo usa un buen nmero de atributos. Genera documentacin para una API de pruebas del paquete com.dummy.test.*, excluyendo el subdirectorio doc-files. Despus, configura los ttulos y fondos de las pginas generadas, define un tag todo, un par de grupos de paquetes para el ndice, y enlaces a documentacin externa.
<javadoc windowtitle="API de pruebas" destdir="${dir.javadoc}" author="true" version="true" use="true" > <packageset dir="${dir.fuentes}" defaultexcludes="yes"> <include name="com/dummy/test/**"/> <exclude name="com/dummy/test/doc-files/**"/> </packageset> <doctitle><![CDATA[<h1>Documentacin de la API</h1>]]></doctitle> <bottom><![CDATA[<i>Copyright &#169; 2007 Dummy, Inc.</i>]]></bottom> <tag name="todo" scope="all" description="To do:"/> <group title="Grupo de paquetes 1" packages="com.dummy.test.a*"/> <group title="Grupo de paquetes 2" packages="com.dummy.test.b*:com.dummy.test.c*"/> <link offline="true" href="http://java.sun.com/j2se/1.5.0/docs/api/" packagelistLoc="C:\tmp"/> <link href="http://developer.java.sun.com/developer/products/xml/docs/api/"/> </javadoc>

- 61 -

5.3.- Tareas opcionales.

Las tareas opcionales son aquellas que no estn incluidas en el ncleo de Ant per se, al considerarse fuera de la funcionalidad general o del caso ms habitual de uso para el que est enfocada la herramienta. No obstante, algunas tareas consideradas como opcionales, como por ejemplo <junit> y <junitreport>, nos sern habitualmente muy necesarias. Para poder usar una tarea opcional habremos de consultar las libreras que necesita dicha tarea (si es que las necesita, no siempre es as), que normalmente se mencionarn, si es el caso, en la documentacin oficial. Si la tarea opcional que queremos utilizar necesita de libreras adicionales, hemos de asegurarnos de que estn en un directorio donde Ant pueda encontrarlas, o de que siempre se incluyan en el classpath de nuestro proyecto. Para conocer estas dependencias, el manual de Ant tiene un apartado Library dependencies. Las tareas opcionales son un sper conjunto de tareas, por encima de las bsicas, que la comunidad de desarrollo entorno a la herramienta ha ido creando con el paso del tiempo para acometer y facilitar todo tipo de procesos relacionados con la construccin y el desarrollo de aplicaciones de diversas tecnologas sobre la plataforma Java usando Ant. A continuacin, se incluye un listado completo de las tareas opcionales que proporciona Ant. En este listado no se entra en ningn detalle sobre sus atributos o elementos anidados, ya que excedera el carcter docente a un nivel de completa introduccin de este documento. El lector s podr usar este listado para localizar rpida y fcilmente la tarea Ant que cubre las necesidades de funcionalidad que est buscando. Tras el listado de tareas opcionales, se incluye, como se hizo en el caso de las tareas opcionales, varias pginas dedicadas a las tareas ms importantes y comnmente usadas en los escenarios de desarrollo ms habituales. En este caso, se han considerado de inters trascendental las tareas <junit> y <junitreport>, que, como se ha comentado ya, son totalmente necesarias en la construccin de proyectos bien diseados.

- 62 -

Listado de tareas opcionales (Ant versin 1.7)

Tarea
Tarea

Descripcin
Descripcin

.NET Tasks

antlr cab chgrp chown cc******* ccm***** depend

Compila cdigo fuente C#. Compila cdigo fuente Visual Basic .NET. Compila cdigo fuente J#. Desensambla ejecutables y libreras .NET. wsdltodotnet Genera cdigo .NET (C# o Visual Basic) desde un WSDL. importtypelib Importa una librera de tipo COM a .NET. Invoca el generador de traductores ANTLR sobre un archivo de gramtica. Crea un archivo CAB de Microsoft. Cambia el grupo al que pertenece un fichero o conjunto de ficheros. Actualmente, esta tarea slo tiene efecto en sistemas UNIX. Cambia los permisos de un fichero o grupo de ficheros dentro de los directorios especificados. Los permisos se establecen siguiendo el estilo habitual de UNIX. Actualmente, slo tiene efecto en sistemas UNIX. Tarea que puede realizar acciones de la herramienta ClearCase: cccheckin, cccheckout, ccuncheckout, etc Consulta el manual para ms detalles. Tarea que puede realizar acciones de la herramienta Synergy, antigua Continuus: ccmcheckin, etc Consulta el manual de Ant para ms detalles. Determina qu archivos de clase estn desactualizados con respecto a su cdigo fuente, eliminando los archivos de clase que dependan de cualquier clase desactualizada y forzando su recompilacin. Usada junto a <javac>.
Tarea Descripcin

csc vbc jsharpc ildasm

blgclient ddcreator iplanet-ejbc EJB Tasks

Borland Application Server versin 4 y 5 Weblogic 4.5.1 iPlanet Application Server 6.0
Elemento anidado Descripcin

ejbjar

borland iPlanet jboss jonas weblogic websphere

Borland Application Server versin 4 y 5 iPlanet Application Server 6.0 JBoss JOnAS 2.4.x y 2.5 Weblogic 5.1 a 7.0 IBM WebSphere 4.0

wlrun Weblogic 4.5.1 a 7.0 wlstop Weblogic 4.5.1 a 7.0 echoproperties Lista las propiedades actuales del proyecto. Implementa un cliente FTP bsico que puede enviar, recibir, listar y borrar ftp ficheros y directorios en un servidor FTP remoto. image Aplica transformaciones de imagen (rotar, etc) a un conjunto de ficheros. Comprueba si una extensin est presente en un fileset o en un jarlib-available extensionset. Si est presente, establece una propiedad dada. Muestra la informacin contenida en los atributos Optional Package y jarlib-display Package Specification de los archivos JAR especificados. Tarea para generar un manifiesto que declara todas sus dependencias. Las jarlib-manifest dependencias se determinan viendo si hay especificaciones Extension o Optional Package en los manifiestos del los archivos JAR de la ruta dada. jarlib-resolve Busca un JAR que satisfaga una extensin, y coloca su ruta en la propiedad. javacc Compila los archivos de cdigo fuente Java especificados. javah Genera cabeceras JNI a partir de una clase Java. Ejecuta el compilador JSP. Puede usarse para precompilar pginas JSP. jspc Luego puede usarse la tarea <javac> para compilar el cdigo Java. - 63 -

Invoca al parser JDepend, que analiza una serie de directorios de cdigo Java y genera mtricas de calidad del diseo para cada clase Java. jjdoc Invoca al generador de documentacin JJDoc para JavaCC. jjtree Invoca el preprocesador JJTree para JavaCC. junit Ejecuta las pruebas del framework JUnit de pruebas de unidad. Mezcla los archivos XML generados individualmente por la tarea <junit> junitreport y genera una salida HTML, aplicndole una hoja de estilo para crear un informe de los resultados de las pruebas visible a travs de un navegador. Convierte ficheros desde su codificacin de caracteres nativa a ASCII usando Unicode. Se usa habitualmente para convertir archivos de cdigo native2ascii fuente mantenidos en una codificacin nativa de sistema operativo a ASCII como paso previo a la compilacin de dicho cdigo. netrexxc Compila un rbol de cdigo fuente NetRexx. Tarea que puede realizar acciones de la herramienta Perforce: p4sync, p4****** p4change, p4edit, p4submit, etc Consulta el manual para ms detalles. propertyfile Crea o modifica archivos de propiedades. Permite al usuario extraer la ltima revisin del cdigo fuente de una pvcs aplicacin desde un repositorio PVCS. Consulta el manual para detalles. replaceregexp Reemplaza una expresin regular por un patrn de sustitucin. rexec Tarea para automatizar una sesin rexec remota. Tarea slo vlida para Unix que invoca al manejador de paquetes rpm. rpm schemavalidate Esta tarea valida archivos XML descritos por un XML Schema. scp Copia ficheros hacia o desde un servidor remoto usando SSH. script Ejecuta un script en un lenguaje que soporte Apache BSF. scriptdef Define una tarea Ant usando un lenguaje script que soporte Apache BSF. Tarea para ejecutar una herramienta de despliegue en caliente para un serverdeploy servidor J2EE de un fabricante especfico. Establece las propiedades del Proxy web de Java, para que las tareas y el setproxy cdigo que estn ejecutndose en la misma mquina virtual Java puedan tener acceso externo a travs del firewall a sitios web remotos. Reproduce un sonido al final del proceso de construccin. El sonido ser sound uno u otro segn la construccin concluya con xito o con un fallo. Tarea que puede realizar acciones de la herramienta SourceOffSite: sosget, sos****** soslabel, soscheckin, etc Consulta el manual de Ant para ms detalles. splash Muestra una pantalla de presentacin momentnea (splash screen). sshexec Ejecuta un comando en un servidor remoto usando SSH. Tarea que puede realizar acciones de la herramienta StarTeam: stcheckin, st******* stcheckuot, stlabel, y stlist. Consulta el manual de Ant para ms detalles. symlink Tarea para administrar los enlaces simblicos en entornos UNIX. telnet Automatiza una sesin remota de Telnet. Identifica claves en ficheros, delimitados por tokens especiales, y los traduce translate a valores ledos desde otros ficheros de recurso (resource bundles). Tarea que puede realizar acciones de la herramienta Visual SourceSafe de vss****** Microsoft: vsscheckin, etc Consulta el manual de Ant para ms detalles. Compila pginas JSP usando el compilador JSP de Weblogic, weblogic.jspc. wljspc Para compilar con un compilador que no sea de Weblogic, usar <jspc>. xmlvalidate Comprueba si ciertos ficheros XML son vlidos (o bien formados). jdepend

- 64 -

Tareas opcionales ms importantes <junit>

Descripcin:

Ejecuta las pruebas del framework JUnit. Esta tarea requiere de una biblioteca externa: junit.jar localizable en el classpath de Ant o del proyecto en construccin.
Atributos: Atributo printsummary Descripcin

Imprime estadsticas para cada caso de prueba. Puede tomar los valores on, off y withOutAndErr. Por defecto: off. fork Ejecuta los tests en una mquina virtual separada. Controla cuantas instancias de la mquina virtual se crean para los tests. Posibles valores: una por cada prueba (perTest), una por lote (perBatch), y una en total (once). Slo las pruebas que tienen las mismas opciones de forkmode filtertrace, haltonerror, haltonfailure, errorproperty y failureproperty pueden compartit una MV. Por defecto: perTest. Detiene el proceso de construccin si un ocurre algn error. Defecto: off. haltonerror errorproperty El nombre de una propiedad que establecer en el evento de un error. Detiene el proceso de construccin si ocurre algn fallo. Los errores haltonfailure tambin se consideran fallos a este efecto. Por defecto: off. failureproperty El nombre de una propiedad a establecer si hay algn fallo en las pruebas. filtertrace Elimina todas las trazas de la pila de Junit y Ant de las trazas de error. Cancela una prueba individual si no termina antes de un cierto tiempo, timeout dado en milisegundos. Se ignora si fork est desactivado. Cantidad mxima de memoria a reservar para la mquina virtual maxmemory independiente. Se ignora si fork est desactivado. El comando usado para invocar a la mquina virtual Java. Por defecto, es jvm java. El nombre y la ruta del comando se resuelve a travs de java.lang.Runtime.exec(). Se ignora si fork est desactivado. dir El directorio en el que invocar la MV. Ignorado si fork est desactivado. No propagar el anterior entorno si se especifican nuevas variables de newenvironment entorno. Ignorado si fork est desactivado. Aadir implcitamente las clases de Ant y la librera JUnit requeridas para includeantruntime ejecutar las pruebas al classpath en modo independiente (usando fork). Enva la salida generada por las pruebas al registro de Ant, as como a los showoutput formatters de salida. Por defecto, slo los formatters reciben la salida. Enva cualquier salida generada por las pruebas a los formatters de las outputformatters pruebas. Por defecto: true. tempdir Directorio donde Ant debera colocar los archivos temporales. Si debera instanciarse un nuevo cargador de clases para cada caso de reloading prueba. Se ignora si fork est desactivado. Por defecto: true. Clona todo el entorno de la mquina virtual de Ant en las MV clonevm independientes. Se ignora si fork est desactivado. Por defecto: false.

- 65 -

Elementos anidados: Elemento anidado Descripcin

classpath test batchtest jvmarg sysproperty

syspropertyset

env
bootclasspath

permissions assertions formatter

Ejemplos:

Representa la ruta en la que buscar las clases que necesita la tarea JUnit. Define una prueba para una clase. Para ms detalles, consulta el manual. Define un lote de clases de prueba. Para ms detalles, consulta el manual. Si fork est activado, podrn pasrsele parmetros adicionales a las nuevas mquinas virtuales a travs de un elemento anidado <jvmarg>. Especifica propiedades de sistema requeridas por la clase. Estarn disponibles para la mquina virtual durante la ejecucin de las pruebas. Pueden especificarse un conjunto de propiedades para usarse como propiedades de sistema con <systempropertyset>. Es posible especificar variables de entorno para pasar a la mquina virtual independiente usando elementos anidados <env>. Para ms detalles, consulte la tarea <exec> en el manual de Ant. La ruta de los archivos de clase. Se ignora si fork est desactivado. Concede o revoca permisos durante la ejecucin de una clase. Se ignora si fork est activado. Para ms detalles, consulte el manual de Ant. Controla la activacin de las aserciones de Java 1.4. Actualmente, las sentencias de asercin se ignoran si fork est desactivado. Los resultados de las pruebas pueden imprimirse en distintos formatos. La salida siempre se enviar a un fichero, a menos que se establezca el atributo usefile a false. El nombre del archivo viene dado por el de la prueba.

Ejecuta la prueba definida en la clase mis.pruebas.ClasePruebas en una mquina virtual independiente. Al final de la prueba, se imprimir una lnea resumiendo los resultados. En el archivo TEST-mis.pruebas.ClasePrueba.txt se generar un informe detallado. El proceso de construccin se interrumpir si alguna prueba falla. <junit printsummary="yes" fork="yes" haltonfailure="yes"> <formatter type="plain"/> <!-- formatter de texto plano --> <test name="mis.pruebas.ClasePrueba"/> </junit> Ejecuta todas las pruebas del directorio dir.clases que incluyen Test en su nombre, mostrando informacin por el registro de Ant y generando informes XML de resultados: <junit printsummary="yes" showoutput="yes" fork="yes" haltonfailure="no" errorProperty="junit.pruebas.fallo" failureProperty="junit.pruebas.fallo"> <classpath refid="classpath.aplicacion"/> <formatter type="xml" /> <!-- generar informes XML --> <batchtest fork="yes" todir="${dir.junit.informes.xml}"> <fileset dir="${dir.clases}"> <include name="**\*Test.class"/> </fileset> </batchtest>

</junit> - 66 -

<junitreport>
Descripcin:

Genera documentacin sobre los resultados de las pruebas efectuadas con la tarea JUnit en formato HTML, de forma que son visibles desde un navegador. <junitreport> mezcla los archivos XML generados individualmente para cada prueba en uno solo y aplica una hoja de estilo al archivo resultante para crear un completo informe de resultados en pginas HTML que puede ser visualizado a travs de cualquier navegador web. Esta tarea necesita el transformador Apache Xalan o Xalan XSLTC. La versin 1.4 del JDK contena el Xalan-J versin 2, mientras que con la versin 1.5 del JDK se incluye una versin del XSLTC. Consulta la documentacin de Ant de esta tarea para ms detalles.
Atributos: Atributo Descripcin

tofile todir

El nombre del archivo XML de agregacin que se crear a partir de los XML de las pruebas individuales previamente generadas por JUnit. El directorio en el que debera guardarse el archivo XML de agregacin.

Elementos anidados: Elemento anidado Descripcin

fileset

El elemento anidado <fileset> sirve para especificar los archivos que la tarea <junitreport> mezclar para generar el archivo XML agregado. Genera un informe HTML basado en el archivo XML de agregacin.
Elemento anidado Descripcin

format styledir

report

todir

Formato del informe generado. Los valores permitidos son frames y noframes. Por defecto: frames. Directorio donde estn definidas las hojas de estilo. Deben llamarse conforme a las siguientes convenciones: - formato frames: junit-frames.xsl - formato noframes: junit-noframes.xsl El directorio de salida de los archivos HTML generados. Pasa parmetros XSL a la hoja de estilo.
Elemento anidado Descripcin

param

name expresin if unless

Nombre del parmetro XSL. Valor textual del parmetro. El parmetro slo se pasar si esta propiedad est establecida. El parmetro se pasar si esta propiedad no est establecida.

- 67 -

Ejemplos:

El siguiente ejemplo generar un archivo XML de agregacin TESTS-TestSuites.xml en el directorio ./informes/xml a partir de los archivos XML individuales con los resultados de cada prueba. Con ese archivo de agregacin, generar el informe por defecto, con frames, en el directorio ./informes/html. <junitreport todir="./informes/xml"> <fileset dir="./informes/xml"> <include name="TEST-*.xml"/> </fileset> <report format="frames" todir="./informes/html"/> </junitreport> El siguiente ejemplo muestra la generacin de informes con parmetros XSL. Se mezclarn todos los archivos XML de las pruebas individuales, situados en ./informes/xml y se generar el habitual archivo XML de agregacin TESTS-TestSuites.xml, que se guardar en el mismo directorio ./informes/xml. Despus, leer la hoja de estilo junit-frames.xsl del directorio .informes/xsl y generar el informe HTML en el directorio ./informes/html. <junitreport todir="./informes/xml"> <fileset dir="./informes/xml"> <include name="TEST-*.xml"/> </fileset> <report todir="./informes/html" styledir="./informes/xsl" format="frames"> <param name="key1" expression="value1"/> <param name="key2" expression="value2"/> </report> </junitreport>

- 68 -

6.- EJEMPLOS.
Tras conocer todos los conceptos bsicos de Ant, su uso, y haber practicado un poco con nuestro primer archivo de construccin, es un buen momento para profundizar ms en la ejercitacin de dichos conocimientos. Para ello, nada mejor que unos cuantos ejemplos de mayor complejidad y que aborden nuevas capacidades. En esta seccin se incluyen algunos ejemplos muy ilustrativos de las tareas ms habituales que normalmente tendremos que disear con Ant para nuestros proyectos. Comenzamos con un ejemplo bsico poco ms elaborado que el que se propona como primer archivo de construccin y se ir ahondando en l y proponiendo variantes con nuevas funcionalidades.

6.1.- Aplicacin HolaMundo bsica.

El ejemplo que se propone en este apartado contiene la funcionalidad bsica ms habitual que se destila normalmente para cualquier proyecto de Ant. Se recomienda usar este ejemplo incluso como plantilla inicial para escribir sobre l proyectos ms elaborados. Puede consultar el archivo de construccin de este ejemplo bsico, con su cdigo completamente comentado para una mayor comprensin de su estructura, en el directorio ejemplos incluido junto a este documento, en el subdirectorio 1-basico.

6.2.- Aplicacin HolaMundo, usando JUnit 4.

En este ejemplo se pone de relevancia como llevar a cabo pruebas de nuestras aplicaciones con Ant usando la nueva API de la versin 4 de JUnit. La versin 4 de este framework de pruebas de unidad introduce las sintaxis de anotaciones para facilitar el proceso de definicin de pruebas, as como nuevas caractersticas que le dan ms potencia y flexibilidad que nunca a nuestras clases de pruebas. Puede consultar el archivo de construccin completo de este ejemplo buscando en el directorio ejemplos incluido junto a este documento, en el subdirectorio 2-junit.

6.3.- Servlet HolaMundo desplegable.

En este ejemplo se pone de manifiesto como usar las tareas war y unwar para simplificar al mximo y facilitarnos todo el proceso de despliegue de nuestros servlets a un servidor de aplicaciones. En este caso, nuestra eleccin ha sido el famoso Apache Tomcat, pero la adaptacin a otro servidor a partir de esta plantilla es inmediata. Puede consultar el archivo de construccin completo de este ejemplo en el directorio ejemplos, dentro del subdirectorio 3-servlet.

- 69 -

7.- RECURSOS ADICIONALES.

En la siguiente seccin se recopilan una serie de referencias a recursos de informacin adicionales sobre las herramientas y tecnologas tratadas en este documento. Siguindolas segn su propio criterio, el lector podr ampliar informacin y conocer en profundidad los conceptos que ms le interesen. Hay que destacar el excelente manual online de Ant, sito en la siguiente URL: http://ant.apache.org/manual/ El manual online de Ant, incluido tambin en la distribucin binaria que puede descargarse desde su pgina oficial, supone la referencia ms completa y actualizada que se puede encontrar actualmente sobre el uso de Ant. Como referencia no tiene rival alguno. No obstante, para una comprensin y manejo rpidos de Ant, el manual no sea la mejor opcin; en ese caso, se recomienda algn tutorial. Para consultar ejemplos complejos, o si se busca un aprendizaje ms guiado de la herramienta, se recomienda acudir a un libro. Adems, en esta seccin se han incluido pginas web con diversos recursos que pueden interesar al lector, como guas, listas de preguntas frecuentes, artculos, etc.

7.1.- Tutoriales.
Hay multitud de tutoriales relacionados con Ant en la red, aunque la mayora estn en ingls. Normalmente, tratan de explicar los conceptos bsicos de Ant en pocas palabras y guiarnos con ejemplos para ir asimilndolo todo de forma ms prctica e intuitiva. Programacin en Java J2SE (Tutorial genrico) [ES] http://www.javahispano.org/cursotext.viewer.action?file=index Excelente coleccin de artculos sobre J2SE, entre los que hay varios sobre Ant [ES] http://www.javahispano.org/articles.list.action?section=1 Primeros pasos con Ant [ES] http://www.chuidiang.com/java/herramientas/ant.php Tutoriales de la pgina web oficial de Ant http://ant.apache.org/manual/tutorials.html Tutoriales de Ant y otras tecnologas Java (Universidad de Birmingham)
http://supportweb.cs.bham.ac.uk/docs/tutorials/docsystem/build/tutorials/tutorialshome.html

Automate your build process using Java and Ant http://www.javaworld.com/javaworld/jw-10-2000/jw-1020-ant.html Generating Ant Buildfile for Eclipse Java project https://eclipse-tutorial.dev.java.net/visual-tutorials/generatingantbuildfile.html Eclipse Ant code templates https://eclipse-tutorial.dev.java.net/visual-tutorials/antcodetemplate.html
First EJB3 Tutorial explaining Ant and showing how to create beans with annotations and JBoss.

http://www.laliluna.de/ejb-3-ant-tutorial-jboss.html - 70 -

7.2.- Pginas web.

En esta seccin encontrar referencias a diversos recursos web y artculos online que pueden resultar interesantes como lectura adicional al contenido de este documento. Tambin se incluyen enlaces a herramientas o tecnologas cuyo uso con Ant podra resultar de inters, as como a pginas web con artculos, consejos y trucos tiles.

Recursos oficiales
Apache Ant http://ant.apache.org Apache Ant manual http://ant.apache.org/manual/ Apache Ant resources http://ant.apache.org/resources.html Apache Ant FAQ http://ant.apache.org/faq.html Apache Ant Wiki http://wiki.apache.org/ant/

Herramientas
Eclipse Ant support
http://help.eclipse.org/help32/topic/org.eclipse.platform.doc.user/concepts/concepts-antsupport.htm

ant4eclipse http://ant4eclipse.sourceforge.net NetBeans Ant debugger module http://ant.netbeans.org/debugger.html JAG- Java Application Generador http://jag.sourceforge.net EJOSA (Enterprise Java Open Source Architecture) J2EE Templates http://www.enhydra.org/ejosa/ IzPack http://www.izforge.com/izpack/ Antigen http://antigen.sourceforge.net

- 71 -

Consejos
Top 15 Ant Best Practices http://www.onjava.com/pub/a/onjava/2003/12/17/ant_bestpractices.html Top Java Tips: Apache Ant http://www.catalysoft.com/articles/TopAntTips.html

Artculos
TheServerSide.com Your Enterprise Java community (excelente pgina) http://www.theserverside.com/discussions/index.tss Ant in anger: using Apache Ant in a production development system http://members.at.infoseek.co.jp/pokopensjant/e/docs/ant_in_anger.html Speeding web development with Apache Ant
http://source.mihelac.org/articles/2006/03/26/speeding-web-development-with-apache-ant

Executing Ant tasks programatically http://myjavablog.blogspot.com/2006/01/executing-ant-tasks-programatically.html Using JavaScript with Ant http://www.sitepen.com/ant/javascript.html How to integrate Subversion, version control software, with Apache Ant
http://blog.taragana.com/index.php/archive/how-to-integrate-subversion-version-control-software-with-apache-ant/

Automatically adding version information into a Java Manifest file with Ant
http://home.subnet.at/peter/2006/04/automatically-adding-version-information-into-a-java-manifest-file-with-ant/

Deployment of CVS-managed applications using Apache Ant http://sis36.berkeley.edu/projects/streek/howto/hydrant-app-deployment.html IDE project system based on Apache Ant
http://www.javalobby.org/forums/thread.jspa?forumID=61&mode=flat&threadID=12166&start=0&msRange=15

Trucos, recetas, etc...

Eclipse & Ant tips http://practicalembeddedjava.com/tools/ant_tips.html Ant Task for parsing JDeveloper 10.1.3 project files: solving the build
http://www.bloggingaboutoracle.org/archives/ant-task-for-parsing-jdeveloper-1013-project-files-solving-the-build

How to run Ant FTP / Telnet / rexec task http://blog.taragana.com/index.php/archive/how-to-run-ant-ftp-telnet-rexec-task/ HOWTO Apache Ant & Tomcat @ Gentoo Linux http://gentoo-wiki.com/HOWTO_Apache_Ant_and_Jakarta_Tomcat

- 72 -

- 73 -

7.3.- Libros.
Ttulo: Autor: Editorial: Fecha: I.S.B.N.: N pginas: Descripcin: Java 2 v5.0. Richardson, Avondolio, Vitale. Anaya Multimedia (Espaa). Junio de 2005. 978-84-415-1855-1. 704. Libro en castellano con una curiosa y bastante original organizacin de sus contenidos. Empieza dando un repaso a las caractersticas de Java v5.0. Despus, comenta tcnicas y herramientas de desarrollo de aplicaciones Java, entre las que prima Ant. Sigue con un captulo sobre patrones de diseo (s, este es de los pocos libros que hablan de diseo), interfaces grficas, manejo de datos con XML, JDBC, JSP, JSTL, interaccin con C/C++ usando JNI, EJB, RMI, CORBA, servicios web, procesos distribuidos con JMS y JMX, un muy extenso captulo sobre seguridad y, para terminar, empaquetado e instalacin de aplicaciones Java. Apache Tomcat 5. Chopra, Bakore, Eaves. Anaya Multimedia (Espaa). Noviembre de 2004. 978-84-415-1780-6. 608. Completsimo libro en castellano que trata todos los aspectos sobre este popular servidor de aplicaciones. Adems, en su apndice C dedica unas pginas a hablar sobre Ant, describiendo su instalacin y explicando todos sus principales conceptos y su uso fundamental. Java 2 v5.0. Felipe Lima Daz. Anaya Multimedia (Espaa). Noviembre de 2005. 978-84-415-1946-6. 496. Otro completsimo libro en castellano que trata un buen nmero de tecnologas. Empieza por dar un repaso a las nuevas caractersticas de la versin 5 de Java, as como sus otros conceptos generales. Despus, da unas buenas nociones bsicas sobre sockets, threads, JDBC, JNI, servlets, JSP, Struts, JUnit, RMI, seguridad en Java, e incluso llega a hablar un poco de EJB. Una gran eleccin como libro de iniciacin. Dedica un captulo entero a Maven, la alternativa ms popular a Ant.

Ttulo: Autores: Editorial: Fecha: I.S.B.N.: N pginas: Descripcin:

Ttulo: Autor: Editorial: Fecha: I.S.B.N.: N pginas: Descripcin:

- 74 -

Ttulo: Autor: Editorial: Fecha: I.S.B.N.: N pginas: Descripcin:

Ant in action. Loughran, Hatcher. Manning publications (EEUU). Mayo de 2007. 978-19-323-9480-1. 672. El libro ms completo y actualizado que puede encontrarse hoy en da sobre Ant. Su inconveniente es que no est en castellano. En realidad es la 2 edicin de un autntico best-seller titulado Java development with Ant, del mismo autor, con un nuevo ttulo. Cubre todas las nuevas posibilidades de la versin 1.7 en mucha profundidad: las antlibs, el desarrollo con EJB 3.0 & J2EE, el despliegue avanzado de aplicaciones usando SmartFrog, validacin de esquemas XML, o la administracin de repositorios con Ivy. Recomendado, por supuesto, a todo aquel que quiera profundizar al mximo en las capacidades de Ant. Ant The definitive guide. Steve Holzner. O'Reilly Media (EEUU). Abril de 2005. 978-05-960-0609-9. 316. Excelente libro de la conocida editorial OReilly. Muy bien estructurado, propone un coherente recorrido de aprendizaje, desde los conceptos ms simples y bsicos de Ant, como propiedades y tareas. El libro es extremadamente prctico, orientado a resultados: ensea los fundamentos necesarios para que el desarrollador novato pueda compilar, empaquetar, desplegar, y probar aplicaciones. Tambin se discute en profundidad las capacidades de integracin de Ant con Subversion para mantenimiento de repositorios de cdigo. Se dedica un captulo a explicar XML, as como el uso de XDoclet y XSLT. Finalmente, se explica el uso de las tareas opcionales, integracin de Ant & Eclipse, y como crear tareas propias. Pro Apache Ant. Matthew Moodie. Apress (EEUU). Noviembre de 2005. 978-15-905-9559-6. 360. Una buena alternativa a los dos primeros ttulos. Estructurado de una manera muy lgica, explica las cosas muy claramente. Empieza con Una introduccin Ant al lector, y posteriormente aborda su instalacin, uso, los tipos de datos de Ant, compilacin, despliegue, documentacin, prueba y ejecucin de aplicaciones con Ant. Despus, dedica un interesante captulo al uso de Ant con proyectos grandes. Finalmente, trata con un reseable detalle la creacin de tareas propias, la extensin de Ant, y termina con una interesante serie de consejos sobre el uso de su API. - 75 -

Ttulo: Autor: Editorial: Fecha: I.S.B.N.: N pginas: Descripcin:

Ttulo: Autor: Editorial: Fecha: I.S.B.N.: N pginas: Descripcin:

8.- FUENTES.
En esta seccin se recogen las fuentes de informacin fundamentales que se han consultado para la elaboracin de este documento. Este grupo de referencias suponen un conjunto de documentacin bsico para conocer los principios ms importantes de la herramienta, pero no necesariamente profundizan en muchos aspectos de la misma. Las referencias de informacin ms completas y actualizadas suele ser la de las pginas web oficiales de las tecnologas tratadas. Para una puesta en marcha rpida, la mejor eleccin es algn tutorial. Si buscamos ejemplos elaborados o un aprendizaje guiado en detalle, normalmente es mejor acudir a un libro. Para aquellos que busquen ms informacin, en la seccin Recursos adicionales se propone una lista mucho ms exhaustiva de fuentes de informacin de varios tipos con los que aprender sobre el ms mnimo detalle acerca del uso y comportamiento de Ant.

Ant
Wikipedia [ES] http://es.wikipedia.org/wiki/Apache_Ant Pgina oficial de Ant http://ant.apache.org Manual oficial de Ant http://ant.apache.org/manual/ Primeros pasos con Ant [ES] http://www.chuidiang.com/java/herramientas/ant.php

Maven
Wikipedia [ES] http://es.wikipedia.org/wiki/Maven Pgina oficial de Maven http://maven.apache.org Primeros pasos con Maven [ES] http://www.chuidiang.com/java/herramientas/maven.php Apache Maven simplifica el proceso de construccin incluso ms que Ant [ES] http://www.programacion.net/java/tutorial/jap_maven/ Descripcin tcnica de Maven [ES] http://metaware-inc.wiki.mailxmail.com/AntMaven Maven magic http://www.theserverside.com/tt/articles/article.tss?l=MavenMagic - 76 -

JAR (Java Archive)

Wikipedia http://en.wikipedia.org/wiki/JAR_(file_format) Java Archive (JAR) files http://java.sun.com/javase/6/docs/technotes/guides/jar/ Packaging Programs in JAR Files http://java.sun.com/docs/books/tutorial/deployment/jar/

Javadoc
Wikipedia http://en.wikipedia.org/wiki/Javadoc Pgina oficial de Javadoc http://java.sun.com/j2se/javadoc/ How to write doc comments for the Javadoc tool http://java.sun.com/j2se/javadoc/writingdoccomments/ Javadoc Technology http://java.sun.com/javase/6/docs/technotes/guides/javadoc/

JUnit
Wikipedia [ES] http://es.wikipedia.org/wiki/JUnit JUnit.org http://www.junit.org JUnit 4 in 10 minutes
http://www.instrumentalservices.com/index.php?option=com_content&task=view&id=45&Itemid=52

An early look at JUnit 4 http://www-128.ibm.com/developerworks/java/library/j-junit4.html

- 77 -

9.- HISTORIAL.
En esta seccin se incluye informacin propia de este mismo documento. Con miras a un futuro mantenimiento y ampliacin del documento, aqu se documentarn los cambios producidos entre las distintas versiones del mismo. Version 1.4 (Martes 20 de Febrero de 2007) Reestructurada la seccin CONCEPTOS BSICOS y aadido un nuevo apartado para hablar de los elementos para especificar rutas: <classpath> y <path>. Adems, se ha revisado la redaccin y el estilo y aadido nuevos ejemplos de cdigo.

Version 1.3 (Lunes 12 de Febrero de 2007) Nueva seccin con las tareas de Ant agrupadas por funcionalidad. La informacin dada en esta nueva seccin nos ser muy valiosa como clarificadora de la divisin de las tareas Ant y como referencia rpida para buscar la tarea que hace una determinada funcionalidad que estamos buscando.

Versin 1.2 (Sbado 10 de Febrero de 2007) Aadidas muchas ms referencias a recursos adicionales online. Tambin se han reestructurado dichas referencias en ms bloques para facilitar su organizacin. Se ampla el nmero de ejemplos con uno adicional que expone el uso de Ant para facilitar el despliegue de nuestros servlets hacia un servidor de aplicaciones.

Versin 1.1 (Lunes 5 de Febrero de 2007) Ampliacin de secciones: ahora se incluyen nuevas secciones dedicadas a explicar conceptos bsicos como referencias y recursos. Se han reorganizado los contenidos, creando una seccin propia dedicada a explicar los CONCEPTOS BSICOS de la herramienta, as como otra dedicada a explicar los fundamentos de EL ARCHIVO DE CONSTRUCCIN. Nueva seccin HISTORIAL para constatar cambios entre versiones del documento.

Versin 1.0 (Mircoles 24 de Enero de 2007) Versin inicial del documento. Se han dividido los contenidos en 7 secciones.

- 78 -