Wednesday, April 28, 2010

Un sencillo Add-on de Spring Roo

Ya tenia ganas de meterme un poquito a las entrañas de Spring Roo para crear un Add-on. Por esa razón estoy escribiendo este pequeño post sobre como crear un Add-on "sencillito" y carismático.

Empezaremos creando el proyecto de un Add-on con el propio Spring Roo de la siguiente forma:


roo> project --topLevelPackage com.jabaddon.practices.springroo.addons.addonsencillito.roo.addon --template ROO_ADDON_SIMPLE


Como lo pueden notar Spring Roo ya viene con un template de proyecto del tipo Add-on Simple. Es importante mencionar que el paquete del proyecto debe terminar en .roo.addon de lo contrario el propio shell les mostrara un mensaje como el siguiente:


Roo add-ons must have a package name ending in .roo.addon; eg com.mycompany.myproject.roo.addon


¿Y porque debe terminar el paquete en .roo.addon? Debido a que a la hora que inicia el Shell de Spring Roo hace un monitoreo del classpath buscando nuevos Add-ons que cargar y es justamente aquellos paquetes que terminan en .roo.addon los que busca y carga.

Ok, despues de ejecutar la creacion del proyecto la estructura de folders y archivos queda de la siguiente forma:


.
|____legal
| |____LICENSE.TXT
|____log.roo
|____pom.xml
|____readme.txt
|____src
| |____main
| | |____assembly
| | | |____assembly.xml
| | |____java
| | | |____com
| | | | |____jabaddon
| | | | | |____practices
| | | | | | |____roo
| | | | | | | |____addons
| | | | | | | | |____addonsencillito
| | | | | | | | | |____roo
| | | | | | | | | | |____addon
| | | | | | | | | | | |____Commands.java
| | | | | | | | | | | |____Operations.java
| | | | | | | | | | | |____PropertyName.java
| | |____resources
| | | |____META-INF
| | | | |____spring
| | | | | |____applicationContext.xml
| | | | | |____log4j.properties
| | |____webapp
| |____test
| | |____java
| | |____resources


El template del proyecto ha creado 3 clases: Commands.java, Operation.java y PropertyName.java; entre otros archivos.

Si abrimos la clase Commands.java notaremos que es una clase que implementa la interfaz: org.springframework.roo.shell.CommandMarker. Las clases que implementan esta interfaz son aquellas que a la hora de iniciar Spring Roo lee y carga. Ademas, esta marcada con la anotación @ScopeDevelopmentShell que le indica a Roo que la clase debe ser creada cuando el Shell de desarrollo es usado.

Notaremos también que hay métodos marcados con la anotación @CliAvailabilityIndicator. Esta anotación le indica al Shell de Roo los métodos que sirven para indicar si un cierto comando esta disponible o no. Esta anotación solo aplica para métodos públicos que no reciben argumentos y que regresan boolean. Se recomienda que la ejecución de este método no sea costosa ya que los métodos que indican si un comando esta disponible o no son llamados regularmente.

Los métodos marcados con la anotación @CliCommand son, en si, la ejecución de un comando. Esta anotación tiene dos parámetros: value, que indica el nombre del comando (pueden ser una o mas cadenas) y help, una cadena con un mensaje de ayuda para el comando.

La clase Commands tiene como atributo a la clase Operation (que recibe en el constructor). Esta clase Operations esta marcada con la anotación @ScopeDevelopment que le indica a Roo que debe instanciar estas clases e inyectarlas a los CommandMaker que tengan constructores que reciban objetos de su tipo.

Basicamente, un Add-on de Spring Roo debe crear clases "Comando" que implementen la interfaz CommandMaker y delegar a objetos "Operaciones" la ejecución de los mismos.

Ok, dejemos un poco al lado la teoría y vayamos un poco mas a la acción. Vamos a instalar el add-on de este proyecto y ver como trabaja.

Para lograr esto ejecutaremos dentro del shell de Roo el comando:


roo> perform assembly


Esto creara un .zip dentro de target el cual es el add-on a instalar con todo lo que necesita (dependencias, recursos, etc.).

Como ejercicio si quieren agreguen dependencias al proyecto, recursos, etc. y ejecuten el "perform assembly" y vean las entrañas del .zip para que vean como va empaquetado un Add-on.

Ya teniendo el .zip lo instalamos desde el shell de Roo con el comando:


addon install --url file://[ruta hacia el .zip]


Esto copiara el .zip a $ROO_HOME/add-ons (si no funciona el comando copien el archivo directamente).

Ahora si reinician el shell de Roo y corren el comando:


roo> addon clean


tendrán la salida:


Loaded com.jabaddon.practices.roo.addons.addonsencillito.roo.addon.Commands; try the 'welcome' commands
____ ____ ____
/ __ \/ __ \/ __ \
/ /_/ / / / / / / /
/ _, _/ /_/ / /_/ /
/_/ |_|\____/\____/ 1.0.0.RELEASE [rev 564]


Welcome to Spring Roo. For assistance press TAB or type "hint" then hit ENTER.


Noten el mensaje de la carga del Addon.

¿Quien imprimió ese mensaje? Solo hay que ver el constructor de la clase Commands.


public Commands(StaticFieldConverter staticFieldConverter, Operations operations) {
Assert.notNull(staticFieldConverter, "Static field converter required");
Assert.notNull(operations, "Operations object required");
staticFieldConverter.add(PropertyName.class);
this.operations = operations;
logger.warning("Loaded " + Commands.class.getName() + "; try the 'welcome' commands");
}


Ok, ahora si escribimos "welcome" en el shell y damos "tab" el shell de Roo nos mostrara los comandos disponibles que empiezan con "welcome".


roo> welcome

welcome property welcome write hej welcome write hello


Esos comandos son justamente los declarados en la clase Commands.

Si ejecutamos el comando:


roo> welcome property


Obtendremos como salida:


roo> welcome property
Username : Abaddon


Y si escribimos "welcome property --name" y damos "tab" obtendremos como salida:


roo> welcome property --name

HOME_DIRECTORY USERNAME


Si vemos el código del método que atiende el comando veremos que el comando recibe un argumento llamado "name" (especificado con la anotación @CliOption) el cual es asignado a un objeto del tipo PropertyName. Y si abrimos la clase PropertyName notaremos que tienen dos atributos públicos finales y estáticos que son justamente los que se muestran cuando damos "tab".


@ScopeDevelopmentShell
public class Commands implements CommandMarker {

...

@CliCommand(value="welcome property", help="Obtains a pre-defined system property")
public String property(@CliOption(key="name", mandatory=false, specifiedDefaultValue="USERNAME", unspecifiedDefaultValue="USERNAME", help="The property name you'd like to display") PropertyName propertyName) {
return operations.getProperty(propertyName);
}

...
}



public class PropertyName implements Comparable {

private String propertyName;

public static final PropertyName USERNAME = new PropertyName("Username");
public static final PropertyName HOME_DIRECTORY = new PropertyName("Home Directory");

...
}


En fin, el modelo de Add-on de Spring Roo esta muy interesante y espero darme el tiempo para ver en futuros post como acceder a los metadatos de un proyecto Roo como: las entidades existentes, las propiedades que tienen, sus relaciones, etc.

2 comments:

Rafael Gutiérrez said...

Que fue lo que encontraste difícil de Grails?

Unknown said...

Precisamente en el video del Google IO 2010 en el que sale Ben Alex ejecutando una demo (expenses.roo) de integración de gwt y roo tienes un ejemplo de master/detail.