跳到主要内容

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 实现本身使用，不应被第三方依赖。com.sun.*JDK 使用的命名空间包括这些“支持”和“不支持”API 的混合体。该 JEP 建议记录有关支持性以及相关类型和包的来源中感兴趣的属性的信息。记录此信息将使 API 的状态更加清晰明确，包括在生成的 javadoc 中，并且还允许工具以编程方式检查是否有不当使用。除了JEP 162中已为 JDK 8 所做的模块化准备之外，还应通过少量增量工作来解决此信息的记录问题。

描述​

用于记录感兴趣的 API 状态的注释和支持类型将驻留在jdk.*命名空间中。换句话说，这些类型将成为 JDK 的一部分，而不是 Java SE 的一部分。除了本身添加的新类型之外jdk.*，注释预计主要用于旧com.sun.*命名空间中的类型。在确定最终的 API 区别之前，预计需要进行一些探索和实验。初始jdk.Supported注释类型已推送到 JDK 8 中以允许试用，它允许布尔支持/不支持分类。其他可能感兴趣的分类包括 JRE 与 JDK、仅针对某些用户/组在 JDK 之外受支持，以及稳定性/演进策略分级。

在遵循“不重复”原则的情况下，最终应该修改 JDK 构建，ct.sym以根据源上的注释构建原型模块系统信息，而不是模糊地依赖文档 makefile，但这种构建重构并不是绝对必要的这项努力的一部分。

风险和假设​

如果此功能的注释最初设计为仅捕获某种布尔值是/否值，并且将来认为有必要进行更多分类，则演化初始类型来对新类型进行建模可能会很尴尬。方案。因此，在 JDK 8 中应谨慎确定一组持久的区别。

依赖关系​

此功能建立在对JEP 162 “准备模块化”进行的调查的基础上。

影响​

  • 其他 JDK 组件：该提案的注释所使用的概念可能有助于规范 JDK 其他部分中的策略，但工作重点是帮助管理非 Java SE API。

  • 兼容性：该功能将允许更好地记录和执行兼容性策略。

  • 文档：新注释将@Documented作为任何生成的 javadoc 包的一部分包含在内。

  • TCK：由于该提案不在 Java SE 范围内，因此不会对 TCK 产生影响。