clipse 中的 API Tools：简介(了解如何使用 Eclipse 管理应用程序的 API)

创建 Application Public Interface（API），尤其是管理各个版本的 API 十分困难。了解如何利用 Eclipse 的 PDE API Tools 来简化此过程，并且无缝地将其集成到日常开发中。注意，本文专门针对 Eclipse V3.4：Ganymede。

在详细介绍 Eclipse Plug-in Development Environment（PDE）内的 Application Public Interface（API）工具之前，让我们谈一谈 Eclipse 中的 API 的含义。

什么是 API？

您是否曾经在 Eclipse 中收到以下警告或错误，并且想知道它们的含义是什么？

图 1. 阻止访问


内部包
根据命名约定，能否真正在插件中构成包 API 取决于是否把包导出到 MANIFEST.MF 文件中。如果是，则视为 API。要创建不是 API 的内容，您可以用 x-internal:=true 属性标记导出的包。这将指示 Eclipse 导出的包可供使用，但是被视为内部包。

导致警告的原因很可能是您正在访问不能使用某种形式的 API 公开访问的代码。通常，API 元素都经过良好记录并且有某种规范。另一方面，非 API 元素被视为内部实现详细信息，并且常常不附带发布文档。上图的 Eclipse 通知您访问了这些内部元素。Eclipse 礼貌地警告您正在访问可能更改并且不受官方支持的代码。那么，确切地说 API 是什么？

由于 Eclipse 基于 Java™ 编程语言，因此有四种 API 元素。让我们逐个查看。

API 包

至少包含一个 API 类或 API 接口的包。

表 1. Eclipse 平台中的包命名约定
命名约定示例包org.eclipse.xyz.*org.eclipse.ui、org.eclipse.swt.widgetsorg.eclipse.xyz.internal.*org.eclipse.compare.internal、org.eclipse.ui.internalorg.eclipse.xyz.internal.provisional.*org.eclipse.equinox.internal.provisional.p2.engine

API 类或接口

API 包中的 public 类或接口，或者在某个其他 API 类或接口中声明或继承的 public 或 protected 类或接口成员。

API 方法

在 API 类或接口中声明或继承的 public 或 protected 方法或构造函数。

API 字段

在 API 类或接口中声明或继承的 public 或 protected 字段。

现在我们已经知道各种各样的 API 元素，让我们讨论 API Tools 及它如何能为您管理这些 API 元素。

回页首

什么是 API Tools？

API Tools 的目的是帮助维护优秀的 API。API Tools 通过报告 API 缺陷来实现维护，例如二进制文件不兼容、不正确的插件版本号、缺少或不正确的 @since 标记及在插件之间使用非 API 代码。具体地说，它设计用于：

• 识别两个版本的软件组件或产品之间的二进制文件不兼容问题。
• 基于 Eclipse 版本控制方案更新插件的版本号。
• 为新添加的类、接口和方法更新 @since 标记。
• 提供新的 javadoc 标记和代码，帮助注释有特殊限制的类型。
• 利用现有信息（位于 MANIFEST.MF 中）定义 Bundle 之间的包的可见性。
• 在插件之间识别非 API 代码的使用。
• 识别非 API 类型是否泄露到 API 中。

回页首

添加 API Tools

要在项目内使用 API Tools，您需要完成两项工作：设置 API 基准和向相关的项目添加 API Tools 属性。

设置 API 基准

要知道是否在破坏 API 的规范，需要设置某种基准以进行兼容性分析。在 API Tools 中，这称为 API 基准并且可以通过 API Baselines 首选项页面设置（参见图 2）。设置 API 基准就像指向基于现有的 Eclipse 安装一样简单。当 API Tools 扫描插件时，它将为您动态生成一个基准。在设置基准后，需要让 Eclipse 项目利用 API Tools。注意，此过程也可以作为构建系统的一部分以无序方式完成，但是这不在本文讨论范围内，并且建议查阅 API Tools wiki 以获得更多信息（请参阅 参考资料）。

图 2. 添加 API 基准

添加 API Tools 项目属性

要查看与 API Tools 相关的任何错误或警告，您的项目需要添加 API Analysis 属性和构建器。这可以通过两种方法完成，并且依赖于是否要将 API Tools 应用到现有项目中。如果与现有项目结合使用，建议的方法是使用 API Tooling Setup 向导（参见图 3）。右键单击项目并选择 PDE Tools > API Tooling Setup 可以访问该向导。在向导中，只需单击想要转换为使用 API Tools 的项目并单击 Finish。这就完成了！

图 3. API Tooling Setup 向导

本文转自IBM Developerworks中国

      请点击此处查看全文