通過 Axis2 開發 Web 服務，第 1 部分: 通過 Axis2 運行時部署和使用簡單 Web 服務

文檔選項 將此頁作為電子郵件發送 樣例代碼 拓展 Tomcat 應用 下載 IBM 開源 J2EE 應用服務器 WAS CE 新版本 V1.1

級別: 中級

Gopalakrishnan U (ugopalak@in.ibm.com), 軟件工程師, IBM India Software Labs
Shreevidya Rao (ugopalak@in.ibm.com), 軟件工程師, IBM

2006 年 6 月 13 日

本文介紹 Axis2 的新體系結構，并說明如何通過 Axis2 部署和使用 Web 服務。本文是有關通過 Axis2 運行時開發 Web 服務的系列文章的第 1 部分（共兩部分）。Axis2 是下一代 Apache Axis Simple Object Access Protocol (SOAP) 運行時。

引言

Axis2 是下一代 Apache Axis。Axis2 雖然由 Axis 1.x 處理程序模型提供支持，但它具有更強的靈活性并可擴展到新的體系結構。Axis2 基于新的體系結構進行了全新編寫，而且沒有采用 Axis 1.x 的常用代碼。支持開發 Axis2 的動力是探尋模塊化更強、靈活性更高和更有效的體系結構，這種體系結構可以很容易地插入到其他相關 Web 服務標準和協議（如 WS-Security、WS-ReliableMessaging 等）的實現中。

Axis2 的特性包括：

• 采用名為 AXIOM（AXIs Object Model，Axis 對象模型）的新核心 XML 處理模型
• 支持 In-Only 和 In-Out 消息交換模式 (MEP)
• 阻塞和非阻塞客戶端 API（應用程序編程接口）
• 支持內置的 Web 服務尋址 (WS-Addressing)
• 支持 XMLBeans 數據綁定
• 新部署模型
• 支持超文本傳輸協議 (HTTP)、簡單郵件傳輸協議 (SMTP) 和傳輸控制協議 (TCP) 等傳輸協議

本系列文章以 Axis2 0.92 版本為基礎。您可以在 Apache 網站獲得 Axis2 的最新版本。

回頁首

Axis 體系結構概述

Axis2 體系結構將邏輯與狀態分離；這允許在并行線程中執行邏輯。服務和調用的靜態狀態和動態狀態分別存儲在 Description 和 Context 類中。Axis2 體系結構是使用 7 個獨立模塊實現的。

1. 信息模型：此模塊管理 SOAP 引擎的狀態。該模型定義一組用于存放狀態的類，而引擎管理這些信息對象的生命周期。信息模型包含兩種用于存放狀態的類。Description 類存放本質上是靜態的且存在于 Axis 引擎實例的整個生命周期中的數據（如傳輸、服務和操作的配置）。Context 類存放調用上下文中有效的服務和操作的動態信息，例如當前請求和響應 SOAP 消息、From 地址、To 地址和其他元素。
2. XML 處理模型：Axis2 引入了一個名為 AXIOM 的新模型，用于處理 SOAP 消息。AXIOM 使用 StAX (Streaming API for XML) 來解析 XML。StAX 是一個標準的流式 Pull 解析器 Java? API。AXIOM 非常精巧，不會減慢 XML 信息集的構建速度——換句話說，對象只有在絕對必要時才會創建。總體而言，AXIOM 和 Axis2 所占用的內存要小于 Axis 1 所占用的內存。
3. SOAP 處理模型：Axis2 體系結構定義了兩個管道（或流），分別稱為 InPipe (InFlow) 和 OutPipe (OutFlow)，用于處理服務器端的請求消息和響應消息。在客戶端，這兩個管道是反向的——換句話說，SOAP 請求消息流經 OutPipe，而響應消息流經 InPipe。管道或流包含一系列分為階段的處理程序。階段按照預先定義的順序執行，如上面的圖 1 所示。除預先定義的階段和處理程序集外，用戶還可以在操作級別、服務級別或全局級別配置用戶階段和相關處理程序。處理程序充當 SOAP 消息的攔截器，可以處理 SOAP 消息的 Header 或 Body。InPipe 是通過以下階段進行配置的：
   • TransportIn
   • PreDispatch
   • Dispatch
   • PostDispatch
   • PolicyDetermination
   • User phases
   • Message validation
   我們將在本系列文章的第 2 部分中詳細介紹上述各階段。請求消息在通過 Inpipe 中配置的所有階段后，到達 MessageReceiver，然后由 MessageReceiver 調用實際服務實現。服務器的 OutPipe 包含以下階段：
   • Message initialization
   • Policy determination
   • User phases
   • MessageOut
   用戶配置的階段位于這兩個管道的用戶階段(User phases) 部分。如果在執行這些管道的過程中發生錯誤，則這些錯誤將通過 InFaultPipe 或 OutFaultPipe 管道。收到 Fault 消息后，在客戶端調用 InFaultPipe；如果某個調用導致將錯誤發送到客戶端，則在服務器端調用 OutFaultPipe。用戶可以將處理程序添加到預先定義的階段，并且按照這些處理程序運行的順序進行配置。
4. 部署模塊：此模塊配置 Axis 引擎并部署服務和模塊。axis2.xml（在 webapps/axis2/WEB-INF 中）包含 Axis2 引擎的全局配置，包括：
   • 全局模塊 (Global modules)
   • 全局接收器 (Global receivers)
   • 傳輸 (Transports)
   • 用戶階段定義 (User phase definitions)
   每個服務的配置都包含在服務存檔的 services.xml 文件中。本文稍后將詳細討論此文件。
5. WSDL 和代碼生成：此模塊從 WSDL 文件中生成客戶端存根和服務器框架代碼。Axis2 代碼生成器發出采用正確 XML 樣式表的 XML 文件，以用所需語言生成代碼。
6. 客戶端 API：Axis2 客戶端 API 調用遵循 WSDL 2.0 定義的 In-Only 和 In-Out 消息模式的操作。客戶端 API 支持 In-Out 操作的阻塞和非阻塞調用。
7. 傳輸：此模塊包含與傳輸層交互的處理程序。傳輸處理程序有兩種類型：TransportListener 和 TransportSender。TransportListener 從傳輸層接收 SOAP 消息，然后將其傳送到 InPipe 進行處理。TransportSender 發送通過指定傳輸從 OutPipe 接收到的 SOAP 消息。Axis2 提供 HTTP、SMTP 和 TCP 的處理程序。對于 HTTP 傳輸，服務器端上的 AxisServlet 和客戶端上的一個簡單的獨立 HTTP 服務器（由 Axis2 提供）充當 TransportReceiver。

回頁首

部署 Axis2

部署 Axis2 與部署 Axis 1 一樣簡單。首先在 Axis2 二進制代碼分發包的 webapps 目錄下查找 Axis2 Web 應用程序 axis2.war。在 servlet 容器中部署此 war 文件。在 Tomcat 中，如果已在服務器配置中將 unpackWARs 設置為 True，則只需將 axis2.war 復制到 $TOMCAT_HOME/webapps 目錄即可部署 Axis2。請立即啟動 Tomcat 并訪問 http://localhost:<port>/axis2。將顯示 Axis2 歡迎頁，單擊此頁上的 Validate 鏈接。您應到達 Axis2 Happiness page，不會出現任何錯誤。

回頁首

開發 StockQuoteService

下面介紹如何使用 In-Only subscribe() 和 In-Out getQuote() 這兩個操作來開發 StockQuoteService。subscribe() 操作將預訂指定代號的每小時報價，而 getQuote() 將獲得指定代號的當前報價。

下面的清單 1 是 StockQuoteService 的實現示例：

				
package stock;
import org.apache.axis2.om.OMAbstractFactory;
import org.apache.axis2.om.OMElement;
import org.apache.axis2.om.OMFactory;
import org.apache.axis2.om.OMNamespace;
		
public class StockQuoteService {
		 
  public void subscribe(OMElement in){
    String symbol = in.getText();
    System.out.println("Subscription request for symbol ="+symbol);
    // put the actual subscribe code here...    
  }
		  
		  
  public OMElement getQuote(OMElement in){
		  
    // Get the symbol from request message
    String symbol = in.getText();
		    
    int quote = 0;
    if(symbol.equals("IBM")){
      quote = 100;
    }
    // Put more quotes here ...
		    
    // Create response
    OMFactory fac = OMAbstractFactory.getOMFactory();
    OMNamespace omNs = fac.createOMNamespace(
      "http://www.developerworks.com/example", "example");
    OMElement resp = fac.createOMElement("getQuoteResponse", omNs);
    resp.setText(String.valueOf(quote));
    return resp;      
  }
}

對方法簽名感到很疑惑？我們將討論上述方法中的 OMElement。

回頁首

部署服務

部署描述符

在 Axis2 中，服務部署信息包含在 services.xml 文件（在 0.92 以前的版本中，此文件名為 service.xml）中。對于上述 StockQuoteService，服務部署描述符與下面的清單 2 類似。

				
<service name="StockQuoteService">
  <parameter name="ServiceClass" locked="xsd:false">
    stock.StockQuoteService
  </parameter>
		
  <operation name="getQuote">
    <messageReceiver 
      class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
  </operation>
		
  <operation name="subscribe">
    <messageReceiver 
      class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/>
  </operation>
</service>

服務的 name 屬性定義服務的名稱。Axis2 使用服務的名稱創建服務的端點地址，例如 http://localhost:<port>/axis2/services/<nameofservice>。因此，對于 StockQuoteService，服務端點為 http://localhost:<port>/axis2/services/StockQuoteService。ServiceClass 參數指定服務實現類。

每個 <operation> 元素定義服務中一個操作的配置。<operation> 的 name 屬性應設置為服務實現類中方法的名稱。messageReceiver 元素定義用于處理此操作的消息接收器。Axis2 針對 In-Only 和 In-Out 操作提供了兩個無數據綁定的內置 MessageReceivers；org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver 用于 In-Only 操作，而 org.apache.axis2.receivers.RawXMLINOutMessageReceiver 用于 In-Out 操作。如果沒有指定 messageReceiver，則 Axis2 將嘗試使用 org.apache.axis2.receivers.RawXMLINOutMessageReceiver 作為缺省的 messageReceiver。上述 RAWXML 消息接收器將傳入 SOAP 消息的 <Body> 的內容作為 OMElement（OMElement 是 XML 元素的 AXIOM 縮寫）傳遞給服務實現。此操作應作為 OMElement 返回 SOAP 響應的 <Body> 元素包含的 XML 內容。這便解釋了為何 subscribe() 和 getQuote() 操作采用和返回 OMElement。

services.xml 還可以包含分為 servicegroup 的多個服務。

打包

Axis 2 服務是作為 Axis Archive (.aar) 打包的。這是一個 JAR 文件（使用 jar 或 zip 實用程序創建），在存檔的 META-INF 目錄中打包了 services.xml 文件。StockQuoteService 在打包成 StockQuoteService.aar 時將具有以下結構：

./stock/StockQuoteService.class
./META-INF/services.xml

預先打包的 StockQuoteService 存檔可以在本文的下載部分中找到。

部署

在 Axis2 中部署服務相當簡單，只需將 .aar 文件復制到 servlet 容器的 axis2 Web 應用程序中的 axis2/WEB-INF/services 目錄下即可。對于 Tomcat，此位置為 $TOMCAT_HOME/webapps/axis2/WEB-INF/services。

另一種部署服務的好方法是使用 Axis2 管理控制臺中的 Upload Service 工具。請轉到 http://localhost:<port>/axis2，然后選擇 Administration 鏈接。輸入用戶名和密碼 admin/axis2，然后登錄。（您可以在 axis2.xml 中配置用戶名/密碼。)在工具部分選擇 Upload Service 鏈接，再選擇 .aar 文件，然后單擊 Upload。就是這樣簡單！如果上傳成功，系統將顯示一條綠色成功消息。服務即被部署，而且可隨時調用。如果要在遠程 Axis2 服務器上部署服務，則此功能非常方便。

回頁首

通過 Axis2 使用 Web 服務

Web 服務調用的特性由 MEP、傳輸協議以及客戶端 API 的同步和/或異步行為決定。Axis2 當前支持 WSDL 2.0 定義的 In-Only 和 In-Out MEP。Axis2 客戶端 API 支持服務的同步和異步調用。在調用 In-Out 操作時，在 API 級別和傳輸級別提供異步行為。API 級別異步是通過回滾獲得的，它使用一個傳輸連接來同時傳輸請求和響應（例如，通過一個 HTTP 連接傳輸請求和響應）。在傳輸級別異步中，使用不同的傳輸連接分別發送請求和接收響應，例如使用 SMTP 進行傳輸時即如此。

下面是使用 Axis2 客戶端 API 調用 In-Only 和 In-Out 操作的詳細信息。

調用 In-Only 操作

org.apache.axis2.clientapi.MessageSender 類用于調用 In-Only 操作（如下面的清單 3 所示），而 In-Only 操作調用 StockQuoteService 的 subscribe() 操作。

				
try{
  EndpointReference targetEPR = new EndpointReference(
      "http://localhost:8080/axis2/services/StockQuoteService");
          
  // Make the request message
  OMFactory fac = OMAbstractFactory.getOMFactory();
  OMNamespace omNs = fac.createOMNamespace(
      "http://www.developerworks.com/example", "example");
  OMElement payload = fac.createOMElement("subscribe", omNs);
  payload.setText("IBM"); 
          
  // Send the request
  MessageSender msgSender = new MessageSender();
  msgSender.setTo(targetEPR);
  msgSender.setSenderTransport(Constants.TRANSPORT_HTTP);
  msgSender.send("subscribe", payload);         
  }catch (AxisFault axisFault) {
      axisFault.printStackTrace();
  }

MessageSender.send() 發送請求消息并將其立即返回。要使用的傳輸由 MessageSender.setSenderTransport() 指定。此示例通過 HTTP 發送消息。

調用 In-Out 操作

使用 org.apache.axis2.clientapi.Call 類可以方便地調用 In-Out 操作。調用 In-Out 操作時，此 Call 類支持下列 4 種模式：

1. 阻塞單傳輸模式：這是調用 In-Out Web 服務操作最簡單的方式。在操作完成和接收到響應或錯誤之前，服務調用被阻塞。它使用一個傳輸連接同時發送和接收響應，如下面的清單 4 所示。

   
   
   清單 4. 阻塞單傳輸模式
   

   try { EndpointReference targetEPR = new EndpointReference( "http://localhost:8080/axis2/services/StockQuoteService"); // Create request message OMFactory fac = OMAbstractFactory.getOMFactory(); OMNamespace omNs = fac.createOMNamespace( "http://www.developerworks.com/example", "example"); OMElement payload = fac.createOMElement("getQuote",omNs); payload.setText("IBM"); // Create the call Call call = new Call(); call.setTo(targetEPR); call.setTransportInfo(Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, false); // Invoke blocking OMElement result = call.invokeBlocking("getQuote", payload); System.out.println("Quote ="+result.getText()); }catch (AxisFault axisFault) { axisFault.printStackTrace(); }

   
   

   代碼的第一部分使用 AXIOM 創建請求消息。Call.setTransportInfo() 設置用于發送請求和獲得響應的傳輸。Call.setTransportInfo() 操作的 Boolean 參數指出是否要使用不同的傳輸連接來分別發送請求和接收響應。在本例中，要求用一個 HTTP 連接發送請求和接收響應。

2. 非阻塞單傳輸模式：在此調用模式中，只使用下面的一個傳輸連接獲得非阻塞調用。如果在一個客戶端應用程序中要完成多個 Web 服務調用，而且不希望每次調用都阻塞客戶端，則需要此類行為。此時，如果響應可用，則調用立即返回且客戶端得以回滾，如下面的清單 5 所示。

   
   
   清單 5. 非阻塞單傳輸模式
   

   try { EndpointReference targetEPR = new EndpointReference( "http://localhost:8080/axis2/services/StockQuoteService"); //Create the request OMFactory fac = OMAbstractFactory.getOMFactory(); OMNamespace omNs = fac.createOMNamespace( "http://www.developerworks.com/example", "example"); OMElement payload = fac.createOMElement("getQuote", omNs); payload.setText("IBM"); // Create the call Call call = new Call(); call.setTo(targetEPR); // Set the transport info. call.setTransportInfo(org.apache.axis2.Constants.TRANSPORT_HTTP, org.apache.axis2.Constants.TRANSPORT_HTTP, false); // Callback to handle the response Callback callback = new Callback() { public void onComplete(AsyncResult result) { System.out.println("Quote = " + result.getResponseEnvelope().getBody().getFirstElement() .getText()); } public void reportError(Exception e) { e.printStackTrace(); } }; // Invoke non blocking call.invokeNonBlocking("getQuote", payload, callback); //Wait till the callback receives the response. while (!callback.isComplete()) { Thread.sleep(1000); } call.close(); } catch (AxisFault axisFault) { axisFault.printStackTrace(); } catch (Exception ex) { ex.printStackTrace(); }

   
   

   Call.invokeNonBlocking() 方法立即返回而不阻塞。Call.invokeNonBlocking() 采用 org.apache.axis2.clientapi.CallBack 的對象，如果響應來自服務，則將觸發此對象。CallBack 有兩個抽象方法 onComplete(AsynchResult) 和 reportError(Exception)，需要由具體的 CallBack 類實現這些方法。在服務調用正常完成后，Axis2 引擎調用 onComplete() 方法。在從服務器獲得錯誤消息后，調用 Callback 的 reportError() 方法。Callback.isComplete() 將指出操作調用是否完成。

   因為上面兩個方法使用一個傳輸連接來發送和接收消息，所以這些方法不適合長時間運行的事務。原因是在響應可用之前，傳輸連接可能會超時。要解決此問題，可使用兩個不同的連接來分別發送請求和接收響應。但因為使用了其他傳輸連接來獲得響應，因此需要將請求和響應關聯起來。Axis2 支持 WS-Addressing，后者通過使用 <wsa:MessageID> 和 <wsa:RelatesTo> Header 可解決此問題。因此，如果使用兩個傳輸，則支持對模塊尋址，如下面兩個模式所示。

3. 阻塞雙傳輸模式：此模式在以下情況下非常有用：服務操作在本質上是 In-Out，但使用的傳輸是單向的（如 SMTP）或服務執行需要很長時間且 HTTP 連接超時。請參見下面的清單 6。

   
   
   清單 6. 阻塞雙傳輸模式
   

   try{ EndpointReference targetEPR = new EndpointReference( "http://localhost:8080/axis2/services/StockQuoteService"); OMFactory fac = OMAbstractFactory.getOMFactory(); OMNamespace omNs = fac.createOMNamespace( "http://www.developerworks.com/example", "example"); OMElement payload = fac.createOMElement("getQuote",omNs); payload.setText("IBM"); Call call = new Call(); call.setTo(targetEPR); call.setTransportInfo( Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, true); //Blocking Invocation OMElement result = call.invokeBlocking("getQuote", payload); System.out.println("Quote = "+result.getText()); }catch (AxisFault axisFault) { axisFault.printStackTrace(); }catch (Exception ex) { ex.printStackTrace(); }

   
   

4. 非阻塞雙傳輸模式：就 API 級別和傳輸級別的非阻塞而言，此模式提供了最大的靈活性，如下面的清單 7 所示。

   
   
   清單 7. 非阻塞雙傳輸模式
   

   try { EndpointReference targetEPR = new EndpointReference( "http://localhost:8080/axis2/services/StockQuoteService"); OMFactory fac = OMAbstractFactory.getOMFactory(); OMNamespace omNs = fac.createOMNamespace( "http://www.developerworks.com/example", "example"); OMElement payload = fac.createOMElement("getQuote",omNs); payload.setText("IBM"); Call call = new Call(); call.setTo(targetEPR); call.setTransportInfo( Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, true); // Callback to handle the response Callback callback = new Callback() { public void onComplete(AsyncResult result) { System.out.println("Quote = " + result.getResponseEnvelope().getBody().getFirstElement() .getText()); } public void reportError(Exception e) { e.printStackTrace(); } }; // Non-Blocking Invocation call.invokeNonBlocking("getQuote", payload, callback); // Wait till the callback receives the response. while (!callback.isComplete()) { Thread.sleep(1000); } call.close(); }catch (AxisFault axisFault) { axisFault.printStackTrace(); }catch (Exception ex) { ex.printStackTrace(); }

   
   

回頁首

總結

在這一由兩部分組成的系列的第 1 部分中，您了解了 Axis2 體系結構以及如何使用不同的調用模式來部署和使用一個簡單的 Web 服務。在本系列的第 2 部分中，您將詳細了解該體系結構，以及如何通過添加處理程序和 Axis2 消息接收器來自定義 Axis2。您還將了解如何使用 Axis2 提供的 XMLBeans 數據綁定支持。

回頁首

下載

	關于下載方法的信息			Get Adobe? Reader?

回頁首

參考資料

• 您可以參閱本文在 developerWorks 全球站點上的 英文原文。
  
  
• Axis2 User Documentation ：開始了解 Axis2 的好地方。
  
  
• Axis2 Architecture Document 提供 Axis2 體系結構的詳細視圖。
  
  
• WSDL 2.0 規范
  
  
• SOA and Web services 有數百篇介紹如何開發 Web 服務應用程序的文章以及入門級、中級和高級教程。
  
  
• IBM developerWorks 團隊在全球舉辦數百場技術講座，您可以免費參加。

• 獲得來自 DB2?、Lotus?、Rational?、Tivoli? 和 WebSphere? 的應用程序開發工具和中間件產品。您可以免費下載產品的評估版，也可以選擇 Linux? 或 Windows? 版本的 developerWorks 免費軟件評估工具包。
  
  

• Axis2 Mailing lists 討論了有關 Axis2 的使用、問題和解決方案。
  
  
• developerWorks 博客 ：加入 developerWorks 社區。
  
  

回頁首

作者簡介

		Gopalakrishnan U 目前是 IBM India Software Labs 中 Web Services Competency 團隊的一員。他最近兩年一直在 IBM 工作，有超過三年半的 Java 和 Web 技術經驗。在過去的一年里，他致力于 Web 服務技術的研究，為 IBM Web Services ToolKit (WSTK) 做出了貢獻。您可以通過 ugopalak@in.ibm.com 與 Gopalakrishnan 聯系。

		Shreevidya Rao 是 IBM Software Labs 中 Research Group 的軟件工程師。她過去一年在 IBM 工作，有五年的 Java 和 J2EE 經驗。她目前致力于開發分布式可管理的記錄程序。您可以通過 ugopalak@in.ibm.com 與 Shreevidya Rao 聯系。