ITPub博客

首页 > Linux操作系统 > Linux操作系统 > 调用 Rational CM API 实现 Rational ClearQuest 的相关操作

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

原创 Linux操作系统 作者:myattitude 时间:2010-09-17 14:35:48 0 删除 编辑
于 芳, 软件工程师, IBM

简介: 在 IBM Rational ClearCase 和 IBM Rational ClearQuest V7.1 版本中,推出了统一的 Java API 来访问 ClearCase 和 ClearQuest 资源,即 Change Management Application Interface(CM API)。本文将为您介绍如何在客户端调用 CM API 实现 ClearQuest 的相关操作。

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 体系结构

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 编程模型

CM API 编程的基本步骤

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

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

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

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

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

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

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

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

5)检查返回的代理对象


图 3. 调用 CM API 时序图
图 3. 调用 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 涉及到的每一个资源对象,都有惟一的位置标识,并且以统一的格式表示:

.:[@]

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


清单 1. ClearQuest 域中的各种资源对象的表示方法示例

cq.action: /@/ 
cq.record: /@/
cq.query: /@/

上述三个例子分别表示一个 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 类型示例

下面这段代码,创建了一个 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 服务

接下来,本文将以“浏览记录”为实例介绍如何调用 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)。


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

引入已有项目

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

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


表 1. 将下列压缩文件从服务器的安装路径中复制过来

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


图 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. 输入用户名和密码

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


清单 4. 获取了一个 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;
}

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


图 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. 查询列表

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


清单 6. 到 CM Server 端获取数据

CqResultSet results = 
        query.doExecute(1, Long.MAX_VALUE, CqQuery.COUNT_ROWS);

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


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

至此,我们通过调用 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/,如需转载,请注明出处,否则将追究法律责任。

下一篇: 没有了~
请登录后发表评论 登录
全部评论

注册时间:2008-07-07

  • 博文量
    172
  • 访问量
    332949