客户端如何调用 Rational CM API 实现 Rational ClearCase 的相关操作

<script type="text/javascript"></script>

级别： 中级

慕容 雪, 软件工程师, IBM

2009 年 1 月 19 日

本文将为您介绍 Rational ClearCase 7.1 带来的新特性之一：IBM Rational CM API。并介绍在客户端进行二次开发时，如何调用 Rational CM API 实现 Rational ClearCase 的相关操作。

每个 Rational 产品都有自己的 API，通过该 API 可以访问特定于其产品的存储库。在 7.1 版本中，Rational 提供了一个统一的 API 来访问 ClearCase 和 ClearQuest 资源，这就是 Rational CM API。

Rational CM API 介绍

IBM Rational CM API 是一个统一的 Java API，从工作空间版本控制和管理（WVCM）API 扩展而来，是用于配置管理的标准 API。用户可以通过该 API 来构建客户端程序用于访问 ClearCase 和 ClearQuest 应用程序，还可以对这些产品构建新的集成。客户端可以有两种形式：基于 Elcipse 的插件形式和 Java 应用程序。（参见 CCRC 的两种形式）。目前该 API 支持 ClearCaes 的 Web 视图。图 1 是 CM API 的工作体系结构，我们可以看到，客户端程序要访问产品数据，必须通过 CM API 提供器和子提供器来调用产品程序。下边我们逐项来说明。

CM API 客户端

客户端程序发出请求的过程，就是对提供器上 CM API 调用的过程。主要使用代理对象来与服务器上资源进行交互。这里简要介绍一下什么是代理对象。Rational CM API 由对象组成，这些对象是在 Rational 产品维护的不同存储库中存储的持久资源的代理。代理是客户端上的对象，代理对象表示 CM API 提供器会话过程中的资源。要访问产品资源，客户端必须首先创建一个实现 CM API 接口的代理对象，该代理对象从提供器对象调用方法，或从另一个代理对象上调用方法，然后客户端可以使用代理对象的方法来访问资源或者修改属性。代理对象是由提供器返回客户端的对象，不占用实际的服务器资源。

CM API 提供器

API 提供器是一个 Java 的包集合，客户端通过使用这些包来实现和服务器端的交互。提供器接收到客户端的请求后，将请求分派到特定于产品的子提供器，子提供器再和相应产品的存储库进行交互，获取请求的相应结果。Rational CM API 就是由 CM API 提供器实现的。那么，CM API 包含哪些程序包呢？

Javax.wvcm

这是 JSR-147 定义的接口，是工作空间版本控制和配置管理程序包。这些接口形成了 CM API 的基础，并定义了对象模型的形式。

com.ibm.Rational.wvcm.stp

STP 程序包从 WVCM 扩展扩展而来，包含 Rational CM API 的接口。这是个独立于 ClearCase 和 ClearQuest 的实现，高于产品一级的抽象。也就是说，还可以从这个包进行具体产品接口的扩展，STP 包只是提供了公共对象模型和公共接口。

CM API 子提供器

子提供器着眼于特定产品，是专门为产品创建的 CM API 扩展程序包。子提供器连接到 API 提供器上，将产品的对象结构映射到 Ratinoal CM API 对象模型上。通过特定产品的程序包的接口，可以方便的实现相关产品上的任务。比如通过 com.ibm.Rational.wvcm.stp.cc 程序包，用户可以配置和管理资产（创建视图，对视图中的元素执行检入，检出操作，查看元素属性等）。通过 com.ibm.Rational.wvcm.stp.cq 程序包，用户可以更改管理功能（创建，修改数据库记录，创建查询，修改记录重字段等）。同样的，子提供器也是一些包的集合：

com.ibm.Rational.wvcm.stp.cq

CQ 程序包是基于 STP 的，对应 ClearQuest 产品的扩展。提供对 ClearQuest 存储库以及底层资源的访问。

com.ibm.Rational.wvcm.stp.cc

CC 程序包也是基于 STP 的，对应于 ClearCase 产品的扩展。同样的，可以访问 ClearCase 存储库和底层资源。另外，CC 程序包还包括了对 WVCM 包的扩展，进而提供访问 ClearCase 资源的接口。

回页首

Rational CM API ClearCase 公共对象模型

在接下来的部分，我们将介绍 CM server API 中面向 ClearCase 的 API。

Rational CM API 公共对象模型基于 WVCM 代理和属性模型扩展而来，它将每个 Rational 产品的对象映射到资源代理层次结构 , 使客户端可以通过接口来访问产品的数据。每个接口都是由上至下一级级扩展而来，每次扩展都会加上特定的信息。比如在 WVCM 包中定义了 resource 这个接口，在 com.ibm.Rational.wvcm.stp 包中被扩展而成 StpResource 接口，在 com.ibm.Rational.wvcm.stp.cq 包中的 CqRecord 接口又是 StpResource 接口的进一步扩展，通过这个接口，用户就可以访问 cq 中的记录信息。下边将介绍一些基本公共对象模型。

提供器对象（provider）

提供器对象在整个 API 开发中占有重要地位，因为客户端只有首先创建提供器对象，才能获取资源代理和访问资源 , 它是用户与服务器之间的“桥梁”。提供器对象完全受客户端控制，并且和服务器上某些资源紧密相关。实例化提供器后，客户端应用程序可向资源代理的提供器发出请求。在 CM API 中，StpProvider、CcProvider 和 CqProvider 是对 WVCM Provider 的扩展。

下边这段代码利用工厂方法实例化一个 cc 子提供器对象：

// 实例化回调参数 mycallback
Callback mycallback = new MyAuthCallback(serverUrl, login, password); 
StpProvider provider = (StpProvider) 
//cc 子提供器
ProviderFactory.createProvider(CcProvider.CC_ONLY_PROVIDER_CLASS, mycallback);………//MyAuthCallback 类实现了 Callback 接口
private static class MyAuthCallback implements Callback 
{………}

mycallback 是一个回调参数，什么是回调？当程序需要访问产品时，需要请求用户凭证，回调就是创建用户认证信息并返回到提供器，而每个提供器实例都拥有一个回调对象来获取任何产品存储库的凭证。

资源和代理对象

资源是放置在产品存储库中的所有集合，它可以是 ClearCase 中的元素或某个版本，也可以是 ClearQuest 中某一个记录。每个资源都有一个位置来唯一的标识，对于基于文件的资源，该位置表示为文件路径名称；对于服务器端资源，该位置包含查找对象所需的信息。Provider 类构建代理用于响应客户端请求，然后客户端就可以调用代理上的方法来创建，修改或删除资源。在 CM API 中，使用 StpLocation 对象表示资源位置，并用于为资源构造代理。如下面代码所示：

// 对文件资源，创建一个位置对象
StpLocation fileLoc = provider.stpLocation("C://sample_view//sample_file.txt"); // 引用位置对象，使用方法 ccFile 为文件资源创建代理对象 my_ctresource。
CcFile my_resource =provider.ccFile(fileLoc);

上例中代理类和创建方法的名称拼写是一样的（CcFile 和 ccFile），区别在于类的首字母需要大写。

属性对象

资源具有属性，每个属性都有名称，类型和值。CM API 中属性名称由 PropertyNameList.PropertyName 对象表示，所有属性名称是一系列类型为 PropertyName 的字段，这些 PropertyName 对象用于从服务器请求属性，并在从服务器获取属性值后访问属性值，都用大写表示。属性值的类型一般为简单数据类型，比如字符串，整型或日期类型。属性的值的获取和设置通过调用代理的 Get 和 Set 方法来实现。Resource 类提供了一些一般方法，以通过使用每个属性的 PropertyName 对象来访问代理定义的属性值（Resource.getProperty(PropertyNameList.PropertyName) 和 Resource.setProperty(PropertyNameList.PropertyName, Object)

属性请求对象

Rational CM API 客户端应用程序必须首先获取对资源的代理，然后才能读或更新属性。在客户端可以从代理访问属性之前，必须将那些属性从资源读入代理中。在将属性从资源读入代理时，客户端应用程序必须将属性的名称包含到属性请求对象中。

PropertyRequest request = new PropertyRequest(Resource.DISPLAY_NAME,
Resource.LAST_MODIFIED); // 构建属性请求对象

回页首

客户端如何访问 CM API

安装需求

首先，客户端应该安装相应 Rational 产品并获得许可证 ; 其次，在自己的 Java 开发环境中，需要用到如表 1 组件：用户可以根据需要，选择不同的子提供器添加到类路径中。

以 Eclipse 插件形式访问

两种方式来创建 Eclipse 插件：1、使用 teamapi 压缩文件和上节列出的 Jar 包来创建插件；2、将 CM API 作为项目导入到 eclipse 中。

以第一种方式为例，要支持从 eclipse 运行时环境来访问 CM API, 需要把 CM API 插件添加到运行时配置，可以将该插件复制到 eclipse 实例中（plugin 目录下）或创建新的安装站点。Teamapi 压缩文件是一个自包含 eclipse 插件，由 CM API JAR 文件和特定于产品的 JAR 文件构成，该文件在产品安装成功后，位于 <install directory>/common 目录下。第二种方式，需要我们提前把所需要的表 1 中列出的所有 JAR 文件复制到一个统一的目录下，然后在 elcipse 工作空间中，新建一个项目，在库文件标签页选择“add external JARs”, 找到刚才放所有 JAR 文件的目录，添加进项目中。如图 2 所示：

以 Java 客户端形式访问

针对 ClearCase 和 ClearQuest 两种产品有不同的访问形式。对 ClearQuest 来说，要使客户端对 ClearQuest 子提供器发出请求，客户端程序必须和 ClearQuest 产品安装在同一台机器上，才能够调用 CM API。

对 ClearCase 来说，由于 ClearCase 子提供器可以支持 Web 视图，所以客户端可以通过 Rational CM 服务器进行远程访问。当前 CM API 还不支持动态视图和快照视图，需要将 JAR 文件从服务器端复制到客户端的安装目录或者插件目录。

回页首

调用 CM API 实现 cc 中 add to source control 的操作

例如，我们要实现把一个客户端本地私有文件加入到 ClearCase 的资源管理中，也就是 add to source control 动作。在开发环境配置上，首先，需要打开一个已经安装了 CCRC7.1 插件的 eclipse 工作空间，在 ClearCase 视图窗口的本地 Web 视图下，新建一个私有文件（C:/Documents and Settings/ccadmin/ccadmin_view/vob1/file5）。切换到 Java 视图窗口，新建一个 Java 项目，引入第 3 节介绍的 cc 所需要的压缩包，并新建一个 Addtosrc.Java 文件，输入程序代码。如果有输入参数，需要在运行设置中指定输入参数，如图 3 所示。

当程序运行完毕后，我们切换回 ClearCase 视图，打开指定 Web 视图路径下的本地文件，发现私有文件 file5 已经被加入资源控制中。同样的，检入，检出功能都可以用这样的流程来做。

那么，如何编写具体程序？

首先，确定该程序的逻辑结构，需要调用的类和方法以及先后顺序。还以 add to source control 为例，它的逻辑结构可以参考图 4、图 5 所示。

主程序需要作三件事：第一，实例化提供器，这里是 ccprovider。第二，构建代理对象，考虑到加入源控制的文件和目录密切相关，这里需要对文件及其父目录分别构建代理对象；第三，调用代理方法实现加入源控制动作，具体又可以分三步走：首先将目录对象检出（doCheckout 方法），然后将文件对象加入源控制（doVersionControl 方法），最后将目录对象检入（doCheckin 方法）。读者可以根据产品中提供的代码示例来自行完成。

回页首

总结

Rational CM API 的推出极大的拓展了产品的应用空间，客户可以应用 API 开发出更自由灵活的应用程序，对 Rational 产品功能或是产品之间的集成应用是一项有益的补充。本文着眼于 CM API 中面向 ClearCase 功能实现的的概要阐释和说明，更多的 API 应用文档和示例代码可以从产品安装目录 common/CM 下的 teamapi.zip 包中获得。

		慕容雪，IBM 中国软件开发实验室，Rational 团队，软件工程师。