Deprecated Annotation

The @Deprecated annotation is a built-in Java marker annotation applied to program elements (classes, methods, fields, interfaces, or constructors) to indicate that they are obsolete and slated for potential future removal. When the Java compiler encounters a reference to an annotated element, it generates a compile-time warning.

Syntax and Attributes

Prior to Java 9, @Deprecated was a simple marker annotation with no attributes. Starting with Java 9, it includes two optional elements to provide stricter lifecycle semantics:

• since (String): Specifies the version in which the API element became deprecated. The default value is an empty string ("").
• forRemoval (boolean): Indicates whether the annotated element is subject to removal in a future version. The default value is false.

@Deprecated(since = "1.5", forRemoval = true)
public void legacyMethod() {
    // Implementation
}

Compiler Behavior

The Java compiler (javac) tracks @Deprecated annotations during the compilation phase.

• Ordinary Deprecation (forRemoval = false): Generates a standard compiler warning when the element is invoked, overridden, or referenced.
• Terminal Deprecation (forRemoval = true): Generates a strict warning indicating that the code will definitively break in a future release.

To view detailed deprecation warnings during compilation, the -Xlint:deprecation flag must be passed to javac:

javac -Xlint:deprecation MyClass.java

Suppressing Warnings

If a developer intentionally references a deprecated element and wishes to suppress the resulting compiler warning, the @SuppressWarnings annotation is applied to the calling code. The suppression string depends on the forRemoval attribute of the target element:

// Suppresses warnings for @Deprecated(forRemoval = false)
@SuppressWarnings("deprecation")
public void callStandardDeprecatedMethod() {
    standardLegacyMethod();
}

// Suppresses warnings for @Deprecated(forRemoval = true)
@SuppressWarnings("removal")
public void callTerminalDeprecatedMethod() {
    terminalLegacyMethod();
}

Javadoc Integration

The @Deprecated annotation is structurally distinct from the @deprecated Javadoc tag. While the annotation triggers compiler warnings and modifies the bytecode metadata, the Javadoc tag is parsed by the javadoc tool to document the deprecation rationale and specify alternative APIs. By convention, both are used concurrently.

/**
 * Calculates the total.
 *
 * @deprecated As of version 2.0, replaced by {@link #calculateTotal(int)}
 */
@Deprecated(since = "2.0", forRemoval = true)
public void calculate() {
    // Implementation
}

Master Java with Deep Grasping Methodology!

Learn More