Package caseine.tags

Annotation Interface ToDoIn

@Retention(RUNTIME)
@Target(METHOD)
public @interface ToDoIn

Pour vider ou remplacer le contenu d'une méthode.

Author:

Yvan Maillot <yvan.maillot@uha.fr>

L'annotation @caseine.tags.ToDoIn

L'annotation @ToDoIn permet de retirer le corps des méthodes qu'elle annote ou de le remplacer par un autre code.

Cible

@ToDoIn ne s'applique qu'aux méthodes.

Formes d'emploi

@ToDoIn s'emploie

1. comme une annotation multivaluée : e.g. @ToDoIn(value = "une consigne à l'étudiant", replacement="{ return \"\"; }")
2. comme une annotation monovaluée : e.g. @ToDoIn("une consigne à l'étudiant")
3. comme une annotation de marquage : @ToDoIn

Effet

L'annotation @ToDoIn a pour effet

1. dans tous les cas, de conserver la signature de la méthode,
2. et selon que la propriété replacement soit renseignée ou non:
   1. Si elle n'est pas renseignée (ou vide), de remplacer son contenu par une instruction minimale qui garantit la compilation, suivie d'un commentaire qui commence par // TODO suivi de la consigne à l'étudiant.
   2. Si elle est renseignée (et non vide), de remplacer le corps de la méthode par du code défini par la valeur de cette propriété (cf. Utilisation de la propriété replacement ci-après).

Utilisation de la propriété replacement

Sans renseigner la propriété replacement (c'est-à-dire par défaut), l'emploi de @ToDoIn est assez naturelle.

En revanche, l'utilisation de la propriété replacement nécessite de prendre quelques précautions :

Le corps de la méthode est

1. soit remplacé par le contenu d'un fichier dont le chemin est donné par la valeur de la propriété replacement, s'il s'agit du chemin d'un ficher accessible.
2. soit remplacé par cette valeur elle-même sinon.

Attention, pour pouvoir déployer sur le serveur, il faut absolument que le code de remplacement soit parsable.

• Il doit notamment commencer par { et finir par }
• S'il contient des guillemets, ils devront être invalidés dans la valeur de la propriété (puisqu'elle est elle-même entre guillemets).
  Par exemple, pour produire { return ""; }, il faut écrire replacement="{ return \"\"; }"
• Ça peut devenir compliqué s'il faut ajouter des sauts de lignes ('\n'), des tabulations ('\t'), des caractères unicode, etc.
  Dans ces cas, et le plus souvent, l'emploi d'un fichier externe est préférable.

Exemple d'annotation de marquage

 @ToDoIn
 public double norme() {
    return sqrt(x*x+y*y);
 }
 

sera remplacé par

 public double norme() {
    return 0.0;
 // TODO
 }
 

Exemple d'annotation monovaluée

 @ToDoIn("Retourner la norme du vecteur")
 public double norme() {
    return sqrt(x*x+y*y);
 }
 

sera remplacé par

 public double norme() {
    return 0.0;
 // TODO Retourner la norme du vecteur
 }
 

Exemple d'annotation multivaluée (sans fichier)

 @ToDoIn(value="Ce code est faux. Corrigez-le", replacement="{double x = 0, y = 0; return x*x+y*y;}")
 public double norme() {
    return sqrt(x*x+y*y);
 }
 

sera remplacé par

 public double norme() {
    double x = 0, y = 0;
    return x*x+y*y;
 // TODO Ce code est faux. Corrigez-le
 }
 

Exemple d'annotation multivaluée (avec fichier)

 @ToDoIn(replacement = "afficher.replacement")
 public static void afficher() {
     System.out.println("Pour afficher : ");
     System.out.println("\\ il faut écrire  System.out.println(\"\\\\\");");
     System.out.println("\" => System.out.println(\"\\\"\");");
     System.out.println("π => System.out.println(\"\\u03C0\");");
     System.out.println("π\t\"π\" => System.out.println(\"\\u03C0\\t\\\"u03C0\\\");");
     System.out.println("Une tabulation => System.out.println(\"\\t\");");
     System.out.println("\\t => System.out.println(\"\\\\t\");");
 }
 

Si "afficher.replacement" est le chemin valide d'un fichier qui contient ceci :

 {
     System.out.println("Pour afficher : ");
     System.out.println("\\ il faut écrire  System.out.println(\"\\\\\");");
     System.out.println("\" => System.out.println(\"\\\"\");");
     System.out.println("π => System.out.println(\"\\u03C0\");");
     System.out.println("π\t\"π\" => System.out.println(\"\\u03C0\\t\\\"u03C0\\\");");
     // Exécutez ce programme et observez !
     // Puis continuez le pour afficher encore ceci :
     // Une tabulation => System.out.println("\t");
     // \t => System.out.println("\\t");
 }
 

Attention les accolades sont nécessaires.

sera remplacé par

 public static void afficher() {
     System.out.println("Pour afficher : ");
     System.out.println("\\ il faut écrire  System.out.println(\"\\\\\");");
     System.out.println("\" => System.out.println(\"\\\"\");");
     System.out.println("π => System.out.println(\"\\u03C0\");");
     System.out.println("π\t\"π\" => System.out.println(\"\\u03C0\\t\\\"u03C0\\\");");
 // Exécutez ce programme et observez !
 // Puis continuez-le pour afficher encore ceci :
 // Une tabulation => System.out.println("\t");
 // \t => System.out.println("\\t");
 // TODO
 }
 

Remarque

Les commentaires de la javadoc sont toujours conservés.

Précautions

@ToDoIn n'entraîne jamais de code non compilable, si la propriété replacement n'est pas utilisée.

En revanche, si la propriété replacement est utilisée, il est possible se retrouver dans l'impossible de pousser votre VPL sur le serveur de Caséine.

Pour plus de détails relire la section "Utilisation de la propriété replacement" plus haut.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	replacement	Définit le remplacement du corps de la méthode annotée.
String	value	Définit la consigne à destination de l'étudiant.

Element Details

value

String value

Définit la consigne à destination de l'étudiant. Elle sera dans le corps de la méthode et précédée de // TODO Par défaut, la consigne est vide.

Returns:

La consigne à destination de l'étudiant.

Default:

""

replacement

String replacement

Définit le remplacement du corps de la méthode annotée.

Returns:

une chaîne de caractères qui est

1. soit la chaîne vide (par défaut)
2. soit le chemin valide d'un fichier qui contient le code à remplacer
3. soit le code lui-même

Attention ce code doit être compilable.

Default:

""