用Web Service查詢RationalClearcase中的UCM項目信息
使用 Java 語言和 Web Service 技術開發 Rational Clearcase UCM 項目信息查詢系統
本系列文章共有兩篇，以一個實際生產環境中使用的 ClearCase 監控系統的開發為例，向讀者介紹如 何使用基於 Java 語言的 Web2.0 和 Web Service 技術來開發一個 Linux 環境下的 ClearCase 監控和 UCM 項目查詢系統。本文是該系列的第二部分，將向您演示如何使用 Java 語言和 Web Service 技術來 開發一個 Rational Clearcase UCM 項目信息查詢系統。
UCM 項目信息查詢系統應用場景介紹
在 Clearcase UCM 模型中包含了很多的記錄項目開發過程和進度變化的信息，例如項目的每個子開發 流中包含了各個分支的開發狀態信息，每個基線中包含了各個不同時刻的項目開發活動信息等。這些信息 對軟件項目開發的各個環節都有很大的幫助。例如在軟件產品的構建過程中可以通過查詢 UCM 活動變更 集來獲取每次產品構建的代碼變更狀況，在項目進度追蹤過程中可以通過查詢各個 UCM 組件的基線來獲 取不同時間點上項目開發的進度狀況。在現有的 Clearcase 客戶端程序 (CCRC,CC Web 和 CC Native Client 等 ) 中，只提供了非常有限的基於 UI 操作的 UCM 項目信息查詢功能（例如可以通過鼠標點擊 的方式查詢特定基線中包含的變更集等功能）。這些功能無法滿足軟件開發中各個環節的需求，同時現有 客戶端沒有提供這些功能的計算機程序編程接口，開發流程中使用的其他軟件（例如產品構建程序）無法 從這些已有的客戶端程序中獲取 UCM 信息。
在常規的方式下 , 為了獲取這些 UCM 信息，軟件開發項目組織需要編寫自定義的腳本程序 ( 這些腳 本程序通常由 Perl 和 Shell 語言編寫，包含了查詢所需 UCM 信息的 cleartool 命令行指令 ) 並按照 需要在 Clearcase 服務器主機上運行這些程序 , 之後需要以某種方式從服務器主機中下載執行結果並解 析所需 UCM 信息。另一種方法是使用 Clearcase 提供的 Rational Team API 編寫基於 Java 語言的自 定義客戶端程序來查詢所需 UCM 信息，但是 Rational Team API 只能在已安裝了 Clearcase 客戶端的 計算機中運行，同時只能由 Java 語言編寫的程序調用。上述兩種方法需要結合使用多種不同的編程語言 ，或者有一定的使用局限性。並且他們都涉及到多台不同物理機器的交互以及多個不同角色的項目成員的 協同工作。過程非常的復雜，並且沒有很好的可維護性和功能可擴展性。
而在使用本文所述的 UCM 項目信息查詢系統時，軟件項目開發團隊只需要在各種項目開發支持軟件中 使用由任意語言編寫的 Web Service 客戶端程序來訪問 UCM 查詢系統即可獲取所需的項目 UCM 信息。 這一過程不需要安裝 Clearcase 客戶端程序，也無需多個不同角色的項目成員的協同工作。開發、使用 的過程非常簡便，同時能夠使軟件開發團隊以一種統一的方式在各種異構的軟件系統中獲取到 Clearcase 服務器中的 UCM 項目狀態信息。
圖 1 是使用上述兩種方式的系統結構對比。在本文的以下部分中首先會介紹 Clearcase UCM 的基本 概念和相關的命令行查詢指令，之後將介紹如何使用 Java 和 Web Service 來開發通用的 UCM 項目信息 查詢系統，這一查詢系統能夠以 SOAP Web Service 的方式向客戶端程序提供 Clearcase UCM 查詢服務 。
圖 1. 常規方式和使用 UCM 項目信息查詢系統方式的結構對比
Rational ClearCase UCM 的基礎概念
UCM (Unified Changed Management), 意為統一變更管理模式，是管理軟件開發過程中所有變更的 " 最佳實踐 "。它定義了一個可以立即用於軟件開發項目的一致並基於活動的變更管理流程。 UCM 通過抽 象層次的提升簡化了軟件開發，從而使得軟件開發團隊能夠從更高的層次根據活動（activity）來管理變 更。通過 UCM，一個開發活動可以自動地同其變更集（changeset, 封裝了所有用於實現該活動的項目工 件）相關聯。以下是 UCM 中常用對象的簡要介紹：
項目（Project）：包含了軟件產品開發的配置管理所需要的 UCM 元數據和一些配置信息，例如 Component、Baseline，Stream 等。
Project VOB（PVOB）：存儲 UCM 所需的一些特殊的信息（如 Proejct，Stream，Activity 及 Change Set 等）的 VOB，UCM Project 的信息必須保存在 PVOB 中。
構件（Component）：軟件開發項目中的代碼、文檔等按一定的目錄結構組織而成的可重用的工件集合 。Component 與 Project 相關聯，Project 管理的所有的對象都從屬於某一個特定的 Component ，每個 Project 至少有一個 Component。
開發流（Development Stream）：為每個開發人員准備的一個獨立的開發環境，包含了在這個開發流 上的 Activity 與修改的配置項的版本信息，UCM 通過開發流簡化了並行開發的配置管理工作。
集成流（Integration Stream）：代表項目開發的代碼主干，每個開發流都是集成流的一個分支，開 發人員在開發流上完成工作後，再將工作結果提交到集成流中，每個 Project 都有一個 Integration Stream。
基線（Baseline）：基線是一個 Component 在某一特定時刻的快照。它包括在此時這一 Component 中所有對象的版本信息集合。當配置一個新工作流時，基線被用來指定哪些版本將被選在此流中。
活動（Activity）：UCM 模式中的一個關鍵概念，跟蹤完成一項開發任務所引起的所有配置項的變更 。在 UCM 模式下為了完成一項開發任務所進行的所有會引起配置項發生變化的操作（Check Out、Check In、Add to Source Control 等）都必須關聯到一個 Activity。這個 Activity 會使用一個變更集 (Change Set) 來記錄這些版本變更。
變更集（Change Set）：記錄了 Activity 所關聯的所有的配置項的版本變更，每個 Activity 都有 一個 Change Set。
清單 1. UCM 對象的層次關系
vob1 vob2
/ | \ / \
目錄 1 目錄 2 目錄 3 目錄 4 目錄 5
| | | | |
PVOB ------------------>comp1 comp2 comp3 comp4 comp5
/ \ | | | | |
project1 project2 ----------->|______|_______|_______|______|_______ 無根構件 NRcomp6
/ \
stream1 stream2
| |
| -deliver-－－> |
Rational ClearCase 中常用的 UCM 查詢指令
Clearcase 中內置的命令行工具 cleartool(/opt/rational/clearcase/bin/cleartool) 中包含有很 多子命令可以用來進行 UCM 相關的操作 , 下面簡要的介紹其中常用的一些查詢和比較命令。
Project 查詢命令 lsproject
lsproject 命令可以用來查詢一個指定的 pvob 中所有 project 的信息，也可以根據某一具體的 project 名稱來查詢該 project 的詳細信息。例如 :
cleartool lsproject -invob /vob_tag/project_pvob ：列出 pvob /vob_tag/project_pvob 中包含 的所有項目信息。
cleartool lsproject -l userProject@/vob_tag/project_pvob ：顯示 pvob /vob_tag/project_pvob 中項目 userProject 的詳細信息。
cleartool lsproject -tree userProject@/vob_tag/project_pvob ：以樹型層次結構顯示 project userProject 中包含的所有子對象（stream，activity 等）。
Stream 查詢命令 lsstream
lsstream 命令可以用來查詢一個 UCM project 中的 Stream 信息。示例如下：
cleartool lsstream -in userProject@/vob_tag/project_pvob ：列表顯示 UCM project userProject 中的所有 Integration Stream。
cleartool lsstream -l userProjectStream_Integration@/vob_tag/project_pvob ：顯示 stream userProjectStream_Integration 的詳細信息。
cleartool lsstream -tree userProjectStream_Integration@/vob_tag/project_pvob ：以樹型層次 結構顯示 Stream userProjectStream_Integration 中包含的所有子對象（子 stream，activity 等）。
Baseline 查詢命令 lsbl
lsbl 命令是 UCM 查詢中非常常用的指令，它可以用來查詢一個指定的 UCM Stream 中包含的 Baseline 的詳細信息 :
cleartool lsbl -stream userProjectStream_Integration@/vob_tag/project_pvob : 列表顯示 UCM stream userProjectStream_Integration 中的所有 baseline。
cleartool lsbl -component projectComponentA@/vob_tag/project_pvob/ -stream userProjectStream_Integration@/vob_tag/project_pvob : 列表顯示 UCM stream userProjectStream_Integration 中 component projectComponentA 中的所有 baseline。
cleartool lsbl -tree -stream userProjectStream_Integration@/vob_tag/project_pvob : 以樹型 層次結構顯示 stream userProjectStream_Integration 中的所有 baseline。
cleartool lsbl -l projectIntegrationStream_BaselineA@/vob_tag/project_pvob : 顯示 baseline projectIntegrationStream_BaselineA 的詳細信息。
cleartool lsbl -tree projectIntegrationStream_BaselineA@/vob_tag/project_pvob : 以樹型層 次結構顯示 baseline projectIntegrationStream_BaselineA 中包含的所有子對象。
Baseline 比較命令 diffbl
diffbl 命令的主要用途是比較兩個不同的 baseline 或 stream 中 activity 的變化情況 , 它可以 用來追蹤項目開發中的代碼變更 , 示例如下 :
cleartool diffbl -predecessor baseline:projectIntegrationStream_BaselineA@/vob_tag/project_pvob : 顯示 baseline projectIntegrationStream_BaselineA 與它前一個 baseline 之間的 Activity 變化。
cleartool diffbl baseline:projectIntegrationStream_BaselineA@/vob_tag/project_pvob baseline:projectIntegrationStream_BaselineB@/vob_tag/project_pvob : 顯示 baseline projectIntegrationStream_BaselineA 和 projectIntegrationStream_BaselineB 之間的 Activity 變 化。
cleartool diffbl stream:userProjectStream_Integration@/vob_tag/project_pvob stream:userProjectStream_DeveloperA@/vob_tag/project_pvob : 顯示 stream userProjectStream_Integration 和 userProjectStream_DeveloperA 之間的 Activity 變化。
Activity 和 Change Set 查詢命令 lsactivity
在 ClearCase UCM 方式下 , 針對某一特定任務進行的所有會引起版本變化的操作都與一個指定的 activity 相關聯在一起，所有的對象版本變化信息都會被記錄在這個 activity 的 change set 中， clearcase 使用命令 lsactivity 來顯示這些信息。示例清單 2 是命令：cleartool lsactivity -l Check_in_license_files_for_toolkit@/vob_tag/project_pvob 的輸出結果，它顯示了 activity Check_in_license_files_for_toolkit 的信息和其中包含的 change set。
清單 2. lsactivity 命令輸出結果
activity "Check_in_license_files_for_toolkit"
2008-03-25T11:22:42+08:00 by UI Dev (uidev.clearusers@UIDevSUPPORT01)
master replica: csdl.project_pvob@/vob_tag/project_pvob/
owner: ccadmin
group: projectdev
stream: UI_DEV@/vob_tag/project_pvob/
title: Check in license files for toolkit
change set versions:
/vob_tag/project_src/Tools/License/LI_zh@@/main/userProjectStream_Integration/UI_DEV/1
/vob_tag/project_src/Tools/License/LI_tr@@/main/userProjectStream_Integration/UI_DEV/1
/vob_tag/project_src/Tools/License/LI_pt@@/main/userProjectStream_Integration/UI_DEV/1
/vob_tag/project_src/Tools/License/LI_pl@@/main/userProjectStream_Integration/UI_DEV/1
/vob_tag/project_src/Tools/License/LI_ko@@/main/userProjectStream_Integration/UI_DEV/1
/vob_tag/project_src/Tools/License/LI_ja@@/main/userProjectStream_Integration/UI_DEV/1
使用 Java 和 Web Service 技術開發 Clearcase UCM 查詢程序
本文所述 Clearcase UCM 查詢程序是一個運行在 Clearcase 服務器主機中的輕量級 Web Service 程 序 , 它包含一個 SOAP Web Service 服務組件和一個本系列文章第一部分中介紹過的操作系統進程調用 組件，用戶通過 HTTP 對 UCM 查詢程序進行 SOAP 式的查詢方法調用。當 UCM 查詢程序接收到用戶請求 後，Web Service 服務組件會將這個方法調用轉換為 cleartool 命令，並使用操作系統進程調用組件執 行這一命令，最後 Web Service 服務組件會將執行結果轉化為 SOAP 對象並將它返回給用戶。圖 2 是本 文所述 Clearcase UCM 查詢程序的基本結構。
圖 2. Rational Clearcase UCM 查詢程序基本結構圖
操作系統進程調用組件的詳細介紹請參考本系列文章的第一部分，本文將著重介紹 SOAP Web Service 服務組件部分。
SOAP Web Service 服務組件
SOAP Web Service 服務組件邏輯上由 UCM cleartool 查詢程序和 SOAP server 程序兩部分組成。 SOAP server 程序接收用戶調用請求，並將調用請求轉發到 UCM cleartool 查詢程序中，查詢程序會根 據調用請求的操作名稱和參數生成 cleartool 命令並使用操作系統進程調用組件執行這些 cleartool 命 令。當 cleartool 命令完成後，查詢程序會根據需要將命令的返回結果解析、封裝成 JavaBean 對象， 並將這些對象傳遞回 SOAP server 程序中。SOAP server 程序會將這些 JavaBean 轉化為 SOAP 可識別 的對象並作為用戶調用請求的結果返回給用戶端程序。圖 3 為 SOAP Web Service 服務組件的結構圖。
圖 3. SOAP Web Service 服務組件結構圖
UCM cleartool 查詢程序
UCM cleartool 查詢程序使用 Java 語言開發 , 程序類位於包 com.cn.ibm.csdl.ecm.build.nerveCell.util.clearcaseUCMQuery 中 , 由查詢工具類 ClearcaseUCMQueryUtil 和一系列代表 UCM 對象數據的 JavaBean 組成。當用戶發起某一 UCM 查詢操作 時 , SOAP server 程序調用 ClearcaseUCMQueryUtil 中的相應 Java 方法。ClearcaseUCMQueryUtil 首 先根據輸入參數生成 cleartool 命令 , 之後使用操作系統進程調用組件執行該命令並在命令完成後解析 返回數據 , 最後將解析後的數據使用 UCM 對象數據 JavaBean 封裝並返回給 SOAP server 程序。清單 3 是 ClearcaseUCMQueryUtil 中的 getCompareBaselineObjWithPredecessor 方法 , 它比較指定的 baseline 和前一個基線的版本變化 , 並將結果封裝在 BaselineCompareInfoObj JavaBean 中。 ClearcaseUCMQueryUtil 中的其他的方法請參考本文附件中的 eclipse 項目工程。
清單 3. getCompareBaselineObjWithPredecessor 方法
public static BaselineCompareInfoObj getCompareBaselineObjWithPredecessor
(String baselineName,String vobName){
String cleartoolPath="/opt/rational/clearcase/bin/cleartool";
String commandString=
cleartoolPath+" diffbl -predecessor baseline:"+baselineName+"@"+vobName;
java.util.List resultList=runSingelRemoteCommand(commandString);
if(resultList==null){return null;}
String returnBaselineInfoHead=(String)resultList.get(0);
if(!returnBaselineInfoHead.startsWith("Comparing the following:")){return null;}
BaselineCompareInfoObj currentBaselineCompareInfoObj=new BaselineCompareInfoObj();
int differencesStart=resultList.indexOf("Differences:")+1;
String[] baselinesArray=new String[2];
baselinesArray[0]=(String)resultList.get(1);
baselinesArray[1]=(String)resultList.get(2);
currentBaselineCompareInfoObj.setBaselines(baselinesArray);
int differencesNum=resultList.size()-differencesStart;
String[] dArray=new String[differencesNum];
for(int i=0;i<differencesNum;i++){
dArray[i]=(String)resultList.get(i+differencesStart);
}
currentBaselineCompareInfoObj.setDifferences(dArray);
return currentBaselineCompareInfoObj;
}
SOAP server 程序
本程序的 Web Service 服務組件使用 Java 6 的 JAX-WS2.0 特性所提供的 SOAP 功能 ( 使用了 cxf 和 Jetty 作為後端類庫 )。使用這一方式可以在 Java6 標准版的環境下提供 Web Service 支持而不需 要將程序部署在 JavaEE 服務器上，從而可以簡化程序的開發難度並降低 Clearcase 主機的負載。使用 JAX-WS2.0 提供 SOAP 服務需要使用 3 個 Java 類 : 一個服務定義接口，一個服務實現類和一個服務發 布類。在 UCM 查詢程序中這些類位於 com.cn.ibm.csdl.ecm.build.nerveCell.util.clearcaseUCMQuery.webservice 包中，以下是它們的說明 :
ClearcaseUCMQueryService: 服務定義接口 , 在這個 interface 中定義了每一個將要發布的 SOAP Web Service UCM 查詢操作 , 清單 4 中的代碼片斷顯示了該接口中操作 getCompareBaselineObjWithPredecessor 的定義。
清單 4. getCompareBaselineObjWithPredecessor 操作的服務接口定義
package com.cn.ibm.csdl.ecm.build.nerveCell.util.clearcaseUCMQuery.webservice;
import javax.jws.WebService;
import com.cn.ibm.csdl.ecm.build.nerveCell.util.clearcaseUCMQuery.BaselineCompareInfoObj;
......
@WebService
public interface ClearcaseUCMQueryService {
......
BaselineCompareInfoObj getCompareBaselineObjWithPredecessor
(String baselineName,String vobName);
......
}
ClearcaseUCMQueryServiceImpl: 服務實現類 , 這個類通過使用 UCM cleartool 查詢程序為 ClearcaseUCMQueryService 定義的每個方法提供了一個實現。清單 5 中的代碼片斷顯示了該類中方法 getCompareBaselineObjWithPredecessor 的實現。
清單 5. getCompareBaselineObjWithPredecessor 操作的服務實現類
package com.cn.ibm.csdl.ecm.build.nerveCell.util.clearcaseUCMQuery.webservice;
import javax.jws.WebService;
import com.cn.ibm.csdl.ecm.build.nerveCell.util.clearcaseUCMQuery.BaselineCompareInfoObj;
import com.cn.ibm.csdl.ecm.build.nerveCell.util.clearcaseUCMQuery.ClearcaseUCMQueryUtil;
......
@WebService(endpointInterface =
"com.cn.ibm.csdl.ecm.build.nerveCell.util.clearcaseUCMQuery.
webservice.ClearcaseUCMQueryService",
serviceName = "ClearcaseUCMQueryService")
public class ClearcaseUCMQueryServiceImpl implements ClearcaseUCMQueryService{
......
public BaselineCompareInfoObj getCompareBaselineObjWithPredecessor
(String baselineName, String vobName) {
return ClearcaseUCMQueryUtil.getCompareBaselineObjWithPredecessor
(baselineName, vobName);
}
......
}
}
ClearcaseUCMQueryServicePublisher: 服務發布類 , 這個類將 ClearcaseUCMQueryService 和 ClearcaseUCMQueryServiceImpl 耦合在一起並發布 UCM 查詢的 SOAP Web Service 服務。
清單 6. ClearcaseUCMQueryServicePublisher 類定義
package com.cn.ibm.csdl.ecm.build.nerveCell.util.clearcaseUCMQuery.webservice;
import javax.xml.ws.Endpoint;
public class ClearcaseUCMQueryServicePublisher{
public static void main(String args[]) throws Exception {
new ClearcaseUCMQueryServicePublisher().
publishService("http://localhost:9101/ccUCMQueryService");
}
public void publishService(String serviceAddress){
ClearcaseUCMQueryServiceImpl implementor = new ClearcaseUCMQueryServiceImpl();
String address = serviceAddress.trim();
Endpoint.publish(address, implementor);
System.out.println("Published Service at :"+serviceAddress);
}
}
當 ClearcaseUCMQueryServicePublisher 中的 main 方法運行後，用戶就可以在地址 http://hostname:9101/ccUCMQueryService 上執行 UCM 查詢程序中的所有 SOAP 查詢操作。通過在 Web 浏覽器中訪問地址 http://localhost:9101/ccUCMQueryService?wsdl 可以獲得這個服務的 WSDL 定義。
從客戶端訪問執行 Rational Clearcase UCM 查詢程序
本文所述的 Clearcase UCM 查詢程序可以接受任何編程語言實現的 SOAP Web Service 客戶端程序的 訪問。下面以 Java 程序實現的一個客戶端 ClearcaseUCMQueryClient 為例演示這一過程。
清單 7. ClearcaseUCMQueryServicePublisher 類定義
package com.cn.ibm.csdl.ecm.build.nerveCell.util.clearcaseUCMQuery.webservice;
import javax.xml.namespace.QName;
import javax.xml.ws.Service;
import javax.xml.ws.soap.SOAPBinding;
import com.cn.ibm.csdl.ecm.build.nerveCell.util.clearcaseUCMQuery.BaselineCompareInfoObj;
......
public class ClearcaseUCMQueryClient {
private static final QName SERVICE_NAME =
new QName("http://webservice.clearcaseUCMQuery.util.nerveCell.build.
ecm.csdl.ibm.cn.com/", "ClearcaseUCMQueryService");
private static final QName PORT_NAME =
new QName("http://webservice.clearcaseUCMQuery.util.nerveCell.build.
ecm.csdl.ibm.cn.com/", "ClearcaseUCMQueryServicePort");
private static ClearcaseUCMQueryService getClearcaseUCMQueryService
(String commandHostAddress){
Service service = Service.create(SERVICE_NAME);
String endpointAddress = commandHostAddress.trim();
service.addPort(PORT_NAME, SOAPBinding.SOAP11HTTP_BINDING, endpointAddress);
ClearcaseUCMQueryService ccQueryService=
service.getPort(ClearcaseUCMQueryService.class);
return ccQueryService;
}
public static BaselineCompareInfoObj getCompareBaselineObjWithPredecessor
(String commandHostAddressString，String baselineName,String vobName){
ClearcaseUCMQueryService ccQueryService=
getClearcaseUCMQueryService(commandHostAddress);
return ccQueryService.getCompareBaselineObjWithPredecessor(baselineName, vobName);
}
......
public static void main(String[] args){
System.out.println(getCompareBaselineObjWithPredecessor
("http://localhost:9101/ccUCMQueryService",
"BaseLine_Name","PVOB_Name"));
}
}
運行該類的 main 方法 , 即可通過 SOAP Web Service 方式獲得 PVOB "PVOB_Name" 中 baseline "BaseLine_Name" 與上一基線比較的版本變化 BaselineCompareInfoObj 數據對象。
結束語
本文介紹了如何使用 Java 和 SOAP Web Service 技術來開發一個 Clearcase UCM 項目信息查詢程序 , 通過使用該查詢程序 , 可以為以 Clearcase 作為版本控制系統的軟件項目開發團隊提供非常靈活的項 目開發版本查詢支持。這一程序還可以作為其他 Clearcase UCM 查詢系統的後端數據源來使用。本文所 介紹的方法也可以為 Clearcase 系統的應用方式提供一個新的思路。
來源：
http://www.ibm.com/developerworks/cn/rational/r-cn-webserviceclearcase2/index.html
