JEP 179：记录 JDK API 的支持与稳定性
概述
长期以来，JDK 存在一个不足之处，即未能明确指定对 com.sun.* 类型以及其他随 JDK 提供但不属于 Java SE 规范的类型的支持和稳定性使用约定。这些约定以及潜在的演进策略应当在这些类型的源代码和生成的类文件中清晰地体现出来。这类信息可以通过 JDK 特定的注解类型来建模。
目标
该提案的主要目标是捕获有关这些 API 状态的预模块化调查结果，并使 JDK 的维护人员和使用 JDK 的开发人员更清楚地了解这些信息。
将 API 标记为可由某些特定方使用、但不通用，也可能很有帮助。
非目标
存储 API 状态信息的预期实现机制是一种或多种注解类型，并辅以用于建模的支持类型，例如枚举。这些类型旨在 JDK 内部使用。如果它们在 JDK 之外也有用，那是一个令人欣喜的结果，但是，举例来说，设计一个具有非常细致的稳定性级别分类的通用分类方案并不在本次工作的范围之内。
动机
除了实现 Java SE API 之外，JDK 的代码库还包含其他不属于 Java SE 规范且位于不同命名空间中的 API 源代码，并且 JDK 发行版中也附带了这些 API。其中一些 JDK API 享有与 Java SE API 类似的通用演进策略；这些 API 可用于通用开发，由 JDK 提供商支持，具有稳定性，并以高度兼容的方式进行演进。而其他包含在 JDK 中的 API 则仅用于 JDK 实现本身，第三方不应依赖这些 API。JDK 使用的 com.sun.* 命名空间中混合了这些“受支持”和“不受支持”的 API。本 JEP 提议在相关类型和包的源代码中记录有关支持状态及其他相关特性的信息。记录这些信息将使 API 的状态更加清晰和明确，包括在生成的 javadoc 中，还可以让工具通过编程方式检查不当使用情况。这项信息记录工作应该在为 JDK 8 进行模块化准备（详见 JEP 162）的基础上，通过少量额外的工作增量完成。
描述
用于记录目标 API 状态的注解和支持类型将位于 jdk.* 命名空间中。换句话说，这些类型将成为 JDK 的一部分，而不是 Java SE 的一部分。除了在 jdk.* 中新增的类型外，这些注解预计主要会用于旧版 com.sun.* 命名空间中的类型。在最终确定 API 区分方案之前，可能需要进行一些探索和实验。初始的 jdk.Supported 注解类型已经被推送到 JDK 8 中，以允许试验性使用，该注解支持布尔值的“受支持/不受支持”分类。其他可能感兴趣的分类包括 JRE 与 JDK 的区分、仅针对某些用户/组在 JDK 外部支持的情况，以及稳定性和演进策略的细化分类。
按照“不要重复自己”（DRY）的原则，最终应该修改 JDK 的构建系统，使其从源代码的注解中构建 ct.sym 原型模块系统的相关信息，而不是隐晦地依赖于文档 Makefile。但这种构建重构并不是这项工作严格必要的部分。
风险与假设
如果此功能的注解最初设计为仅捕获某种布尔值（是/否），而未来认为需要更多分类时，将初始类型演变为新方案可能会很尴尬。因此，在 JDK 8 中应谨慎确定一组持久的区别。
依赖
此特性基于为 JEP 162，Prepare for Modularization 所进行的调查构建。
影响
- 其他 JDK 组件：本提案中注解所使用到的概念可能有助于将其他部分的 JDK 政策形式化，但工作的重点是帮助管理非 Java SE 的 API。
- 兼容性：该功能将允许更好地记录和执行兼容性政策。
- 文档：新的注解将会被
@Documented修饰，因此会作为生成的任何 javadoc 文档包的一部分包含在内。 - TCK（技术兼容性套件）：由于本提案不属于 Java SE 范围，所以不会对 TCK 产生影响。