1. Información general
En este tutorial rápido, veremos las API obsoletas en Java y cómo usar la anotación @Deprecated .
2. La anotación @Deprecated
A medida que un proyecto evoluciona, su API cambia. Con el tiempo, hay ciertos constructores, campos, tipos o métodos que no queremos que la gente use más.
En lugar de romper la compatibilidad con versiones anteriores de la API del proyecto, podemos etiquetar estos elementos con la anotación @Deprecated .
@Deprecated les dice a otros desarrolladores que el elemento marcado ya no debe usarse . También es común agregar algo de Javadoc junto a laanotación @Deprecated para explicar cuál sería una mejor alternativa que cumple con el comportamiento correcto:
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; } }
Recuerde que un compilador solo muestra la advertencia de API obsoleta si el elemento Java anotado se usa en algún lugar del código. Entonces, en este caso, solo se mostraría si hubiera un código que llamara al método de cálculo .
Además, también podemos comunicar el estado obsoleto en la documentación utilizando la etiqueta Javadoc @deprecated .
3. Atributos opcionales agregados en Java 9
Java 9 agrega algunos atributos opcionales a la anotación @Deprecated : since y forRemoval .
El atributo since requiere una cadena que nos permita definir en qué versión se desaprobó el elemento. El valor predeterminado es una cadena vacía.
Y forRemoval es un booleano que nos permite especificar si el elemento se eliminará en la próxima versión. Su valor predeterminado es falso:
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 pocas palabras, el uso anterior significa que el cálculo ha quedado obsoleto desde la versión 4.5 de nuestra biblioteca y que está programado para su eliminación en la próxima versión principal.
Es útil para nosotros agregar esto, ya que el compilador nos dará una advertencia más fuerte si descubre que estamos usando un método con ese valor.
Y ya hay soporte de IDE para detectar usos de un método marcado con forRemoval = true. IntelliJ, por ejemplo, tacha el código con una línea roja en lugar de una negra.
4. Conclusión
En este artículo rápido, vimos cómo usar la anotación @Deprecated y sus atributos opcionales para marcar el código que ya no debería usarse.
El código fuente completo de los ejemplos se puede encontrar en GitHub.