En Java, es común deprecar un método o clase para indicar a los desarrolladores consumidores que dejen de usarlo en su código. Deprecar un código (clase o método) es solo una bandera que las herramientas como el IDE, el compilador o el análisis de código estático (por ejemplo, SonarQube) usan para mostrar esas advertencias al desarrollador. Básicamente es agregar la anotación @Deprecated a la clase o método, como una buena práctica como parte de Java Doc, el atributo @deprecated se puede usar para incluir información adicional.
La idea detrás de deprecar un código es evitar que cambios importantes en nuestras API afecten otros sistemas y proporcionar un tiempo de transición a los consumidores para realizar y aplicar los cambios requeridos utilizando las alternativas recomendadas. Sin embargo, debido a que a veces, cuando algo está en desuso, nunca se elimina, es común ver código en desuso a través de muchas versiones durante mucho tiempo, y como mala práctica.
Es por eso que Java 9 agregó el atributo forRemoval a la anotación @Deprecated, el propósito es hacerle saber al desarrollador que existe una intención real en el futuro cercano (próximos lanzamientos) de eliminar completamente ese código. Por lo tanto, dejar de usarlo debe ser una alta prioridad.
El comportamiento para el compilador es el mismo, usar forRemoval = true no agrega ningún comportamiento nuevo al código, pero como propietarios del código podemos sentirnos mejor si informamos a los desarrolladores consumidores de un cambio importante que se avecina en una nueva versión.
/**
* Delete multiple items from the list.
*
* @deprecated Not for public use.
* This method is expected to be retained only as a package
* private method. Replaced by
* {@link #remove(int)} and {@link #removeAll()}
*/
@Deprecated (forRemoval = true)
public synchronized void delItems(int start, int end) {
...
}