Java mind: Créer des rapports HTML montrant les différences entre 2 versions d'une API avec JDiff

JDiff est un outil permettant d’analyser les sources de deux versions d’une API afin de construire un rapport HTML présentant les différences entre ces deux versions. Cet outil est entre autre utilisé par Google pour générer les changements de l’API Guava ou ceux de l’API Android.

JDiff ne va pas faire un comparatif textuel comme on peut le faire à partir d’un gestionnaire de code source (SVN ou GIT) mais il va comparer la javadoc générées à partir des sources des différentes versions. JDiff est un fait un doclet qui va formater la sortie de la Javadoc

javadoc -doclet jdiff.JDiff -docletpath jdiff.jar
 [-apiname <API name>]
 [-apidir <optional directory where the API XML file is to be placed>]
 [-oldapi <name of old API>]
 [-oldapidir <optional directory where the old API XML file is located>]
 [-newapi <name of new API>]
 [-newapidir <optional directory where the new API XML file is located>]
 [-sourcepath <source path>]
 [-javadocnew <javadoc files location for the new API>]
 [-javadocold <javadoc files location for the old API>]
 [-baseURI <base>]
 [-excludeclass <exclusion level>]
 [-excludemember <exclusion level>]
 [-nosuggest <suggestion level>]
 [-firstsentence]
 [-docchanges]
 [-checkcomments]
 [-packagesonly]
 [-showallchanges]
 [-retainnonprinting]
 [-excludetag <exclude tag>]
 [-stats]
 [-windowtitle <text>]
 [-doctitle <HTML text>]
 [-version]
 [-help]

Utiliser JDiff en ligne de commande

Nous allons prendre un exemple concret dans lequel nous allons comparer les différences entre les versions 4.4 et 4.10 de l’API Junit (les sources sont récupérables par exemple sur un repo maven)

Vous devez dans un premier temps utiliser JDiff pour générer un fichier XML contenant l’API liée à l’ancienne version du projet (version 4.4).

javadoc -doclet jdiff.JDiff  -docletpath D:\apps\jdiff-1.1.1\jdiff.jar 
 -apiname "Junit4.4" -sourcepath junit-4.4-sources -subpackages .

Vous allez devoir ensuite faire la même opération sur la version 4.10

javadoc -doclet jdiff.JDiff  -docletpath D:\apps\jdiff-1.1.1\jdiff.jar 
 -apiname "Junit4.10" -sourcepath junit-4.10-sources -subpackages .

La dernière étape consistera à comparer le contenu des deux fichiers XML et de générer un rapport au format HTML

javadoc -doclet jdiff.JDiff -docletpath D:\apps\jdiff-1.1.1\jdiff.jar -d 
 newdocs -stats -oldapi "Junit4.4" -newapi "Junit4.10" D:\apps\jdiff-1.1.1\Null.java

On spécifie un fichier Null.java dans l’exemple ci dessus pour que la commande javadoc ne génère pas d’erreur car elle nécessite forcément en argument le nom d’une classe ou d’un package. Le traitement ne se base que sur les deux fichiers xml utilisé précédemment.

Pour pouvoir faire fonctionner cette dernière étape j'ai du reprendre le jar JDiff pour intégrer à l'intérieur les classes Xerces qu'il n'arrivait pas à retrouver lors de son exécution. Mais il est préférable d'utiliser JDiff via Ant

Utiliser JDiff via un script Ant
L’utilisation en ligne de commande est un peu fastidieuse. Lorsque vous téléchargez l’application vous bénéficier d’un jar vous permettant d’exécuter via Ant.

Reprenons notre exemple. Nous devons créer un fichier build.xml ayant la forme suivante qui sera exécuté via ant

<?xml version="1.0" encoding="UTF-8"?>
<project name="jdiff" default="jdiff_report" basedir=".">
  <target name="jdiff_report" depends="">
    <property name="JDIFF_HOME" value="D:/apps/jdiff-1.1.1" />
    <taskdef name="jdiff"
    classname="jdiff.JDiffAntTask" 
    classpath="${JDIFF_HOME}/antjdiff.jar" />

    <jdiff destdir="myreport" verbose="on" stats="on" docchanges="on">
      <old name="Junit 4.4">
        <dirset dir="C:/temp/junit-4.4-sources" includes="**" />
      </old>
      <new name="Junit 4.10">
        <dirset dir="C:/temp/junit-4.10-sources" includes="**" />
      </new>
    </jdiff>
  </target>
</project>

Après exécution vous pouvez ouvrir le rapport HTML généré dans le répertoire myreport. Ce rapport vous indiquera tous les changements au niveau de l’API.

Vous pouvez consulter un exemple en ligne avec Guava.

Utilisation sous Jenkins
Vous pouvez facilement utiliser cet utilitaire pour vos librairies techniques au sein de Jenkins. Je vais prendre un exemple sur un serveur sous Windows.

1. copier la librairie jDiff dans un répertoire sur votre serveur hébergeant Jenkins.

2. créer un nouveau job dans lequel vous définissez deux paramètres apiNewVersion et apiOldVersion. Vous pouvez soit choisir des paramètres de type String où vous saisissez des URL vers des tags sous SVN ou Git de vos librairies. Pour ce cas précis je préfère utiliser le type “List de tag SVN”.

3. Définissez des lignes de commande permettant de récupérer les sources des deux versions de votre librairie

4. La ligne de commande suivante est un peu particulière. On génère via un script le fichier de construction ant.

5. Vous n’avez plus qu’à définir une tâche appelant Ant et le tour est joué

6. Pour pouvoir publier le rapport sur la page d’accueil du job j’utilise le plugin “Publish HTML reports”

Conclusion
Jdiff est assez simple à mettre en place et je trouve que les rapports générés sont une bonne base pour présenter les évolutions entre deux versions d’une API à une équipe qui doit se charger de la migration d’un projet.

Si vous voulez plus d’informations je vous laisse lire cette page

Java mind

Pages

vendredi 31 mai 2013

Créer des rapports HTML montrant les différences entre 2 versions d'une API avec JDiff

2 commentaires: