简介： 在 IBM Rational ClearCase 和 IBM Rational ClearQuest V7.1 版本中，推出了统一的 Java API 来访问 ClearCase 和 ClearQuest 资源，即 Change Management Application Interface(CM API)。本文将为您介绍如何在客户端调用 CM API 实现 ClearQuest 的相关操作。
Change Management Application Interface（以下简称 CM API）是一种统一的、客户端的 Java API。它扩展自 SR-147：WVCM (Workspace Versioning and Configuration Management)，是一种面向资源的数据模型，并实现了针对具体作用域服务细分。并且由于该接口是在 Java5.0 的基础上实现的，因此具有跨平台性。
CM API 的功用，对于 Rational ClearCase 和 Rational ClearQuest 产品来说，它实现了对 V7.1 及以后版本中产品统一的用户界面、各产品之间的集成提供了强大的支持；对于用户来说，可以通过 CM API 遵循 ClearCase 和 ClearQuest 的业务行为和规则对服务器的资源进行访问（如图 1 所示）。
CM API 公共对象主要有提供器（Providers）、资源（Resources）、位置（Locations）以及属性（Properties）。
调用 CM API 编写程序主要遵照以下几点规则：
1）客户端的提供器（Provider）对象代表了用户，可以与一个或多个服务器连接
2）Servers 上存储着多种类型的资源（Resources）
3）资源对象都位于一定的存储库（Repositories）中
4）每一个资源对象都已惟一的位置（Locations）来标识
5）资源对象拥有某些特定类型的属性（Properties）
6）资源对象可以具有内容（Content）
7）资源对象支持对特定类型的操作
8）客户端使用代理（Proxy）来完成以下操作：
读 / 写资源属性；
读 / 写资源内容；
对资源进行操作。
图 2 表明上述关系。其中代理是 CM API 客户端的 Java 对象，用来代表服务器端的资源。
基于这种编程模型，如果客户端调用 CM API 继而通过 CM Server 访问服务器的资源，基本的步骤如下（如图 3 所示）：
1）根据操作的对象创建一个提供器对象
2）根据资源对象的位置创建一个代理对象
3）将资源的属性值付给代理对象（可选）
4）代理对象执行“do”操作，可完成下列操作中的一个
服务器端将这个属性的新值写入资源对象；
服务器执行某项特定的操作；
服务器读取属性值并返回给客户端。
5）检查返回的代理对象
ClearQuest CM API 沿用了 WVCM 的编程模型，即 Providers、Resources、Locations 和 Properties，以及四者之间遵循的逻辑关系。除此之外， ClearQuest CM API 一些特有的性质，将在这一节中着重介绍。
如上所述，CM API 具有域服务细分的特点：客户端调用 CM API 执行访问 ClearQuest 资源时，是由 CqProvider（Provider 的一个子接口）提供服务。如下代码所示，创建了一个 CqProvider 对象：
清单 1. 创建一个 CqProvider 对象
CqProvider provider = (CqProvider) ProviderFactory .createProvider(CQ_ONLY_PROVIDER_CLASS, callback); |
其中 callback 是一个回调参数，用于验证用户凭证。
CM API 涉及到的每一个资源对象，都有惟一的位置标识，并且以统一的格式表示：
.:[@] |
对于 ClearQuest 域中的各种资源对象，其表示方法举例说明如下：
清单 1. ClearQuest 域中的各种资源对象的表示方法示例
cq.action: /@/ cq.record: /@/ cq.query: /@/ |
上述三个例子分别表示一个 ClearQuest 的 action 对象、record 对象和 query 对象的位置标识格式。
实际上，做为典型的变更追踪管理系统，ClearQuest 的业务功能与行为并不与 WVCM 所定义的典型版本控制管理系统的业务模型与行为相符合。因此大多数来自于 WVCM 的资源类型对 ClearQuest 来说并不适用。ClearQuest CM API 对于 WVCM 的资源层次结构，只沿用了 Resource 及其子接口 Folder；并从 CM API 已经扩展的 StpResouce 等接口之上，扩展出适合于 ClearQuest 的众多接口，如 CqResource，CqRecourd, CqDbset 等等，图 4 描述了以 CqResource 为轴心的各个资源接口类型间的扩展关系。
图 4. ClearQuest 域 Resource 类型示例
下面这段代码，创建了一个 CqRecord 对象的代理：
CqRecord record = provider.buildProxy(CqRecord.class, “Defect/SAMPL00000011@DBSET1/SAMPL”); |
在包含 CM API 的第一个发布版本的 ClearCase 和 ClearQuest V7.1 中，ClearQuest CM API 通过 ClearQuest Core JNI 接口，间接的调用本地 ClearQuest Core 对 ClearQuest DBSET 进行访问，即以 JNI(Java Native Interface) 的方式来实现的（如图 5）。因此，客户端对 ClearQuest 子提供器发出请求，客户端程序必须和 ClearQuest 产品（至少包含客户端组件）安装在同一台机器上，才能够使用 CM API。在 CM API 未来的发布版本中，将可以通过 CM Server 实现真正的客户端 - 服务器模式访问。
图 5. ClearQuest CM API 连接 ClearQuest 服务
接下来，本文将以“浏览记录”为实例介绍如何调用 ClearQuest CM API 对 ClearQuest 进行数据访问与相关操作。
如果读者希望通过示例程序来学习 CM API 的使用，可以将 teamapi 作为一个已经存在的项目导入到 Eclipse 中。teamapi 是 ClearQuest 产品安装目录下的一个压缩包，位于 \common\CM，包含了一些调用 CM API 的项目。读者可以按照以下两步引入项目：
1）将 teamapi.zip 解压缩到一个目录，如 D:\teamapi
2）启动 Eclipse, 选择 File->Import->General->Existing Project into Workspace -> Browse-> 选择 D:\teamapi （如图 6）。
引入已有项目
如果读者希望自己调用 CM API 来开发自己的项目，则可以按照以下步骤进行：
1）创建一个目录，如 D:\teamjar，将下列压缩文件从服务器的安装路径中复制过来；
| Jar 文件 | 功用 |
|---|---|
| /common/stpwvcm.jar | WVCM 接口 |
| /common/stpcmmn.jar | CM API 公共组件实现 |
| / ClearQuest/stpcq.jar | ClearQuest 组件的实现 |
| ./ ClearQuest/cqjni.jar | ClearQuest JNI 实现 |
2）在 Eclipse 中创建一个新的项目；
3）右键项目名称 ->BuildPath->Add External Add External Archives-> 浏览到 D:\ teamjar 并选中以上全部 4 个 jar 文件（如图 7）。
对于 ClearQuest 领域的 CM API 而言，目前，能够实现如下的功能：
- 创建、修改和删除记录（例如，创建缺陷更改请求记录类型）
- 选择操作并更改状态
- 创建查询，选择查询并执行该查询；另外，修改现有查询并使用新名称保存该查询
- 创建、修改和删除记录中的字段值
下面以 teamapi sample 项目中的 ViewRecord.java 来分析 ClearQuest CM API 的调用。
- ClearQuest 服务器的设置：使用 ClaearQuest Maintainance Tool 创建一个 Schema Repository: Schema1，用户数据库命名为 CQ1；
- 客户端的设置：启动 ClearQuest Eclipse 客户端，创建一个新的连接：CQDB1
下边这段代码位于 Utilities 类中，它利用工厂方法实例化一个提供器对象：
static StpProvider getProvider() throws Exception {
try {
Callback callback = new StpCallback() {
public Authentication getAuthentication(String r, int c){
return null; /* Will not be called */
}
public Authentication getAuthenticationEx(Domain domain,String realm,
int retryCount,StpProvider provider,WvcmException failure) throws WvcmException{
// Get username and password from prompted dialogue
……
}
};
// Instantiate a Provider
return (StpProvider) ProviderFactory
.createProvider(StpProvider.PROVIDER_CLASS, callback);
} catch (InvocationTargetException ite) {
//report problem
}
}
|
再通过如下语句获得 ClearQuest 子提供器对象：
CqProvider provider = Utilities.getProvider().cqProvider(); |
上述代码中的 getAuthenticationEx 方法，用来实现获取用户名和密码。
下面代码获取了一个 CqUserDB 类型的资源列表：
static ResourceList getUserDbList(CqProvider provider,
PropertyRequest feedback) throws WvcmException{
PropertyRequest wantedProps =
new PropertyRequest(CqDbSet.CURRENT_USER
.nest(CqUser.SUBSCRIBED_DATABASES.nest(feedback)));
ResourceList result = provider.resourceList();
for (CqDbSet set : provider.doGetDbSetList(wantedProps)) {
if (set.getResourceError() == null)
result.addAll(set.getCurrentUser().getSubscribedDatabases());
}
return result;
}
|
这样用户就可以通过下拉列表选择用户数据库：
接下来，获取用户数据库中的所有查询：
userDb = (CqUserDb)userDb.doReadProperties
(new PropertyRequest(CqUserDb.ALL_QUERIES.nest (CqQuery.USER_FRIENDLY_LOCATION)));
CqQuery[] queries = setUserFriendlyLocation(userDb.getAllQueries()).
toArray(new CqQuery[]{});
|
图 10. 查询列表
如下代码实现了到 CM Server 端获取数据：
CqResultSet results =
query.doExecute(1, Long.MAX_VALUE, CqQuery.COUNT_ROWS);
|
再经过显示处理之后，得到如下图的运行效果：
至此，我们通过调用 CM API 实现了在客户端访问 ClearQuest 存储中的数据。
Rational CM API 为 ClearCase 和 ClearQuest 的用户，特别是其中的 Java 开发人员提供了统一的访问接口，方便用户将已有的开发和应用与 Rational 产品结合。本文重点介绍了 ClearQuest CM API 特性，希望能对读者了解 ClearQuest CM API 提供帮助。
原文链接：http://www.ibm.com/developerworks/cn/rational/r-cn-cmapicq/index.html
来自 “ ITPUB博客 ” ，链接：http://blog.itpub.net/14780914/viewspace-674292/，如需转载，请注明出处，否则将追究法律责任。
转载于:http://blog.itpub.net/14780914/viewspace-674292/
1856
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
