Introduction a CRaSH : application à la visualisation d'un cache EHcache

• Jboss 7.1.1.Final.
• Maven 3.
• Le code de l'appli se trouve sur GitHub : https://github.com/crashub/spring-ehcache-demo.

L'installation se résume à récupérer l'archive de CRaSH (www.crashub.org) et à la décompresser. Elle n'est pas obligatoire si vous utilisez le mode ssh ou Telnet.

• Téléchargez le code source de l'appli sur GitHub : https://github.com/crashub/spring-ehcache-demo.
• Construction du war :

cd sandbox
mvn clean package

• Déploiement dans JBoss

Une fois le war construit, il ne vous reste plus qu'à le copier dans le répertoire deployments de JBoss (${JBOSS_DIR}/standalone/deployments).

L'application démo n'a été testée que sur jboss-as-7.1.1.Final.

L'objectif est de contrôler le cache de l'application démo en se connectant à la JVM de cette application à l'aide de CRaSH et en exécutant un script d'affichage du cache.
Voici les étapes à réaliser :

• création d'un script d'affichage du cache : spring_cache.groovy ;
• intégrer CRaSH dans notre application démo (ajout des dépendances Maven, de spring_cache.groovy et des fichiers de configuration) ;
• packaging et déploiement de notre application démo sur JBoss ;
• Utilisation de CRaSH.

L'application démo est très simple. Elle donne la possibilité d'ajouter, de lister et d'effacer les utilisateurs. Pour accéder à l'application démo, il suffit de se rendre sur http://localhost:8080/demo/ et vous arriverez sur la page suivante :

Pour afficher les données présentes dans notre cache, nous avons besoin d'un script. Ce script sera ensuite placé dans le répertoire WEB-INF/crash/commands/ de notre application démo.

Dans cette version (crsh.shell.embed.spring 1.1), il est obligatoire de mettre les scripts dans le répertoire WEB-INF/crash/commands/ .

IV-C-1. Comment fonctionne ce script ?▲

IV-C-2. Script d'affichage du cache▲

%spring_cache showCache

package crash.commands.base
import org.crsh.command.CRaSHCommand
import org.crsh.cmdline.annotations.Usage
import org.crsh.cmdline.annotations.Command
import org.crsh.cmdline.annotations.Argument

import org.crsh.cmdline.annotations.Required
import org.crsh.shell.ui.UIBuilder

import fr.dr.sandbox.controller.Customer;
import fr.dr.sandbox.controller.CustomerComponent;
import java.lang.reflect.Method;
import java.util.List;

/**
* Spring commands to list Customer in cache for the demo application.
* @author drieu
*
*/
@Usage("Spring cache commands")
@Command
class spring_cache extends CRaSHCommand {

 @Usage("Show values that are loaded in cache")
 @Command
 public void showCache() {
   def bean = context.attributes.beans["customerComponent"];
   if (null != bean) {
     out.println("Cache contents :");
     List<Customer> lst = bean.getCache();
     if (null != lst) {
     for(Customer c : lst) {
         out.println("Name:" + c.getName());
         out.println("Id:" + c.getId());
         c.show();
    }
  }
 }
 }
}

IV-C-3. Intégrer CRaSH dans notre application démo▲

IV-C-4. Ajout des dépendances Maven▲

<dependency>
    <groupId>org.crsh</groupId>
       <artifactId>crsh.shell.embed.spring</artifactId>
       <version>1.1.0</version>
</dependency>
<dependency>
   <groupId>org.crsh</groupId>
   <artifactId>crsh.shell.core</artifactId>
   <version>1.1.0</version>
</dependency>
<dependency>
   <groupId>org.crsh</groupId>
   <artifactId>crsh.shell.packaging</artifactId>
   <version>1.1.0</version>
   <type>war</type>
   <classifier>spring</classifier>
</dependency>

IV-C-5. Configuration des modes d'accès à CRaSH▲

<bean class="org.crsh.spring.SpringWebBootstrap">
   <property name="config">
   <props>
   <prop key="crash.telnet.port">5000</prop>
   <!-- VFS configuration -->
   <prop key="crash.vfs.refresh_period">1</prop>
   <!-- SSH configuration -->
   <prop key="crash.ssh.port">2000</prop>
   <!-- Authentication configuration -->
   <prop key="crash.auth">simple</prop>
   <prop key="crash.auth.simple.username">admin</prop>
   <prop key="crash.auth.simple.password">admin</prop>
   </props>
   </property>
   </bean>
   <bean class="org.crsh.telnet.TelnetPlugin"/>

telnet 5000 localhost
ssh -p 2000 -l admin localhost (mdp admin)

IV-C-6. Packaging et déploiement▲

mvn clean package

L'utilisation de CRaSH est très simple. Pour se connecter à une JVM, il y a plusieurs solutions :

• mode ssh ;
• mode telnet ;
• mode Attach.

Dans notre exemple, nous allons utiliser le mode ssh. CRaSH étant embarqué dans l'application démo avec la configuration ssh (utilisateur admin et port 2000), il nous suffit d'avoir un client ssh pour se connecter :

ssh -p 2000 -l admin localhost

Une fois connecté, vous pouvez saisir help pour avoir une liste des commandes disponibles :

Vous constatez la présence de notre commande spring_cache. Pour obtenir de l'aide sur cette commande, il faudra saisir : spring_cache.

Pour utiliser notre commande, il nous suffit de faire : spring_cache showcache.
Cette commande va nous permettre d'afficher la liste des Customers présents dans notre cache.

Au démarrage, nous avons chargé un utilisateur dans notre cache (cf. Annexes) :

% spring_cache showcache
Cache contents :
Name:Smith
Id:1

Ensuite, nous pouvons ajouter un autre utilisateur dans notre cache. Pour cela, il suffit de cliquer
sur Add customer sur la page http://localhost:8080/demo/.
Si nous retournons sur la page d'accueil après avoir ajouté le customer, nous verrons bien deux lignes dans notre tableau :

Ensuite, si on retourne dans notre Shell, on voit bien que le cache a été mis à jour :

% spring_cache showcache
Cache contents :
Name:Smith
Id:1
Name:john
Id:2

Cette partie décrit comment nous avons implémenté la gestion du cache dans l'application démo dans les deux cas suivants :

• au démarrage ;
• dans l'application.

Nous utilisons ehcache 1.6.1 avec Spring 3.1.1.RELEASE dans notre application démo.
Pour cela, nous définissons un cacheManager avec Spring dans le fichier sandbox.xml :

<ehcache:annotation-driven cache-manager="cacheManager" />

Nous utilisons ensuite ce cacheManager dans notre application pour effectuer des opérations de lecture, écriture, effacement. Nous accédons à ce cache de deux manières :

• au démarrage ;
• par l'interface web.

Nous remplissons le cache au démarrage avec un Customer. Pour cela, nous avons défini un listener dans notre web.xml :

<listener-class>
fr.dr.sandbox.listener.CacheListener
</listener-class>

Ce listener contient une méthode contextInitialized dans laquelle nous avons placé notre code qui va charger un Customer en cache.

CacheManager cacheManager = (CacheManager) WebApplicationContextUtils.getWebApplicationContext(servletContext).getBean("cacheManager");
Cache cache = cacheManager.getCache("customer");
Customer c = new Customer();
c.setId("1");
c.setName("Smith");
c.setAddress("Smith Address");

cache.put(new Element(c.getId(),c));

Au démarrage de l'application, on voit que ce chargement est bien effectué dans les logs :

14:53:32,044 INFO  [fr.dr.sandbox.listener.CacheListener] (MSC service thread 1-2) ========> contextInitialized() : BEGIN.
14:53:32,047 INFO  [fr.dr.sandbox.listener.CacheListener] (MSC service thread 1-2) ========> contextInitialized() : Customer Smith was added in cache.
14:53:32,047 INFO  [fr.dr.sandbox.listener.CacheListener] (MSC service thread 1-2) ========> contextInitialized() : END

Il est possible de réaliser des opérations sur le cache par l'interface web. Pour cela, nous définissons les opérations dans le Controller qui vont appeler les méthodes de gestion du cache qui se trouvent dans CustomerComponent.

Exemple :

L'accès à http://localhost:8080/demo/clearCache va appeler la méthode suivante du Controller :

/**
* Clear all data in cache.
* @return String text message OK or KO.
*/
@RequestMapping(value = "/clearCache", method = { RequestMethod.GET })
@ResponseStatus(HttpStatus.OK)
public @ResponseBody
String clearCache() {
      customerComponent.clearCache();
      return "Cache successfully Cleaned";
}

CRaSH fournit plusieurs solutions pour se connecter sur des JVM. Nous allons présenter dans cette partie les différents modes.

V-D-1. Mode standalone▲

%cd $CRASH_HOME/bin
%crash.sh

V-D-2. Mode Attach▲

%$JDK_HOME/bin/jps
3165 RemoteMavenServer
20650 Test
20651 Jps

%cd $CRASH_HOME/bin
%crash.sh 20650

V-D-3. Mode embarqué▲

V-D-4. Autres modes▲

Il existe deux possibilités pour créer une commande :

• en tant que Script.
  
  Dans ce cas, vous écrivez directement votre code dans votre script Groovy. Voici l'exemple de la commande clock :

package crash.commands.base
for (int i = 0;i < 10;i++) {
    out.cls();
    out << "Time is" + i + "\n";
    out.flush();
    Thread.sleep(1000);
}

• en tant que classe.
  

Cette méthode simplifie grandement la création de commande. Dans cette partie, nous présenterons seulement les annotations de base nécessaires à la création d'une commande.
Avec les commandes CRaSH, vous avez énormément de possibilités. Vous pouvez par exemple ajouter de la complétion, créer des tableaux de résultats…
Pour plus d'informations, allez voir la documentation sur www.crashub.org.

Voici la structure d'une commande :

@Usage("JDBC connection")
class jdbc extends CRaSHCommand {
  
  @Usage("connect to database with a JDBC connection string")
  @Command
  public String connect(
 ...
  }

@Command : permet de définir qu'une méthode ou une classe est une commande ;

@Usage : permet de définir l'aide qui sera affichée.

Si elle est placée au-dessus de la classe qui extends Command alors cette aide sera affichée avec la commande help.

Dans notre cas, lorsque l'on saisira la commande help, on aura la sortie suivante avec l'annotation @Usage("JDBC connection")  :

%help
Try on of the following commands with -h or --help switch:

NAME    DESCRIPTION
env     dipslay the term env
help    provides basic help
java    various java language commands
jdbc    JDBC connection

Nous pouvons aussi placer cette annotation au-dessus d'une méthode identifiée comme Command. Par exemple, pour la méthode connect de JDBC, nous avons :@Usage("connect to database with a JDBC connection string"). Donc si on saisit :

%jdbc help

on retrouvera alors cette description :

The most commonly used jdbc commands are:
   props            show the database properties
   close            close the current connection
   table            describe the tables
   open             open a connection from JNDI bound datasource
   connect          connect to database with a JDBC connection string
   execute          execute SQL statement
   info             describe the database
   tables           describe the tables

Il existe aussi des annotations pour définir les arguments (exemple : @Argument) et les options(exemple :@Option(names=["p","password"]).