Annotation Java @Deprecated

1. Vue d'ensemble

Dans ce rapide didacticiel, nous examinerons les API obsolètes en Java et comment utiliser l' annotation @Deprecated .

2. L' annotation @Deprecated

Au fur et à mesure qu'un projet évolue, son API change. Au fil du temps, il y a certains constructeurs, champs, types ou méthodes que nous ne voulons plus que les gens utilisent.

Au lieu de rompre la compatibilité descendante de l'API du projet, nous pouvons baliser ces éléments avec l' annotation @Deprecated .

@Deprecated indique aux autres développeurs que l' élément marqué ne doit plus être utilisé . Il est courant d'ajouter également du Javadoc à côté de l'annotation @Deprecated pour expliquer quelle serait une meilleure alternative qui sert le bon comportement:

public class Worker { /** * Calculate period between versions * @deprecated * This method is no longer acceptable to compute time between versions. * 

Use {@link Utils#calculatePeriod(Machine)} instead. * * @param machine instance * @return computed time */ @Deprecated public int calculate(Machine machine) { return machine.exportVersions().size() * 10; } }

N'oubliez pas qu'un compilateur affiche uniquement l'avertissement d'API obsolète si l'élément Java annoté est utilisé quelque part dans le code. Donc, dans ce cas, cela ne montrerait que s'il y avait du code qui appelait la méthode de calcul .

De plus, nous pouvons également communiquer le statut obsolète dans la documentation en utilisant la balise Javadoc @deprecated .

3. Attributs facultatifs ajoutés dans Java 9

Java 9 ajoute des attributs facultatifs à l' annotation @Deprecated : since et forRemoval .

L' attribut since nécessite une chaîne qui nous permet de définir dans quelle version l'élément a été déconseillé. La valeur par défaut est une chaîne vide.

Et forRemoval est un booléen qui nous permet de spécifier si l'élément sera supprimé dans la prochaine version. Sa valeur par défaut est false:

public class Worker { /** * Calculate period between versions * @deprecated * This method is no longer acceptable to compute time between versions. * 

Use {@link Utils#calculatePeriod(Machine)} instead. * * @param machine instance * @return computed time */ @Deprecated(since = "4.5", forRemoval = true) public int calculate(Machine machine) { return machine.exportVersions().size() * 10; } }

En termes simples, l'utilisation ci-dessus signifie que Calculate est obsolète depuis la version 4.5 de notre bibliothèque et que sa suppression est prévue dans la prochaine version majeure.

Il est utile pour nous d'ajouter ceci car le compilateur nous donnera un avertissement plus fort s'il constate que nous utilisons une méthode avec cette valeur.

Et les IDE prennent déjà en charge la détection des utilisations d'une méthode marquée avec forRemoval = true. IntelliJ, par exemple, traverse le code avec une ligne rouge au lieu d'une ligne noire.

4. Conclusion

Dans cet article rapide, nous avons vu comment utiliser l' annotation @Deprecated et ses attributs facultatifs pour marquer le code qui ne devrait plus être utilisé.

Le code source complet des exemples est disponible à l'adresse over sur GitHub.