Xdoclet Java todavía más fácil

Una de las cosas que más me gustó de Java cuando lo conocí fué la elegancia que se desprende del lenguaje. El hecho de que sea un lenguaje orientado a objetos con gestión de excepciones y sin necesidad de usar punteros por parte del programador, es algo que todos los que nos hemos peleado con el código agradecemos profundamente (sí sí... sé que muchos de los nerds que me podrían leer me dirian que los punteros son muy útiles... y no les falta razón... si es que los que somos unos inútiles somos los humanos, que tendemos a equivocarnos).
Pero las cosas no podían ser todas de color de rosa, Java fué creciendo y con él también crecieron las tecnologías que le rodeaban. Todavía me acuerdo del primer servlet que programé (allá por el año 98) que después instalé en el JRun sin demasiadas complicaciones. La realidad ha cambiado y ahora los servlets se supone que han de estar comprendidos en una aplicación web. Y aquí es donde se empieza a complicar la cosa. Ya no basta con implementar una interfaz, ahora hay que crear un descriptor de despliegue (deployment descriptor).
Se ha pasado de desarrollar aplicaciones standalone a aplicaciones hospedadas en contenedores. Las ventajas son muchas, simplificación de la programación al tener un montón de servicios disponibles para las aplicaciones de negocio. Desde la seguridad, la transaccionalidad, las trazas, etc... son servicios facilmente accesibles para los desarrolladores sin necesidad de tener que programarlos uno mismo. La desventaja mayor podría ser el hecho de que para poder acoplar dicha aplicación en el contenedor, tenemos que crear el famoso descriptor de despliegue.
Hasta ahora los descriptores de despliegue han sido unos archivos xml que basicamente definen como se debe de conectar el componente que se ha desarrollado en el contenedor que lo va a alojar. De esta manera, estamos haciendo uso de los servicios que nos proporciona el servidor sin tener que programar practicamente nada.
Pero si se va a tener un descriptor de despliegue para una aplicación, suena razonable pensar que se ha de estar tocando dicho descriptor constantemente según se vaya avanzando en dicha aplicación. Resultando una tarea pesada el estar constantemente revisándolo, preocupándose por su validez tanto semántica como sintáctica. Y aquí es donde comienza el meollo de la cuestión...
Volviendo a la elegancia de java, una de las cosas que más me gusta de java son sus fantásticos Javadocs. Siempre que he tenido que alejarme de java para usar otro lenguaje me he encontrado con que la documentación de ese lenguaje solía ser, en el 99% de los casos, peor de lo que normalmente es en el mundo java. Eso se debe a que Sun se preocupó mucho de hacer la tarea de documentación algo rápido y productivo para los desarrolladores (que tanto odiamos estar comentando cosas que a veces ni siquiera hemos hecho nosotros).
Javadoc es una herramienta incluida en todo jdk que sirve para leer el código fuente de una aplicación java y producir la documentación de la misma. El proceso es sencillo, basta con poner unos comentarios (que empiezan por /** y terminan por */) junto con unas etiquetas especiales (siempre empiezan por @).
Así, por ejemplo, si queremos producir la documentación de una clase bastaría con poner lo siguiente:

/**
* Clase de ejemplo para el uso de javadocs
* @author Eduardo de Vera
* @version 1.0
*/
public class ClaseDocumentada {

/**
* Metodo de ejemplo para javadoc
* @param parametro que le pasamos a la documentación
* @return String de retorno
*/
public String method (String parametro)
{
return parametro;
}
}

Si esta clase la pasamos por la herramienta javadoc, nos producirá un bonito archivo html con los comentarios formateados. Queda fuera de este artículo explicar paso a paso como crear javadocs, pero estoy seguro de que hay mucha información en la red para poder hacerlo.
Bien, llegados a este punto el lector se estará preguntando qué tipo de cacao estoy montando entre descriptores de despliegue y javadocs (con toda la razón del mundo porque aparentemente no tienen nada que ver).
Y es aquí donde llega la unión de ambas cosas: XDoclet. Xdoclet amplia el conjunto de etiquetas especiales javadoc (@algo) para poder crear, además de documentación, archivos de despliegue. Ahora todo lo que comprende a nuestra aplicación está en un único punto, el código fuente. Eso nos da una ventaja tremenda puesto que no tenemos que estar saltando de archivo en archivo sintentando seguir la lógica del contenedor. Ahora tenemos todo lo que involucra a una clase (servlet, ejb, action, hibernate pojo, etc...) en un único archivo (el código fuente de la clase) disponible con un simple click.
Después solo tenemos que pasar Ant o Maven con su extensión de Xdoclet y, casi por arte de magia, se nos crearán los archivos de despliegue, se compilará la aplicación y se nos empaquetará lista para entregarla al cliente.
Para ver lo sencillo que puede ser hacer un servlet que será contenido en una aplicación web, bastaría con ver el siguiente ejemplo:

package org.etux.servlets;

import javax.servlet.http.*;
import java.io.IOException;

/**
* @web.servlet description="Descripción del servlet" display-name="Nombre del servlet a mostrar" name="ServletEjemplo"
* @web.servlet-mapping url-pattern="/servletEjemplo"
*
* Comentarios normales del javadoc
* @author Eduardo de Vera
* @version 1.0
*/
public class ServletEjemplo
{
protected void doPost(HttpServletRequest request, HttpServletResponse) throws ServletException, IOException {
//logica del servlet
}

protected void doGet(HttpServletRequest request, HttpServletResponse) throws ServletException, IOException {
//logica del servlet
}
}

Una vez que pasasemos el archivo por el xdoclet (usando ant o maven) obtendríamos un web.xml con los siguientes datos:


...
<servlet>
<servlet-name>ServletEjemplo</servlet-name>
<display-name>Nombre del servlet a mostrar</display-name>
<description><!--[CDATA[Descripción del servlet]]--></description>
<servlet-class>org.etux.servlets.ServletEjemplo</servlet-class>
</servlet>

<servlet-mapping>
<servlet-name>ServletEjemplo</servlet-name>
<url-pattern>/servletEjemplo</url-pattern>
</servlet-mapping>
...


Obviamente no hemos usado todas las etiquetas disponibles para los servlet, pudiéndose poner parámetros de inicialización de los servlets, por ejemplo. También hay que destacar que esto es xdoclet aplicado a servlets, pero la lista de tecnologías para las que se usa xdoclet no para de crecer, siendo las más destacadas ejb, servlets, struts, hibernate, jdo, jmx, spring, etc...