In Java, it’s common to deprecate a method or class to indicate consumer developers to stop using it on their code. Deprecating a code (class or method) is only a flag that tools like the IDE, the compiler or static code analysis (ex. SonarQube) use to display that warnings to the developer. It’s basically adding the annotation @Deprecated to the class or method, as a good practice as part of the Java Doc, the @deprecated attribute can be used to include additional information.
The idea behind deprecating code is to avoid breaking changes in our APIs, and provide a transition time to consumers to realize and apply the require changes using the recommended alternatives. However, because sometimes when something is deprecated is never removed, it’s common to see deprecated code through many versions during a long time, and as bad practice developers are used to continue using it, because they don’t know the importance of stop using it.
That’s why Java 9 added the attribute forRemoval to the @Deprecated annotation, the purpose is to let know the developer there is a real intention in the short coming future (next releases) to remove completely that code. Therefore, stop using it should be a high priority.
The behavior for the compiler is the same, using the forRemoval = true doesn’t add any new behavior to the code, but as code owner we can feel better to inform consumer developers of a breaking change coming in a new version.
/**
* 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) {
...
}