rspec/rules/S5738/java/rule.adoc

Java 9 introduced a flag for the ``++@Deprecated++`` annotation, which allows to explicitly say if the deprecated code is planned to be removed at some point or not. This is done using ``++forRemoval=true++`` as annotation parameter. The javadoc of the annotation explicitly mention the following: 


____
If true, it means that this API element is earmarked for removal in a future release.

If false, the API element is deprecated, but there is currently no intention to remove it in a future release.

____

While usually deprecated classes, interfaces, and their deprecated members should be avoided rather than used, inherited or extended, those already marked for removal are much more sensitive to causing trouble in your code soon. Consequently, any usage of such deprecated code should be avoided or removed.


== Noncompliant Code Example

[source,java]
----
/**
 * @deprecated As of release 1.3, replaced by {@link #Fee}. Will be dropped with release 1.4.
 */
@Deprecated(forRemoval=true)
public class Foo { ... }

public class Bar {
  /**
   * @deprecated  As of release 1.7, replaced by {@link #doTheThingBetter()}
   */
  @Deprecated(forRemoval=true)
  public void doTheThing() { ... }

  public void doTheThingBetter() { ... }

  /**
   * @deprecated As of release 1.14 due to poor performances.
   */
  @Deprecated(forRemoval=false)
  public void doTheOtherThing() { ... }
}

public class Qix extends Bar {
  @Override
  public void doTheThing() { ... } // Noncompliant; don't override a deprecated method marked for removal
}

public class Bar extends Foo {  // Noncompliant; Foo is deprecated and will be removed

  public void myMethod() {
    Bar bar = new Bar();  // okay; the class isn't deprecated
    bar.doTheThing();  // Noncompliant; doTheThing method is deprecated and will be removed

    bar.doTheOtherThing(); // Okay; deprecated, but not marked for removal
  }
}
----


== See

* https://cwe.mitre.org/data/definitions/477[MITRE, CWE-477] - Use of Obsolete Functions
* https://wiki.sei.cmu.edu/confluence/x/6TdGBQ[CERT, MET02-J.] - Do not use deprecated or obsolete classes or methods
* RSPEC-1874 for standard deprecation use


ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

include::message.adoc[]

'''
== Comments And Links
(visible only on this page)

include::comments-and-links.adoc[]
endif::env-github,rspecator-view[]