¿Cómo declarar o marcar un método Java como obsoleto?

284

Me gustaría hacer que uno de mis métodos sea "obsoleto" = ya no se usa.

Pero aún así me gustaría tenerlo en mi API. Solo quiero mostrar "advertencia" a cualquiera que use ese método.

¿Cómo puedo lograr eso?

Pavel Janicek
fuente
10
¿@Deprecrated no es una opción para ti?
templatetypedef
18
Lo es, pero no lo sabía ... por eso estoy haciendo la pregunta :)
Pavel Janicek
44
¡Los comentarios no son el lugar para respuestas!
mattumotu

Respuestas:

577

Uso @Deprecateden método. No te olvides de aclarar el campo javadoc:

/**
 * Does some thing in old style.
 *
 * @deprecated use {@link #new()} instead.  
 */
@Deprecated
public void old() {
// ...
}
Vladimir Ivanov
fuente
2
¿Cómo se vincula una biblioteca externa? por ejemplo: com.hello.api.PublicController # new
Faizan Kazi
@LinuxLars completamente de acuerdo! Java 9 agregó un par de atributos para comenzar a tomar en serio la desaprobación, pero agregar otro atributo reasoncon un valor predeterminado de ""no podría haber sido perjudicial
pregunta el
3
Desearía que el @deprecatedmensaje en el comentario pudiera agregarse a @Deprecated(un lugar para arreglarlos a todos) ...
U. Windl
88

Utilice tanto la @Deprecatedanotación como la@deprecated etiqueta JavaDoc.

los @deprecated etiqueta JavaDoc se utiliza con fines de documentación.

La @Deprecatedanotación indica al compilador que el método está en desuso. Esto es lo que dice en el documento Sun / Oracles sobre el tema:

Usar la @Deprecatedanotación para desaprobar una clase, método o campo asegura que todos los compiladores emitirán advertencias cuando el código use ese elemento del programa. Por el contrario, no hay garantía de que todos los compiladores siempre emitan advertencias basadas en la @deprecatedetiqueta Javadoc, aunque los compiladores de Sun actualmente lo hacen. Otros compiladores no pueden emitir tales advertencias. Por lo tanto, usar la @Deprecatedanotación para generar advertencias es más portátil que confiar en la @deprecatedetiqueta Javadoc.

Puede encontrar el documento completo en Cómo y cuándo desaprobar las API

ShaMan-H_Fel
fuente
1
No del todo cierto. Tanto javadoc como el método del compilador de anotaciones están en desuso
Bohemian
17
@Bohemian En realidad, eso no es del todo cierto. La anotación se define en la sección 9.6.1.6 de la especificación del lenguaje Java ( java.sun.com/docs/books/jls/third_edition/html/… ), mientras que la etiqueta javadoc no. Entonces la anotación es parte del lenguaje. Si decide escribir su propio compilador de Java, puede ignorar la etiqueta javadoc, pero debe reconocer la anotación.
ShaMan-H_Fel
@ ShaMan-H_Fel Creo que el modelo javadoc también funciona. Porque era la única opción antes de Java 5, y funcionó. Cuando marcó un método con la @deprecatedetiqueta javadoc (en Java 4-), el compilador marcó el método (clase, campo) como obsoleto y los IDE mostraron advertencias, incluso cuando no había fuente disponible.
Amir Pashazadeh
42

ya que faltaban algunas explicaciones menores

Use @Deprecatedanotaciones en el método como este

 /**
 * @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) {
}

recuerda explicar:

  1. ¿Por qué ya no se recomienda este método ? Qué problemas surgen al usarlo. Proporcione un enlace a la discusión sobre el asunto, si corresponde. (recuerde separar las líneas para facilitar la lectura<br/>
  2. Cuando será removido . (deje que sus usuarios sepan cuánto pueden confiar en este método si deciden seguir el viejo método)
  3. Proporcione una solución o enlace al método que recomienda. {@link #setPurchasePrice()}
azerafati
fuente
¿No debería ser <br/>, en lugar de </br>?
argh1969
@ argh1969, cierto! No recuerdo de dónde saqué la plantilla de aquel entonces. Pero puedo confirmar que ambas versiones funcionan. Aunque estoy editando a favor de los estándares.
azerafati
37

Hay dos cosas que puedes hacer:

  1. Añade el @Deprecated anotación al método y
  2. Agregue una @deprecatedetiqueta al javadoc del método

¡Deberías hacer las dos cosas !

Citando la documentación de Java sobre este tema:

Comenzando con J2SE 5.0, desaprueba una clase, método o campo utilizando la anotación @Deprecated. Además, puede usar la etiqueta @doc obsoleta de Javadoc para indicar a los desarrolladores qué usar en su lugar.

El uso de la anotación hace que el compilador de Java genere advertencias cuando se utiliza la clase, el método o el campo en desuso. El compilador suprime las advertencias de desaprobación si una unidad de compilación desaprobada usa una clase, un método o un campo desaprobados. Esto le permite crear API heredadas sin generar advertencias.

Se recomienda encarecidamente utilizar la etiqueta Javadoc @deprecated con comentarios apropiados que expliquen cómo utilizar la nueva API. Esto garantiza que los desarrolladores tendrán una ruta de migración viable desde la antigua API a la nueva API

Bohemio
fuente
Significa que el comentario de javadoc es muy recomendable además de la anotación, ¡no como un reemplazo! Por eso siempre es mejor poner ambos.
morellet.d
@ morellet.d Gracias por señalarlo. Básicamente, he reescrito mi respuesta ahora (¡no leí el documento con suficiente atención!). Saludos
Bohemio
8

Use la anotación @Deprecated para su método, y también debe mencionarla en sus javadocs.

amit
fuente
El enlace ahora está roto
Yetti99
3

Echa un vistazo a la @Deprecatedanotación.

jham
fuente