Una de las herramientas más importantes con las que cuenta la plataforma Java es, sin duda, el javadoc. A través de ella es posible crear una referencia completa y homogénea de todo el conjunto de clases definidas es nuestro proyecto.

Toda página de una clase del javadoc está dividida en distintas zonas, la primera de ellas muestra la situación jerárquica de la clase respecto a la clase padre Object. Bajo la situación jerárquica aparece la lista de interfaces que implementa si existe alguna y, por último, la lista de clases que la extienden. Para las interfaces aparece la lista de superinterfaz en primer lugar y la lista de subinterfaces en segundo.

Aunque esta información pueda ser suficiente en muchos casos, no estaría de más completarla con diagramas de clases que permitan una rápida visualización de la jerarquía de clases de nuestro proyecto. Ese es el objetivo de este post, añadir diagramas de clases UML a nuestro javadoc.

Para ello necesitaremos dos cosas básicamente :

• Graphviz, librería que permite la generación de gráficos.
• UMLGraph plugin para maven que sobreescribe el doclet que genera el javadoc para insertar los gráficos generados por Graphviz.
• Maven

A continuación vamos a ver como instalar Graphviz y como configurar el pom.xml del proyecto maven para que use el plugin UMLGraph.

Instalación de Graphviz

Hay varias formas de hacerlo, bajando el fuente y compilando, haciendo un checkout del repositorio CVS o dejando que el sistema de paquetes de tu sistema operativo lo haga todo por tí . Esto último es lo que haremos pues la finalidad de éste post es otra.

sudo apt-get update
sudo apt-get install graphviz
man dot

La última entrada es sólo para comprobar que el paquete ha sido instalado correctamente.

Modificación del fichero pom.xml del proyecto

Simplemente se debe añadir al fichero las siguientes líneas de código

...
<reporting>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <configuration>
        <doclet>gr.spinellis.umlgraph.doclet.UmlGraphDoc</doclet>
        <docletArtifact>
          <groupId>gr.spinellis</groupId>
          <artifactId>UmlGraph</artifactId>
          <version>4.6</version>
        </docletArtifact>
        <additionalparam>
          -inferrel -inferdep -quiet -hide java.* -collpackages java.util.* -qualify
          -postfixpackage -nodefontsize 9
          -nodefontpackagesize 7
        </additionalparam>
      </configuration>
    </plugin>
  </plugins>
</reporting>
...

Para generar el javadoc se ejecutará el comando mvn javadoc:javadoc dentro del directorio
donde se encuentra el fichero pom.xml.

Hoy he empezado a trabajar en las oficinas del cliente del proyecto que me ocupará los próximos meses y he tenido que configurar todo mi sistema para que se conecte a Internet a través de un proxy. Aunque esta configuración es trivial, voy a comentar los ficheros que hay modificar para que tanto Maven como Subversion pueden acceder a repositorios externos a través de un proxy.

Maven

En Maven el fichero que tiene que ser modificado se llama settings.xml y está situado bajo el directorio $MAVEN_HOME/config, siendo $MAVEN_HOME el directorio base de instalación de Maven.

Dentro de este fichero será necesario buscar el siguiente bloque de código :

<proxies>
<proxy>
<id>optional</id>
<active>true</active>
<protocol>http</protocol>
<username>proxyuser</username>
<password>proxypass</password>
<host>proxy.host.net</host>
<port>80</port>
<nonProxyHosts>local.net,some.host.com</nonProxyHosts>
</proxy>
</proxies>

Simplemente debéis establecer los parámetros de la configuración de acceso al proxy en los elementos correspondientes, por ejemplo :

<proxy>
<!-- Parámetro opcional -->
<id>Proxy oficina cliente</id>
<active>true</active>
<protocol>http</protocol>
<username>proxyUser</username>
<password>proxyPassword</password>
<host>10.23.22.43</host>
<port>80</port>
<!-- Direcciones a excluir de pasar por el proxy -->
<nonProxyHosts>localhost, 10.23.23.44</nonProxyHosts>
</proxy>
</proxies>

Subversion

La configuración de Subversion es muy parecida, aunque permite mayor flexibilidad. En este caso el fichero a modificar se encuentra en la ruta /etc/subversion/servers. La flexibilidad que aporta Subversion a la hora de configurar el acceso a un repositorio via proxy está reflejada en la posibilidad de configurar un proxy global para todos los repositorios o la posibilidad de establecer la configuración de un proxy para grupo de repositorios.

El ficheros de configuración base es el siguiente :

### This file specifies server-specific protocol parameters,
### including HTTP proxy information, and HTTP timeout settings.
###
### The currently defined server options are:
###   http-proxy-host            Proxy host for HTTP connection
###   http-proxy-port            Port number of proxy host service
###   http-proxy-username        Username for auth to proxy service
###   http-proxy-password        Password for auth to proxy service
###   http-proxy-exceptions      List of sites that do not use proxy
###   http-timeout               Timeout for HTTP requests in seconds
###   http-compression           Whether to compress HTTP requests
###   neon-debug-mask            Debug mask for Neon HTTP library
###   ssl-authority-files        List of files, each of a trusted CAs
###   ssl-trust-default-ca       Trust the system 'default' CAs
###   ssl-client-cert-file       PKCS#12 format client certificate file
###   ssl-client-cert-password   Client Key password, if needed.
###
### HTTP timeouts, if given, are specified in seconds.  A timeout
### of 0, i.e. zero, causes a builtin default to be used.
###
### The commented-out examples below are intended only to
### demonstrate how to use this file; any resemblance to actual
### servers, living or dead, is entirely coincidental.

### In this section, the URL of the repository you're trying to
### access is matched against the patterns on the right.  If a
### match is found, the server info is from the section with the
### corresponding name.

[groups]
# group1 = *.collab.net
# othergroup = repository.blarggitywhoomph.com
# thirdgroup = *.example.com

### Information for the first group:
# [group1]
# http-proxy-host = proxy1.some-domain-name.com
# http-proxy-port = 80
# http-proxy-username = blah
# http-proxy-password = doubleblah
# http-timeout = 60
# neon-debug-mask = 130

### Information for the second group:
# [othergroup]
# http-proxy-host = proxy2.some-domain-name.com
# http-proxy-port = 9000
# No username and password, so use the defaults below.

### You can set default parameters in the 'global' section.
### These parameters apply if no corresponding parameter is set in
### a specifically matched group as shown above.  Thus, if you go
### through the same proxy server to reach every site on the
### Internet, you probably just want to put that server's
### information in the 'global' section and not bother with
### 'groups' or any other sections.
###
### If you go through a proxy for all but a few sites, you can
### list those exceptions under 'http-proxy-exceptions'.  This only
### overrides defaults, not explicitly matched server names.
###
### 'ssl-authority-files' is a semicolon-delimited list of files,
[global]
# http-proxy-exceptions = *.exception.com, www.internal-site.org
# http-proxy-host = defaultproxy.whatever.com
# http-proxy-port = 7000
# http-proxy-username = defaultusername
# http-proxy-password = defaultpassword
# http-compression = no
# No http-timeout, so just use the builtin default.
# No neon-debug-mask, so neon debugging is disabled.
# ssl-authority-files = /path/to/CAcert.pem;/path/to/CAcert2.pem

Como puedes observar, en la primera parte del fichero se definen los grupos, groups, con la url de los repositorios asociados.

[groups]
group1 = *.collab.net
othergroup = repository.blarggitywhoomph.com
thirdgroup = *.example.com

Observad que se permite el mapeo de todos los subdominios de un dominio mediante el uso de *.

En la segunda parte del fichero, se especifica la configuración del proxy asociada a cada grupo. En primer lugar se especifica, [entre corchetes] el nombre del grupo de repositorios a configurar y posteriormente los parámetros propios de configuración del proxy, cuyos nombres son autoexplicativos.

[group1]
http-proxy-host = proxy1.some-domain-name.com
http-proxy-port = 80
http-proxy-username = blah
http-proxy-password = doubleblah
http-timeout = 60

Por último, es posible definir una configuración global de acceso a todos los repositorios, se realiza bajo la etiqueta [global]

[global]
http-proxy-exceptions = localhost, 10.23.23.44
http-proxy-host = 10.23.22.43
http-proxy-port = 80
http-proxy-username = proxyUser
http-proxy-password = proxyPassword

Para una configuración más avanzada consultar la referencia oficial.