1. Overview

1.概述

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

在这个快速教程中，我们将看看Java中的废弃API以及如何使用@Deprecated注解。

**2. The @Deprecated Annotation**

2.@DeprecatedAnnotation

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.

随着项目的发展，其API也会发生变化。随着时间的推移，有一些构造函数、字段、类型或方法，我们不希望人们再使用。

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

我们可以用@Deprecated注解.来标记这些元素，而不是破坏项目API的后向兼容性。

@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:

@Deprecated告诉其他开发者，标记的元素不应该再被使用。通常在@Deprecated注解的旁边添加一些Javadoc，以解释什么是更好的替代方案，以达到正确的行为。

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.

请记住，只有在代码中的某个地方使用了被注释的Java元素时，编译器才会显示过时的API警告。因此，在这种情况下，只有在有代码调用calculate method时才会显示。

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

此外，我们也可以通过使用Javadoc的@deprecated标签在文档中传达废弃状态。

3. Optional Attributes Added in Java 9

3.Java 9中增加的可选属性

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

Java 9为@Deprecated注解增加了一些可选的属性。since和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.

since属性需要一个字符串，让我们定义该元素在哪个版本被废弃。默认值是一个空字符串。

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:

而forRemoval是一个boolean，允许我们指定该元素是否会在下一个版本中被移除。它的默认值是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.

简单地说，上述用法意味着calculate从我们的库的4.5版本开始就被废弃了，并且它被计划在下一个主要版本中被移除。

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.

而且IDE已经支持 检测标有forRemoval=true的方法的使用。例如，IntelliJ通过代码用红线而不是黑线进行打击。

4. Conclusion

4.总结

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.

在这篇快速文章中，我们看到了如何使用@Deprecated注解及其optional属性来标记不应继续使用的代码。

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

这些例子的完整源代码可以在GitHub上找到over。