Java @Deprecated 注解

1. Overview

In this quick tutorial, we’ll have a look at deprecated APIs in Java and how to use the @Deprecated annotation.

2. The @Deprecated Annotation

As a project evolves, its API changes. Over time, there are certain constructors, fields, types or methods that we don’t want people to use anymore.

Instead of breaking the backward compatibility of the project’s API, we can tag these elements with the @Deprecated annotation*.*

@Deprecated tells other developers that the marked element should no longer be used. It’s common to also add some Javadoc next to the @Deprecated annotation to explain what would be a better alternative that serves the right behavior:

public class Worker {
    /**
     * Calculate period between versions
     * @deprecated
     * This method is no longer acceptable to compute time between versions.
     * <p> Use {@link Utils#calculatePeriod(Machine)} instead.
     *
     * @param machine instance
     * @return computed time
     */
    @Deprecated
    public int calculate(Machine machine) {
        return machine.exportVersions().size() * 10;
    }
}

Remember that a compiler only displays the deprecated API warning if the annotated Java element is used somewhere in the code. So, in this case, it would only show if there was code that called the calculate method.

Also, we can communicate the deprecated status in the documentation as well by using the Javadoc @deprecated tag.

3. Optional Attributes Added in Java 9

Java 9 adds some optional attributes to the @Deprecated annotation: since and forRemoval.

The since attribute requires a string that lets us define in which version the element was deprecated. The default value is an empty string.

And forRemoval is a boolean that allows us to specify if the element will be removed in the next release. Its default value is false:

public class Worker {
    /**
     * Calculate period between versions
     * @deprecated
     * This method is no longer acceptable to compute time between versions.
     * <p> Use {@link Utils#calculatePeriod(Machine)} instead.
     *
     * @param machine instance
     * @return computed time
     */
    @Deprecated(since = "4.5", forRemoval = true)
    public int calculate(Machine machine) {
        return machine.exportVersions().size() * 10;
    }
}

Simply put, the above usage means that calculate has been deprecated since 4.5 of our library and that its scheduled for removal in the next major release.

It’s helpful for us to add this since the compiler will give us a stronger warning if it finds that we are using a method with that value.

And there is already support from IDEs to detect uses of a method marked with forRemoval=true. IntelliJ, for example, strikes through the code with a red line instead of a black one.

4. Conclusion

In this quick article, we saw how to use the @Deprecated annotation and its optional attributes to mark code that should no longer be used.

The full source code for the examples can be found over on GitHub.