Suivre le développement des règles métier avec Dolphin et Jenkins

Update : une démo de la page statique est disponible à cette adresse : http://dolphindemo.flo.cloudbees.net/

Dolphin est un plugin Maven d'analyse d'annotations de suivi des exigences métier dans le code Java. Il permet d'assurer la traçabilité de règles métier depus les spécifications détaillées et le code. Il permet de connaitre quelle méthode implémente une règle métier particulière et le niveau d'avancement de celle-ci.

C'est un outil que j'ai développé afin d'assurer la traçabilité et avoir une idée de l'avancement de l'implémentation des règles métier au sein des projets.

Nous allons voir comment le mettre en place sur un projet, puis comment tirer parti de son usine logicielle et de Jenkins pour récupérer les indicateurs de manière automatisée en "quasi" temps réel.
Les sources de Dolphin sont récupérable à cette adresse : https://github.com/florentdupont/dolphin.

Enrichir le code avec l'API

 l'API comporte deux annotations :

• @BusinessRule, pour la traçabilité des règles métier
• @DevelopmentStatus, pour le suivi d'avancement.

L'annotation @BusinessRule indique les règles métiers implémentées sur une méthode. Cette annotation porte 2 attributs : 

• id représente l'identifiant de la règle 
• version représente la version de la règle. 

Par exemple :

  @BusinessRule(id="RG_0009", version="0.1")
  public void myMethod() {
      // blabla
  }

Si plusieurs règles sont appliquées sur une méthode, alors on peut indiquer les différents identifiants en spécifiant les valeurs multiples entre accolades {} : Dans l'exemple ci dessous, myMethod() implémente la règle RG_0009 en version 0.1 et la règle RG_0010 en version 0.2.

  @BusinessRule(id={"RG_0009", "RG_0010"}, version={"0.1", "0.2"})
  public void myMethod() {
    // ...
  }

L'annotation @DevelopmentStatus permet d'indiquer l'avancement d'un développement. L'annotation porte sur une méthode. Par exemple, une méthode en cours de développement :

  @DevelopmentStatus(StatusType.ONGOING)
  public void myMethod() {
    //...    
  }

Il existe 5 types de statut :

•  TODO : méthode à implémenter 
• ONGOING : méthode en cours de développement 
• DONE : méthode implémentée, mais pas encore testée 
• TESTED : méthode testée unitairement. Passe les tests unitaires 
• INTEGRATED : méthode testée en intégration. Passe les tests d'intégration. 

Bien que les deux annotations pourraient être utilisées indépendamment, l'intérêt est évidemment de les utiliser conjointement afin de pouvoir bénéficier de l'avancement de l'implémentation des règles métier. L'exemple ci-dessous montre un exemple d'utilisation conjointe.

  public class MyClass {

    @BusinessRule(id="RG_0001", version="1.0")
    public void myMethod1() {
      // ...
    }

    @BusinessRule(id="RG_0016", version="1.0")
    @DevelopmentStatus(StatusType.DONE)
    public void myMethod2() {
      // ...
    }
}

Analyser les résultats

L'outil fait une analyse statique sur le code compilés (*.class). J'ai implémenté cette analyse en utilisant la librarie ASM qui permet de faire de l'analyse de Bytecode Java. L'utilisation d'une analyse statique depuis le Bytecode est plus complexe à mettre en oeuvre que de l'introspection (quoique...) mais elle présente surtout l'intérêt de pouvoir faire une analyse sans avoir à charger dynamiquement une classe. La classe peut donc très bien ne pas avoir ses classes liées chargées pour être analysée (ce qui est très utile lors de très gros projet et de Maven Dependency Hell...).

Une façon très simple de lancer l'outil, une fois installé, est de lancer la commande suivante : 

  mvn clean package -DskipTests com.dolphin:dolphin-maven-plugin:1.3:dolphin -DdolphinPrefix=com.mypackage.test

Le résultat de l'analyse est disponible dans le répertoire target/dolphin sous la forme d'un rapport HTML.

Le rapport HTML est une application HTML5 statique qui permet d'afficher une échelle du nombre de méthode analysées, ainsi que le status d'avancement de chaque méthode. Le tableau récapitulatif peut être trié par classe, par méthode, par règle ou par version. Il propose également une zone de recherche.
L'export XLS est également possible.

Intégration dans Jenkins 

L'intérêt est de pouvoir automatiser cette analyse et de l'intégrer dans Jenkins pour pouvoir disposer, de manière régulière et en quasi-temps réel, l'avancement.

Etant donné que Dolphin est disponible sous la forme d'un plugin Maven, il est tout à fait possible de l'intégrer à une construction Jenkins.

Voici un type de paramétrage pouvant être mis en place : 

Ce qui déclenche le Build : 

Scrutation de l'outil de gestion de version : H/20 * * * 1-5 

Build : 

Goals et options : 

  mvn clean package -DskipTests com.dolphin:dolphin-maven-plugin:1.3:dolphin -DdolphinPrefix=com.mypackage.test

Action à la suite de Build :
Archiver des artefacts : fichiers à archiver :

target/dolphin/**

C'est cette dernière étape qui va nous intéresser. Nous utilisons Jenkins comme "serveur Web", en mettant à disposition les fichiers HTML statiques directement accessible depuis ses constructions.

En cliquant sur index.html, on se rend compte que le résultat est accessible sur une URL du type :

http://MY_SERVER/jenkins/job/MY_JOB/BUILD_NUMBER/artifact/target/dolphin/index.html

On peut donc facilement, en gérant la rétention des constructions, garder une version de l'export par construction et ainsi garder un historique des différentes analyses Dolphin.

 L'intérêt pour le chef de projet est d'avoir une vision de la dernière analyse. Dans ce cas, on tire parti des URL Jenkins pour nous aider puisque Jenkins met à disposition les dernière construction sous un formalisme d'URL toujours identique, à savoir :;

http://MY_SERVER/jenkins/job/MY_JOB/lastSuccessfulBuild/artifact/target/dolphin/index.html

Ce lien peut ensuite être utilisé pour accéder rapidement aux résultats de dernière analyse, peu importe le numéro de construction utilisé par Jenkins, et notamment être utilisé directement depuis un tableau de bord par exemple.