内容


调用 Rational CM API 实现 Rational ClearQuest 的相关操作

Comments
下载 Rational ClearQuest 试用版  |  Rational ClearQuest ALM Appliance(预配置系统)
获取免费的 Rational 软件工具包系列,下载更多的 Rational 软件试用版

CM API 介绍

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 所示)。

图 1. CM API 体系结构
图 1. CM API 体系结构
图 1. CM API 体系结构

CM API 对象模型

CM API 公共对象主要有提供器(Providers)、资源(Resources)、位置(Locations)以及属性(Properties)。

CM API 编程模型

调用 CM API 编写程序主要遵照以下几点规则:

1)客户端的提供器(Provider)对象代表了用户,可以与一个或多个服务器连接

2)Servers 上存储着多种类型的资源(Resources)

3)资源对象都位于一定的存储库(Repositories)中

4)每一个资源对象都已惟一的位置(Locations)来标识

5)资源对象拥有某些特定类型的属性(Properties)

6)资源对象可以具有内容(Content)

7)资源对象支持对特定类型的操作

8)客户端使用代理(Proxy)来完成以下操作:

  读 / 写资源属性;

  读 / 写资源内容;

  对资源进行操作。

图 2 表明上述关系。其中代理是 CM API 客户端的 Java 对象,用来代表服务器端的资源。

图 2. CM API 编程模型
图 2. CM API 编程模型
图 2. CM API 编程模型

CM API 编程的基本步骤

基于这种编程模型,如果客户端调用 CM API 继而通过 CM Server 访问服务器的资源,基本的步骤如下(如图 3 所示):

1)根据操作的对象创建一个提供器对象

2)根据资源对象的位置创建一个代理对象

3)将资源的属性值付给代理对象(可选)

4)代理对象执行“do”操作,可完成下列操作中的一个

  服务器端将这个属性的新值写入资源对象;

  服务器执行某项特定的操作;

  服务器读取属性值并返回给客户端。

5)检查返回的代理对象

图 3. 调用 CM API 时序图
图 3. 调用 CM API 时序图
图 3. 调用 CM API 时序图

ClearQuest CM API 的特点

ClearQuest CM API 沿用了 WVCM 的编程模型,即 Providers、Resources、Locations 和 Properties,以及四者之间遵循的逻辑关系。除此之外, ClearQuest CM API 一些特有的性质,将在这一节中着重介绍。

ClearQuest CM API 的提供器

如上所述,CM API 具有域服务细分的特点:客户端调用 CM API 执行访问 ClearQuest 资源时,是由 CqProvider(Provider 的一个子接口)提供服务。如下代码所示,创建了一个 CqProvider 对象:

清单 1. 创建一个 CqProvider 对象

CqProvider provider = (CqProvider) ProviderFactory
.createProvider(CQ_ONLY_PROVIDER_CLASS, callback);

其中 callback 是一个回调参数,用于验证用户凭证。

ClearQuest CM API 的位置对象

CM API 涉及到的每一个资源对象,都有惟一的位置标识,并且以统一的格式表示:

<domain>.<namespace>:[<name>@]<repository>

对于 ClearQuest 域中的各种资源对象,其表示方法举例说明如下:

清单 1. ClearQuest 域中的各种资源对象的表示方法示例
cq.action: <record-type>/<action-name>@<dbset>/<userdb> 
cq.record: <record-type >/<record-name>@<dbset>/<userdb>
cq.query: <quesry-type >/<query-name>@<dbset>/<userdb>

上述三个例子分别表示一个 ClearQuest 的 action 对象、record 对象和 query 对象的位置标识格式。

ClearQuest CM API 的资源类型

实际上,做为典型的变更追踪管理系统,ClearQuest 的业务功能与行为并不与 WVCM 所定义的典型版本控制管理系统的业务模型与行为相符合。因此大多数来自于 WVCM 的资源类型对 ClearQuest 来说并不适用。ClearQuest CM API 对于 WVCM 的资源层次结构,只沿用了 Resource 及其子接口 Folder;并从 CM API 已经扩展的 StpResouce 等接口之上,扩展出适合于 ClearQuest 的众多接口,如 CqResource,CqRecourd, CqDbset 等等,图 4 描述了以 CqResource 为轴心的各个资源接口类型间的扩展关系。

图 4. ClearQuest 域 Resource 类型示例
图 4. ClearQuest 域 Resource 类型示例
图 4. ClearQuest 域 Resource 类型示例

下面这段代码,创建了一个 CqRecord 对象的代理:

清单 2. 创建一个 CqRecord 对象的代理
CqRecord record = provider.buildProxy(CqRecord.class,
“Defect/SAMPL00000011@DBSET1/SAMPL”);

ClearQuest CM API 与服务器通信

在包含 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 服务
图 5. ClearQuest CM API 连接 ClearQuest 服务
图 5. ClearQuest CM API 连接 ClearQuest 服务

调用 CM API 对 ClearQuest 进行相关操作与数据访问

接下来,本文将以“浏览记录”为实例介绍如何调用 ClearQuest CM API 对 ClearQuest 进行数据访问与相关操作。

环境设置

引入已有项目

如果读者希望通过示例程序来学习 CM API 的使用,可以将 teamapi 作为一个已经存在的项目导入到 Eclipse 中。teamapi 是 ClearQuest 产品安装目录下的一个压缩包,位于 <install-dir>\common\CM,包含了一些调用 CM API 的项目。读者可以按照以下两步引入项目:

1)将 teamapi.zip 解压缩到一个目录,如 D:\teamapi

2)启动 Eclipse, 选择 File->Import->General->Existing Project into Workspace -> Browse-> 选择 D:\teamapi (如图 6)。

图 6. 引入 teamapi 项目
图 6. 引入 teamapi 项目
图 6. 引入 teamapi 项目

引入已有项目

如果读者希望自己调用 CM API 来开发自己的项目,则可以按照以下步骤进行:

1)创建一个目录,如 D:\teamjar,将下列压缩文件从服务器的安装路径中复制过来;

表 1. 将下列压缩文件从服务器的安装路径中复制过来
Jar 文件 功用
<install-dir>/common/stpwvcm.jar WVCM 接口
<install-dir>/common/stpcmmn.jar CM API 公共组件实现
<install-dir>/ ClearQuest/stpcq.jar ClearQuest 组件的实现
.<install-dir>/ ClearQuest/cqjni.jar ClearQuest JNI 实现

2)在 Eclipse 中创建一个新的项目;

3)右键项目名称 ->BuildPath->Add External Add External Archives-> 浏览到 D:\ teamjar 并选中以上全部 4 个 jar 文件(如图 7)。

图 7. 引入 CM API JAR 文件
图 7. 引入 CM API JAR 文件
图 7. 引入 CM API JAR 文件

ClearQuest CM API 功能

对于 ClearQuest 领域的 CM API 而言,目前,能够实现如下的功能:

  1. 创建、修改和删除记录(例如,创建缺陷更改请求记录类型)
  2. 选择操作并更改状态
  3. 创建查询,选择查询并执行该查询;另外,修改现有查询并使用新名称保存该查询
  4. 创建、修改和删除记录中的字段值

调用 CM API 浏览 CQ 数据库记录

下面以 teamapi sample 项目中的 ViewRecord.java 来分析 ClearQuest CM API 的调用。

准备工作

  1. ClearQuest 服务器的设置:使用 ClaearQuest Maintainance Tool 创建一个 Schema Repository: Schema1,用户数据库命名为 CQ1;
  2. 客户端的设置:启动 ClearQuest Eclipse 客户端,创建一个新的连接:CQDB1

代码分析

下边这段代码位于 Utilities 类中,它利用工厂方法实例化一个提供器对象:

清单 3. 利用工厂方法实例化一个提供器对象
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 方法,用来实现获取用户名和密码。

图 8. 输入用户名和密码
图 8. 输入用户名和密码
图 8. 输入用户名和密码

下面代码获取了一个 CqUserDB 类型的资源列表:

清单 4. 获取了一个 CqUserDB 类型的资源列表
static ResourceList<CqUserDb> getUserDbList(CqProvider provider, 
               PropertyRequest feedback) throws WvcmException{
PropertyRequest wantedProps =
new PropertyRequest(CqDbSet.CURRENT_USER
.nest(CqUser.SUBSCRIBED_DATABASES.nest(feedback)));
ResourceList<CqUserDb> result = provider.resourceList();
for (CqDbSet set : provider.doGetDbSetList(wantedProps)) {
if (set.getResourceError() == null)
result.addAll(set.getCurrentUser().getSubscribedDatabases());
        }
        return result;
}

这样用户就可以通过下拉列表选择用户数据库:

图 9. 选择数据库链接
图 9. 选择数据库链接

接下来,获取用户数据库中的所有查询:

清单 5. 获取用户数据库中的所有查询
userDb = (CqUserDb)userDb.doReadProperties
    (new PropertyRequest(CqUserDb.ALL_QUERIES.nest (CqQuery.USER_FRIENDLY_LOCATION)));
CqQuery[] queries = setUserFriendlyLocation(userDb.getAllQueries()).
toArray(new CqQuery[]{});
图 10. 查询列表
图 10. 查询列表
图 10. 查询列表

如下代码实现了到 CM Server 端获取数据:

清单 6. 到 CM Server 端获取数据
CqResultSet results = 
        query.doExecute(1, Long.MAX_VALUE, CqQuery.COUNT_ROWS);

再经过显示处理之后,得到如下图的运行效果:

图 11. 查询运行结果
图 11. 查询运行结果
图 11. 查询运行结果

至此,我们通过调用 CM API 实现了在客户端访问 ClearQuest 存储中的数据。

总结

Rational CM API 为 ClearCase 和 ClearQuest 的用户,特别是其中的 Java 开发人员提供了统一的访问接口,方便用户将已有的开发和应用与 Rational 产品结合。本文重点介绍了 ClearQuest CM API 特性,希望能对读者了解 ClearQuest CM API 提供帮助。


相关主题


评论

添加或订阅评论,请先登录注册

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=Rational
ArticleID=521313
ArticleTitle=调用 Rational CM API 实现 Rational ClearQuest 的相关操作
publish-date=09132010