What is @Deprecated annotation in Java

The @Deprecated annotation marks a method, class, constructor, field, or package as outdated — signaling to other developers that it should no longer be used and may be removed in a future version. It generates compiler warnings and IDE indicators whenever deprecated code is called.

Basic Usage

Apply @Deprecated directly above the element you want to mark:

public class Calculator {

    @Deprecated
    public int add(int a, int b) {
        return a + b;
    }

    public int addValues(int a, int b) {
        return a + b;
    }
}

When another class calls calc.add(1, 2), the compiler emits a warning and most IDEs render the method name with strikethrough styling.

The since and forRemoval Attributes (Java 9+)

Java 9 added two optional attributes to @Deprecated that make the annotation more informative:

public class DataProcessor {

    @Deprecated(since = "2.0", forRemoval = true)
    public void processLegacy(String data) {
        // old implementation
    }

    public void process(String data) {
        // new implementation
    }
}

When forRemoval = true, IDEs and tools can distinguish between "use with caution" and "stop using this immediately." The compiler also emits a stronger warning variant (removal category vs. deprecation category).

The @deprecated Javadoc Tag

Alongside the annotation, always add a @deprecated Javadoc tag that explains why the element is deprecated and what to use instead:

/**
 * Computes the sum of two integers.
 *
 * @deprecated As of version 2.0, use {@link #addValues(int, int)} instead.
 *             This method does not handle integer overflow correctly.
 */
@Deprecated(since = "2.0", forRemoval = true)
public int add(int a, int b) {
    return a + b;
}

The @deprecated tag (lowercase) is what appears in Javadoc HTML output. The @Deprecated annotation (uppercase) is what the compiler and tools read. Both serve different audiences — use both together.

Deprecating a Class

/**
 * @deprecated Use {@link NewAuthService} instead. This class will be
 *             removed in version 4.0.
 */
@Deprecated(since = "3.0", forRemoval = true)
public class LegacyAuthService {
    // ...
}

Deprecating a class does not automatically deprecate its methods — each element is deprecated independently. However, marking the class gives a clear signal that the entire API is being retired.

Deprecating a Constructor

public class Connection {

    @Deprecated(since = "1.5")
    public Connection(String url, String user, String password) {
        // password passed as plain string — insecure
    }

    public Connection(String url, String user, char[] password) {
        // char[] is cleared after use — preferred
    }
}

When to Use @Deprecated

• You've written a better version of a method and want callers to migrate to it
• A class or API is being retired in an upcoming major version
• A security or correctness issue was found in the current implementation
• External library APIs that you're wrapping have been replaced

Don't use @Deprecated as a way to "soft delete" code you're too lazy to remove. If something should go, remove it. Reserve deprecation for situations where you need to maintain backward compatibility across a transition period.

Suppressing Deprecation Warnings

If you're intentionally calling deprecated code (e.g., during a migration), suppress the warning to keep build output clean:

@SuppressWarnings("deprecation")
public void migrationCode() {
    legacyService.processLegacy(data); // intentional — being migrated
}

Only suppress when you have a deliberate reason. Blanket suppression at the class level hides all deprecation warnings, including ones you genuinely need to fix.

Summary

Use @Deprecated when you have a better alternative and want to give callers time to migrate. Always add since and forRemoval attributes (Java 9+) so callers understand the urgency, and pair the annotation with a @deprecated Javadoc tag that points to the replacement. The annotation generates compiler warnings and IDE indicators — use @SuppressWarnings("deprecation") only when you're intentionally calling deprecated code during a controlled migration.