Cómo dar de baja las API | Java

La desactivación de una API requiere el uso de dos mecanismos diferentes: la anotación @Deprecated y la etiqueta @deprecated Javadoc.

La anotación @Deprecated marca una API de una manera que se registra en el archivo de clase y está disponible en tiempo de ejecución. Esto permite que varias herramientas, como javac y jdeprscan, detecten y marquen el uso de API obsoletas. La etiqueta @deprecated Javadoc se utiliza en la documentación de API obsoletas, por ejemplo, para describir el motivo de la desaprobación y sugerir API alternativas.

Tenga en cuenta las mayúsculas: la anotación comienza con una D mayúscula  y la etiqueta Javadoc comienza con una d minúscula.

Uso de la anotación @Deprecated

Para indicar obsolescencia, anteponga @Deprecated al módulo, clase, método o declaración de miembro. La anotación contiene estos elementos:

• @Deprecated (since = "<version>")
• <versión> es la versión en la que la API quedó obsoleta. Esto es para fines informativos. El valor predeterminado es la cadena vacía ("").
• @Deprecated (forRemoval = <boolean>)
• forRemoval = true indica que la API está sujeta a eliminación en una versión futura.
• forRemoval = false recomienda que el código ya no utilice esta API; sin embargo, no existe la intención actual de eliminar la API. Este es el valor predeterminado.

Por ejemplo: @Deprecated (since = "9", forRemoval = true)

La anotación @Deprecated hace que la documentación generada por Javadoc se marque con uno de los siguientes, siempre que aparezca ese elemento de programa:

• Obsoleto.
• En desuso, para eliminación: este elemento de API está sujeto a eliminación en una versión futura.

La herramienta javadoc genera una página nombrada deprecated-list.html que contiene la lista de API obsoletas y agrega un enlace en la barra de navegación a esa página.

El siguiente es un ejemplo simple del uso de la anotación @Deprecated de la clase java.lang.Thread:

public class Thread implements Runnable {
    ... 
    @Deprecated(since="1.2")
    public final void stop() {
        ...
    }
    ...

Semántica de la obsolescencia

Los dos elementos de la anotación @Deprecated brindan a los desarrolladores la oportunidad de aclarar qué significa la desaprobación para sus API exportadas.

Para la plataforma JDK:

• @Deprecated (forRemoval = true) indica que la API es elegible para ser eliminada en una versión futura de la plataforma JDK.
• @Deprecated (since = " <version>") contiene la cadena de la versión de JDK que indica cuándo el elemento de la API quedó obsoleto, para aquellos obsoletos en JDK 9 y posteriores.

Si mantiene bibliotecas y produce sus propias API, entonces probablemente use la anotación @Deprecated. Debe determinar y comunicar su política sobre las eliminaciones de API. Por ejemplo, si publica una nueva biblioteca cada 6 semanas, puede optar por desaprobar una API para su eliminación, pero no eliminarla durante varios meses para que sus clientes tengan tiempo de migrar.

Uso de la etiqueta Javadoc @deprecated

Utilice la etiqueta @deprecated en el comentario de javadoc de cualquier elemento de programa obsoleto para indicar que ya no se debe utilizar (aunque pueda seguir funcionando). Esta etiqueta es válida en todos los comentarios de documentación de clase, método o campo. La etiqueta @deprecated debe ir seguida de un espacio o una nueva línea. En el párrafo que sigue a la etiqueta @deprecated, explique por qué el artículo quedó obsoleto y sugiera qué usar en su lugar. Marque el texto que hace referencia a nuevas versiones de la misma funcionalidad con una etiqueta @link.

Cuando encuentra una etiqueta @deprecated, la herramienta javadoc mueve el texto que sigue a la etiqueta @deprecated al frente de la descripción y lo precede con una advertencia. Por ejemplo, esta fuente:

/**
* ...
* @deprecated  This method does not properly convert bytes into
* characters.  As of JDK 1.1, the preferred way to do this is via the
* {@code String} constructors that take a {@link
* java.nio.charset.Charset}, charset name, or that use the platform's
* default charset.
* ...
*/
@Deprecated(since="1.1")
public String(byte ascii[], int hibyte) {
    ...

genera la siguiente salida:

@Deprecated(since="1.1")
public String​(byte[] ascii, 
    int hibyte)
Deprecated. This method does not properly convert bytes into characters. As of 
JDK 1.1, the preferred way to do this is via the String constructors that take a 
Charset, charset name, or that use the platform's default charset.

Si usa la etiqueta @deprecated Javadoc sin la correspondiente anotación @Deprecated, se genera una advertencia.