呼叫 Rational CM API 實現 Rational ClearQuest 的相關操作

簡介： 在 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 體系結構

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 程式設計模型

CM API 程式設計的基本步驟

基於這種程式設計模型，如果客戶端呼叫 CM API 繼而通過 CM Server 訪問伺服器的資源，基本的步驟如下（如圖 3 所示）：

1）根據操作的物件建立一個提供器物件

2）根據資源物件的位置建立一個代理物件

3）將資源的屬性值付給代理物件（可選）

4）代理物件執行“do”操作，可完成下列操作中的一個

　　伺服器端將這個屬性的新值寫入資源物件；

　　伺服器執行某項特定的操作；

　　伺服器讀取屬性值並返回給客戶端。

5）檢查返回的代理物件

圖 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 型別示例

下面這段程式碼，建立了一個 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 服務

接下來，本文將以“瀏覽記錄”為例項介紹如何呼叫 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 專案

引入已有專案

如果讀者希望自己呼叫 CM API 來開發自己的專案，則可以按照以下步驟進行：

1）建立一個目錄，如 D:\teamjar，將下列壓縮檔案從伺服器的安裝路徑中複製過來；

表 1. 將下列壓縮檔案從伺服器的安裝路徑中複製過來

2）在 Eclipse 中建立一個新的專案；

3）右鍵專案名稱 ->BuildPath->Add External Add External Archives-> 瀏覽到 D:\ teamjar 並選中以上全部 4 個 jar 檔案（如圖 7）。

圖 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. 輸入使用者名稱和密碼

下面程式碼獲取了一個 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. 選擇資料庫連結

接下來，獲取使用者資料庫中的所有查詢：

清單 5. 獲取使用者資料庫中的所有查詢

userDb = (CqUserDb)userDb.doReadProperties
    (new PropertyRequest(CqUserDb.ALL_QUERIES.nest (CqQuery.USER_FRIENDLY_LOCATION)));
CqQuery[] queries = setUserFriendlyLocation(userDb.getAllQueries()).
toArray(new CqQuery[]{});

如下程式碼實現了到 CM Server 端獲取資料：

清單 6. 到 CM Server 端獲取資料

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

再經過顯示處理之後，得到如下圖的執行效果：

圖 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/，如需轉載，請註明出處，否則將追究法律責任。