Spring BeanDoc. Primeros pasos

Una de las cosas que tiene Spring por las cuales creo me ha comenzado a gustar es que, tiene todo un conjunto de proyectos al rededor del framework principal.

Solo tenemos que ver el listado dentro del sitio oficial de Spring para darnos cuenta de esto:

• Spring Framework
• Spring Web Flow
• Spring Web Services
• Spring Security (Acegi Security)
• Spring Dynamic Modules For OSGi(tm) Service Platforms
• Spring Batch
• Spring Integration
• Spring LDAP
• Spring IDE
  
• Spring Modules
• Spring JavaConfig
• Spring Rich Client
• Spring .NET
• Spring BeanDoc

De entre todos estos proyectos, le he dado una revisada al Spring BeanDoc y me ha encantado ya que existen un par de cosas que he aprendido sobre la documentacion:

• Nunca es suficiente la documentación que dejas sobre tu código.
• Mientras mas documentación legible dejes, menos te maldecirá la persona que lo retome.
• Dicha persona puedes ser tu mismo si vuelves tiempo después al mismo proyecto :P

Por eso es que me ha encantado este subproyecto de Spring, ya que, como su nombre lo dice, ayuda a documentar la información de los Beans que utilizas en tu aplicación.

El presente documento muestra cuales son los pasos para poner en marcha y utilizar las bondades de esta herramienta:

Paso 1. Accedemos a la página principal del proyecto y descargamos la última distribución estable.
http://spring-beandoc.sourceforge.net/

Figura 1. Home de Spring BeanDoc

Este es el enlace para descargar la version 0.8.1

http://sourceforge.net/project/showfiles.php?group_id=209187

Figura 2. Descarga desde sourceforge

Descargamos el archivo: spring-beandoc-0.8.1-bin.zip

Una vez descargado, al descomprimirlo obtenemos una estructura como la siguiente:

Figura 3. Estructura de carpetas de Spring BeanDoc.

La página principal nos pide que instalemos adicionalmente un programa que nos ayuda a generar los grafos de la documentación.

Paso 2. Instalación de GraphViz.

Visitamos http://graphviz.org/

Figura 4. Home de graphviz.org

El enlace para descargar la versión actual - para Windows - es:

http://graphviz.org/Download_windows.php

Descargamos el archivo:graphviz-2.16.1.exe

Lo ejecutamos:

Figura 5. Instalación de Graphviz.

Al terminar la instalacion, debe quedarnos una estructura como la siguiente:

Figura 6. Estructura de carpetas de Graphviz.

Paso 3. Proceso de verificación.

A grandes rasgos, Spring BeanDoc genera la documentación y los grafos a partir de los XML's de configuracion de nuestros spring Beans.

La siguiente imagen intenda ilustrar esto:

Figura 7. Diagrama de bloques de Spring BeanDoc.

La ubicación de esos XML's y otros parámetros de configuración se definen en un archivo .properties y a partir de él Spring BeanDoc se encarga de hacer el trabajo sucio.

Aquí las modificaciones que realice al archivo petclinic-beandoc.properties que se ubica dentro de la carpeta de examples:

• Se definio la ubicación de los XML's de entrada
• Se definio la carpeta de salida
• Se definio la ubicación del archivo dot.exe que genera los grafos.

# ----------------------------------------------------------------------------
# Petclinic beandoc.properties configuration file.
#
# See the 'template-beandoc.properties file for annotated examples of what
# you can configure.
# ----------------------------------------------------------------------------

input.files=C:/WorkArea/dev/spring/beandoc/spring-beandoc-0.8.1/samples/petclinic/*.xml
output.dir=output/petclinic

html.title=Petclinic Application Context
html.cssUrl=wheat.css


compiler.dotExe=C:/Program Files/Graphviz2.16/bin/dot.exe

graphs.colourBeans[.*Proxy$]=#badbad
graphs.ignoreBeans[0]=^org\.springframework.*Property.*Configurer
graphs.ignoreBeans[1]=.*MessageSource
graphs.rankBeans[0]=.*DataSource
graphs.outputType=png
# ----------------------------------------------------------------------------

Ya que tenemos definido nuestro archivo properties, solo necesitamos ejecutar la clase que realiza la transformación:

Esta es:
org.springframework.beandoc.client.BeanDocClient

Esa clase se encuentra en el jar: spring-beandoc-0.8.1.jar y recibe un como parametro el archivo .properties.

Así, para generar nuestra documentación a partir del ejemplo del petclinic tenemos que debemos ejecutar:

[INSTALL_BEANDOC]/samples> java org.springframework.beandoc.client.BeanDocClient --properties petclinic-beandoc.properties

[Asegurate de agregar todos los jars ubicados en la carpeta [INSTALL_BEANDOC]\lib para que la compilación no se queje con un NoClassDefFoundError o en su defecto ejecutalo con la opcion -cp]

Y listo!!!

Figura 8. Documentación generada con la herramienta.

Hemos generado nuestra documentación de nuestro proyecto spring a partir de nuestros archivos XML utilizando la herramienta BeanDoc.

Saludos!!!
RuGI
Isaac Ruiz Guerra.