Construyendo aplicaciones con Apache Ant Miguel Ángel Rodríguez Manzano 1.4 (Martes 20 de Febrero de 2007)
Curso: Lugar:
Arquitecto Java en Tecnología J2EE (2006-2007) Forman Centro de formación e innovación de Andalucía Parque Tecnológico de Andalucía C/ Severo Ochoa, 30 29590 Campanillas (Málaga)
1.- INTRODUCCIÓN. 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 genérico de cualquier aplicación: la compilación, construcción (“build ” en inglés) y prueba de aplicaciones software desarrolladas, fundamentalmente, usando el lenguaje de programación Java. Ant es similar en concepto al clásico “make” característico 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 construcción de proyectos de software de aplicaciones Java. La diferencia más notoria entre Ant y make es que Ant usa XML para describir los procesos de construcción y sus dependencias, mientras que make tiene su propio formato para escribir un “makefile”. Apache Ant es un proyecto de la Fundación Apache Software y, por tanto, de código-abierto (“open-source” en inglés) y libre distribución, bajo los términos 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 conversión de un producto de Sun en un proyecto de código-abierto. Este producto, el motor (“ engine”) de implementación de referencia de la especificación JSP/Servlet (que más tarde sería conocido como Apache Tomcat). La herramienta “make”, de código 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 había 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 básicas dadas en un fichero de construcción (“build file”) escrito en XML, que, por defecto, tiene el nombre “ build.xml”. La versión 1.1 de Ant fue oficialmente liberada al público 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 quizás, incluso superar— al propio Tomcat. Para terminar, se dice que su nombre viene de un acrónimo que vendría a significar algo como “ A nother neat tool” (“Otra herramienta guay” en inglés). Así mismo, es una curiosa coincidencia que la palabra “ant” (“hormiga” en inglés) apareciera en el artículo “Recursive make considered harmful” (“El make recursivo considerado peligroso”) de Peter Miller (un artículo que describía los problemas de construcción de la herramienta make que más tarde Ant se propondría resolver) como nombre en algunas estructuras de los proyectos que, a modo de ejemplo, se utilizaban en dicho artículo. -3http://slidepdf.com/reader/full/construyendo-aplicaciones-con-apache-ant
1.3.- ¿Por qué Ant? Una buena pregunta, desde luego. A lo largo de estos últimos años, Ant se ha convertido en uno de los iconos del mundillo open-source Java. Para una inmensa mayoría de los desarrolladores, ya es un hecho común el ver un fichero “build.xml” acompañando a todo proyecto software que se precie… Existen otras herramientas para la compilación y construcción de aplicaciones software basadas en tecnologías 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 consecución de este enorme éxito y para los que Ant fue ideado en un principio es, sin duda alguna, la independencia prácticamente absoluta de la plataforma de desarrollo que, gracias a las tecnologías Java™ y XML, puede ofrecer Ant. Desde que Ant estuvo ya no fue necesario tener que usar confusos makefiles con comandos Unix o disponible, 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 permitía al desarrollador usar su convención favorita y la adaptaba.
Estandarización del proceso de construcción Para la construcción de nuestras aplicaciones ahora sólo 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 fácilmente su comportamiento (a través del archivo de construcción) para adaptarlo a nuestras necesidades.
Sencilla integración con JUnit Además de eso, Ant hace gala de otras características 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 más importantes es la facilidad de Ant para integrar pruebas de unidad JUnit en el proceso de construcción de nuestras aplicaciones. Esto ha provocado el que Ant haya impulsado a muchos desarrolladores a adoptar modelos de desarrollo conducidos según las pruebas (“ test-driven”), o “programación extrema”.
Extensiones: hasta el infinito y más allá ¿Se te quedan cortas las potentes capacidades que te ofrece Ant? ¿Quieres personalizar aún más ciertos procesos para tus proyectos? No hay problema. Ant, proporcionando una API propia sobre la que trabajar, permite la definición de tareas y procesos personalizados al máximo que ponen a disposición de los desarrolladores capacidades extraordinarias. Por nombrar someramente algunas de las más importantes: pruebas JUnit, compilación .NET (existen así como una versión de AntXML, para .NET, llamada NAnt), salida JSP, librerías, EJB, JavaCC, cabeceras C para específica JNI, validación así como facilidades de comunicaciones como FTP, multimedia con imágenes y sonido, o ejecución de todo tipo de comandos y scripts. -4http://slidepdf.com/reader/full/construyendo-aplicaciones-con-apache-ant
2.- INSTALACIÓN. 2.1.- Descarga. Vamos a proceder a instalar Ant en nuestra máquina. Para ello, en primer lugar, acudimos a la página oficial del proyecto, ubicada en la siguiente URL: http://ant.apache.org Acudimos a la sección de descargas de la página 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 versión 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 información básica Scripts para el lanzamiento de la aplicación Contiene librerías jar de Ant, y otras para dependencias Contiene la documentación de Ant (de obligada lectura ;-) Contiene otros archivos (xsl para generar informes, ...)
Los directorios que más habremos de visitar serán normalmente “lib”, para añadir librerías requeridas por ciertas tareas adicionales que queramos usar y que tengas otras librerías no incluidas con la distribución de Ant como dependencia, o, de vez en cuando, el directorio “docs”, cuando necesitemos consultar la documentación del proyecto.
2.3.- Instalación. La instalación de la aplicación 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 prácticamente independiente de la plataforma en que es usado, no usa ninguna estructura de datos de ningún sistema operativo para almacenar datos de configuración propios, salvo algunas variables de entorno que, a continuación, en las siguientes líneas, pasaremos a establecer.
2.4.- Variables de entorno. Ant sólo requiere para su funcionamiento del establecimiento de unas pocas variables de entorno en nuestro sistema operativo, básicamente para localizar la ruta de la herramienta. Son las siguientes: Variable
ANT_HOME PATH JAVA_HOME
Contenido
Ruta donde está instalado Ant. Hay que añadirle 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 más escuetamente, JDK) en nuestro sistema. La variable de entorno PATH es bastante común en muchos sistemas operativos. Se usa para comunicar al sistema operativo en cuestión rutas del disco donde se ubican aplicaciones que queremos que estén alcanzables desde cualquier parte del árbol de directorios del sistema. A continuación, vamos a sugerir como hacer esta mínima configuración para los sistemas operativos más comunes:
Microsoft Windows y OS/2 Encontrándonos en el intérprete de comandos, y asumiendo que tenemos Ant instalado el directorio C:\ant y de el JDK de Java C:\jdk, habremos “set” paraen instanciar las variables entorno de laensiguiente manera: de usar el comando 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
Tener un enlace simbólico o, en este caso, una variable de entorno que apunte a la última versión del JDK hace más fácil las actualizaciones a nuevas versiones del mismo.
3.- CONCEPTOS BÁSICOS. A continuación, vamos a explicar ciertos conceptos básicos que conviene conocer previamente al uso de la herramienta. Estos conceptos básicos, tales como “target ” o “dependencia” pueden resultarte familiares si ya has lidiado con el clásico “make” u otras herramientas de construcción. No obstante, conviene saber cómo están definidas en Ant. Además de esto, Ant añade otros conceptos básicos propios muy importantes, como son las tareas, propiedades, targets, dependencias, referencias, o los recursos.
3.1.- Tareas. Una tarea es una etiqueta XML válida que puede aparecer en el archivo “build.xml”. Una tarea equivale a algún proceso que Ant puede llevar a cabo por nosotros: borrar o renombrar ficheros, comprimirlos, compilar código fuente, ejecutar pruebas, etc, etc… Las tareas Ant (como etiquetas XML del archivo de construcción que son) pueden tener atributos, así como, en su caso, elementos anidados.
atributo1="valor.atributo1" atributo2="valor.atributo2" ... atributoN="valor.atributoN" >
Más adelante, entraremos detalle del funcionamiento de las tareas, enunciando listados de las tareas en de más Ant atendiendo a diversos criterios, y pasaremos a explicar con relativo nivel de detalle las tareas más importantes. Las tareas más básicas y comúnmente usadas, están agrupadas en la documentación de Ant bajo el nombre de “core tasks” (“tareas del núcleo” de la herramienta). Además de estas tareas básicas predefinidas e incluidas con Ant, que forman el corpus primordial de funcionalidades que necesitaremos habitualmente, existen tareas opcionales, “optional tasks”. Para usarlas, normalmente sólo habrá que importar una serie de librerías en los directorios necesarios de Ant. Finalmente, para los más inquietos, Ant también 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 construcción de nuestros proyectos. -7http://slidepdf.com/reader/full/construyendo-aplicaciones-con-apache-ant
3.2.- Propiedades. Las propiedades son una serie de datos guardados, similares a variables, que se definen mediante una etiqueta especial válida en el archivo de construcción: la etiqueta property , aunque también pueden establecerse a través de un fichero externo. Una propiedad tiene un nombre y un valor; el nombre es sensible a mayúsculas y minúsculas. 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:
Para referenciar su valor donde sea necesario, habremos de escribir el nombre de la propiedad entre llaves empezando por un símbolo de dólar: ${nombre.propiedad }
En una propiedad podemos guardar, por ejemplo, el nombre de los directorios por defecto de compilación, valores de entorno, directorio de salida javadoc, etc… Por ejemplo, la siguiente línea define una propiedad src.dir, que mantendría guardada la ruta relativa al proyecto donde encontrar las clases de la aplicación:
Tras esto, cada vez que queramos referenciar el directorio donde se alojan las clases de aplicación, sólo tendremos escribir ${src.dir}. Estode facilita el mantenimiento dellaarchivo de construcción y unaque mayor flexibilidad a la hora afrontar cambios en cualquiera de los procesos de la construcción de la aplicación. Así pues, las propiedades nos ayudan a establecer, controlar y parametrizar la lógica del proceso de construcción. No obstante, no podemos comprobar o comparar el valor de una propiedad, sólo podemos consultar si una propiedad está establecida o no. Para poder comprobar condiciones más complejas, se recomienda crear targets específicos de comprobación, normalmente etiquetados en su nombre con el sufijo “check”. Por ejemplo, la siguiente línea 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 aplicación, y establece la propiedad junit.instalado según proceda:
Finalmente, hay que comentar que las propiedades pueden establecerse en archivos de construcción, pero también a través de un fichero externo con:
En el archivo de propiedades, podemos establecer los valores para algunas propiedades predeterminadas de Ant o establecer las nuestras propias para configurar proceso de construcción para que se ajuste al máximo a nuestras necesidades siendo el además de fácil modificación ante posibles cambios (simplemente editando algunas líneas de un fichero de texto). Un extracto de un fichero build.properties relativamente común en cualquier proyecto podría 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 común definir todo tipo de propiedades entorno a las opciones de compilación del código fuente, empezando incluso por el propio compilador a usar (cada vez es mayor el número de alternativas al compilador de Sun), opciones de compilación, y diversas rutas de directorio, tanto para la localización de ciertas librerías, ficheros fuente o rutas de salida para los productos del proceso de construcción.
3.3.- Targets. Un “target” u objetivo (de construcción) no es más que es un conjunto de tareas referenciadas bajo un nombre representativo, que debería ilustrar el objetivo (nunca mejor dicho) a conseguir al que están enfocada la ejecución de dicho target. La definición habitual de un target tiene el siguiente aspecto general: ... definición del target ...
Normalmente, siguiendo una convención no escrita, los nombres de objetivos más habituales que los desarrolladores suelen escribir para Ant son: Nombre del target
Objetivo por defecto: suele ejecutar todos los demás targets. Procesos varios de inicialización para la construcción. Borra los archivos de bytecode (*.class) de la aplicación. Crea la estructura de directorios apropiada en el disco. Compila el código fuente de la aplicación. Realiza las pruebas internas o JUnit de la aplicación. Empaqueta la aplicación en un Java AR chive. Genera la documentación de nuestra aplicación con javadoc.
Nota, por supuesto, que estos objetivos no están predefinidos en Ant, sino que el desarrollador tiene que escribirlos adecuadamente en el fichero “build.xml” para cada aplicación. Evidentemente, cadarelativamente desarrolladorhabitual, puede llamar a lasutarea convernácula: un nombre a su elección (por poner un ejemplo usando lengua quedando “compile” como “compilar” en castellano, o “kompilieren” en alemán). No obstante, estos nombres aquí enumerados suelen ser los más habituales. Se muestran además como referencia, puesto que nosotros, en mayor o menor medida, siempre vamos a tener que definir targets muy similares a esos. Como mínimo, siempre habremos de definir un target para poder compilar nuestro código fuente, aunque será habitual definir algunos más a poco que nuestro proyecto sea de una cierta envergadura. A veces, pueden aparecer targets con nombres que incluyen un guión como “-init”. Esto suele ser una convención que indica que dicho target no ha de llamarse desde la línea de comandos, sino que es para uso interno del proceso de construcción.
3.4.- Dependencias. Una dependencia es una relación de anterioridad en el tiempo o en secuencia entre los targets. Por la propia naturaleza del proceso de construcción de una aplicación, ciertos pasos, targets u objetivos tienen que ir antes que otros. El ejemplo típico 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 después, puesto que empaquetaremos los archivos de bytecode generados anteriormente y no los actualizados. Es necesario que cualquier herramienta de construcción que defina targets proporcione algún 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: ... definición del target ...
En la expresión anterior tenemos un bloque de definición de un target llamado “compile” (que compilará nuestro código fuente y generará los archivos bytecode *.class), que, para que pueda ser ejecutado, habrán de ejecutarse previamente los targets “junit” (pruebas de unidad JUnit) y “prepare” (creación de la estructura de directorios de salida). El atributo depends de Ant sólo especifica el orden en el que los targets deberían 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 ejecutar dichos targets el orden en el que aparecen en eldependerá atributo de depends (deintenta izquierda a derecha), pero noen necesariamente ocurrirá así. Todo las dependencias concretas que haya establecidas en cada caso particular. Supongamos que tenemos el siguiente ejemplo de targets con dependencias:
name="A"/> name="B" depends="A"/> name="C" depends="B"/> name="D" depends="C,B,A"/>
Si ejecutamos el target D, podría pensarse que, según el orden especificado, el primer encódigo, ejecutarse será el C, del B y eldeA… ¡noeles así! Como podemos ver en eltarget propio C depende deseguido B, y B depende A, Pero, así que primero en ejecutarse es A (que no tiene ninguna dependencia), luego B, C y, finalmente, D. Todos los targets, independientemente de en el número de otros targets en los que aparezcan como dependencia, se ejecutarán una única vez. Es decir, si en el ejemplo anterior se ejecuta el target A, después, al ejecutarse el B, aunque B dependa de A, como A ya se ha ejecutado, no es necesario que A vuelva a ejecutarse.
3.5.- Referencias. A algunos elementos del fichero de construcción 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 código XML que necesitamos usar un número muy grande de veces a lo largo del fichero de construcción. Así pues, las referencias posibilitan la reutilización de código y facilitan un muy rápido mantenimiento de los ficheros de construcción frente a posibles cambios. Sólo hemos de incluir un atributo “id” con el nombre de referencia en la definición y luego referenciarlo usando mismo nombre cuando lo necesitemos a través del atributo “refid”. Por ejemplo, imaginemos que tenemos el siguiente trozo de código:
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 código anterior de la siguiente manera:
3.6.- Rutas. Ant define instrumentos muy convenientes para poder especificar rutas de ficheros o directorios, para que, posteriormente, puedan ser manejados por las demás entidades del archivo de construcción.
Elementos de ruta locales a una tarea En Ant, para definir y agrupar información de rutas que queremos aplicar en la tarea local, se usa el elemento , que tiene dos atributos: location y path, que, a su vez, pueden especificarse alternativamente como atributos del mismo nombre de un elemento anidado . Atributo
Descripción
location
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
path
de especificar rutas predefinidas, en otro caso, debería optarse location por usar . múltiples elementos anidados con atributos
Elemento anidado
Descripción Atributo
pathelement
location path
Descripción
Idéntico al atributo location. Idéntico al atributo path.
Hay que comentar, además, que dentro de la etiqueta pueden colocarse una o más colecciones de recursos (los recursos y colecciones de recursos se explican un pocoestas más colecciones adelante) como elementos anidados parade añadir más rutas. (rutas Evidentemente, habrán de contener recursos un tipo apropiado o ficheros). Dichos recursos se añaden en el orden en que se especifican en el archivo de construcción, aunque colecciones como , , y no tienen especificada una relación de orden. Para más 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:
Este mismo ejemplo puede abreviarse usando el atributo path propio:
Un ejemplo también habitual es el que enumera una lista de archivos de librería:
Elementos de ruta globales Si queremos definir una estructura que contenga rutas de fichero que podamos reutilizar un número indeterminado de veces, usaremos un elemento 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 construcción (sobre todo en el caso de aplicaciones complejas o grandes proyectos) de forma fácil, ordenada, potente y, no menos importante, ágil a la hora de su mantenimiento. Los atributos y elementos anidados de son exactamente los mismos que los de . No obstante, los volvemos a reproducir aquí como referencia: Atributo
Descripción
location
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, debería optarse por usar múltiples elementos anidados con atributos location.
path Elemento anidado
Descripción Atributo
pathelement
location path
Descripción
Idéntico al atributo location. Idéntico al atributo path.
Dentro de la etiqueta , igual que ocurría con , pueden colocarse una o más colecciones de recursos (los recursos y colecciones de recursos se explican un poco más adelante) como elementos anidados para potenciar las facilidades de especificación de rutas. Por supuesto, estas colecciones habrán de contener recursos de un tipo apropiado (rutas o ficheros). Como siempre, dichos recursos se añaden en el orden en que se especifican en el archivo de construcción, aunque colecciones como , , y no tienen especificada una relación de orden. Como veremos más adelante, define una colección de recursos implícita, por tanto, dentro de un elemento pueden anidarse, a su vez, otros elementos . Ejemplos:
Forma habitual de uso del elemento , con y sin elementos anidados:
Definición un formado por una ruta predefinida (que consta de una lista de dos librerías, separas por un punto y coma “;”) y un archivo suelto adicional:
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 implementación 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 versión 1.5.2 de la herramienta, el uso explícito de los mismos es mucho más reciente, de la versión 1.7, así que es posible que no se vean mucho aún en la mayoría de ficheros de construcción, pero su enorme potencial asegura que serán adoptados masivamente por los desarrolladores.
Recurso básico. Todos los demás tipos de recurso derivan de este tipo. Un archivo desde el sistema deun ficheros local. Una URL deaccesible un recurso accesible desde sistema remoto. Una cadena de texto Java del tipo String. Es de sólo lectura. Representa una propiedad de Ant. Representa un recurso Java cargable a través del Java classloader. Representa una entrada de un archivo ZIP. Representa una entrada de un archivo TAR. Da soporte GZip a una colección de recursos anidada en su interior. Da soporte Bzip2 a una colección de recursos anidada en su interior.
Ejemplos:
Así pues, por ejemplo, si queremos definir cierto fichero de nuestra aplicación como un recurso para poder acceder a él en la definición de nuestro fichero de construcción, podríamos hacer:
Otros ejemplos: " classpath="${ruta.librerias}"/>
Con estos recursos básicos tenemos la suficiente funcionalidad para hacer uso de prácticamente cualquier recurso que necesitemos para la construcción de nuestras aplicaciones, pero sólo podemos cargarlos de uno en uno. Imaginemos que necesitamos especificar cientos o miles de recursos; la tarea se haría muy tediosa. Para facilitarnos la vida en ese caso, Ant soporta también colecciones de recursos. - 16 http://slidepdf.com/reader/full/construyendo-aplicaciones-con-apache-ant
Colecciones de recursos Las colecciones de recursos son entidades abstractas que pueden agrupar un número indeterminado de recursos individuales para facilitar su gestión. Algunos de los tipos de datos clásicos de Ant han sido rediseñados para comportarse como colecciones de recursos. Este es el caso de todos los tipos de datos relacionados con conjuntos de ficheros y propiedades: Colección
fileset, dirset, filelist, path y sus derivados tarfileset zipfileset propertyset
Descripción
Colecciones básicas para el manejo de grupos de ficheros. Todas ellas contienen múltiples referencias a recursos de tipo file. Puede contener recursos file o tarentry según la configuración. Puede contener recursos file o zipentry según la configuración. Contiene un conjunto de recursos propertyresource.
Además de estas, se añaden una nueva serie de colecciones predefinidas: Colección
resources files restrict sort first tokens union intersect difference
Descripción
Colección de recursos genérica. Colección de archivos similar a fileset. Filtra una colección de archivos a los que cumplen ciertos criterios. Colección de recursos ordenada según algún criterio. Selecciona los n primeros elementos de la colección anidada. Tokens de cadenas de caracteres (recursos string) recogidos de la colección de recursos anidada. Conjunto unión de colecciones las colecciones de recursos anidadas. Intersección de las 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 más cómoda y potente. Esto facilita el diseño de los archivos de construcción, 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 más cómodo.
Definición de un classpath local a una tarea en la que usamos colecciones de recursos para incluir y excluir ficheros y directorios concretos. El siguiente código construye un elemento classpath que contiene el valor de la propiedad classpath, jar lib seguido declasses una lista ,de todos archivos con extensión directorio todos loslos directorios classes (el patróndel dedirectorio ruta ** encaja, el 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 referenciado.
Ejemplo importante. Definición de un elemento global con un nombre de referencia ruta.base con la ruta básica de búsqueda de clases de la aplicación, que incluye: las rutas guardadas en la propiedad classpath, todos los archivos jar de librería del directorio lib, así como todas las clases alojadas en el directorio classes. Nótese que, a diferencia de los ejemplos de código 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 construcción.
Suponiendo que tenemos definido el ejemplo anterior, podemos referenciar al elemento de nombre “ruta.base” desde dentro incluso de otro :
4.- EL ARCHIVO DE CONSTRUCCIÓN. El archivo de construcción, normalmente llamado “ build.xml”, es el elemento fundamental de información sobre el que se sustenta Ant para guiar el proceso de construcción de nuestra aplicación. En el archivo de construcción el desarrollador puede definir con todo detalle las opciones, funcionalidades, la secuencia y el comportamiento del proceso de construcción. Tras instalar Ant en nuestra máquina, deberemos proceder a escribir nuestro propio fichero de construcción para poder construir nuestra aplicación. En la siguiente sección procederemos a explicar más detalladamente las tareas básicas del mismo. Para cada tarea, describiremos su función, explicaremos sus atributos y mostraremos una serie de ejemplos relevantes para la ocasión.
4.1.- Proyecto . El proyecto es la estructura de mayor alto nivel en la jerarquía de Ant. Todo archivo de construcción “build.xml” ha de tener uno y sólo un proyecto. En esta etiqueta se contendrá información básica para la especificación del proceso de construcción. Veamos: Atributo
Descripción
name
Nombre de nuestro proyecto. Generalmente, el nombre de la aplicación. Directorio base. La ruta del disco raíz del proyecto. Se puede especificar de antemano también 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 más alto nivel.
basedir default
Así pues, si queremos especificar un proyecto para nuestra aplicación, llamada “Formanager” y situada en la ruta “C:\Proyectos\Formanager”, escribiríamos: ... definición del proyecto ...
No obstante, si el archivo “build.xml” va a estar colocado en el mismo directorio base que se indica (lo más habitual), para una mayor generalidad, se recomienda usar “.” (referencia local al directorio actual) como directorio base. Así pues, quedaría: ... definición del proyecto ...
Recordemos que el archivo de construcción es un fichero XML y debe contener en su primera línea la cabecera de todo archivo XML. De ahí la primera línea del ejemplo.
4.2.- Propiedad . Mediante la etiqueta property (en realidad es una tarea, pero es tan básica que hemos preferido explicarla fuera de la sección dedicada a las tareas) podemos guardar información para el control del flujo del proceso de construcción en una propiedad, o un conjunto de propiedades, que se podrán establecer explícitamente desde la propia etiqueta, o bien que se leerán 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 mayúsculas/minúsculas). Una propiedad puede tener valor o no (en cuyo caso se dice que la propiedad “no está establecida”, en inglés “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, además, 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 construcción. así, las propiedades se comportan de una forma más similar a lasde constantes que aVisto las variables. Atributo
Descripción
name value location refid resource file url
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 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 sería “entorno.PATH”, y para acceder a su valor “${entorno.PATH}”. Nótese que se distinguen mayúsculas y minúsculas: es “PATH” y no “Path”. classpath El classpath en el que buscar el recurso. classpathref El classpath dado como referencia a un 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 llamarán “forman.nombrepropiedad”. Viendo esto, podemos darnos cuenta de que hay 6 formas de establecer valores para las propiedades de nuestra aplicación: Proporcionando su nombre (name) y un valor (value). Proporcionando su nombre (name) y una referencia (refid) a otra propiedad. 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 válido. 5) Proporcionando el nombre de un recurso (resource) que contenga el fichero de 1) 2) 3)
6)
propiedades a utilizar. 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 -
Aunque es posible utilizar combinaciones de estas formas, no se recomienda hacerlo. Debería usarse una única forma de establecer cada una de las propiedades, ya que, por ejemplo, podrían producirse errores si las propiedades no se establecen en el orden esperado. El atributo valor de referencias las propiedades puede perfectamente conteneren referencias otras propiedades. Dichas se resolverán en el justo momento que la a propiedad es establecida. Esto también es así para las propiedades cargadas desde fichero.
Propiedades predefinidas Además 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
Descripción
La ruta absoluta del directorio base del proyecto, tal cual se estableció en el atributo basedir de la etiqueta . ant.file La ruta absoluta del fichero de construcción usado. ant.version La versión de Ant. ant.project.name El nombre del proyecto que estamos construyendo, tal cual se estableció en el atributo name de la etiqueta . La versión de la JMV (Máquina Virtual Java) que ha detectado Ant. ant.java.version Actualmente puede contener los valores “1.2”, “1.3”, “1.4” y “1.5”. Directorio raíz de Ant. NOTA: Esta propiedad es establecida por el ant.home script lanzador de Ant, y podría no tener valor en entornos integrados basedir
de desarrollo (o IDEs), como Eclipse o NetBeans, que hagan uso de Ant.
4.3.- Target . Mediante la etiqueta target modelaremos las funcionalidades de los procesos de nuestro fichero de construcción. 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
name depends if unless description
Descripción
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 algún valor) para que este target sea ejecutado. Nombre de una propiedad que no debe estar establecida (es decir, que aún no se le haya dado ningún valor) para que este target sea ejecutado. Breve descripción textual de la función del target.
Así pues, la forma general de un target se parecerá a la siguiente: ... definición del target ...
Si tenemos un target que sólo queremos que se ejecute solamente cuando se den ciertas condiciones, podemos definir targets de comprobación, como mencionábamos en el apartado que dedicamos a las propiedades. Podemos usar la tarea condition para comprobar cierta condición y, en base a ello, establecer o no una propiedad a algún valor. Por ejemplo, si queremos comprobar la existencia de ciertos ficheros antes de ejecutar un target, podríamos definir algo similar a lo siguiente: INFO: Los archivos historial.txt y changelog.txt están presentes.
Como podemos ver, lo que realmente hacemos es crear un target de comprobación del que dependerá el target principal y en el que comprobaremos la condición que nos interesa. Es una buena opción tener un target genérico de comprobación de múltiples propiedades, que, además, sea ejecutado, siempre que sea posible, al principio del flujo de la construcción del proyecto.
4.4.- Nuestro primer archivo de construcción. Después de haber comprendido los conceptos básicos de la herramienta, así como sus tareas más fundamentales, estamos en condiciones ya de ir poniendo en práctica todos nuestros recién adquiridos conocimientos realizando un primer ejemplo de archivo de construcción. Para ello, vamos a ir desarrollando un ejemplo básico de fichero de construcción ambientado en unas condiciones lo más generales posibles, yendo paso a paso, y explicando en detalle cada una de nuestras acciones. 1º) Creamos un archivo de construcción 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 específico de archivos XML. NOTA: si usamos un editor de textos que no codifique el archivo de texto de salida con una codificación Unicode UTF-8 podemos problemas. Ant rechazará, arrojando un error en dicho caso, cualquier archivo que notener pueda leer correctamente. Especialmente problemáticos (estas cosas se dicen por experiencia propia) pueden ser caracteres como las tildes (áéíóú) que puedan contener los comentarios de nuestro archivo de construcción. 2º) Añadimos la cabecera XML básica al archivo.
3º) Definimos nuestro proyecto de construcción: tendrá el nombre (name) de, por ejemplo, “HolaMundo”, su directorio base (basedir) será el mismo en el que está colocado el archivo construcción (por tanto, el directorio o “.”) y su target por defecto será el targetde“todo ”, que ejecutará todos los targetsactual disponibles. ... definición del proyecto ...
4º) Una vez definido nuestro proyecto, seguimos escribiendo ya dentro de su bloque. Definimos las propiedades generales del proyecto. Conviene definir unas cuantas propiedades básicas, según nuestro propio criterio, con (al menos) rutas para la localización de nuestros archivos, así como para guardar los archivos compilados de bytecode, o la ruta de salida de la documentación generada por javadoc, entre otras.
name="dir.fuentes" name="dir.clases" name="dir.jar" name="dir.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.
5º) Vamos definiendo uno por uno todos los targets que vamos a necesitar. Primeramente, definiremos el target por defecto “todo”, que estará vacío y que lo más importante a tener en cuenta es que tendrá en su atributo depends los nombres de todos los demás 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 construcción que han sido especificados en el depends, luego ejecutar el target “todo” (vacío) y terminar.
6º) Definimos el resto de targets. Lo más habitual es definir los targets según el orden lógico en el que van a ejecutarse habitualmente, es decir, si lo primero que se va a hacer generalmente es compilar el código fuente, lo más intuitivo es definir el target “compilar” en primer lugar, y así sucesivamente.
Como podemos ver, el target “compilar” no depende de ningún otro, así que es candidato para ser ejecutado el primero de todos. Además, podemos observar que se ha usado una tarea que aún no hemos visto: . Esta tarea es una de las tareas básicas (“Core tasks”) de Ant, que nos permite compilar un árbol de archivos Java. En el atributo srcdir le indicamos la localización de la raíz de nuestro árbol de archivos de código fuente Java (localización que ya definimos en la propiedad “ dir.fuentes”) y en el atributo destdir le indicamos el directorio raíz al cual copiará los archivos de bytecode generados tras la compilación (esta ruta también la guardamos en la propiedad “dir.clases”). Para más información sobre la tarea , puedes consultar la sección “Tareas básicas” de este mismo documento, o acudir a la documentación oficial de Ant.
El target “empaquetar”, que depende de la ejecución previa de “compilar”, ejecuta una tarea , que se encargará de empaquetar nuestra aplicación 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 serán todos aquellos que se encuentren en el directorio dado por el atributo basedir.
El target “documentar”, que no depende de la ejecución previa de ningún otro para ejecutarse, lleva a cabo una tarea , que se encarga de generar la documentación de nuestra aplicación a partir de su código fuente usando la herramienta javadoc de Sun, proporcionada como parte del JDK (Kit de Desarrollo Java). Para más información sobre dicha herramienta y su uso, acuda a la documentación oficial de Sun Microsystems. 7º) Cerramos el bloque de proyecto y revisamos nuestro código. Una vez que hemos definido todos los targets de nuestro fichero de construcción, ya hemos terminado. Lo único que nos queda por hacer es cerrar el bloque del proyecto con (que es siempre la última línea de cualquier fichero de construcción de Ant) y, después, siempre viene bien revisar nuestro código para repasar lo que estamos haciendo y buscar cualquier errata.
Nuestro primer archivo de construcción: código completo Una vez que hayamos terminado con todos los pasos necesarios para escribir el archivo de construcción, nos habrá quedado algo similar a lo siguiente: build.xml
5.- TAREAS. En la siguiente sección vamos a hablar con relativa profundidad de unas cuantas tareas que podemos usar en Ant para poder sacar adelante los procesos de construcción personalizados de nuestras aplicaciones. Dejaremos fuera de este documento todas aquellas tareas que se salgan de nuestro entorno de trabajo más habitual: el proceso de desarrollo de aplicaciones Java J2SE/J2EE robustas, su documentación, prueba, empaquetado y, finalmente, su despliegue en un servidor de aplicaciones. Las tareas más sencillas se explicarán en detalle. Sin embargo, en las tareas más complejas sólo entraremos en un nivel de detalle suficiente para explicar el uso más general y facilitar la comprensión de las mismas. Obviamente, no tiene sentido referenciar todas las posibilidades de la selección completa de las tareas Ant en este documento, ya que excedería en demasía de su carácter docente y de introducción. Para poder consultar el funcionamiento y uso de todas las tareas de que dispone Ant, con una descripción completa y en detalle, lo mejor es acudir a su excelente manual, a la sección “Ant Tasks” (”Tareas Ant”), donde puede consultarse información tanto de tareas básicas como opcionales. El manual de Ant viene ya incluido de serie con el archivo de distribución de la herramienta, así como también está disponible actualizado en su página web oficial a través de la siguiente dirección: http://ant.apache.org/manual/ Como ya habíamos mencionado anteriormente, una tarea Ant se corresponde en el fichero de construcción con unadeetiqueta XML, que puede tener atributos (llamados parámetros en la terminología Ant) y elementos anidados, que son ciertas etiquetas interiores que nos servirán 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 explicación concisa sobre su función. El aspecto de una tarea habitual con elementos anidados tiene el siguiente aspecto:
Hay que comentar también que hay algunos tipos especiales de tareas con ciertas características, como las tareas que heredan de MatchingTask, y que tienen una serie de atributos adicionales. A continuación, sigue una explicación someras de tareas que, ya sean básicas u opcionales, nos convendrá conocer en nuestro entorno habitual de trabajo y desarrollo. ¡Happy Ant-ing!
5.1.- Tareas según su funcionalidad. Las tareas de Ant pueden reunirse en diversos grupos atendiendo a su funcionalidad. Para disponer de una referencia rápida de las mismas, y facilitar su localización cuando necesitemos consultar si Ant dispone de cierta tarea, aquí sigue una enumeración de todas las tareas de Ant agrupadas según su tipo de funcionalidad. Puedes consultar esta información totalmente actualizada acudiendo también al manual oficial de Ant, en su apartado “Overview of Ant Tasks”, del que esta sección supone una mera traducción y adaptación al castellano. Se ha decidido incluir este apartado del manual casi tal cual porque es una forma muy rápida y clarificadora de comprender la división de las tareas de Ant, y como referencia nos será muy valiosa.
Listado (no exhaustivo) de tareas según su funcionalidad (Ant versión 1.7)
Archive Tasks Tarea
Descripción
bunzip2 bzip2 cab ear gunzip gzip
Descomprime un archivo comprimido con GZip o BZip2. Comprime un archivo usando el algoritmo GZip o BZip2. Crea un archivo CAB de Microsoft. Extensión de la tarea para facilitar la creación de archivos EAR. Descomprime un archivo GZip. Comprime en GZip un conjunto de archivos.
jar manifest rpm signjar tar unjar untar unwar unzip war zip
Empaqueta en JAR un conjunto de archivos. Crea un archivo de manifiesto. Tarea sólo válida 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 extensión de la tarea para facilitar la creación de archivos WAR. Crea un archivo ZIP.
Audit/Coverage Tasks Tarea
jdepend
Descripción
Invoca al parser JDepend, que analiza una serie de directorios de código Java y genera métricas de calidad del diseño para cada clase Java.
Determina qué archivos de clase están desactualizados con respecto a su código fuente, eliminando los archivos de clase que dependan de cualquier clase desactualizada y forzando su recompilación. Usada junto a . Compila los archivos de código fuente Java especificados. Ejecuta el annotation processor tool (apt) y opcionalmente compila el código fuente original, y cualquier código generado. Ejecuta el compilador JSP. Puede usarse para precompilar páginas JSP para una rápida invocación inicial de páginas JSP, el despliegue en un servidor sin toda la JDK instalada, o simplemente comprobación de la sintaxis de las páginas sin desplegarlas. Luego puede usarse la tarea para compilar el código Java. Compila un árbol de código fuente NetRexx. Ejecuta el compilador RMI sobre los ficheros especificados.
wljspc
Compila páginas el compilador de Weblogic, Para compilar conJSP un usando compilador que no seaJSP de Weblogic, usarweblogic.jspc. .
depend javac apt
jspc
Deployment Tasks Tarea
Descripción
serverdeploy Tarea para ejecutar una herramienta de despliegue en caliente para un servidor J2EE de un fabricante específico.
Tarea Documentation Tasks
javadoc
stylebook
Descripción
Genera documentación del proyecto usando la herramienta javadoc. Ejecuta el generador de documentación Apache Stylebook. Al contrario que con la versión de línea de comandos de esta herramienta, todos los tres argumentos son obligatorios para ejecutar esta tarea.
EJB Tasks Tarea
Descripción
blgclient Borland Application Server versión 4 y 5 ddcreator Weblogic 4.5.1 iplanet-ejbc iPlanet Application Server 6.0 Elemento anidado de
wlrun
borland iPlanet jboss j onas w eblogic websphere Weblogic 4.5.1 a 7.0
wlstop
Weblogic 4.5.1 a 7.0
ejbjar
Descripción
Borland Application Server versión 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
Ejecuta Ant con un nuevo archivo de construcción, opcionalmente además 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 construcción, 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 código fuente con un conjunto de archivos de destino. Si cualquiera de los archivos de código fuente es más nuevo que cualquiera de los de destino, todos los de destino son borrados. Ejecuta un comando. Similar a , pero sin conjuntos de ficheros. Ejecuta una clase Java en la máquina virtual Java de Ant o en otra aparte. Una tarea contenedora. Todas las tareas anidadas dentro de ella se ejecutarán en paralelo en su propio thread independiente. Unasecuencia. tarea contenedora. Todas lasagrupar tareas anidadas dentrodedetareas ella se ejecutan en Su principal uso es subconjuntos que han de ejecutarse secuencialmente dentro de la tarea . Suspende la ejecución de Ant por un periodo de tiempo (dado en mseg). Esta tarea es útil cuando la construcción o el despliegue requiere de un intervalo de tiempo entre tareas. Llama a cierto target para todos los subproyectos definidos. Bloquea la ejecución hasta que se cumplan ciertas condiciones. Esta tarea está orientada a sincronizar distintos procesos en paralelo de .
Cambia los permisos y/o atributos de un fichero o ficheros dentro de los directorios especificados. Actualmente, sólo 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 sólo 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, sólo tiene efecto en sistemas UNIX. Cambia el usuario al quesólo pertenece un fichero o conjunto de ficheros. Actualmente, esta tarea tiene efecto en sistemas UNIX. Concatena múltiples 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 más . 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 añadir o eliminar tabuladores, saltos de página, 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 código “diff” a un archivo. - 30 -
Reemplaza las ocurrencias de una cadena de texto por otra en un fichero. Reemplaza una expresión regular por un patrón de sustitución. Sincroniza dos árboles de directorios. Genera un nombre para un archivo temporal y establece una propiedad. Cambia la fecha de modificación de un fichero, creándolo si no existe.
Java2 Extensions Tasks Tarea
Descripción
Comprueba si una extensión está presente en un fileset o en un jarlib-available extensionset. Si está presente, establece una propiedad. Muestra la información 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 jarlib-resolve
los manifiestos archivos JAR. una extensión, y coloca su ruta en la Intenta localizardel unlos JAR que satisfaga propiedad especificada.
Logging Tasks Tarea
record
Descripción
Lanza un listener que graba la salida del proceso de construcción a un fichero. Se permiten varios recorders simultáneos con distintos ficheros.
Mail Tasks Tarea
mail
Descripción
Envía un correo electrónico saliente usando SMTP.
Miscellaneous Tasks Tarea Descripción defaultexcludes Modifica la lista por defecto de patrones de exclusión de ficheros de Ant. Envía texto a la consola del sistema ( System.out) o a un fichero. echo Fuerza salir del proceso de construcción arrojando una BuildException,
y, opcionalmente, muestra un mensaje con información adicional. Genera una clave (key) dentro de un almacén de claves (keystore). Permite la interacción de los usuarios durante el proceso de construcción mostrando un mensaje y leyendo una línea de entrada desde la consola. Ejecuta un script en un lenguaje que soporte Apache BSF. Reproduce un sonido al final del proceso de construcción. El sonido será uno u otro según la construcción concluya con éxito o con un fallo. Muestra una pantalla de presentación momentánea (splash screen). Ejecuta una serie de sentencias SQL en una base de datos usando JDBC. Añade una nueva definición de tarea para usarla en el proyecto actual. DSTAMP TSTAMP Establece propiedades y TODAY del proyecto. Añade unalas definición de tipo para ,poder usarlo en el proyecto actual. Comprueba si ciertos ficheros XML son válidos (o bien formados).
Compila código fuente C#. Compila código fuente Visual Basic .NET. Compila código fuente J#. Desensambla ejecutables y librerías .NET. wsdltodotnet Genera código .NET (C# o Visual Basic) desde un archivo WSDL. importtypelib Importa una librería de tipo COM a .NET.
Pre-process Tasks Tarea
antlr antstructure
Descripción
Invoca el generador de traductores ANTLR sobre un archivo de gramática. Genera un DTD para los archivos de construcción que contiene diversa
información todas las tareas reconocidas en ese momento porlos Ant. Importa otrosobre archivo de construcción y potencialmente sobrescribe targets del mismo con los del archivo de construcción actual. javacc Invoca el compilador-compilador JavaCC sobre un archivo de gramática. javah Genera cabeceras JNI a partir de una clase Java. jjdoc Invoca al generador de documentación JJDoc para JavaCC. jjtree Invoca el preprocesador JJTree para JavaCC. macrodef Define una nueva tarea como una macro. Convierte ficheros desde su codificación de caracteres nativa a ASCII native2ascii usando Unicode. Se usa habitualmente para convertir archivos de código fuente mantenidos en una codificación nativa de sistema operativo a ASCII como paso previo a la compilación de dicho código. 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 leídos desde otros ficheros de recurso ( resource bundles). typedef Añade una definición de tipo para poder usarlo en el proyecto actual. xslt Procesa un conjunto de documentos por el transformador XSLT. import
Property Tasks Tarea available basename
buildnumber
condition dirname echoproperties
loadfile loadproperties
makeurl pathconvert property propertyfile
Establece una propiedad si ciertoDescripción recurso existe en tiempo de ejecución. Establece una propiedad al último elemento de una ruta especificada. Puede usarse para hacer un seguimiento del número de construcción. Establece una propiedad si se dan ciertas condiciones. Establece una propiedad a la ruta del último directorio de una ruta dada. Lista las propiedades actuales del proyecto. Carga un fichero en una propiedad. Carga propiedades Ant desde un archivo externo. 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 separador especificado y la guarda en una determinada propiedad. Establece una propiedad (dando nombre y valor) o varias (vía fichero). Crea o modifica archivos de propiedades. - 32 -
Establece una propiedad si un cjto de ficheros es más reciente que otro. Encuentra una determinada clase o recurso. xmlproperty Carga valores de propiedades desde un archivo XML bien formado.
whichresource
Remote Tasks Tarea
ftp rexec scp setproxy sshexec telnet
Descripción
Implementa un cliente FTP básico que puede enviar, recibir, listar y borrar ficheros y directorios en un servidor FTP remoto. Tarea para automatizar una sesión 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 código que estén ejecutándose en la misma máquina virtual Java puedan tener acceso externo a través del firewall a sitios web remotos. Ejecuta un comando en un servidor remoto usando SSH. Automatiza una sesión remota de Telnet.
SCM (Source Configuration Management) Tasks Tarea
Descripción
cvs
Administra paquetes/módulos recibidos desde un repositorio CVS. cvschangelog Genera un informe XML de los cambios guardados en un repositorio CVS. Añade entradas a un archivo .cvspass. Añadir entradas a este fichero tiene cvspass el mismo efecto que la ejecución de un comando cvs login. cvstagdiff Genera un informe XML de cambios diferenciales entre dos tags o fechas. cc******* Tarea que puede realizar acciones de la herramienta ClearCase: cccheckin, cccheckout, ccuncheckout, etc… Consulta el manual para más detalles. ccm***** Tarea que puede realizar acciones de la herramienta Synergy , antigua Continuus: ccmcheckin, etc… Consulta el manual de Ant para más detalles. Tarea que puede realizar acciones de la herramienta Visual SourceSafe de vss****** Microsoft: vsscheckin, etc… Consulta el manual de Ant para más detalles. Tarea que puede realizar acciones de la herramienta Perforce: p4sync, p4****** p4change, p4edit, p4submit, etc… Consulta el manual para más detalles. Permite al usuario extraer la última revisión del código fuente de una pvcs aplicación desde un repositorio PVCS. Consulta el manual para detalles. Tarea que puede realizar acciones de la herramienta SourceOffSite: sosget, sos****** soslabel, soscheckin, etc… Consulta el manual de Ant para más detalles. st*******
Tarea que puede realizar acciones deellamanual herramienta stcheckuot, stlabel, y stlist. Consulta de AntStarTeam: para más stcheckin, detalles.
Testing Tasks Tarea
Descripción
junit
Ejecuta las pruebas del framework JUnit de pruebas de unidad. Mezcla los archivos XML generados individualmente por la tarea junitreport y genera una salida HTML, aplicándole una hoja de estilo para crear un informe de los resultados de las pruebas visible a través de un navegador.
5.2.- Tareas básicas. Las tareas básicas son aquellas que están incluidas en el núcleo de Ant per se, sin necesidad de incluir librerías adicionales, y que proporcionan las capacidades más fundamentales de la herramienta. Son el conjunto mínimo de tareas que el equipo de desarrollo de Ant ha acordado que van a necesitarse en el orden del día de nuestro trabajo. Enumeraremos mediante una tabla la lista completa de todas las tareas básicas de Ant a modo de referencia, y después pasaremos a explicar brevemente las más importantes y comúnmente usadas en nuestro escenario habitual de trabajo.
Listado completo de tareas básicas (Ant versión 1.7) Tarea
Descripción
ant antcall antstructure apply
Lanza la construcción de un subproyecto. Lanza la ejecución de un target dentro de un mismo proyecto. Genera un DTD informativo para los ficheros de construcción de Ant. Ejecuta un comando en el sistema sobre un conjunto de ficheros. Lanza el annotation processor tool (apt), y, opcionalmente, compila el código original, así como cualquier código fuente generado. Establece una propiedad si existe cierto recurso en tiempo de ejecución. Determina el nombre del fichero de una ruta absoluta o relativa. Tarea básica para ir registrando un número de construcción. Descomprime un recurso comprimido con BZip2. Comprime un recurso a un archivo de salida usando el algoritmo BZip2.
Genera checksums. tarea usarse ficheros. Cambia permisos deEsta acceso de puede ficheros. Sólopara tieneverificar efecto en UNIX. Concatena uno o más recursos a un único fichero de salida o la consola. Establece una propiedad si se cumple cierta condición. Copia archivos o colección 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 versión del cliente y el servidor CVS. Añade 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 diagnóstico desde dentro de Ant. Útil si se quiere lanzar su modo de diagnóstico desde dentro de un entorno de desarrollo (IDE). Establece una propiedad con el directorio padre de una ruta de fichero. Extensión 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 estén bloque.Similar a apply, pero sin ficheros. Ejecuta unincluidos comandoendesusistema. Provoca un fallo en el proceso de construcción, arrojando una excepción - 34 -
BuildException con un mensaje informativo. filter Establece tokens de cadenas de caracteres para filtrado de ficheros. fixcrlf Ajusta las convenciones locales de salto de línea y retorno de carro. genkey Genera una clave cifrada de firma en un almacén de claves (keystore). get Descarga un fichero desde URL (podemos usar http:, ftp:, jar:, https:). gunzip Descomprime un recurso usando GZip. gzip Comprime un recurso usando el algoritmo GZip. import Importa un fichero de construcción externo completo al proyecto actual. input Permite la interacción del usuario durante el proceso de construcción. jar Empaqueta en JAR un conjunto dado de ficheros. java Ejecuta una clase Java en la máquina virtual. javac Compila un árbol de código fuente Java. Genera la documentación del proyecto usando la herramienta javadoc. javadoc length Muestra o establece una propiedad con la longitud de fichero o cadena. Especialización de loadresource para ficheros. loadfile loadproperties Carga los contenidos de cierto fichero como propiedades de Ant. loadresource makeurl mail macrodef manifest
Carga un recurso lo almacena una propiedad. Convierte rutas detextual ficheroy en URLs tipoen file: Envía un correo electrónico saliente vía SMTP. Define una nueva tarea usando los elementos anidados . Crea un archivo de manifiesto para poder incluirlo en un archivo JAR. Convierte un recurso path en una propiedad válida que pueda usarse manifestclasspath para establecer el atributo Class-Path de un manifiesto. mkdir Crea un directorio (y todos sus padres, hasta la rama final), si no existe. move Mueve ficheros a un nuevo directorio. nice Consulta o establece la prioridad de la hebra actual de ejecución de Ant. Tarea contenedora (puede contener otras tareas). Todas las tareas parallel contenidas dentro de esta tarea correrán paralelamente en su thread. patch Aplica un parche diferencial (diff) a un archivo. pathconvert Convierte una colección de recursos en una lista de nombres de archivo. Permite definir nuestras propias tareas en un archivo de construcción. presetdef Usando esta tarea podemos definir nuestras propias tareas. Establece una propiedad (dados su nombre y valor) o un conjunto de las property mismas a través de un fichero externo de propiedades. Define un recorder, es decir, un listener que guarda la salida generada record por el proceso de construcción a un fichero. replace Reemplaza en un conjunto de ficheros una cadena de texto por otra. resourcecount rmic sequential signjar sleep sql subant sync tar taskdef tempfile
Sirve para consultar el tamaño colecciones de recursos o establecer propiedades con dicho número.de Puede usarse como condición. Compila clases en el rmic (Java RMI stub compiler) del JDK. Tarea contenedora. Las tareas anidadas son ejecutadas en secuencia. La función de esta tarea es agrupar tareas secuenciales en . Firma archivos JAR usando la herramienta jarsigner del JDK. Detiene (o duerme) Ant durante un breve periodo de tiempo. Útil si el proceso de construcción 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 colección. Crea un archivo TAR para agrupar colecciones de ficheros. Añade una definición de tarea al proyecto actual para que pueda usarse. Crea un archivo temporal que es asignado a una propiedad. - 35 -
Cambia fecha de última modificación de un fichero. Si no existe, lo crea. Establece las propiedades DSTAMP, TSTAMP y TODAY del proyecto. Añade la definición de una tarea o tipo de datos al proyecto para que typedef pueda ser usado en él. es una generalización de esta. unjar Descomprime un archivo JAR. untar Desempaqueta un archivo TAR. unwar Despliega un archivo WAR. unzip Descomprime un archivo ZIP. Establece una propiedad si una serie de archivos de destino son más uptodate recientes que otra serie de archivos fuente. Bloquea la ejecución hasta que se dan una serie de condiciones. Esta tarea está enfocada a sincronizar una serie de procesos que se están waitfor ejecutando en paralelo dentro de una tarea . Busca una clase o recurso y establece una propiedad con su URL si el whichresource recurso o fichero en cuestión es encontrado. Una extensión de la tarea para manejar las características war WEB-INF, web.xml, etc). especiales de los WARdesde (directorio xmlproperty Carga valores de ficheros propiedades un archivo XML bien formado. xslt Pasa un conjunto de documentos a través de un procesador XSLT. zip Crea un archivo comprimido en ZIP a partir de un conjunto de ficheros.
Lanza la construcción de un subproyecto con su propio archivo de construcción. Atributos: Atributo
Descripción
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
property reference target
Descripción
Nombre de una propiedad que queremos propagar al subproyecto. Para más información, 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 múltiples targets.
Ejemplos:
Lanza Ant sobre un subproyecto, unicado en el subdirectorio subproyecto:
Como el ejemplo anterior, lanza Ant sobre un subproyecto, unicado en el subdirectorio subproyecto, pero se especifica un nombre de archivo de construcción subbuild.xml diferente al nombre por defecto, y, en lugar del target por defecto, invoca a compilar:
Como el ejemplo anterior, pero pasando atributos al subproyecto a través de una propiedad individual y de un fichero de propiedades externo:
Lanza la ejecución de un target dentro de un mismo proyecto. Atributo
Descripción
target inheritAll inheritRef
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.
Elemento anidado
Descripción
property reference target
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 múltiples targets.
Ejemplos:
En el siguiente código, desde el target un-target-cualquiera se invoca a otro target imprimir-mensaje:
Ejecuta un comando en el sistema, con un conjunto de ficheros como argumento. Es una de las tareas más potentes de entre las que proporciona Ant. Atributo
executable dir dest
spawn relative forwardslash type
Descripción
Nombre del comando a ejecutar, sin argumentos. Directorio de trabajo donde el comando debería ejecutarse. Directorio donde esperamos que el comando guarde los ficheros de salida. Atributo sólo válido 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 estarán 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 deberían pasarse al comando usando barras /, incluso el sistema operativo requiere otro separador, la invertida. Indica elsitipo de rutas que se pasan al comando: si sólo como se consideran las rutas de archivo (file), directorio (dir) o ambos (both). Defecto: file. - 38 -
Si los nombres de fichero se añaden automáticamente. 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 condición . Un archivo desde el que se recogerá la entrada estándar hacia el comando. Una cadena que hace de flujo de entrada al comando. Exclusivo con input. Fichero al que volcar la salida de la ejecución del comando. Fichero al que volcar la salida de error de la ejecución del comando. Atributo para poder ver la salida de error del comando por el log de Ant. outputproperty La propiedad en la que volcar la salida del comando. Alternativa al fichero. errorproperty La propiedad en la que volcar el error del comando. Alternativa al fichero. resultproperty La propiedad en la que se almacenará el código de retorno del comando. Ejecuta el comando una sola vez, con todos los ficheros como argumento parallel del comando. Si está a false, se ejecuta el comando una vez por archivo. Limita la cantidad de paralelismo a un cierto número de ficheros en cada maxparallel momento. Si se usa un valor <= 0, se deja ilimitado. Por defecto: ilimitado. Si se sobrescriben o anexan las salidas de ejecución de los comandos en un append parallel fichero. establecido a false , habrá que ponerlo a true . timeout Detiene Si el comando sifue no termina en un periodo de tiempo (dado en mseg). failonerror Detiene el proceso de construcción si el comando devuelve un código != 0. failifexecutionfails Detiene el proceso de construcción si no puede ejecutarse el comando. No ejecuta el comando si no se le pasan ficheros al comando o si todos los skipemptyfilesets que se les pasa son más viejos que los ficheros objetivo. No propagar las variables de entorno anteriores entorno cuando se newenvironment especifican nuevas variables de entorno. Por defecto: false. vmlauncher Ejecuta el comando usando las facilidades de la JVM cuando sea posible. Cuando este atributo se establece a true, el nombre del ejecutable se resolveExecutable resuelve primeramente en el del proyecto y luego en el directorio basedir elegido para la ejecución del comando. Imprimir un resumen tras la ejecución del comando. Por defecto: false. verbose ignoremissing Ignorar los ficheros especificados no existentes. Por defecto: true. Fuerza la sobreescritura de ficheros saltándose la comparación, aunque los force ficheros de destino sean más nuevos que los de origen. Por defecto: false.
addsourcefile os osfamily input inputstring output error logError
Elemento anidado
Descripción
Colección de recursos
Podemos pasarle a la tarea cualquier colección de recursos con la lista de rutas de los recursos a ejecutar: fileset, filelist, dirset, etc.
mapper
Un mapper especifica los archivos relativos al atributo dest para comprobación de dependencias. Argumento de línea de comandos para pasar al comando. Por defecto, los nombres de los archivos a ejecutar serán añadidos al final de la línea 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 para marcar el punto exacto de inserción donde irán esos nombres de fichero. Similar a srcfile, pero marca la colocación del archivo objetivo. Este elemento sólo puede especificarse si se define un mapper anidado.
arg srcfile
targetfile env redirector
Especifica variables de entorno para recibir pasar alentrada comando en y Redirector de E/S anidado. Permite desde enviaranidados. salida hacia ficheros diferentes para cada archivo fuente a enviar al comando. - 39 -
El código del siguiente ejemplo invoca: comando argumento1 NOMBREFICHEROFUENTE argumento2
para absoluta todos losde ficheros del directorio /tmp, reemplazando con la ruta cada fichero. Si parallel se puso a trueNOMBREFICHEROFUENTE , NOMBREFICHEROFUENTE será reemplazado con los nombres de fichero absolutos de todos los ficheros, separados por espacios.
El código siguiente aplica el “comando” ejecutable ficticio a todos los ficheros que encajen en el patrón “*.file” del directorio “src”. El 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 . Finalmente, dentro de una etiqueta introducimos una referencia a out como un , que nos permitirá realizar una comprobación de dependencia de los archivos de salida con los de entrada.
id="out" type="glob" from="src/*.file" to="dest/*.out"
Establece una propiedad si está disponible (available, en inglés) cierto recurso en tiempo de ejecución. Este recurso puede ser una clase dentro del classpath del proyecto, un fichero, un directorio u otro recurso dentro de la máquina 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 básico sobre el proceso de construcción en base a la existencia o no de ciertos recursos. Atributo
property value classname file resource classpath classpathref filepath
Descripción
Nombre de la propiedad que queremos usar. El valor a establecer en la propiedad. Por defecto: true.
searchparents
El nombre nombre del de lafichero clase aa buscar El buscar.dentro del classpath del proyecto. El nombre del recurso a buscar en la máquina 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 búsqueda. Por defecto: false.
Elemento anidado
Descripción
type ignoresystemclasses
classpath filepath
Classpath donde buscar una clase o un recurso. Ruta de archivo donde buscar un fichero.
Ejemplos:
Comprobación de si está disponible la clase principal de una aplicación y establece la propiedad “main.presente” si es así.
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.
Establece una propiedad si se da cierta condición. Esta tarea es una generalización de las tareas y .
Las condiciones se especifican mediante elementos anidados especiales dentro esta tarea y de la tarea . La lista de elementos anidados de la tabla correspondiente supone una selección básica con los más utilizados. Para una lista exhaustiva y detallada, acude al manual de Ant, a la sección “Conditions Task”. Atributo
Descripción
property value
Nombre de la propiedad que queremos usar. El valor a establecer en la propiedad si se da la condición. Defecto: true. El valor a establecer en la propiedad si no se da la condición. Por defecto, si
else
no se da la condición, no se establece la propiedad. Elemento anidado
Descripción
Niega mediante un not lógico la condición que contenga anidada. not Realiza un and lógico entre sus elementos anidados. and Realiza un or lógico entre sus elementos anidados. or Realiza un xor lógico entre sus elementos anidados. xor Idéntica a la tarea . available Idéntica a la tarea . uptodate NOTA: Todos los demás elementos anidados que pueden usarse dentro de tienen atributos propios, son más complejos y menos comúnmente usados. Ant pone a disposición de sus usuarios un completo conjunto de elementos de comprobación de condiciones. Para más detalles, como ya se ha mencionado antes, acude al manual de Ant. Ejemplos:
Comprueba que estén disponibles en el classpath del proyecto las clases “DataHandler” y “Transport”, ambas. Y, si es así, establece a true la propiedad “javamail.completo”.
Copia un fichero o una colección de recursos a un nuevo fichero o directorio. Por defecto, los ficheros sólo se copian si los ficheros que quieren copiarse son más 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 colección de recursos y proporcionar un directorio de destino a través del atributo todir. Atributo
Descripción
file
El archivo a copiar. Da a los archivos copiados la misma fecha de última modificación preservelastmodified que tenían los ficheros originales. tofile El nombre de archivo al que copiar. todir overwrite
El directorio los al que copiar. Sobrescribir archivos aunque los de destino sean más nuevos. Indica si se debería llevar a cabo filtrado de tokens usando los filtering filtros del archivo de construcción 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. includeEmptyDirs Copia los posibles directorios vacíos. Por defecto: true. 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 construcción no se detiene. Por defecto: true. verbose Para que la tarea escriba un mensaje con los ficheros copiados. encoding El sistema de codificación a usar cuando se filtren los ficheros. outputencoding El sistema de codificación 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 sólo enablemultiplemappings procesará el primer archivo o directorio. Este atributo es relevante sólo si se ha especificado un subelemento mapper. El número 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 comprobación de la fecha granularity de última modificación al nivel de milisegundos. Por defecto, es 1 segundo, o 2 segundos enysistemas DOS. en Este atributo distintas puede sercon útil si los archivos fuente destino están máquinas relojes no sincronizados.
Colección de recursos mapper filterset filterchain targetfile env redirector
Descripción
Podemos pasarle a la tarea cualquier colección 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, latokens tarea copy un identity mapper. Usado para reemplazar en losutiliza ficheros copiados. Las cadenas de filtrado son un grupo de filtros de lectura según un orden. Los usuarios pueden definir las suyas propias. Se procesarán antes de los filtersets definidos. Consulta el manual de Ant para más información. Similar a srcfile, pero marca la colocación del archivo objetivo. Este elemento sólo puede especificarse si se define un mapper anidado. Especifica variables de entorno para pasar al comando en anidados. Redirector de E/S anidado. Permite recibir entrada desde y enviar salida hacia ficheros diferentes para cada archivo fuente a enviar al comando.
Ejemplos:
Copia un único fichero:
Copia un único fichero a un directorio:
Copiar un directorio a otro directorio:
Copia un conjunto de ficheros a un directorio (2 formas distintas de hacerlo):
Copia un conjunto de ficheros a un directorio, anexando .bak al nombre de los ficheros:
Borra un fichero, un directorio y todos sus subdirectorios, o un conjunto de ficheros dados por una o más 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 exclusión implícita de archivos por defecto. Si queremos que la tarea 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 exclusión, podemos usar la tarea para indicar mediante colecciones anidadas de recursos los ficheros a excluir por defecto. Atributo
file dir
Descripción
El nombre del fichero a borrar, dado como una ruta absoluta o relativa. El directorio que deseamos borrar, incluyendo sus subdirectorios.
verbose
Si se pone a true, se muestran los nombres de los archivos borrados. Modo “silencioso”. Si nos el archivo o directorio especificado no existe o no es posible borrarlo, Ant no muestra ningún mensaje de diagnóstico (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 configuración emula a la opción –f del comando rm de UNIX. Activar esta opción, 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 construcción, o si simplemente sale en el log del proyecto sin más. Sólo es relevante si quiet es false. Defecto: true. includeemptydirs Indica si hay que borrar los directorios vacíos cuando se usan filesets. defaultexcludes Indica si hay que usar o no la lista por defecto de exclusión de archivos. Indica si usar el método deleteOnExit() de la clase File si hay un fallo deleteonexit al intentar borrar un fichero. Esto provoca que la máquina virtual Java intente borrar el fichero cuando su proceso esté terminando. Defecto: false. Elemento anidado
Descripción
Colección de Podemos pasarle a la tarea cualquier colección 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 exclusión de archivos por defecto. Ejemplos:
Borrado de un fichero y de un directorio:
Borrado de todos los archivos de extensión .bak del directorio actual:
Extensión de la tarea con opciones especiales que simplifican la creación 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 estén al tanto de ello. Si se desea evitar esto, establezca el atributo duplicate a un valor distinto de “ add” (por defecto). Atributo
Descripción
destfile appxml basedir
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, además de empaquetarlos. Por defecto es true. A menos que el atributo keepcompression sea false, compress esta opción se aplicará al archivo entero, y no sólo a los archivos añadidos. Para ficheros existentes, conservar la compresión como estaba inicialmente keepcompression e ignorar el valor del atributo compress. Por defecto: false. Codificación de caracteres para los nombres de fichero dentro del archivo. encoding Por defecto: UTF-8. IMPORTANTE: No se recomienda cambiar este valor en ningún caso, ya que el archivo dejará de ser legible para Java. filesonly Almacena en el archivo sólo entradas de ficheros. Por defecto: false. 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. includesfile Nombre de un fichero que incluye patrones de nombres de ficheros a incluir. Cada línea del fichero se toma como un patrón de inclusión. Lista separada por comas o espacios de patrones de nombres de fichero que excludes se excluirán delfichero archivo. Por defecto: se excluyen sólo losde default excludes. Nombre de un que incluye patrones de nombres ficheros a excludesfile excluir. Cada línea del fichero se toma como un patrón de exclusión. defaultexcludes Usar los patrones de exclusión 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 válidos para este atributo son: “add” (se añade una duplicate entrada adicional - peligroso), “preserve”, y “fail”. Por defecto: “add”.
roundup
level
Indica si elnúmero tiempopar de modificación de los ficheros ha de redondearse siguiente (es decir, un redondeo por arriba). Los archivosalZIP almacenan la fecha de última modificación 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 compresión: 0 (sin compresión) – 9 (máxima compresión).
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 través de los atributos input e inputstring. Atributo
Descripción
executable dir
Nombre del comando a ejecutar, sin argumentos. Directorio de trabajo donde el comando debería ejecutarse. Directorio donde esperamos que el comando guarde los ficheros de salida. Atributo sólo válido 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 estarán 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.
dest spawn os osfamily input inputstring output error logError
. Familia del desde sistema tal y como se usaestándar en la condición Un archivo el operativo, que se recogerá la entrada hacia el comando. Una cadena que hace de flujo de entrada al comando. Exclusivo con input. Fichero al que volcar la salida de la ejecución del comando. Fichero al que volcar la salida de error de la ejecución del comando. Atributo para poder ver la salida de error del comando por el log de Ant. outputproperty La propiedad en la que volcar la salida del comando. Alternativa al fichero. errorproperty La propiedad en la que volcar el error del comando. Alternativa al fichero. resultproperty La propiedad en la que se almacenará el código de retorno del comando. Indica si se sobrescriben (valor a false) o anexan las salidas de ejecución append de los comandos a los ficheros de salida y error. Por defecto: . false timeout Detiene el comando si no termina en un periodo de tiempo (dado en mseg). failonerror Detiene Ant si el comando devuelve un código != 0. Por defecto: false. failifexecutionfails Detiene Ant si no puede ejecutarse el comando. Por defecto: true. No propagar las variables de entorno anteriores entorno cuando se newenvironment especifican nuevas variables de entorno. Por defecto: false. vmlauncher Ejecuta el comando usando las facilidades de la JVM cuando sea posible. Cuando este atributo es true, el nombre del ejecutable se resuelve de resolveExecutable inicio en el basedir del proyecto y luego en el de ejecución del comando. Indica si se deben usar las variables de entorno del sistema a la hora de searchpath resolver la ruta del ejecutable. Por defecto: false. Elemento anidado
arg env redirector
Descripción
Argumento de línea de comandos para pasar al comando. Especifica variables de entorno para pasar al comando en anidados. Redirector de E/S anidado. Consulte la documentación para más detalles.
Ejemplos:
Abre en el navegador Firefox la página inicial del manual de Ant:
Empaqueta una serie de ficheros en un archivo JAR (Java ARchive). Por defecto, se usa el directorio base del proyecto como raíz de los ficheros a incluir en el archivo de empaquetado. No se almacenarán los permisos de los archivos en el JAR. Si no se proporciona ningún archivo de manifiesto, Ant generará uno básico. 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 estén al tanto de ello. Si se desea evitar esto, establezca el atributo duplicate a un valor distinto de “ add” (por defecto). Atributo
Descripción
destfile basedir
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, además de empaquetarlos. Por defecto es true. A menos que el atributo keepcompression sea false, esta opción se aplicará al archivo entero, y no sólo a los archivos añadidos. Para ficheros existentes, conservar la compresión como estaba inicialmente e ignorar el valor del atributo compress. Por defecto: false. Codificación de caracteres para los nombres de fichero dentro del archivo. Por defecto: UTF-8. IMPORTANTE: No se recomienda cambiar este valor en ningún caso, ya que el archivo dejará de ser legible para Java. Almacena en el archivo sólo 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.
compress keepcompression
encoding filesonly includes includesfile
NombreCada de unlínea fichero que incluye patrones ficheros a incluir. del fichero se toma como de unnombres patrón dedeinclusión. Lista separada por comas o espacios de patrones de nombres de fichero excludes que se excluirán del archivo. Por defecto: se excluyen sólo los default excludes. Nombre de un fichero que incluye patrones de nombres de ficheros a excludesfile excluir. Cada línea del fichero se toma como un patrón de exclusión. Indica si se han de usar o no los patrones de exclusión de nombres de defaultexcludes fichero por defecto de Ant a la hora del empaquetado. Por defecto: false. manifest Nombre del archivo de manifiesto a usar. Comportamiento si se encuentran archivos de manifiesto adicionales en filtersetmanifest colecciones zipfileset o zipgroupfileset. Valores válidos: “skip” (saltárselos), “merge” (mezclarlos) o “mergewithoutmain” (mezclarlos ignorando la sección Main-Class). Por defecto: “ skip”. 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 qué hacer si no hay ficheros que incluir en el JAR. Valores válidos: whenmanifestonly “fail” (detiene Ant), “skip” (no se crea ningún JAR), y “create” (crea el JAR vacío sólo con el manifiesto dentro). Por defecto: “create”. Indica el comportamiento de la tarea cuando se encuentra un fichero duplicado. Valores válidos para este atributo son: “add” (se añade una duplicate index
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 característica específica del JDK v1.3+. A menos que se especifiquen - 48 -
archivos jar con elementos indexjars anidados, en el índice sólo se incluirán los ficheros del jar actual. Por defecto: false. La codificación de caracteres usada para leer el manifiesto JAR, cuando se especifica un archivo de manifiesto externo. Indica si el tiempo de modificación de los ficheros ha de redondearse al siguiente número par (es decir, un redondeo por arriba). Los archivos ZIP almacenan la fecha de última modificación 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 compresión: 0 (sin compresión) – 9 (máxima compresión).
Elemento anidado
metainf manifest indexjars service
Descripción
Especifica un fileset con todos los ficheros que han de incluirse en el directorio META-INF del archivo JAR. Este elemento es una tarea anidada que permite crear desde el archivo de construcción un manifiesto a medida. Este elemento especifica una estructura de rutas en las que se encuentran ficheros JAR a los que se les construirán índices. Este elemento sólo se tiene en cuenta si el atributo index se estableció a true. Esta tarea no creará entradas de índice para archivos vacíos o que sólo contengan ficheros en el directorio META-INF. Especifica un servicio. Consulte la documentación de Ant para más detalles.
Ejemplos:
Empaquetar los ficheros de “${build}/classes” en el archivo “aplicacion.jar”:
Empaquetar los ficheros de “${build}/classes” a un archivo “aplicacion.jar”. Sólo se empaquetan los ficheros bajo el directorio “paquete/test”, excluyendo los ficheros (en cualquier subdirectorio a partir de esa raíz) que se llamen Test.class:
excludes="**/Test.class"
Creación de un archivo JAR especificando un servicio con dos implementaciones distintas del interfaz de scripting de la versión 6 del JDK:
Ejecuta una clase en la máquina virtual de Java actual (la de Ant) o en otra aparte si se establece el atributo fork a true. Atributo
Descripción
classname
Nombre de la clase a ejecutar. Localización del archivo JAR que queremos ejecutar (por supuesto, debe tener una entrada Main-Class válida 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 definido en el proyecto. Ejecuta la clase en otra instancia de la máquina virtual Java distinta fork (independiente) a la de Ant. Por defecto: false. Permite que un proceso continúe vivo después de que Ant termine. spawn Requiere que fork esté a true, y no es compatible con los atributos input, output, error y result (estarán desactivados por defecto). El comando usado para invocar la máquina virtual Java, por defecto es “java”. El comando se resuelve usando java.lang.Runtime.exec(). jvm Se ignora si fork está desactivado. Máxima cantidad de memoria que puede reservar la máquina virtual maxmemory separada. Se ignora si fork está desactivado. Detiene el proceso de construcción si el comando termina con un código de failonerror retorno distinto de 0. Por defecto: false. El nombre de una propiedad en la que guardar el código de retorno. Sólo es
resultproperty
false y fork es true. de interés sienfailonerror Directorio el que invocar es la máquina virtual. Ignorado si fork es false. Fichero al que volcar la salida. Si la salida de error no es redirigida también output a algún 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 algún archivo o propiedad. Indica si los ficheros de salida y error deberían ser anexados o sobrescritos. append Defecto: false, así que los ficheros se sobrescribirán en cada ejecución. 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 estándar. 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 opción si y sólo si fork está activado. Si está a true, todas las propiedades de sistema y el classpath de arranque
dir
clonevm
(bootclasspath) la máquina separada serán mismas que .las de la MV de Ant. Sedeignora si forkvirtual está desactivado. Por las defecto: false - 50 -
Pueden usarse elementos anidados y para especificar argumentos para la clase y la máquina virtual separada respectivamente. Especifica propiedades de sistema requeridos por la clase.
syspropertyset classpath
Especifica unde conjunto propiedades de sistema. Un conjunto rutas o de archivos que formen el classpath de la aplicación. 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 máquina virtual separada. env Consulta la tarea exec en el manual de Ant para más detalles. permissions Permite conceder y revocar permisos durante la ejecución de una clase. Para más información, consulta el apartado “Permissions” del manual. assertions Controla la activación o no de las aserciones de Java 1.4. Para especificar un redireccionador de E/S. redirector Para más información sobre este atributo, consulta el manual de Ant. NOTA: Por defecto, se ignora el código de retorno de una tarea . No obstante, se puede guardar dicho código 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 construcción. De forma análoga, si failonerror=false y fork=false, también la propia tarea debe devolver 0, o se interrumpirá el proceso de construcción. Ejemplos:
Ejecución de una clase en la máquina virtual de Ant con un classpath que incluye un JAR:
Ejecuta “aplicacion.jar” en una máquina virtual separada (con fork a true, como se requiere para ejecutar JAR) un máximo de memoria. Al especificar a truearchivos , un código de con retorno distinto de de 128MB la construcción. failonerror 0 interrumpe
Compila un árbol de directorios de código fuente Java. Escanea recursivamente un directorio en busca de código fuente Java. Se deben de seguir las convenciones genéricas de Java en cuanto a la colocación de los archivos de la aplicación, mapeando la jerarquía del paquete como directorios en el disco. Se pueden incluir y excluir explícitamente 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 . 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 compiler de una tarea concreta. tareas de un proyecto) o el atributoson Los valores válidos para estas propiedades los siguientes: Valor
classic javac1.1 javac1.2 modern javac1.3 javac1.4 javac1.5 javac1.6
jikes gcj jvc microsoft kcj sj symantec extJavac
Descripción
Con todos estos valores, se usará el compilador estándar del JDK v1.1/v1.2 de Sun Microsystems. Cualquiera de los tres valores es válido. classic es el valor más habitual, pero javac1.1 y javac1.2 son alias válidos. Todos estos valores sirven para usar el compilador estándar moderno del JDK de las últimas versiones v1.3 / v1.4 / v1.5 / v1.6 de Sun Microsystems, con soporte para las últimas y más modernas características del lenguaje Java en el código fuente. Los otros valores son alias alternativos a modern. Compilador open-source Jikes. Una opción a tener en cuenta. Compilador gcj, parte del proyecto GCC (GNU Compiler Collection). Compilador de línea 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 máquina virtual propia.
NOTA: En Windows, cuando el compilador moderno se usa en modo no separado (es decir, con fork a lateral false), que bloquea los ficheros de classpath deeslaque tarea no loso libera. El efecto provoca este comportamiento no se podrán yborrar mover dichos archivos después de ejecutar la tarea , y no se liberarán hasta que haya terminado completamente el proceso de construcción, cuando Ant haya terminado. El atajo para esquivar este problema es simplemente ejecutar la tarea de compilación en una máquina virtual separada (con fork a true). La tarea , como puede suponer el lector, es una de las más importantes y trascendentales de Ant, dada su importancia con respecto al proceso de construcción. Por eso, aquí se le dedican varias páginas a describir con relativo detalle todas sus principales características. No obstante, por supuesto, se insta al lector a consultar profusamente toda la documentación recogida en el apartado dedicado a esta importante tarea en el manual oficial de Ant. - 52 http://slidepdf.com/reader/full/construyendo-aplicaciones-con-apache-ant
Localización de los ficheros de código fuente Java a compilar. Directorio donde almacenar las clases resultantes de la compilación. Lista de ficheros (separados por comas o espacios) a compilar. Pueden includes usarse patrones. Por defecto, se incluirán todos los ficheros **.java. El nombre de un fichero que contiene una lista de ficheros a incluir. includesfile También pueden incluirse patrones de rutas en este fichero. Lista de ficheros (separados por comas o espacios) a excluir del proceso de excludes compilación. Pueden usarse patrones. Por defecto, no se excluirá ningún fichero, salvo los archivos de exclusión por defecto de Ant. excludesfile El nombre de un fichero que contiene una lista de ficheros a excluir. También pueden incluirse patrones de rutas en este fichero. classpath El classpath a utilizar en la compilación. La ruta raíz a usar en la compilación. Por defecto, será el valor dado por el sourcepath atributo srcdir, o elementos anidados . Si en algún momento se quiere suprimir la opción sourcepath, se puede hacer sourcepath=””. bootclasspath Localización de las clases de arranque (bootstrap). ya classpathref El sourcepath classpath a utilizar, comoreferencia referenciaaaun unelemento elemento yadefinido. definido. a usar, como sourcepathref bootclasspathref El bootclasspath, dado como referencia a un elemento ya definido. extdirs Localización de las extensiones instaladas. Codificación de caracteres de los ficheros fuente. encoding NOTA: el compilador gcj aún no soporta esta opción. Indica si hay que pasar la opción –nowarn al compilador. Defecto: off. nowarn Indica si el compilador generará información de depuración. Defecto: off. debug Cadena clave a pasar junto a la opción de depuración (-g) que indica el nivel de información de depuración que se quiere recibir. Actualmente, esta opción está soportada por el compilador oficial de Sun, a partir de la versión 1.2, así como por jikes. Los compiladores que no implementen esta debuglevel opción la ignorarán. Valores válidos son: none, o una lista separada por comas de las claves lines, vars y source. Si se especifica el uso de salida de depuración 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 técnicas de optimización al código fuente que genera. Por defecto: off. NOTA: Esta opción es ignorada por el optimize compilador de Sun a partir de la versión 1.3, ya que se hizo innecesaria la optimización en tiempo de compilación.
deprecation
target
verbose depend includeAntRuntime
Indica si el compilador debería arrojar información sobre la antigüedad o la condición de obsoletos de ciertas clases o métodos. Por defecto: off. Genera archivos de clase con bytecode para una versión específica de la máquina virtual Java. NOTA: el valor por defecto dependerá de la versión de la máquina virtual sobre la que esté ejecutándose Ant. En particular, si se usa un JDK v1.4+, las clases generadas no serán compatibles con una máquina 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 opción SIEMPRE. Se puede especificar un valor por defecto para este atributo con la propiedad ant.build.javac.target. Activa una salida más verbosa en el compilador. Por defecto: no. Activa la traza de dependencias para los compiladores que soporten esta opción (en este caso, classic y jikes). Si incluir las librerías de ejecución de Ant en el classpath. Por defecto: yes. - 54 -
Si incluir las librerías de ejecución 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á ejecutándose Ant. Tamaño inicial de la memoria de la máquina virtual si javac se ejecuta externamente (se ignora si no es así). Puede especificarse en bytes o usando unidades más grandes, por ejemplo: 83886080, 81920k o 80m. Por defecto: tamaño por defecto asignado por la implementación de MV. Igual a memoryInitialSize, pero para el tamaño máximo de la MV. Si los errores de compilación detendrá la construcción. Por defecto: true. Valor de la opción de línea de comandos –source; será ignorado por todas las implementaciones previas a javac1.4 (o modern cuando Ant no está ejecutándose en una máquina virtual v1.3), así como por jikes. Si se usa este atributo con jikes, se debe estar seguro de que dicha versión de jikes soporte la opción –source. Por defecto: no se pasa –source al compilador. NOTA: el valor por defecto de este atributo dependerá de la versión de la máquina virtual en la que esté ejecutándose Ant. Se recomienda encarecidamente especificar esta opción SIEMPRE. Se puede especificar un valor por defecto para este atributo a través 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 máquina virtual actual. La lista de valores válidos es la que se menciona en la tabla anterior. Si han de listarse por pantalla los nombres deser losinteresante archivos desicódigo fuente que entren al proceso de compilación. Puede no estamos seguros de qué ficheros exactamente le llegan al compilador. Defecto: no. Directorio donde Ant debería colocar los archivos temporales. Este atributo sólo se usa si la tarea se envía a una máquina virtual separada y, además, los argumentos de línea de comandos pasan de 4KB de longitud. Por defecto: directorio dado por la propiedad java.io.tmpdir de Ant.
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
bootclasspath valores de dichos conceptos usando elementos por otra parte, extdirs mucho más potentes y expresivos (los atributos,anidados, por ejemplo, no pueden contener espacios) que los simples atributos de la cabecera de la tarea. A diferencia de los anteriores elementos anidados, no tiene el src mismo nombre que el correspondiente atributo de la tarea. El elemento anidado se corresponde con el atributo srcdir de la tarea. Este elemento anidado es la vía que proporciona Ant para personalizar las opciones de compilación para pasarle a compiladores concretos. Se puede especificar un argumento acompañado del compilador para el que sirve. Atributos
value compilerarg
line file path compiler
Descripción
Un argumento sencillo. Puede contener espacios. Una lista dedeargumentos espacios. El nombre un fichero. separada Se pasarápor su ruta absoluta. Una ruta. Se puede usar “;” o “:” como separador. Ant los convertirá a la convención de la plataforma. El argumento especificado sólo se pasa si se trata del compilador que dicta este atributo. Así controlamos el no pasarle a los compiladores comandos irreconocibles.
Ejemplos:
Compilación de todos los archivos *.java del directorio dado por la propiedad src. Las clases la compilación se guardan el directorio dadodepor la esta propiedad buildgeneradas . Se usa el por classpath por defecto. Esta es laenforma más básica usar tarea.
srcdir="${src}" destdir="${build}"
/>
Idem al anterior, pero incluyendo el archivo xyz.jar en el classpath y excluyendo de la compilación todos los archivos de código fuente que terminen en “Ejemplo.java”. Además, se pide al compilador que proporcione salida de depuración. También se especifica que el código fuente está escrito con las capacidades de la versión 1.4 de Java, es decir que, por ejemplo, podemos usar aserciones, pero no clases genéricas (la genericidad se introdujo en la v1.5).
srcdir="${src}" destdir="${build}" classpath="xyz.jar" debug="on" source="1.4" >
Genera documentación del código fuente usando la herramienta javatool. Escanea recursivamente un directorio en busca de código fuente Java que encaje con losson patrones de inclusión y que no lo haga con loscompilación, de exclusión. no controla cuales los archivos “cambiados” desde la última asíEsta quetarea siempre generará la documentación de todas las clases. NOTA: la tarea llama a System.exit(), por lo que no puede ser ejecutada en la misma máquina virtual que Ant sin interferir su ejecución. Por tanto, esta tarea se ejecuta siempre en una máquina virtual separada. Atributo
Descripción
sourcepath Especifica la ruta de los archivos de código fuente. sourcepathref Ruta del código fuente, dada como una referencia a un elemento . sourcefiles destdir maxmemory
Lista de archivos código fuente separados por comas. Para especificar archivos sueltos ade compilar puede usarse el elemento anidado . Directorio de destino para los ficheros generados. Máxima memoria reservable para la máquina virtual de javadoc. Lista de paquetes separados por comas (terminando en *). Para especificar packagenames nombres de paquetes puede usarse el elemento anidado . packageList El nombre de un archivo con una lista de los paquetes a incluir. classpath Especifica donde encontrar los archivos de clases para esta tarea. bootclasspath Especifica la ruta de los archivos de clase de arranque ( bootclasspath). classpathref El classpath a utilizar, como referencia a un elemento ya definido. bootclasspathref
verbose locale encoding version use author splitindex windowtitle
El bootclasspath, como referencia a un elemento definido. Localización de lasdado extensiones instaladas. Resumen de la documentación en un archivo HTML. Modo de acceso: public, protected, package, o private. Por defecto: protected. Muestra en la documentación sólo miembros y clases públicos. Muestra en la documentación miembros y clases públicos o protegidos. Muestra en la documentación generada miembros y clases de visibilidad pública, protegida o con una visibilidad de ámbito de paquete. Muestra en la documentación todos los miembros y clases, incluyendo todos aquellos de visibilidad privada. Genera la salida usando el doclet de emulación del JDK v1.1. Disponible a partir de la versión 1.2 del JDK. Muestra mensajes de salida sobre la actividad de javadoc. Cadena de localización a utilizar, por ejemplo: en_US, en_US_WIN, etc. Codificación de caracteres de los archivos de código fuente. Incluye párrafos @version. Por defecto: true. Crea páginas sobre el uso de paquetes y clases. Incluye párrafos @autor. Por defecto: true. Divide el índice en un fichero por letra. Por defecto: false. Título de la página de índice que se mostrará en el navegador (texto).
doctitle header footer
Título incluiren enla la cabecera página dedeíndice HTML). Texto aa incluir todas(código las páginas generadas (HTML). Texto a incluir en el pie de página de todas las páginas generadas (HTML).
extdirs overview access public protected package private old
Texto a incluir en la parte de abajo de las páginas generadas (HTML). Enlaza a la salida javadoc de una URL. Ver elemento anidado . Enlaza a documentos en una usando la lista de paquetes de linkoffline . Separa las URLs con espacios. Véase elemento anidado . Define un grupo de paquetes que han de estar agrupados en la página inicial de resumen. Véase también el elemento anidado . Los argumentos están separados por comas, y cada argumento son dos group cadenas de caracteres separadas por un espacio: el primero es el título del grupo y el segundo una lista de paquetes separadas por “:”. Si se necesita especificar más de un grupo, o un grupo cuyo título contiene una coma o un espacio, se recomienda usar un elemento anidado . nodeprecated No incluir la información de las etiquetas @deprecated. notree No generar la jerarquía de clases. noindex No generar ningún índice. nohelp No generar ningún enlace de ayuda. nonavbar No generar la barra de navegación. serialwarn helpfile stylesheetfile charset docencoding
@serial. Generar avisos referidos a la etiqueta Especifica el archivo de ayuda que queremos usar. Especifica la hoja de estilo CSS que queremos usar. Juego de caracteres para la visualización en otras plataformas. Codificación de caracteres de los archivos generados. Especifica el archivo de clase que arranca el doclet que queremos usar para doclet generar nuestra documentación. Véase el elemento anidado . Ruta del archivo de clase del doclet que suele especificarse normalmente docletpath en la herramienta javadoc con la opción –doclet. docletpathref Ruta del archivo de clase del doclet, como una referencia a un . Permite añadir parámetros adicionales a la línea de comandos . javadoc additionalparam Útil para doclets. Los parámetros que contengan espacios han de ser marcados con " Véase también el elemento anidado . failonerror Detiene el proceso de construcción si el comando no retorna un 0. Lista de nombres de paquetes (separados por comas) para los que no excludepackagenames queremos que se genere documentación. Véase también el elemento anidado . defaultexludes Indica si deberían tenerse en cuenta los patrones de exclusión por defecto. Indica si el nombre del fichero fuente especificado en sourcefiles o como elementos anidados deberían escribirse en un archivo temporal useexternalfile para hacer más corta la orden de línea de comandos. Esto también se aplica a los nombres de paquetes especificados a través del atributo packagenames o con elementos anidados . 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 código fuente que se compilaría usando “ javac –source 1.4”. Esta opción está disponible desde la versión 1.4 del JDK. Genera hipervínculos a archivos de código fuente. Por defecto: no. linksource Esta opción está disponible desde la versión 1.4 del JDK. Usa el nuevo algoritmo breakiterator. Por defecto: no. breakiterator Esta opción está disponible desde la versión 1.4 del JDK.
noqualifier includenosourcepackages
all o una lista de Activa el argumento Valores nombres de paquetes–noqualifier. separados por comas.válidos: Si includenosourcepackages está a true, documenta también los
paquetes que no contienen código fuente Java, sólo un package.html. Especifica un ejecutable javadoc concreto que usar en lugar del binario por defecto (el javadoc del JDK en el que está ejecutándose Ant).
Elemento anidado
Descripción
Los atributos correspondientes a las rutas archivos de código a documentar (sourcepath), las rutas dede laslos clases necesarias parafuente la sourcepath documentación externa de la aplicación o las pertenecientes a librerías classpath (classpath), o las clases básicas de arranque para la máquina virtual bootclasspath (bootclasspath), pueden especificarse también de forma más flexible usando elementos anidados en lugar de sus correspondientes atributos. Un conjunto de directorios, dado por un elemento , que se le pasarán a javadoc como nombres de paquetes. Ant supone que el directorio packageset base del packageset apunta a la raíz de la jerarquía de paquetes. Los atributos packagenames, excludepackagenames y defaultexcludes no tienen efecto alguno sobre los elementos anidados . Todos los archivos indicados en este elemento anidado son enviados a javadoc como archivos de código fuente. Ant automáticamente incluye el patrón **/*.java (y **/package.html si includenosourcepackage es true) en este conjunto de ficheros. Este elemento anidado puede usarse fileset para documentar archivos fuente que estén en el paquete por defecto, o si se quiere excluir ciertos ficheros de la documentación. Los atributos packagenames, excludepackagenames y defaultexcludes no tienen efecto alguno sobre los elementos anidados . sourcefiles Un contenedor para colecciones de recursos. Todos los archivos contenidos en dichas colecciones se pasarán a javadoc como archivos de código fuente. Igual Atributo a una entrada individual de la lista dada por packagenames. Descripción package name Nombre del paquete a incluir (puede ser un *). Igual a una entrada individual de la lista dada por excludepackagenames. excludepackage
source doctitle header footer botton link
Atributo
Descripción
name Nombre del paquete a excluir (puede ser un *). Igual a una entrada individual de la lista dada por sourcefiles. Atributo
Descripción
file El archivo de código 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
href offline packageListLoc resolveLink
Descripción
La URL de la documentación 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 documentación. Directorio que contiene un archivo lista de paquetes para documentación externa. Es necesario especificar este atributo sólo si offline se especificó a true. Si el atributo es un nombre de fichero relativo, Ant - 59 -
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 más. Reúne paquetes en grupos en la página de resumen. Cada grupo estará en una tabla. Sirve para lo mismo que el atributo group. No obstante, con group
elementos se pueden especificar varios grupos. NOTA: los atributos deanidados este elemento anidado son a su vez elementos anidados. Atributo
Descripción
title Título del grupo. packages Lista de paquetes del grupo, separados por “:”. Se utiliza para especificar el doclet que javadoc usará para procesar los archivos de código fuente. Un buen número de los argumentos de la tarea son en realidad argumentos para el doclet por defecto. Si alguno de estos atributos es especificado (sólo deberían especificarse si pueden ser interpretados por el doclet en uso), se le pasará al doclet por defecto usando precisamente elementos anidados. Si el doclet doclet
requiere parámetros adicionales, pueden pasarse a través de elementos anidados (sólo se pueden pasar cadenas de caracteres). Ejemplo:
Sirve para especificar tags (etiquetas) personalizados. Esta opción sólo está disponible con la versión 1.4 de Java. Si se quiere especificar una etiqueta estándar usando un elemento anidado para determinar el orden en el que las etiquetas se procesan, no deberá establecerse una descripción para dichos tags. Atributos
tag
Descripción
name Nombre del tag. description Descripción del tag (por ejemplo: “To do:”). Si el tag está activado o no. Por defecto: true. enabled Á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, scope types, constructors, methods, fields, o también all. Por defecto: all. Si se especifica este atributo, este elemento se comportará como un implícito. Los archivos incluidos en dicho fileset deberían contener cada definición de un tag en una línea separada, tal y como se menciona en la guía de referencia de Javadoc: dir
ejb.bean:t:XDoclet EJB Tag todo:a:To Do
NOTA1: En la guía de referencia de Javadoc, la descripción está entre comillas. Esto no funcionará cuando se use desde fichero, ya que la descripción se pasa entre comillas cuando se envía aSijavadoc . NOTA2: se especifica este atributo, todos los demás atributos de este elemento son ignorados. - 60 http://slidepdf.com/reader/full/construyendo-aplicaciones-con-apache-ant
Este elemento anidado se usa para especificar taglets personalizados. Esta opción sólo está disponible con la versión 1.4 de Java. Atributo
taglet
name
Descripción
El nombre de la clase taglet. Por ejemplo: com.sun.tools.doclets.ToDoTaglet . Una ruta especificando la ruta de la clase taglet, como, por
path ejemplo, “/home/taglets ”. Esta información proporcionarse a través de un elemento anidadopuede . 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 línea de comandos. Atributo
arg
value file path pathref line
Descripción
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 convención de la plataforma. Una ruta, dada como referencia a un elemento . Una lista de argumentos separada por espacios.
Ejemplos:
El siguiente ejemplo es el más básico y habitual: genera la documentación de los archivos a partir de los archivos de código fuente ubicados en el directorio dado por la propiedad dir.fuentes, y almacena la documentación generada en el directorio dir.javadoc.
5.3.- Tareas opcionales. Las tareas opcionales son aquellas que no están incluidas en el núcleo de Ant per se, al considerarse fuera de la funcionalidad general o del caso más habitual de uso para el que está enfocada la herramienta. No obstante, algunas tareas consideradas como opcionales, como por ejemplo y , nos serán habitualmente muy necesarias.
Para poder usar una tarea opcional habremos de consultar las librerías que necesita dicha tarea (si es que las necesita, no siempre es así), que normalmente se mencionarán, si es el caso, en la documentación oficial. Si la tarea opcional que queremos utilizar necesita de librerías adicionales, hemos de asegurarnos de que estén 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 súper conjunto de tareas, por encima de las básicas, que la comunidad de desarrollo entorno a la herramienta ha ido creando con el paso del tiempo para y facilitar todo tipo de procesos conJava la construcción desarrollo deacometer aplicaciones de diversas tecnologías sobrerelacionados la plataforma usando Ant. y el A continuación, se incluye un listado completo de las tareas opcionales que proporciona Ant. En este listado no se entra en ningún detalle sobre sus atributos o elementos anidados, ya que excedería el carácter docente a un nivel de completa introducción de este documento. El lector sí podrá usar este listado para localizar rápida y fácilmente 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 páginas dedicadas a las tareas más importantes y comúnmente usadas en los escenarios desarrollo másy habituales. En este, que, caso,como se han de ya, interés trascendental las de tareas seconsiderado ha comentado son totalmente necesarias en la construcción de proyectos bien diseñados.
Listado de tareas opcionales (Ant versión 1.7) Tarea
Descripción Tarea
Descripción
csc vbc jsharpc ildasm
Compila código fuente C#. Compila código fuente Visual Basic .NET. .NET Tasks Compila código fuente J#. Desensambla ejecutables y librerías .NET. wsdltodotnet Genera código .NET (C# o Visual Basic) desde un WSDL. importtypelib Importa una librería de tipo COM a .NET. antlr Invoca el generador de traductores ANTLR sobre un archivo de gramática. cab Crea un archivo CAB de Microsoft. Cambia el grupo al que pertenece un fichero o conjunto de ficheros. chgrp Actualmente, esta tarea sólo tiene efecto en sistemas UNIX. Cambia los permisos de un fichero o grupo de ficheros dentro de los chown directorios especificados. Los permisos se establecen siguiendo el estilo cc******* ccm***** depend
habitual UNIX.realizar Actualmente, tiene efecto en sistemas UNIX. Tarea quedepuede accionessólo de la herramienta ClearCase: cccheckin, cccheckout, ccuncheckout, etc… Consulta el manual para más detalles. Tarea que puede realizar acciones de la herramienta Synergy , antigua Continuus: ccmcheckin, etc… Consulta el manual de Ant para más detalles. Determina qué archivos de clase están desactualizados con respecto a su código fuente, eliminando los archivos de clase que dependan de cualquier clase desactualizada y forzando su recompilación. Usada junto a . Tarea
blgclient ddcreator iplanet-ejbc EJB Tasks
ejbjar
Descripción
Borland Application Server versión 4 y 5 Weblogic 4.5.1 Elemento anidado Server 6.0 iPlanet Application
borland iPlanet jboss j onas w eblogic w ebsphere
Descripción
Borland Application Server versión 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 básico que puede enviar, recibir, listar y borrar ftp ficheros y directorios en un FTP remoto. image Aplica transformaciones de servidor imagen (rotar, etc) a un conjunto de ficheros. Comprueba si una extensión está presente en un fileset o en un jarlib-available extensionset. Si está presente, establece una propiedad dada. Muestra la información 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 extensión, y coloca su ruta en la propiedad. javacc Compila los archivos de código fuente Java especificados. javah Genera cabeceras JNI a partir de una clase Java. Ejecuta el compilador JSP. Puede usarse para precompilar páginas JSP. jspc Luego puede usarse la tarea para compilar el código Java. - 63 http://slidepdf.com/reader/full/construyendo-aplicaciones-con-apache-ant
Invoca al parser JDepend, que analiza una serie de directorios de código Java y genera métricas de calidad del diseño para cada clase Java. Invoca al generador de documentación JJDoc para JavaCC. Invoca el preprocesador JJTree para JavaCC. Ejecuta las pruebas del framework JUnit de pruebas de unidad. Mezcla los archivos XML generados individualmente por la tarea
junitreport y genera una salida HTML, aplicándole una hoja de estilo para crear un informe de los resultados de las pruebas visible a través de un navegador. Convierte ficheros desde su codificación de caracteres nativa a ASCII usando Unicode. Se usa habitualmente para convertir archivos de código native2ascii fuente mantenidos en una codificación nativa de sistema operativo a ASCII como paso previo a la compilación de dicho código. netrexxc Compila un árbol de código fuente NetRexx. Tarea que puede realizar acciones de la herramienta Perforce: p4sync, p4****** p4change, p4edit, p4submit, etc… Consulta el manual para más detalles. propertyfile Crea o modifica archivos de propiedades. Permite al usuario extraer la última revisión del código fuente de una pvcs aplicación desde un repositorio PVCS. Consulta el manual para detalles. replaceregexp Reemplaza una expresión regular por un patrón de sustitución. rexec Tarea para automatizar una sesión rexec remota. Tarea sólo válida 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 específico. setproxy sound sos****** splash sshexec st******* symlink telnet translate vss****** wljspc xmlvalidate
Establece propiedades del Proxy web de máquina Java, paravirtual que las tareas y el código quelas estén ejecutándose en la misma Java puedan tener acceso externo a través del firewall a sitios web remotos. Reproduce un sonido al final del proceso de construcción. El sonido será uno u otro según la construcción concluya con éxito o con un fallo. Tarea que puede realizar acciones de la herramienta SourceOffSite: sosget, soslabel, soscheckin, etc… Consulta el manual de Ant para más detalles. Muestra una pantalla de presentación momentánea (splash screen). Ejecuta un comando en un servidor remoto usando SSH. Tarea que puede realizar acciones de la herramienta StarTeam: stcheckin, stcheckuot, stlabel, y stlist. Consulta el manual de Ant para más detalles. Tarea para administrar los enlaces simbólicos en entornos UNIX. Automatiza una sesión remota de Telnet. Identifica claves en ficheros, delimitados por tokens especiales, y los traduce a valores leídos desde otros ficheros de recurso ( resource bundles). Tarea que puede realizar acciones de la herramienta Visual SourceSafe de Microsoft: vsscheckin, etc… Consulta el manual de Ant para más detalles. Compila páginas JSP usando el compilador JSP de Weblogic, weblogic.jspc. Para compilar con un compilador que no sea de Weblogic, usar . Comprueba si ciertos ficheros XML son válidos (o bien formados).
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 construcción. Atributos: Atributo printsummary
fork
Descripción
Imprime estadísticas para cada caso de prueba. Puede tomar los valores on, off y withOutAndErr. Por defecto: off. Ejecuta los tests en una máquina virtual separada.
Controla cuantas instancias de la máquina virtual se crean para los tests. Posibles valores: una por cada prueba (perTest), una por lote (perBatch), y una en total (once). Sólo las pruebas que tienen las mismas opciones de forkmode filtertrace, haltonerror, haltonfailure, errorproperty y failureproperty pueden compartit una MV. Por defecto: perTest. haltonerror Detiene el proceso de construcción si un ocurre algún error. Defecto: off. errorproperty El nombre de una propiedad que establecer en el evento de un error. Detiene el proceso de construcción si ocurre algún fallo. Los errores haltonfailure también se consideran fallos a este efecto. Por defecto: off. failureproperty El nombre de una propiedad a establecer si hay algún fallo en las pruebas. filtertrace timeout
Elimina una todasprueba las trazas de la pila determina Junit y Ant dede lasun trazas error. Cancela individual si no antes ciertodetiempo, dado en milisegundos. Se ignora si fork está desactivado. Cantidad máxima de memoria a reservar para la máquina virtual maxmemory independiente. Se ignora si fork está desactivado. El comando usado para invocar a la máquina virtual Java. Por defecto, es jvm java. El nombre y la ruta del comando se resuelve a través 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. includeantruntime Añadir implícitamente las clases de Ant y la librería JUnit requeridas para ejecutar las pruebas al classpath en modo independiente (usando fork). Envía la salida generada por las pruebas al registro de Ant, así como a los showoutput formatters de salida. Por defecto, sólo los formatters reciben la salida. Envía cualquier salida generada por las pruebas a los formatters de las outputformatters pruebas. Por defecto: true. tempdir Directorio donde Ant debería colocar los archivos temporales. Si debería 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 máquina virtual de Ant en las MV clonevm independientes. Se ignora si fork está desactivado. Por defecto: false.
classpath test batchtest jvmarg sysproperty syspropertyset
env bootclasspath
permissions assertions formatter
Descripción
Representa la ruta en la que buscar las clases que necesita la tarea JUnit. Define una prueba para una clase. Para más detalles, consulta el manual. Define un lote de clases de prueba. Para más detalles, consulta el manual. Si fork está activado, podrán pasársele parámetros adicionales a las nuevas máquinas virtuales a través de un elemento anidado . Especifica propiedades de sistema requeridas por la clase. Estarán disponibles para la máquina virtual durante la ejecución de las pruebas. Pueden especificarse un conjunto de propiedades para usarse como propiedades de sistema con . Es posible especificar variables de entorno para pasar a la máquina virtual independiente usando elementos anidados . Para más detalles, consulte la tarea en el manual de Ant. La ruta de los archivos de clase. Se ignora si fork está desactivado. Concede o revoca permisos durante la ejecución de una clase. Se ignora si fork está activado. Para más detalles, consulte el manual de Ant. Controla la activación de las aserciones de Java 1.4. Actualmente, las sentencias de aserción 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.
Ejemplos:
Ejecuta la prueba definida en la clase en una máquina mis.pruebas.ClasePruebas virtual independiente. Al final de la prueba, se imprimirá una línea resumiendo los resultados. En el archivo TEST-mis.pruebas.ClasePrueba.txt se generará un informe detallado. El proceso de construcción se interrumpirá si alguna prueba falla.
Ejecuta todas las pruebas del directorio dir.clases que incluyen “Test” en su nombre, mostrando información por el registro de Ant y generando informes XML de resultados:
printsummary="yes" showoutput="yes" fork="yes" haltonfailure="no" errorProperty="junit.pruebas.fallo" failureProperty="junit.pruebas.fallo">
Genera documentación sobre los resultados de las pruebas efectuadas con la tarea JUnit en formato HTML, de forma que son visibles desde un navegador. 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 páginas HTML que puede ser visualizado a través de cualquier navegador web. Esta tarea necesita el transformador Apache Xalan o Xalan XSLTC. La versión 1.4 del JDK contenía el Xalan-J versión 2, mientras que con la versión 1.5 del JDK se incluye una versión del XSLTC. Consulta la documentación de Ant de esta tarea para más detalles. Atributos: Atributo
tofile todir
Descripción
El nombre del archivo XML de agregación que se creará a partir de los XML de las pruebas individuales previamente generadas por JUnit. El directorio en el que debería guardarse el archivo XML de agregación.
Elementos anidados: Elemento anidado
Descripción
El elemento anidado sirve para especificar los archivos que la fileset
tarea mezclará para generar el archivo XML agregado. Genera un informe HTML basado en el archivo XML de agregación. Elemento anidado
Descripción
format
Formato del informe generado. Los valores permitidos son frames y noframes. Por defecto: frames. Directorio donde están 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 parámetros XSL a la hoja de estilo.
styledir
report
todir
Elemento anidado
param
name expresión if unless
Descripción
Nombre del parámetro XSL. Valor textual del parámetro. El parámetro sólo se pasará si esta propiedad está establecida. El parámetro se pasará si esta propiedad no está establecida.
El siguiente ejemplo generará un archivo XML de agregación 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 agregación, generará el informe por defecto, con frames, en el directorio “./informes/html”.
El siguiente ejemplo muestra la generación de informes con parámetros XSL. Se mezclarán todos los archivos XML de las pruebas individuales, situados en “./informes/xml” y se generará el habitual archivo XML de agregación TESTS-TestSuites.xml, que se guardará en el mismo directorio “./informes/xml”. Después, leerá la hoja de estilo junit-frames.xsl del directorio “.informes/xsl” y generará el informe HTML en el directorio “./informes/html”.
6.- EJEMPLOS. Tras conocer todos los conceptos básicos de Ant, su uso, y haber practicado un poco con nuestro primer archivo de construcción, es un buen momento para profundizar más en la ejercitación de dichos conocimientos. Para ello, nada mejor que unos cuantos ejemplos de mayor complejidad y que aborden nuevas capacidades. En esta sección se incluyen algunos ejemplos muy ilustrativos de las tareas más habituales que normalmente tendremos que diseñar con Ant para nuestros proyectos. Comenzamos con un ejemplo básico poco más elaborado que el que se proponía como primer archivo de construcción y se irá ahondando en él y proponiendo variantes con nuevas funcionalidades.
6.1.- Aplicación «HolaMundo» básica. El ejemplo que se propone en este apartado contiene la funcionalidad básica más habitual que se destila normalmente para cualquier proyecto de Ant. Se recomienda usar este ejemplo incluso como plantilla inicial para escribir sobre él proyectos más elaborados. Puede consultar el archivo de construcción de este ejemplo básico, con su código completamente comentado para una mayor comprensión de su estructura, en el directorio “ejemplos” incluido junto a este documento, en el subdirectorio “1-basico”.
6.2.- Aplicación «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 versión 4 de JUnit. La versión 4 de este framework de pruebas de unidad introduce las sintaxis de anotaciones para facilitar el proceso de definición de pruebas, así como nuevas características que le dan más potencia y flexibilidad que nunca a nuestras clases de pruebas.
Puede consultar el archivo de construcción 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 máximo y facilitarnos todo el proceso de despliegue de nuestros servlets a un servidor de aplicaciones. En este caso, nuestra elección ha sido el famoso Apache Tomcat, pero la adaptación a otro servidor a partir de esta plantilla es inmediata. Puede consultar el archivo de construcción completo de este ejemplo en el directorio “ejemplos”, dentro del subdirectorio “3-servlet”.
7.- RECURSOS ADICIONALES. En la siguiente sección se recopilan una serie de referencias a recursos de información adicionales sobre las herramientas y tecnologías tratadas en este documento. Siguiéndolas según su propio criterio, el lector podrá ampliar información y conocer en profundidad los conceptos que más 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 también en la distribución binaria que puede descargarse desde su página oficial, supone la referencia más completa y actualizada que se puede encontrar actualmente sobre el uso de Ant. Como referencia no tiene rival alguno. No obstante, para una comprensión y manejo rápidos de Ant, el manual no sea la mejor opción; en ese caso, se recomienda algún tutorial. Para consultar ejemplos complejos, o si se busca un aprendizaje más guiado de la herramienta, se recomienda acudir a un libro. Además, en esta sección se han incluido páginas web con diversos recursos que pueden interesar al lector, como guías, listas de preguntas frecuentes, artículos, etc.
7.1.- Tutoriales. Hay multitud de tutoriales relacionados con Ant en la red, aunque la mayoría están en inglés. Normalmente, tratan de explicar los conceptos básicos de Ant en pocas palabras y guiarnos con ejemplos para ir asimilándolo todo de forma más práctica e intuitiva. Programación en Java J2SE (Tutorial genérico) [ES] http://www.javahispano.org/cursotext.viewer.action?file=index Excelente colección de artículos 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 página web oficial de Ant http://ant.apache.org/manual/tutorials.html Tutoriales de Ant y otras tecnologías 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.
7.2.- Páginas web. En esta sección encontrará referencias a diversos recursos web y artículos online que pueden resultar interesantes como lectura adicional al contenido de este documento. También se incluyen enlaces a herramientas o tecnologías cuyo uso con Ant podría resultar de interés, así como a páginas web con artículos, 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/
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
Artículos TheServerSide.com – Your Enterprise Java community (excelente página) 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
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
7.3.- Libros. Título: Java 2 v5.0. Autor: Richardson, Avondolio, Vitale. Editorial: Anaya Multimedia (España). Fecha: Junio de 2005. I.S.B.N.: 978-84-415-1855-1. Nº páginas: 704. Descripción: Libro en castellano con una curiosa y bastante original organización de sus contenidos. Empieza dando un repaso a las características de Java v5.0. Después, comenta técnicas y herramientas de desarrollo de aplicaciones Java, entre las que prima Ant. Sigue con un capítulo sobre patrones de diseño (sí, este es de los pocos libros que hablan de diseño), interfaces gráficas, manejo de datos con XML, JDBC, JSP, JSTL, interacción con con C/C++ EJB,extenso RMI, CORBA, web, procesos distribuidos JMSusando y JMX,JNI, un muy capítuloservicios sobre seguridad y, para terminar, empaquetado e instalación de aplicaciones Java. Título: Autores: Editorial: Fecha: I.S.B.N.: Nº páginas:
Apache Tomcat 5. Chopra, Bakore, Eaves. Anaya Multimedia (España). Noviembre de 2004. 978-84-415-1780-6. 608.
Descripción: Completísimo librosobre en castellano trata todos los aspectos este popularque servidor de aplicaciones. Además, en su apéndice C dedica unas páginas a hablar sobre Ant, describiendo su instalación y explicando todos sus principales conceptos y su uso fundamental. Título: Autor: Editorial:
Java 2 v5.0. Felipe Lima Díaz. Anaya Multimedia (España).
Fecha: Noviembre de 2005. I.S.B.N.: 978-84-415-1946-6. Nº páginas: 496. Descripción: Otro completísimo libro en castellano que trata un buen número de tecnologías. Empieza por dar un repaso a las nuevas características de la versión 5 de Java, así como sus otros conceptos generales. Después, da unas buenas nociones básicas sobre sockets, threads, JDBC, JNI, servlets, JSP, Struts, JUnit, RMI, seguridad en Java, e incluso llega a hablar un poco de EJB. Una gran elección como libro de iniciación. Dedica un capítulo entero a Maven, la alternativa más popular a Ant.
Ant in action. Loughran, Hatcher. Manning publications (EEUU). Mayo de 2007. 978-19-323-9480-1. 672.
Descripción: El completo actualizado quelibro puedemás encontrarse hoyy en día sobre Ant. Su inconveniente es que no está en castellano. En realidad es la 2ª edición de un auténtico best-seller titulado «Java development with Ant», del mismo autor, con un nuevo título. Cubre todas las nuevas posibilidades de la versión 1.7 en mucha profundidad: las antlibs, el desarrollo con EJB 3.0 & J2EE, el despliegue avanzado de aplicaciones usando SmartFrog, validación de esquemas XML, o la administración de repositorios con Ivy. Recomendado, por supuesto, a todo aquel que quiera profundizar al máximo en las capacidades de Ant. Título: Ant – The definitive guide. Autor: Steve Holzner. Editorial: O'Reilly Media (EEUU). Fecha: Abril de 2005. I.S.B.N.: 978-05-960-0609-9. Nº páginas: 316. Descripción: Excelente libro de la conocida editorial O’Reilly. Muy bien estructurado, propone un coherente recorrido de aprendizaje, desde los conceptos más simples y básicos de Ant, como propiedades y tareas. El libro es extremadamente práctico, orientado a resultados: enseña los fundamentos necesarios para que el desarrollador novato pueda compilar, empaquetar, desplegar, y probar aplicaciones. También se discute en profundidad las capacidades de integración de Ant con Subversion para mantenimiento de repositorios de código. Se dedica un capítulo a explicar XML, así como el uso de XDoclet y XSLT. Finalmente, se explica el uso de las tareas opcionales, integración de Ant & Eclipse, y como crear tareas propias. Título: Pro Apache Ant. Autor: Matthew Moodie. Editorial: Apress (EEUU). Fecha: Noviembre de 2005. I.S.B.N.: 978-15-905-9559-6. Nº páginas: 360. Descripción: Una buena alternativa a los dos primeros títulos. Estructurado de una manera muy lógica, explica las cosas muy claramente. Empieza con Una introducción Ant al lector, y posteriormente aborda su instalación, uso, los tipos de datos de Ant, compilación, despliegue, documentación, prueba y ejecución de aplicaciones con Ant. Después, dedica un interesante capítulo al uso de Ant con proyectos grandes. Finalmente, trata con un reseñable detalle la creación de tareas propias, la extensión de Ant, y termina con una interesante serie de consejos sobre el uso de su API. - 75 http://slidepdf.com/reader/full/construyendo-aplicaciones-con-apache-ant
8.- FUENTES. En esta sección se recogen las fuentes de información fundamentales que se han consultado para la elaboración de este documento. Este grupo de referencias suponen un conjunto de documentación básico para conocer los principios más importantes de la herramienta, pero no necesariamente profundizan en muchos aspectos de la misma. Las referencias de información más completas y actualizadas suele ser la de las páginas web oficiales de las tecnologías tratadas. Para una puesta en marcha rápida, la mejor elección es algún tutorial. Si buscamos ejemplos elaborados o un aprendizaje guiado en detalle, normalmente es mejor acudir a un libro. Para aquellos que busquen más información, en la sección “Recursos adicionales” se propone una lista mucho más exhaustiva de fuentes de información de varios tipos con los que aprender sobre el más mínimo detalle acerca del uso y comportamiento de Ant.
Ant Wikipedia [ES] http://es.wikipedia.org/wiki/Apache_Ant Página 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 Página 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 construcción – incluso más que Ant [ES] http://www.programacion.net/java/tutorial/jap_maven/ Descripción técnica de Maven [ES] http://metaware-inc.wiki.mailxmail.com/AntMaven Maven magic http://www.theserverside.com/tt/articles/article.tss?l=MavenMagic - 76 http://slidepdf.com/reader/full/construyendo-aplicaciones-con-apache-ant
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 Página 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
9.- HISTORIAL. En esta sección se incluye información propia de este mismo documento. Con miras a un futuro mantenimiento y ampliación del documento, aquí se documentarán los cambios producidos entre las distintas versiones del mismo. Version 1.4 (Martes 20 de Febrero de 2007) -
Reestructurada la sección CONCEPTOS BÁSICOS y añadido un nuevo apartado para hablar de los elementos para especificar rutas: y . Además, se ha revisado la redacción y el estilo y añadido nuevos ejemplos de código.
Version 1.3 (Lunes 12 de Febrero de 2007) -
Nueva sección con las tareas de Ant agrupadas por funcionalidad. La información dada en esta nueva sección nos será muy valiosa como clarificadora de la división de las tareas Antfuncionalidad y como referencia rápida para buscar la tarea que hace una determinada que estamos buscando.
Versión 1.2 (Sábado 10 de Febrero de 2007) -
Añadidas muchas más referencias a recursos adicionales online. También se han reestructurado dichas referencias en más bloques para facilitar su organización. Se amplía el número de ejemplos con uno adicional que expone el uso de Ant para facilitar el despliegue de nuestros servlets hacia un servidor de aplicaciones.
Versión 1.1 (Lunes 5 de Febrero de 2007) -
Ampliación de secciones: ahora se incluyen nuevas secciones dedicadas a explicar conceptos básicos como “referencias” y “recursos”. Se han reorganizado los contenidos, creando una sección propia dedicada a explicar los CONCEPTOS BÁSICOS de la herramienta, así como otra dedicada a explicar los fundamentos de EL ARCHIVO DE CONSTRUCCIÓN. Nueva sección HISTORIAL para constatar cambios entre versiones del documento.
