Comment déclarer ou marquer une méthode Java comme obsolète?


284

Je voudrais rendre une de mes méthodes "obsolète" = plus utilisée.

Mais j'aimerais quand même l'avoir dans mon API. Je veux juste montrer un "avertissement" à toute personne utilisant cette méthode.

Comment puis-je y parvenir?


10
@Deprecated n'est-il pas une option pour vous?
templatetypedef

18
C'est vrai, mais je ne le savais pas ... c'est pourquoi je pose la question :)
Pavel Janicek


4
les commentaires ne sont pas le lieu des réponses!
mattumotu

Réponses:


578

Utilisez la @Deprecatedméthode. N'oubliez pas de clarifier le champ javadoc:

/**
 * Does some thing in old style.
 *
 * @deprecated use {@link #new()} instead.  
 */
@Deprecated
public void old() {
// ...
}

2
Comment liez-vous une bibliothèque externe? par exemple: com.hello.api.PublicController # new
Faizan Kazi

@LinuxLars complètement d'accord! Java 9 a ajouté quelques attributs pour commencer à prendre la dépréciation au sérieux, mais l'ajout d'un autre attribut reasonavec une valeur par défaut de ""n'aurait pas pu faire de mal
asgs

3
J'aimerais que le @deprecatedmessage dans le commentaire puisse être ajouté à @Deprecated(un endroit pour les réparer tous) ...
U. Windl

88

Utilisez à la fois l' @Deprecatedannotation et la @deprecatedbalise JavaDoc.

La @deprecatedbalise JavaDoc est utilisée à des fins de documentation.

L' @Deprecatedannotation indique au compilateur que la méthode est obsolète. Voici ce qu'il dit dans le document Sun / Oracles sur le sujet:

L'utilisation de l' @Deprecatedannotation pour déprécier une classe, une méthode ou un champ garantit que tous les compilateurs émettront des avertissements lorsque le code utilise cet élément de programme. En revanche, rien ne garantit que tous les compilateurs émettront toujours des avertissements basés sur la @deprecatedbalise Javadoc, bien que les compilateurs Sun le fassent actuellement. D'autres compilateurs peuvent ne pas émettre de tels avertissements. Ainsi, l'utilisation de l' @Deprecatedannotation pour générer des avertissements est plus portable que l'utilisation de la @deprecatedbalise Javadoc.

Vous pouvez trouver le document complet sur Comment et quand déprécier les API


1
Pas tout à fait vrai. Les deux méthode TELL javadoc et annotation compilateur est dépréciée
Bohemian

17
@Bohemian En fait, ce n'est pas tout à fait vrai. L'annotation est définie dans la section 9.6.1.6 de Java Language Specification ( java.sun.com/docs/books/jls/third_edition/html/… ), contrairement à la balise javadoc. L'annotation fait donc partie du langage. Si vous décidez d'écrire votre propre compilateur Java, vous pouvez ignorer la balise javadoc, mais vous devez reconnaître l'annotation.
ShaMan-H_Fel

@ ShaMan-H_Fel Je crois que le modèle javadoc fonctionne aussi. Parce que c'était le seul choix avant Java 5, et cela a fonctionné. Lorsque vous avez marqué une méthode avec la @deprecatedbalise javadoc (dans Java 4-), le compilateur a marqué la méthode (classe, champ) comme obsolète et les IDE ont affiché des avertissements, même lorsqu'aucune source n'était disponible.
Amir Pashazadeh

42

car il manquait quelques explications mineures

Utilisez une @Deprecatedannotation sur la méthode comme celle-ci

 /**
 * @param basePrice
 * 
 * @deprecated  reason this method is deprecated <br/>
 *              {will be removed in next version} <br/>
 *              use {@link #setPurchasePrice()} instead like this: 
 * 
 * 
 * <blockquote><pre>
 * getProduct().setPurchasePrice(200) 
 * </pre></blockquote>
 * 
 */
@Deprecated
public void setBaseprice(int basePrice) {
}

n'oubliez pas d'expliquer:

  1. Pourquoi cette méthode n'est plus recommandée . Quels problèmes surviennent lors de son utilisation. Fournissez un lien vers la discussion sur la question, le cas échéant. (n'oubliez pas de séparer les lignes pour plus de lisibilité<br/>
  2. Quand il sera supprimé . (faites savoir à vos utilisateurs combien ils peuvent encore compter sur cette méthode s'ils décident de s'en tenir à l'ancienne méthode)
  3. Fournissez une solution ou un lien vers la méthode que vous recommandez {@link #setPurchasePrice()}

Cela ne devrait-il pas être <br/>, au lieu de </br>?
argh1969

@ argh1969, c'est ça! ne me souviens pas d'où j'ai obtenu le modèle à l'époque. Mais je peux confirmer que les deux versions fonctionnent. Bien que j'édite en faveur des normes.
azerafati

37

Il y a deux choses que tu peux faire:

  1. Ajoutez l' @Deprecatedannotation à la méthode et
  2. Ajouter une @deprecatedbalise au javadoc de la méthode

Vous devriez faire les deux !

Citant la documentation java sur ce sujet:

À partir de J2SE 5.0, vous déconseillez une classe, une méthode ou un champ à l'aide de l'annotation @Deprecated. De plus, vous pouvez utiliser la balise Javadoc @deprecated pour indiquer aux développeurs ce qu'il faut utiliser à la place.

L'utilisation de l'annotation oblige le compilateur Java à générer des avertissements lorsque la classe, la méthode ou le champ obsolète est utilisé. Le compilateur supprime les avertissements de dépréciation si une unité de compilation déconseillée utilise une classe, une méthode ou un champ déconseillé. Cela vous permet de créer des API héritées sans générer d'avertissements.

Il est fortement recommandé d'utiliser la balise Javadoc @deprecated avec des commentaires appropriés expliquant comment utiliser la nouvelle API. Cela garantit que les développeurs auront un chemin de migration réalisable de l'ancienne API vers la nouvelle API


8

Utilisez l' annotation @Deprecated pour votre méthode et vous devez également la mentionner dans vos javadocs.


Le lien est maintenant rompu
Yetti99

3

Jetez un œil à l' @Deprecatedannotation.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.