Eclipse 平台
API 约束规则

版本 0.15 - 上次修订时间:2001 年 5 月 30 日 12:00

这里是 Eclipse 平台 API(及其它组件)的客户机的约束规则。

API 的含义

Eclipse 平台定义了供其客户机使用的 API 元素,即编写插件的 ISV。这些插件可依次定义它们的客户机的 API 元素等等。API 元素具有以下共性:它们具有有关它们应执行的内容和有关它们的用途的规范。支持 API 元素:Eclipse 平台小组将修订实现错误(如果其中存在与指定行为的偏差)。由于中断 API 更改通常代价高昂,因此 Eclipse 平台小组还将尝试通过连续的主要发行版有节制地改进 API 元素。

如何区分 API 与非 API

通过它们的性质来区分:API 元素进行了归档且具有规范;相反,非 API 元素是内部实现详细信息,通常没有已发布的文档或规范。因此,如果找不到某个元素的文档,这通常就指示该元素不是 API 元素。

要想区分得更清楚,可将平台的代码库分成 API 包和非 API 包,而所有的 API 元素都在指定的 API 包中声明。

将其它任何事务认为是内部实现详细信息且不受所有客户机限制。合法的客户机代码决不能引用非 API 元素的名称(甚至不能使用 Java 反映)。在某些情况下,Java 语言的名称辅助功能规则用来禁止非法引用。但是,在许多情况下,这是不可能的。遵守以下简单规则就可完全避免这个问题:

一般规则

API 元素的规范是根据该元素的 Java 源代码中的 Javadoc 注释生成的。对于某些类型的元素,规范的格式为合同。例如,在方法的情况下,合同是以下两方间的合同:方法的调用者和方法的实现器。基本规则是: 词语“必须”用于 API 合同中时,表示双方都有责任务必遵从所列条件;如果没有做到,则被认为是一个会导致未指定(且可能是不可预测的)后果的编程错误。 其它普通规则:

调用公共 API 方法

对于大多数客户机,大多数 Eclipse API 在 API 接口或类上采取公共方法的形式,适当时供客户机调用。

实例化平台 API 类

并非所有具体 API 类都可被任何人实例化。API 类具有一个指示可据其创建实例的条款的实例化合同。合同可能还涉及如剩余的初始化责任(例如:在实例完全活动之前配置某个属性)和相关联的生命周期责任(例如:调用 dispose() 以释放实例占用的操作系统资源)之类的事项。在 Javadoc 类注释中对供客户机实例化的类显式地作了标志(标以类似于“客户机可实例化”之类的词).

对平台 API 类划分子类

只能对 API 类的子集划分子类。API 类具有一个指示可据其声明子类的条款的子类合同。此合同还涉及初始化责任和生命周期责任。在 Javadoc 类注释中对供客户机划分子类的类显式地作了标志(标以类似于“客户机可子类化”之类的词).

调用受保护 API 方法

通常允许从子类中调用继承的受保护和公共方法;但是,与从层次结构外部调用公共方法相比,这通常需要更小心地来正确进行调用。

覆盖 API 方法

仅可覆盖公共和受保护 API 方法的某个子集。每个 API 方法都有一个指示一些条款的子类合同,子类可根据这些条款覆盖该方法。缺省情况下,是不允许进行覆盖的。对被覆盖的实际方法实现检查子类合同是很重要的;在覆盖该方法时,不会自动传递子类合同的条款。

实现平台 API 接口

客户机仅可实现 API 接口的某个子集。API 接口具有一个指示根据其可实现这些接口的条款的合同。在 Javadoc 类注释中对供客户机实现的接口显式地作了标志(标以类似于“客户机可实现”之类的词). 客户机可声明 API 接口的子接口(当且仅当允许客户机实现子接口时)。

实现公共 API 方法

请参阅“覆盖 API 方法”。

访问 API 类和接口中的字段

客户机可读取 API 字段(它们大部分为终态)。某些结构类似的对象可能具有非终态的公共字段,除非另有指示,否则客户机可读写这些字段。

转换已知 API 类型的对象的类型

已知 API 类型的对象仅可转换为另一 API 类型(或有条件地使用 instanceof 进行类型转换),如果在 API 中显式允许这样做。 当然,将任何对象的类型转换为非 API 类或接口总是不合适的。

不遵循规则

不管是有意还是无意造成的,违反规则都会造成不良后果。如果有因为您破坏了规则而惩罚您的 API 警察,则一切都会容易得多。但是,情况并非如此。对于大部分情况,API 一致性是作为一个受欢迎的系统运作的,每一个客户机都有责任了解规则并遵守它们。

有关 API 元素的合同定界受支持的和持续的行为。随着 Eclipse 平台的成熟和发展,指导其如何发展的将会是 API 合同 。脱离了这些合同,任何事情都不受支持,可在任何时候(甚至在发布过程中或在不同的操作系统平台之间)不另行通知即进行更改。不符合上述规则的客户机代码在以下情况下可能会失效:在平台的不同版本和补丁级别上;在不同的底层操作系统上运行时;与另一共同驻留插件混合运行时或以另一工作台透视图运行时等等。实际上,甚至没有人会有兴趣去思考任何特定违规事件到底会怎样对您产生负面作用。对于那些选择忽略规则的人,不要说我们没有警告过您啊。要是发生了问题,最多会有人说“我告诉过您的”。

另一方面,遵循上述规则的客户机插件代码应继续在平台的不同版本和补丁级别上工作、在不同的底层操作系统上工作并应与其它插件和平共处。如果每个人都按这些规则办事,则 Eclipse 平台将为构建令人兴奋的新产品提供稳定且受支持的基础。