Exemple de Template Simples

Que fait cet exemple ?

1. Un seul fichier sommaire.txt qui contiendra les informations rassemblées à partir de tous les fichiers *.java.
2. Un fichier 'nom_classe'.txt pour chaque fichier java.

Pour exécuter cet  exemple :

1. Installer Ant et XDoclet.
2. Télécharger l'archive extemplate.zip (contenant les fichiers de l'exemple) en cliquant sur l'image : .
3. Décompresser cette archive.
4. Modifier le fichier build.xml pour qu'il contienne les chemins appropriés à votre système.
5. Lancer Ant (commande 'ant') dans le répertoire contenant le fichier build.xml.
6. Regarder les fichiers générés dans le répertoire 'dest'.

Présentation des différents fichiers

• Fichiers sources - Fichiers Java à partir desquels on souhaite générer d'autres fichiers.
  ./src/paquetage1/MaClasse.java
  ./src/paquetage1/MonAutreClasse.java
  ./src/paquetage2/MaClasse.java
  
• Templates - templates XDoclet qui contrôlent ce à quoi vont ressembler les fichiers générés.
  ./sommaire.xdt
  ./each-class.xdt
  
• Ant build - La génération se produit lorsque vous lancez ce fichier (via la commande ant)
  ./build.xml

Liste des fichiers et explication

Dans cet exemple nous n'avons défini que 2 balises spécifiques :

• @test.importance : balise de niveau classe.
• @test.autre : balise de niveau méthode.

./src/paquetage1/MaClasse.java

 package paquetage1;

/**
 * C'est une classe
 * @test.importance MAJEUR
 */

public class MaClasse
{
    /**
     * Une méthode.
     *           
     * @test.autre CECI EST LA VALEUR DU TAG test.autre
     */

    String Bonjour()
    {
        return "Bonjour";
    }
}

./src/paquetage1/MonAutreClasse.java

package paquetage1;

/**
 * C'est une autre classe
 * @test.importance MINEURE
 */
public class MonAutreClasse
{

}

./src/paquetage2/MaClasse.java

package paquetage2;

/**
 * C'est une autre classe 
 * @test.importance MINEURE
 */
public class MaClasse
{

}

./sommaire.xdt

- Liste pour toutes les classes

<XDtClass:forAllClasses>

   - <XDtClass:className/>, dans le paquetage '<XDtPackage:packageNameAsPath/>'

	<XDtClass:ifHasClassTag tagName="test.importance">
   	   <XDtClass:ifClassTagValueEquals value="MAJEUR" tagName="test.importance">
	      ******************************************
	      <XDtClass:classTagValue tagName="test.importance"/>
	      ******************************************
	   </XDtClass:ifClassTagValueEquals>

   	   importance : <XDtClass:classTagValue tagName="test.importance"/>

	</XDtClass:ifHasClassTag>

    <XDtMethod:forAllMethods>
      - <XDtMethod:methodName/>()
    </XDtMethod:forAllMethods>

</XDtClass:forAllClasses>

Dans notre exemple, XDoclet va parcourir toutes les classes (forAllClasses) et pour chacune indiquer son nom (className)et son paquetage.
    Ensuite on teste si une classe contient la balise test.importance
    si c'est le cas, on teste si cette balise a pour valeur MAJEUR 
            si oui on affiche la valeur de la balise entouré par des étoiles.
            Ensuite on affiche la valeur de la balise test.importance.
        On parcourt ensuite toutes les méthodes (forAllMethods) de chaque classe et on affiche leur nom (methodName).

./each-class.xdt

Classe <XDtClass:className/>, dans le paquetage '<XDtPackage:packageNameAsPath/>'
<XDtMethod:forAllMethods>
    - <XDtMethod:methodName/>()
    <XDtMethod:ifHasMethodTag tagName="test.autre">
        - <XDtMethod:methodTagValue tagName="test.autre" />
    </XDtMethod:ifHasMethodTag>
</XDtMethod:forAllMethods>

./build.xml

<project default="generation">

<!-- INITIALISATION DES VARIABLES -->
  <target name="initialisation">
    <path id="class.path">
<!-- ADAPTER CE PATH A VOTRE SYSTEME-->    
        <fileset dir="c:/xdoclet/lib" includes="*.jar"/>
    </path>
   </target>

<!-- CREATION DU REPERTOIRE DE SORTIE -->
  <target name="repertoire" depends="initialisation">
      <mkdir dir="dest" />
   </target>


<!--  GENERATION DES FICHIERS -->

    <target name="generation" depends="repertoire">

	<taskdef name="doclet" classname="xdoclet.DocletTask"
	  classpathref="class.path" />

        <!-- UN SEUL FICHIER -->
        <doclet destdir="./dest" sourcePath="./src">
            <fileset dir="src" includes="**\*.java"/>
            <template templateFile="sommaire.xdt"
		 destinationfile="sommaire.txt" />
        </doclet>

        <!-- FICHIERS POUR CHAQUE CLASSE -->
        <doclet destdir="dest" sourcePath="./src">
            <fileset dir="src">
                <include name="**/*.java"/>
            </fileset>
            <template
                templateFile="each-class.xdt"
                destinationfile="{0}.txt">
            </template>
        </doclet>

    </target>
</project>

• La première initialisation permet de définir où se trouvent les fichiers .jar utiles à XDoclet. Le chemin indiqué dans l'exemple doit être adapté à votre système. Ce chemin est placé dans la variable appelée  class.path.
• La seconde repertoire permet de créer le répertoire dest qui contiendra les fichiers générés.
• La troisième generation permet d'appeler les procédures XDoclet et de générer les fichiers à partir des templates spécifiés. Les tâches XDoclet sont encadrées par des balises <xdoclet ...>, on y indique le répertoire de destination (où seront placés les fichiers générés) et le répertoire source (où trouver les fichiers source). A l'intérieur, pour générer les fichiers, on indique les fichiers à traiter (dans notre cas **\*.java indique tous les fichiers java de tous les sous-répertoires de src), le template à utiliser et le nom du fichier de sortie.  

Fichiers générés :

• Dans le répertoire dest on obtient donc un fichier  sommaire.txt qui contient le nom toutes les classes et leur packages avec la valeur de leur balise test.importance (et des étoiles si cette importance est MAJEUR) et leurs méthodes.
• Dans les sous répertoire paquetage1 ou 2 se trouvent les fichiers nom_classe.txt qui contiennent le nom de la classe et son paquetage, et toutes leurs méthodes ainsi que la valeur de la balise test.autre si elle est présente.