Maven JXR Plugin: publica el código fuente en el site.
0. Índice de contenidos.
- 1. Introducción.
- 2. Entorno.
- 3. Configuración.
- 4. Informe «Source Xref».
- 5. Configuración con PMD.
- 6. Configuración con CheckStyle.
- 7. Tips & Tricks.
- 8. Conclusiones.
1. Introducción
JXR es un plugin para maven, de tipo reporting, que genera en el site un informe con los fuentes java de tu aplicación: «Source Xref».
Con la misma estructura de páginas que el javadoc (FRAMES NO FRAMES), se puede navegar por el código fuente de las clases gracias a que incluye hiperenlaces entre las mismas.
El plugin, además, sirve como base para otros plugins que generan informes basados en el código fuente. De este modo, configurado con PMD, permite el acceso directo a la línea de código que provoca la violación de una regla desde el propio informe de PMD.
2. Entorno.
El tutorial está escrito usando el siguiente entorno:
- Hardware: Portátil Asus G1 (Core 2 Duo a 2.1 GHz, 2048 MB RAM, 120 GB HD).
- Sistema operativo: Windows Vista Ultimate.
- JDK 1.5.0_15
- Eclipse 3.4, con q4e.
3. Configuración.
La configuración del plugin es bastante simple, en la sección de reporting del fichero de descripción del proyecto (pom.xml), debemos incluir la dependencia al plugin:
...... ...... org.apache.maven.plugins maven-jxr-plugin
En el site del plugin podemos encontrar una configuración para un proyecto multimódulo: basta con incluir la etiqueta <aggregate> a la configuración:
...... ...... org.apache.maven.plugins maven-jxr-plugin ... true ...
Se puede configurar en comandita con el plugin que genera el javadoc, de modo que desde el informe de «Source Xref», al acceder al código fuente de una clase tengamos un acceso directo al javadoc de la misma:
...... ...org.apache.maven.plugins maven-javadoc-plugin ... org.apache.maven.plugins maven-jxr-plugin ... true /apidocs ...
En la etiqueta <javadocDir> se configura el path relativo para acceder al raíz del javadoc publicado. Al ejecutarlo en local puede que no se enlace correctamente, el enlace será el correcto una vez publicado el site en un servidor web (podéis comprobarlo ejecutando mvn site:run y accediento al site a través de http://localhost:8080 en un browser).
4. Informe «Source Xref».
El informe se generará dentro del ciclo de vida de maven, en el goal específico del site, en la fase de release, o invocándo a la generación de una manera directa. Si estamos trabajando con Elcipse y q4e:
En la sección de informes del site se generará la opción correspondiente a la informe «Source Xref»:
Pulsando sobre la misma se mostrará una página, del estilo del javadoc, con acceso a los paquetes y las clases, mostrando el código fuente de las clases de la aplicación:
Si lo hemos configurado correctamente en la cabecera de cada fuente se podrá enlazar con el javadoc y desde el propio fuente se puede navegar por las clases incluidas en la distribución, como en el ejemplo desde la clase HibernateDao se accede a la interfaz Dao:
5. Configuración con PMD.
Podemos configurar que el informe de PMD incluya un enlace directo al código que causa la violación de la regla. Para ello basta con incluir la etiqueta <linkXref> a true:
...... ...... org.apache.maven.plugins maven-pmd-plugin 2.4 true UTF-8 20 1.5 /rulesets/clone.xml /rulesets/j2ee.xml
Ahora, desde el propio informe, se puede acceder al código fuente mediante un enlace a la línea que aparece a la derecha de la fila. En el ejemplo mostramos una violación de código duplicado con cpd:
6. Configuración con CheckStyle.
La configuración con CheckStyle es transparente, basta con incluir la configuración del plugin, y enlaza por defecto con el informe de Xref.
...... ...... org.apache.maven.plugins maven-checkstyle-plugin config/maven_checks.xml
A continuación, un ejemplo del resultado:
Efectivamente y sí, a la clase le falta el javadoc ;-).
7. Tips & Tricks.
En función del volumen de la aplicación y el número de informes que tengamos configurados, maven puede que necesite más memoria que la asignada por defecto a la jvm que lo ejecuta y se produzca un java.lang.OutOfMemoryError: Java heap space.
Para estos casos podemos redimensionar el tamaño de la memoria asignado al proceso, definiendo la variable de entorno MAVEN_OPTS.
En el ejecutable mvn o mvn.bat, podemos configurarla, puesto que viene con un ejemplo de ello:
set MAVEN_OPTS=-Xms512m -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=256m
8. Conclusiones.
Maven no nos deja de sorprender y, cada día que pasa, se hace más imprescindible en nuestra casa.
La configuración via plugins, esto es, el hecho de que con una simple configuración obtengamos tanta funcionalidad, lo hace cada vez más potente.
Nuestra experiencia nos dicta que debemos invertir tiempo en mejorar la calidad y, con esta herramienta, el análisis de los informes relacionados con la misma se hace más legible.
Si necesitáis ayuda en la definición de vuestro marco de trabajo o en la configuración de las métricas de calidad, podeis contactarnos en autentia.com.
Un saludo.
Jose
