应用JDK 9 @不推荐使用的增强功能

我在博客文章JDK 9 @Deprecated Annotation Enhancements中讨论了针对@Deprecated注释的当前建议的JDK 9增强功能。在本文中，我将更详细地介绍这些次要增强功能的建议用法，并说明关键的Java SE API如何已经应用了这些@Deprecated增强功能。

JEP 277主页面（“ Enhanced Deprecation”）的当前版本指出：“增强@Deprecated注解的主要目的是向工具提供有关API弃用状态的更详细的信息。” 该页面还描述了添加到@Deprecated批注[ forRemoval()和since() ]的两个新方法：

“用于forRemoval()的方法返回boolean 。如果为true ，则表示此API元素已指定在将来的版本中删除。如果为false ，则不推荐使用API元素，但是目前不打算在将来的版本中将其删除。此元素的默认值为false 。 … forRemoval() boolean元素，如果为true ，则表示有意在将来的项目版本中删除该API元素。因此，会提前向API用户发出警告，如果他们不从API迁移过来，则他们的代码在升级到较新版本时可能会被破坏。如果forRemoval()为false ，则表明建议从已弃用的API迁移，但没有删除该API的任何具体意图。”
“一个名为since()方法，它返回String 。该字符串应包含不赞成使用此API的发行版或版本号。它具有自由格式的语法，但是发行版编号应遵循与@since Javadoc标记相同的方案，以用于包含已弃用API的项目。 …此元素的默认值为空字符串。”

本文清楚地表明，其意图是能够明确声明是否可能（计划中）删除不推荐使用的元素，或者是否没有计划删除不推荐使用的元素。对于该不赞成使用的元素的客户来说，这可能是重要的信息，他们需要以何种紧急程度将不赞成使用的元素的使用更改为其他元素。

Java SE API上新的JDK 9 @Deprecated方法的应用还可以指导如何使用它们。关于这一点， JEP 277页面当前指出（我的重点是增加），“几个Java SE API将添加，更新或删除@Deprecated注释。下面列出了一些建议的更改。除非另有说明，否则此处列出的弃用项不适用 。请注意，这不是Java SE 9中不推荐使用的全面列表。还请注意，其中一些项目将不会在Java SE 9中实现 。” 考虑到这一概述，我现在将注意力转向当前JDK 9 API文档中的示例，以说明这些概念。

JEP 277的网页当前列出“向Optional.get方法添加@Deprecated（ JDK-8160606 ）”作为适用于“建议的更改”的Java SE API之一。由于不推荐使用Optional.get（）当前与一个错误（ JDK-8160606 ）相关联，因此即使当前的Javadoc文档尚未显示已应用，但JDK 9仍未排除它。接下来的两个屏幕快照展示了Java SE 9中尚未弃用Optional.get（）的情况。

Java SE 8：引入了Optional.get()

JavaSE8OptionalGetNotDeprecated

Java SE 9：尚未弃用Optional.get()

JDK9OptionalGetNotYet已弃用

已弃用，无拆除计划

JEP 277在Java SE API列表中弃用了“盒装原语”的构造函数，并在@Deprecation处理中提出了“建议的更改”。接下来的两个屏幕快照演示了JDK 9版本的Boolean确实将新的@Deprecated注释应用于其构造函数。

Java SE 8：不建议使用Boolean构造函数

JavaSE8NotDeprecatedBooleanConstructors

Java SE 9： since=9不推荐使用Boolean构造函数

JDK9DeprecatedBooleanConstructors

值得注意的是，新应用的@Deprecated批注包含一个新方法（ since="9" ），而不包括另一个（不forRemoval() 。在这种情况下，除非另有说明，否则Boolean的用户应假定，从Java SE 9开始不推荐使用Boolean构造函数，但是目前尚无删除这些不推荐使用的构造函数的计划。

就JDK 9 @Deprecated注释而言，Applet类的处理与“盒装原始”构造函数类似。像盒装基元类的构造函数一样，在JDK 9中新弃用了与小应用程序相关的类，在注释中添加了since="9" ，以使其清楚地表明它们已使用Java SE 9进行了注释，而没有指定了forRemoval() （意味着假定为false ）。小程序弃用由JEP 289 （“弃用小程序API”）涵盖，该程序的确声明“将@Deprecated(since="9")批注添加到选定的小程序相关类。

自JDK 9起@Deprecated Applet类，但没有forRemoval()

不推荐使用JavaSE9Applet

弃用并计划移除

JDK 9中已弃用并标记为删除的示例之一是System.runFinalizersOnExit（boolean）。以下屏幕快照表明，此方法在Java SE 8中已被弃用，但是在Java SE 9中已弃用该方法，也表明有意删除此方法。我还喜欢它传达的信息，表明该方法在Java 1.2中已被弃用。

Java SE 8：不推荐使用的方法，删除计划或版本最初不建议使用

JavaSE8不推荐使用的SystemRunFinalizersOnExit

Java SE 9：不推荐使用的方法通信原始不推荐使用的版本和删除意图

JDK9不建议使用RemoveTrueSystemRunFinalizersOnExit

结论

JEP 277是有关@Deprecated的当前缺陷以及JDK 9的较小增强如何减轻这些缺陷的至少一部分的高度可读的论文。尽管从许多方面来说，JDK 9更改为@Deprecated可能被称为“婴儿步骤”，但与JDK 9之前的版本@Deprecated ，它们确实提供了一些标准化的功能来传达特定的弃用历史和未来计划。所谓的“ Java SE中的用法”本身很有趣，因为它描述了几个Java SE API（本文中仅强调了其中的一个子集），这些API被提议更改其弃用状态或具有有关弃用历史的其他详细信息和/或将来的计划添加到其中。