個人收藏Lotuser進階系列——通過 Lotus Domino Java 代理消費 Web 服務

作為 IBM Lotus Domino 7 的新特性，Web 服務設計項目是向世界公開服務的主要途徑。但是您知道使用 Apache Axis 架構消費 Web 服務是多麼容易嗎？本文獲得如何利用 Apache Axis 和 Lotus Domino 7 技術建立 Web 服務消費者的知識。

Web 服務是一種允許兩台或更多的電腦在網路中互動的系統設計。這種服務的主要優點是，它是在多台不同作業系統的電腦和應用伺服器之間發送對象的標準解決方案。例如，我們的公司使用 Web 服務從一台運行 Microsoft .NET Framework 的電腦向基於 IBM Lotus Domino 的內連網發布文章。我們最近完成了另一個項目，公開了 Lotus Domino 7 伺服器上的 Web 服務的專題報告。基於 Java 的應用伺服器讀取報表服務器，我們必須協商的惟一東西是 Web Services Description Language（WSDL）檔案。

本文向您展示了如何建立 Domino Java 代理消費 Web 服務。它使用 Apache Axis 產生 Java 存根並讀取 WSDL 檔案。我們提供一個包含可以在本文以下部分使用的 Web 服務的資料庫樣本。更多資訊請參見 “下載” 部分。

本文假設您是一個有經驗的 Lotus Notes 和 Domino 應用程式開發人員，熟悉新的 Domino Web 服務設計項目。要學習有關新的 Domino Web 服務設計項目的更多知識，請參閱 developerWorks Lotus 文章 “Lotus Notes/Domino 7 Web Services”。

Web 服務的組件

Web 服務包含幾個組件。這些組件包括：

• WSDL 檔案
• 面向服務體繫結構（Service-Oriented Architecture，SOA）
• 各種協議

 

WSDL 檔案

WSDL 是 Web 服務安裝的粘合劑（glue）。每個 Web 服務發布一個 WSDL 檔案，該檔案包含它可以處理哪些方法和自變數的資訊，以及不同方法返回什麼對象的資訊。本文使用的是一個包含簡單 Web 服務的資料庫（在本執行個體中，是 Lotus Domino 7 資料庫）。

儘管這個 Web 服務很簡單，但是這個服務的 WSDL 檔案是十分詳細的。當然，這麼詳細的一個原因是 WSDL 檔案使用詳細的格式，XML。可是，考慮到 WSDL 檔案包含 Web 服務發送和接收的所有對象的描述，這個檔案大小不算過分。本文 Web 服務例子的 WSDL 檔案有一個名為 ComplexClass 的 Java 類，程式碼片段如下所示：

<complexType name="MyComplexClass"> <sequence> <element name="alpha" nillable="true" type="xsd:string"/> <element name="calcA" type="xsd:int"/> <element name="calcB" type="xsd:int"/> <element name="result" nillable="true" type="xsd:int"/> </sequence> </complexType>

面向服務體繫結構

面向服務體繫結構（Service-Oriented Architecture，SOA）在過去的十年已經出現。簡單地說，SOA 是一種軟體體繫結構，它更多地集中於業務而不是公用的、技術驅動的解決方案。它基本上是以消費者-提供者方式設計用於 Web 服務的體繫結構。SOA 方法分離各個層，消費者通過服務層與業務對象進行互動，而不是直接進行互動。

關於 SOA 的更多資訊，請參閱 developerWorks SOA 和 Web 服務上的 SOA and Web services 新手入門 頁面。

Web 服務使用的協議

Web 服務訊息不受使用 HTTP 的限制。它也可以使用 SMTP、Extensible Messaging and Presence Protocol（XMPP），甚至 FTP。但是，必須遵守 SOAP；否則，接收系統就很難解釋訊息。在老一點兒的系統上，可以找到 XML-Remote Procedure Call（XML-RPC），但是 SOAP 是目前正確的協議。

Web 服務的好處是您不必研究各種協議和標準：所有這些都由應用伺服器和開發工具處理。在這個例子中，Apache Axis 協助您解釋 WSDL 並產生 Java 程式碼端。

資料庫樣本

在開始使用 Apache Axis 工具前，必須有一個發布 WSDL 檔案的 Web 服務。在本文的 “下載” 部分，有兩個資料庫樣本：WebServiceConsumer.nsf 和 MyWebService.nsf。它們的名稱表明了它們的作用。在把 MyWebService.nsf 下載到 Lotus Domino 7 伺服器之後，用可以運行受限代理的 ID 標記 Web 服務設計項目 —— MyWebservice。WebServiceConsumer.nsf 僅供參考。

回頁首

Apache Axis

Apache Axis 是一個包括 SOAP 伺服器和許多產生並部署 Web 服務的不同工具的完整架構。在本文中使用通訊部分和 WSDL2Java 方法。但是，首先必須安裝 Apache Axis。

先決條件

在可以構建、測試和部署本文中描述的解決方案前，必須具備如下條件：

• Lotus Domino 7 伺服器和 IBM Lotus Domino Designer
• Java 軟體開發套件（JDK）
• Apache Axis 架構

 

我們假設您已經安裝了 Lotus Domino 7，並且您知道如何獲得 Java 環境並運行。（本文的 “參考資料” 部分提供了所有必須下載的連結。）

表 1 顯示了在我們的系統中使用的檔案結構。如果您選擇複製這個結構，可以重用稍後提到的批次檔和類路徑，也可以選擇使用您自己的策略。我們為每一個目錄使用工作名稱，這樣不會混亂。批次檔是由變數驅動的，所以可以很容易地修改一兩行代碼使它在您的系統中運行。

表 1. 建議的檔案結構

工作名稱	路徑
伺服器路徑	C:\lotus\DominoR7StandAlone
JDK 版本 2	C:\java\j2re1.4.2_09
Apache Axis	C:\java\Axis
工作目錄	C:\java\consumer

下載並安裝 Apache Axis

在下載 Apache Axis 之後，將軟體包解壓到 Axis 目錄。（參見表 1 的建議路徑。）本文使用 Apache Axis 提供的兩個特性。一個是通訊類，實際上，除了要把它們匯入 Domino 環境，您不需要知道其他的任何東西。另一個特性是 wsdl2java 工具，Apache Axis 可以使用該工具讀取 WSDL 檔案並為所有需要的方法和對象產生完整的 Java 存根。

可以啟動 shell 並開始運行 Apache Axis 類，但是我們發現啟動每個命令要使用 100 個字元以上的類路徑是很不方便的。一個解決方案是在一般 Java 類路徑中為 Apache Axis 設定所需要的完整的類路徑，但是我們更喜歡另一個解決方案：維護設定類路徑的批次檔。以下程式碼片段顯示了名為 wsdl2java.bat 的批次檔，它存在於工作目錄中。

@echo OFF rem ******************************************************* rem *** wsdl2java.bat **** rem ******************************************************* set AXISPATH=c:\java\AXIS\lib set JAVAPATH=C:\java\j2re1.4.2_09 set DOMINOJAVAPATH=C:\lotus\DominoR7StandAlone\jvm\lib\ext set CP=%AXISPATH%\axis.jar set CP=%CP%;%AXISPATH%\commons-logging-1.0.4.jar set CP=%CP%;%AXISPATH%\commons-discovery-0.2.jar set CP=%CP%;%AXISPATH%\jaxrpc.jar set CP=%CP%;%AXISPATH%\saaj.jar set CP=%CP%;%DOMINOJAVAPATH%\mail.jar set CP=%CP%;%DOMINOJAVAPATH%\activation.jar set CP=%CP%;%AXISPATH%\wsdl4j-1.5.1.jar %JAVAPATH%\bin\java -cp %CP% org.apache.axis.wsdl.WSDL2Java %1

回頁首

建立 Web 服務消費代理

通過從 Web 服務擷取 WSDL 檔案開始建立代理。我們假設您正在使用已提供的 Web 服務 —— MyWebservice —— 並已經將它複製到 Lotus Domino 7 伺服器。要想看到 WSDL 檔案，將瀏覽器指向資料庫並通過命令 ?WSDL 開啟 Web 服務， 1 所示。

圖 1. 在瀏覽器中顯示 WSDL 檔案的例子

在確定 WSDL 檔案出現後，可以把 WSDL 檔案儲存到工作目錄中，或者使用 URL 將 Apache Axis 工具包直接指向網路中的 WSDL 資源。現在，可以開始從 WSDL 檔案產生 Java 存根。

回頁首

從 WSDL 檔案產生 Java 檔案

WSDL2Java 函數可以把檔案名稱作為參數，如下所示：

C:\java\consumer>wsd12java.bat MyWebservice.xml

或者以 WSDL 檔案的完整的 Uniform Resource Indicator（URI）作為參數：

C:\java\consumer>wsd12java.bat http://localhost/mywebservice.nsf/MyWebService?WSDL

為了在本地工作，下載並使用名稱 MyWebservice.xml 把 WSDL 檔案儲存到工作目錄中，如第一個命令所示。

注意：我們工作使用的 Web 服務只是為了示範的目的（例如，沒有使用名稱空間）。所以，您現在在工作目錄中看到一個名為 DefaultNamespace 的新目錄。

wsdl2java.bat 的運行結果是產生五個 Java 檔案：

• DominoSoapBindingStub.java
• HelloWorld.java
• HelloWorldService.java
• HelloWorldServiceLocator.java
• MyComplexClass.java

 

在這五個檔案中，只有兩個是真正重要的：HelloWorld.java 和 MyComplexClass.java。其他三個用於執行調用和解析響應。如果您想學習更多關於 Apache Axis 架構的內容，建議您訪問 Apache Axis wiki。

HelloWorld.java 是一個描述 Web 服務可以處理的方法和自變數的介面。MyComplexClass.java 是 MyComplexClass 對象的 JavaBeans 版本，當調用 getMyComplexClass() 方法時 Web 服務用它進行響應。

現在，在 Domino 7 資料庫中建立一個新的指令碼庫，可以使用它消費 Web 服務。

回頁首

把 Java 檔案匯入 Lotus Notes

Web 服務消費代理使用 Apache Axis 產生的檔案。匯入 Java 檔案最容易的方法是建立 Java 指令碼庫（不要與 JavaScriptlibrary 混淆）。匯入檔案並記住將工作目錄設定為基礎路徑（參見圖 2）。

圖 2. 儲存 Apache Axis 產生的 Java 存根的指令碼庫

注意：基礎目錄是工作目錄，而不是 DefaultNamespace 目錄，這一點非常重要。

當指令碼庫放在適當的位置並編譯過之後，就可以關閉它並建立新的 Java 代理。這個代理使用 Apache Axis 客戶機類。這些類是 Axis 架構的一部分，所以必須匯入。

Apache Axis 客戶機位於 Axis 目錄下的 Java 封存檔案（JAR 檔案）中。有一些向代理公開這些類的選項，其中一個選項是直接在代理中匯入這些類。但是由於這些類的天然性質 —— 當您發現 Web 消費是多麼容易的時候就可以多次使用它們 —— 把它們儲存到 IBM Lotus Notes 的其他 JAR 檔案使用的 .\jvm\lib\ext 目錄中是更自然的方法。

在 Lotus Notes 客戶機目錄中，將 JAR 檔案 axis.jar、commons-discovery-0.2.jar 和 commons-logging-1.0.4.jar 從 .\Axis\lib 複製到 .\jvm\lib\ext。（在使用這些附加檔案之前必須重新啟動 Lotus Notes 客戶機。）當 Lotus Domino Designer 運行時，在開始調用 Web 服務之前只剩下幾個步驟。

回頁首

調用 Web 服務的 Lotus Notes 代理

當 JAR 檔案放在 .\jvm\lib\ext 目錄下並已經重新啟動 Lotus Domino Designer 之後，就可以編寫 Web 消費代理的代碼了。從建立普通的 Java 代理開始。下一步，開啟 Edit Project 視窗匯入先前建立的指令碼庫。關閉項目屬性視窗，並添加必須的如下所示的匯入行：

00 import lotus.domino.*; 01 import java.net.URL; 02 import org.apache.axis.client.Call; 03 import org.apache.axis.client.Service; 04 import DefaultNamespace.*; 05 import java.io.*; 06 public class JavaAgent extends AgentBase { 07 public void NotesMain() { 08 try { 09 Session session = getSession(); 10 AgentContext agentContext = session.getAgentContext(); 11 12 URL endpoint = new URL("http://localhost:80/MyWebService.nsf/MyWebService"); 13 14 Service service1 = new Service(); 15 DominoSoapBindingStub service = new DominoSoapBindingStub(endpoint,service1); 16 String greeting=service.getGreeting(); 17 System.out.println(greeting); 18 19 String greeting2=service.getGreeting("Lotus"); 20 System.out.println(greeting2); 21 22 } catch(Exception e) { 23 e.printStackTrace(); 24 } 25 } 26}

在第 12 行，建立一個標準的 Java URL 指向您想要使用的 Web 服務。在第 14 行，執行個體化 Apache Axis 提供的 Service() 類。然後，在第 15 行執行個體化 DominoSoapBindingStub 服務，並使用新建立的 service1 對象和第 12 行的 URI 提供它。在第 16 行，用 Web 服務方法 getGreeting() 提供的值設定新的字串。

儲存代理並啟動 Java 控制台。（這個控制台是惟一一個現在能看到任何活動的地方。）當開啟調試視窗時，選擇新的資料庫，然後運行代理， 3 所示。

圖 3. 當代理完成後的 Java 控制台

正如您所見，使用 Apache Axis 和 wsdl2java 工具非常節省時間。以前，在 Lotus Domino 5 代理中消費 Web 服務時，您必須坐下來手工解碼 SOAP 訊息！

回頁首

在伺服器上運行 Web 服務消費代理

現在有了一個可以使用 Web 服務進行互動的強大代理。例如，您組織的內連網可以以比過去使用的 Comma Separated Value（CSV）檔案更奇特更精確的方式預訂最新的天氣預報。還可以將 Web 服務與昂貴的 Enterprise Resource Planning（ERP）系統一起使用。

在伺服器上運行這個代理不需要其他的步驟。只要保證在 Agent Properties 對話方塊中將 “Set runtime security level” 屬性設定為 “2. Allows restricted operations”，簽名者就可以有適當的訪問權。

把先前描述的必要的 JAR 檔案複製到 Lotus Domino 伺服器的 .\jvm\lib\ext 路徑。但是注意，如果在正在運行代理的同一台伺服器上調用 Domino Web 服務，可能會經曆死結。

結束語

本文描述了構建 Domino 代理來消費 Web 服務的步驟。利用 Apache Axis 架構，可以節省許多時間並集中於業務價值。Apache Axis 已經使用了一段時間，它是穩定且可靠的。使用這樣一個第三方的工具使系統更易受攻擊，但是這個風險遠小於 SOA 能夠為您的組織所帶來的好處。