JEP 179: Document JDK API Support and Stability | 文档化 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 享有与 Java SE API 类似的通用演化策略；这些 API 可用于一般开发，由 JDK 提供者提供支持，稳定，并以大致兼容的方式演化。JDK 中包含的其他 API 仅供 JDK 实现本身使用，并且不应令第三方依赖。JDK 使用的 com.sun.* 命名空间包含了这些"支持"和"不支持"的 API 的混合体。本提案旨在在相关类型和包的源代码中记录与支持性和其他属性相关的信息。记录这些信息将使 API 的状态更加清晰明确，包括在生成的 javadoc 中，还可以让工具自动检查不适当的使用情况。记录这些信息应该是在为 JDK 8 进行的模块化准备工作之外的一个小型增量努力中解决，参见 JEP 162 。
描述
用于记录感兴趣的 API 状态的注解和支持类型将位于 jdk.* 命名空间中。换句话说，这些类型将是 JDK 的一部分，而不是 Java SE 的一部分。除了在 jdk.* 本身添加的新类型之外，预计这些注解主要将用于传统的 com.sun.* 命名空间中的类型。在确定最终的 API 区分集之前，需要进行一些探索和实验。最初的 jdk.Supported 注解类型已经在 JDK 8 中推出，以允许试用，它允许进行支持/不支持的布尔分类。其他可能的感兴趣的分类包括 JRE 与 JDK 之间的区别、仅针对特定用户/组在 JDK 之外的支持，以及稳定性/演化政策的变化程度。
遵循“不要重复自己”的原则，最终应修改 JDK 构建过程，从源代码的注解中构建 ct.sym 原型模块系统信息，而不是在文档制作过程中进行隐晦的依赖。但是，这种构建重构并不是此努力的严格必要部分。
风险和假设
如果此功能的注解最初仅设计为以布尔值的形式捕获某种类型的是/否值，并且在将来认为需要更多分类，那么将初始类型演化成新方案可能会很棘手。因此，在 JDK 8 中应该谨慎确定一个持久的区分集合。
依赖关系
此功能是基于为 JEP 162，为模块化做准备 进行的调查研究而构建的。
影响
其他 JDK 组件：此提案的注解所使用的概念可能有助于规范化 JDK 的其他部分中的策略，但该工作的重点是帮助管理非 Java SE API。
兼容性：该功能将使得兼容性策略能够更好地被记录和执行。
文档：新的注解将是
@Documented，因此将作为生成的 javadoc 包的一部分包含在内。TCK：由于这个提案是在 Java SE 之外的，所以没有 TCK 的影响。