简介: 在 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/