如何使用WebSphere MQ FTE Ant與最佳實踐

開始之前

關於本教程

本教程詳細地介紹了 IBM WebSphere MQ FTE 所提供的 Ant 功能以及相關命令與任務，並結合具體實例，演示如何基於 Eclipse 平台開發 Ant 腳本以實現更強大的文件傳輸功能，最後提出開發 FTE Ant 任務腳本的最佳實踐。

目標

希望讀者通過本教程，能夠了解：

WebSphere MQ FTE 中所提供的 Ant 功能；

基於 Eclipse 開發 FTE Ant 任務腳本；

使用 FTE Ant 的最佳實踐

先決條件

本教程要求讀者了解 WebSphere MQ、WebSphere MQ FTE 以及 Apache Ant 的基本概念、基本功能和基本操作步驟。

前言

IBM WebSphere MQ File Transfer Edition（簡稱 MQFTE）結合 WebSphere MQ 的消息傳輸解決方案，提供了受管的文件傳輸功能，實現了消息傳輸平台與文件傳輸平台的完美統一，逐步成為信息傳輸領域的主流解決方案。MQFTE 的一個重要擴展是與 Apache Ant 的有效集成，通過使用 Ant 腳本，MQFTE 能夠利用可解讀的腳本語言執行更為復雜的文件傳輸任務，因此豐富和擴展了 MQFTE 文件傳輸的集成能力和覆蓋面。

WebSphere MQ FTE Ant 功能介紹

Ant 簡介

Another Neat Tools (Ant) 是一種基於 java 的 build 工具。理論上來說，它類似於（Unix）C 中的 make ，但又有所不同，Ant 運行時需要 XML 格式的文件不是 Shell 命令文件。通常情況下，用戶使用 Ant 來構建 java 程序，包括類庫、.jar 文件、.war 文件等等。Ant 腳本是 XML 文件，其中包含許多步驟的任務，例如創建文件夾、調用 java 編譯器、傳遞編譯參數等工作。

Ant 是 Apache 軟件基金會 JAKARTA 目錄中的一個子項目，Ant 是純 java 語言編寫的，所以具有很好的跨平台性，並且 Ant 操作簡單，它由一個內置任務和可選任務組成的，運行時只需要一個 XML 文件 ( 構建文件 )。 Ant 通過調用 target 樹，就可以執行各種 task。每個 task 實現了特定接口對象。由於 Ant 構建文件是 XML 格式的文件，所以很容易維護和書寫，而且結構很清晰。由於 Ant 的跨平台性和操作簡單的特點，它很容易集成到一些開發環境中去。關於 Ant 的更詳細介紹請參與參考 [1]。

WebSphere MQ FTE Ant 功能概述

MQFTE 的一個重要擴展是與 Apache Ant 的有效集成，基於 MQFTE 平台，用戶通過使用 Ant 腳本，利用可解讀的腳本語言來執行更為復雜的文件傳輸任務，通常每個任務的執行都依賴於之前的任務執行情況，這是受管文件傳輸中非常普遍的需求。基於 Apache Ant 的可擴展性，FTE Ant 擴展了 Ant 的功能，它創建出符合 MQFTE 可解讀的消息並提交給 FTE 代理，用於執行復雜的文件傳輸任務，如圖 1 所示。

圖 1 FTE Ant 架構

FTE Ant 任務

FTE 提供了如表 1 所示的 Ant 任務，用戶可以使用這些任務實現文件傳輸功能。

表 1：FTE Ant 任務列表

任務名稱 任務描述 awaitoutcome 等待 filecopy，filemove 或者 call 操作結束 call 向代理發送調用請求，代理會基於請求內容執行相關命令或程序，並返回結果。 cancel 取消受管文件傳輸任務（filecopy 或 filemove）或者調用請求 (call) filecopy Filecopy 在 MQ FTE 代理之間拷貝文件，源文件不被刪除 filemove Filemove 在 MQ FTE 代理之間移動文件，當源文件被成功地轉移到目的地後，源文件被刪除。 ignoreoutcome 忽略 filecopy、filemove 或 call 命令的執行結果。當用 defer 方式指定 filecopy、filemove 或 call 命令時，Ant 任務會分配特定資源來跟蹤這些命令的執行結果，當不再需要這些執行結果時，使用 ignoreoutcome 任務釋放資源。 ping 用於判斷當前代理是否能夠處理文件傳輸任務 uuid 產生任意隨機標識，並賦予某些屬性，例如可以用該標識產生作業名。

FTE Ant 命令

FTE Ant 功能提供了一個強大的命令 fteant，在 MQFTE 環境下運行 Ant 腳本，執行復雜的文件傳輸任務。與標准的 Ant 命令不同，fteant 需要實現定義 Ant 腳本文件。Fteant 的重要參數包括如表 2 所示：

表 2：fteant 命令參數

參數名稱 是否必選 說明 -debug 或 -d 否 產生調試輸出 -quiet 或 -q 否 產生最少輸出 -verbose 或 -v 否 產生詳細輸出 -keep-going 或 -k 否 執行所有不依賴於失敗任務的所有任務 －D( 屬性名 )=( 屬性值 ) 否 指定某些屬性的屬性值，該屬性值具有最高優先權 -propertyfile 否 屬性文件，包含執行該任務的屬性值定義 -f(Ant 任務腳本 ) 是 指定需要運行的 Ant 任務腳本文件

例如命令形式：

fteAnt -f FTECOPYPrePostSamp.xml -DDSTFILE=\tmp\MyFile4.txt -DjobName=myTestjob

表示執行 Ant 任務腳本 FTECOPYPrePostSamp.xml，並設置其中的兩個屬性 DSTFILE 和 jobName 為特定的屬性值。

WebSphere MQ FTE Ant 開發與最佳實踐

WMQ FTE Ant 開發環境配置

下文將詳細介紹如何使用 MQ FTE 資源管理器開發 Ant 腳本。

打開 MQ 資源管理器，選擇“窗口”菜單，選擇“首選項”，在左側列表中選擇“WebSphere MQ 資源管理器”，將啟動模式修改為“在 Eclipse 工作台中”。

在首選項左側列表中選擇“常規”— >“編輯器”－>“文檔關聯”，在右側選擇“添加”，如圖 2 所示：

圖 2 文件關聯

在對話框中填入“*.xml”，並選擇確定；

在相關聯的編輯器中選擇“Ant 編輯器”，並選擇“缺省值”，並選擇“確定”如圖 3 所示。

圖 3 Ant 編輯器

重新啟動 MQ 資源管理器，選擇“打開視圖”按鈕，選擇“資源”，選擇“確定”。

在首選項左側列表選擇“Ant”— >“運行時”，選擇“全局條目”，選擇“添加外部 JAR”，如圖 4 所示：

圖 4 Ant 運行時

浏覽至 <MQFTE INSTALL DIRECTORY>/lib 目錄，將其下的所有 .jar 文件選中，選中“打開”，其中 <MQFTE INSTALL DIRECTORY> 為 MQFTE 的安裝目錄。

選擇“Ant 主目錄”，浏覽至 <MQFTE INSTALL DIRECTORY>/ant 目錄，選擇“確定”。

設置環境變量 FTEAnt_HOME 為 <MQFTE INSTALL DIRECTORY>/ant，FTEAnt_WMQ_HOME 為 <MQ INSTALL DIRECTORY> 變量，其中 <MQ INSTALL DIRECTORY> 為 MQ 的安裝目錄 。

使用 ftepingagent 命令測試各個代理是否活動，如圖 5 所示。

圖 5 ftepingagent 命令

FTE Ant 任務樣例

下面描述如何使用 FTE Ant 功能來執行文件傳輸任務。

簡單文件傳輸

使用在上文中配置好的 WMQFTE Ant 開發環境創建項目，並創建 Ant 文件 testsample.xml，在該文件的前端會出現 Ant 文件標識，將如下文件拷貝到 testsample.xml 中：

代碼 1：testsample.xml

<?xml　version='1.0'?>
　 <project　xmlns:fte="antlib:com.ibm.wmqfte.ant.taskdefs"　name="testsample"
　 default="job"　basedir="."　>
　 <target　name="step1"　description="Transfer　file">
　　　 <fte:filecopy　cmdqm="C_QM"
　　　　 src="A1@A1_QM"　dst="A2@A2_QM"
　　　　 outcome="await"
　　　　 jobname="testsample"
　　　　 rcproperty="step1.result">
　　 <fte:metadata>
　　 <fte:entry　name="departId"　value="Demo"　/>
　　 </fte:metadata>
　　　 <fte:filespec　srcfilespec="E:\fileinput\WMQSS_Securing_WMQFTEV70.pdf"
　　　　 dstfile="E:\fileoutput\transfered_file.pdf"　overwrite="true"/>
　　　 </fte:filecopy>
　　 </target>
　 <target　name="job"　depends="step1"　/>
　 </project>

其中 project 可以包含一個或多個 target，一個 target 可以依賴於其他的 target。target 中調用 Tasks，例如在上面例子中，名為“step1”的 target 中包含的 Tasks 為 “filecopy”，其中相關參數請參閱參考資料 [6]。

在 testsample 文件上點擊右鍵，選擇“運行方式”，選擇“Ant 構建”，在 console 視圖中顯示該 Ant 任務執行結果輸出，如圖 6 所示：

圖 6 文件傳輸 console 輸出

啟動 WMQ FTE 圖形管理界面，如圖 7 所示，有一條與 filecopy 任務相對應的記錄出現：

圖 7 filecopy 任務記錄

多功能文件傳輸任務

在上述簡單文件傳輸 Ant 任務基礎之上，定義具有更多功能特征的 Ant 文件傳輸任務。下面將實現一個特定的文件傳輸任務：

1 ．在文件傳輸之前，Ant 任務調用源文件所在系統的命令“netstat – n”，檢查源系統的端口使用情況；

2 ．執行文件傳輸任務，並在被傳輸的文件名前面加上文件發送的日期標記；

3 ．在文件落地之後，執行目標文件所在系統的命令“netstat – n”，檢查目標系統的端口使用情況；

配置過程如下。

修改源系統與目標系統上代理屬性配置文件。打開發送代理與接收代理的屬性配置文件 <config_directory>\config\<coordination_QMgr_name>\agents \<agent_name>\agent.properites，添加如下所示屬性定義：

commandPath=C:\\WINDOWS\\system32;
　 maxCommandOutput=204800
　 maxDestinationTransfers=8
　 maxSourceTransfers=8

netstat 命令位於“c:\WINDOWS\system32”目錄下，保存並關閉該文件。

按照如下模式編寫 Ant 文件傳輸腳本：

代碼 2：多功能文件傳輸腳本

<?xml　version='1.0'?>
　 <project　xmlns:fte="antlib:com.ibm.wmqfte.ant.taskdefs"
　 name="SimpleTransfer"　default="job"　basedir="."　>
　 <description>　Complex　FTE　file　Transfer　with　datestamp　file　name,
　　 pre　and　post　program　invocations　</description>

　 <!--　Target：init。定義一系列全局變量；用　${timestamp}　獲取當前日期函數，作為文件名　-->
　 <target　name="init"　description="Set　Global　variables">
　 <tstamp>
　　 <format　property="timestamp"　pattern="yyyyMMdd"　/>
　 </tstamp>
　 <property　name="srcfile"　value="e:\fileinput\File.txt"　/>
　 <property　name="dstfile"　value="e:\${timestamp}_File.txt"　/>
　 <property　name="SNODE"　value="A1@A1_QM"/>
　 <property　name="DNODE"　value="A2@A2_QM"/>
　 <property　name="cmdqm"　value="C_QM"/>
　 <property　name="jobName"　value="Complex　file　transfer"　/>
　 <property　name="departId"　value="IBM　service"　/>
　 </target>

　 <!--Target:step1.　定義任務　filecopy;　定義事先處理任務　fte:presrc;　定義事後處理任務　fte:postdst　-->
　 <target　name="step1"　depends="init"　description="Transfer　file">
　　　 <fte:filecopy　cmdqm="${cmdqm}"
　　　　 src="${SNODE}"　dst="${DNODE}"
　　　　 outcome="await"
　　　　 jobname="${jobName}"
　　　　 rcproperty="step1.result">
　　 <fte:metadata>
　　 <fte:entry　name="departId"　value="${departId}"　/>
　　 <fte:entry　name="jobName"　value="${jobName}"　/>
　　 </fte:metadata>
　　　 <fte:filespec　srcfilespec="${srcfile}"　dstfile="${dstfile}"
　 overwrite="true"/>
　　 <fte:presrc　command="netstat"　successrc="0">
　　 <fte:arg　value="-n"　/>
　　 </fte:presrc>
　　 <fte:postdst　command="netstat"　successrc="0">
　　 <fte:arg　value="-n"　/>
　　 </fte:postdst>
　　　 </fte:filecopy>
　　 </target>

　 <!--Target:check1.　定義文件傳輸結果判斷條件　;　定義輸出文件傳輸結論；-->
　 <target　name="check1"　depends="step1"　description=
"Check　return　code　and　set　variables">
　 <condition　property="step1-failed">
　　 <not>
　　 <equals　arg1="${step1.result}"　arg2="0"　/>
　　 </not>
　 </condition>
　 <fail　if="step1-failed"
　 message="step1　transfer　failed　MAXRC=${step1.result}.">
　 </fail>
　 <echo　message="The　FTE　transfer　was　successfull!"　/>
　 </target>

　 <!--Target：job.　定義　job,　確定　target　之間的依賴關系　-->
　 <target　name="job"　depends="init,　step1,check1"　/>
　 </project>

右鍵選擇“運行方式”，選擇“Ant 構建”，控制台輸出如下信息：

init:
　 step1:
　 [fte:filecopy]　BFGAN0046I:　正在發出要將文件從“A1@A1_QM”復制到“A2@A2_QM”的請求。
　 [fte:filecopy]　BFGAN0048I:
　　 已對復制操作分配傳輸標識　414d5120435f514d2020202020202020dafb184b20005e03。
　 [fte:filecopy]　BFGAN0050I:
　　 復制操作　414d5120435f514d2020202020202020dafb184b20005e03　成功完成。
　 check1:
　　　 [echo]　The　FTE　transfer　was　successfull!
　 job:
　 BUILD　SUCCESSFUL
　 Total　time:　1　second

打開 MQFTE 管理控制台傳輸日志，顯示文件傳輸日志，其中包括事先處理與事後處理的命令信息，如圖 8 所示。

圖 8 復雜文件傳輸結果

在“[preSourceCall] c:\WINDOWS\system32\netstat.exe”上右鍵，並選擇屬性，即可看到在源系統上的事先處理命令“netstat -n”的執行結果，如圖 9 所示。同理也可查看事後處理結果。

 

圖 9 事先處理結果

檢查文件輸出目錄，被傳輸文件名已經改為 20091207_File.txt。

WMQ FTE Ant 開發調試

Eclipse 平台提供了 Ant 任務腳本的調試工具，通過添加斷點，執行任務腳本的跟蹤與調試。如圖 10 所示，在需要調試的腳本處右鍵，選擇“添加斷點”。

圖 10 Ant 任務腳本添加斷點

在 Ant 編輯界面中右鍵，選擇“調試方式”，選擇“Ant 構建”，即可進入 Ant 的腳本調試狀態，如圖 11 所示。

圖 11 Ant 任務腳本調試

FTE Ant 最佳實踐

MQ FTE Ant 功能為文件傳輸領域提供了更大的靈活性，在定義 Ant 任務腳本過程中，經過探索與比較，建議用戶采用下面幾條最佳實踐建議。

使用 init 任務初始化全局屬性與變量

使用 init 任務來初始化全局屬性與變量，使之後的腳本文件引用全局變量與屬性，可以提高腳本修改效率。通常情況下，init 任務放在腳本的最前端，並設置變量缺省值，並使用 tstamp 函數獲取腳本執行時間點。在 Ant 腳本編寫過程中，建議將 init 任務與具體 Ant 任務結合起來，定義為通用 Ant 任務“模板”，通過更改 init 部分的變量，即可修改整個 Ant 任務定義。例如以下代碼所示：

代碼 3：定義全局屬性與變量

<target　name="init"　description="Set　Global　variables">
　 <tstamp>
　　 <format　property="timestamp"　pattern="yyyyMMdd"　/>
　 </tstamp>
　 <property　name="srcfile"　value="e:\fileinput\File4.txt"　/>
　 <property　name="dstfile"　value="e:\${timestamp}_File4.txt"　/>
　 <property　name="SNODE"　value="A1@A1_QM"/>
　 <property　name="DNODE"　value="A2@A2_QM"/>
　 <property　name="cmdqm"　value="C_QM"/>
　 <property　name="jobName"　value="Complex　file　transfer"　/>
　 <property　name="departId"　value="IBM　service"　/>
　 </target>

　 <target　name="step1"　depends="init"　description="Transfer　file">
　　　 <fte:filecopy　cmdqm="${cmdqm}"
　　　　 src="${SNODE}"　dst="${DNODE}"
　　　　 outcome="await"
　　　　 jobname="${jobName}"
　　　　 rcproperty="step1.result">
　　 <fte:metadata>
　　 <fte:entry　name="departId"　value="${departId}"　/>
　　 <fte:entry　name="jobName"　value="${jobName}"　/>
　　 </fte:metadata>
　　 …　…　…　…　

使用“條件”任務

在 Ant 任務腳本中加入對任務執行結果的判斷條件，以此作為下一步操作的基礎。例如下面代碼所示，在 target check1 中，對 step1 的返回結果進行判斷，判斷該返回值是否為 0。

代碼 4：定義“條件”任務

<condition　property="step1-failed">
　　 <not>
　　　 <equals　arg1="${step1.result}"　arg2="0"　/>
　 </not>
　　 </condition>

調用“fail”函數

在 Ant 腳本中加入錯誤處理部分，即調用 Ant 的 fail 函數，例如下面代碼所示：

代碼 5：定義“fail”函數

<fail　if="step1-failed"
　 message="step1　transfer　failed　MAXRC=${step1.result}.">
　　 </fail>

總結

本文介紹了 WebSphere MQ File Transfer Edition 7.0 所提供 Ant 功能，並以此實現了簡單、復雜文件傳輸任務，並描述了 Ant 任務腳本開發的環境配置、跟蹤調試與最佳實踐，為基於 WMQ FTE 實現大文件傳輸提供技術參考。