web-dev-qa-db-fra.com

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

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

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

Comment puis-je y arriver?

javadeprecated
271
Pavel Janicek

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

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

Utilisez les deux annotations _@Deprecated_ et la balise _@deprecated_ JavaDoc.

La balise JavaDoc _@deprecated_ est utilisée à des fins de documentation.

L'annotation _@Deprecated_ indique au compilateur que la méthode est obsolète. Voici ce qui est écrit dans le document Sun/Oracles sur le sujet:

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

Vous pouvez trouver le document complet à l'adresse Comment et quand désapprécier les API

85
ShaMan-H_Fel

puisque certaines explications mineures manquaient

Utilisez @Deprecated l'annotation sur la méthode comme ceci

_ /**
 * @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 se posent lors de son utilisation? Fournissez un lien vers la discussion sur le sujet, le cas échéant. (n'oubliez pas de séparer les lignes pour plus de lisibilité _<br/>_
  2. Quand il sera supprimé. (indiquez à vos utilisateurs à quel point ils peuvent toujours compter sur cette méthode s'ils décident de rester à l'ancienne)
  3. Fournir une solution ou lien vers la méthode que vous recommandez {@link #setPurchasePrice()}
37
azerafati

Il y a deux choses que tu peux faire:

  1. Ajoutez l’annotation @Deprecated à la méthode, et
  2. Ajoutez une balise @deprecated au javadoc de la méthode

Vous devriez faire les deux !

Citant le documentation Java à 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 quoi utiliser à la place.

L'utilisation de l'annotation entraîne 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épréciée utilise une classe, une méthode ou un champ obsolète. 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 les commentaires appropriés expliquant comment utiliser la nouvelle API. Cela garantit aux développeurs un chemin de migration utilisable de l'ancienne API vers la nouvelle API.

35
Bohemian

Utilisez le annotation@Deprecated pour votre méthode, et vous devriez également le mentionner dans vos javadocs.

8
amit

Jetez un coup d'œil à l'annotation @Deprecated.

4
jham