SOAP（簡單對象訪問協議）是一種利用XML編碼數據的有線協議。它是同類協議中要求最低的一個規范，只定義了有線協議所要求的最關鍵的部分，有意地忽略了垃圾收集、對象激活等方面的細節。
SOAP對于Java開發者來說尤其重要，因為它讓平臺無關和可移植的Java程序更容易協同操作，使得Java的寶貴特性進一步增值。事實上，如果Java 2平臺企業版（J2EE）的下一個版本讓SOAP成為一種必須遵循的有線協議，規定所有遵從J2EE規范的應用服務器都必須支持SOAP協議，我也不會感到奇怪。不過就現在來說，我想我的猜想應該暫停了。
這個系列的文章總共四篇，這是第二篇。在這里，我要介紹的是Apache SOAP實現。
一、Apache SOAP概述
Apache SOAP，即Apache Software Foundation對SOAP規范的實現，建立在IBM的SOAP4J的基礎上。和所有其他Apache工程類似，Apache SOAP源代碼開放，按照Apache許可協議發行。我覺得這是當前最好的SOAP實現之一。然而，雖然Apache SOAP遵從SOAP規范1.1版本，但它缺乏SOAP 1.1所包含的某些功能（參見本文最后的“參考資源”，了解Apache SOAP支持功能的清單）。
1.1、下載和安裝Apache SOAP
如前所述，Apache SOAP可以免費下載（參見“參考資源”中提供的下載鏈接）。我為我的Windows NT便攜機下載了soap-bin-2.0.zip文件，該文件包含Apache SOAP 2.0，這是寫作本文時的最新版本。安裝Apache SOAP可謂輕而易舉，共包含如下三個簡單的步驟：
- 解開下載所得文件的ZIP壓縮：解開壓縮之后就得到了一個soap-2_0子目錄。我把ZIP文件的內容解壓縮到E盤的根目錄下，因此有了一個包含Apache SOAP的E:\soap-2_0目錄。
- 配置Web環境：要有一個支持Servlet和JSP的Web服務器。至此，你可能遇到下面兩種情況之一：
- 情況1：已經有一個支持Servlet和JSP的Web服務器，而且你覺得配置這個服務器沒有問題。在這種情況下，請配置服務器，使得瀏覽器可以訪問http://localhost:8080/apache-soap/，打開soap-2_0 \webapps\soap\目錄下面的index.html文件。
- 情況2：沒有支持Servlet和JSP的Web服務器，或者雖然有這樣一個服務器，卻不想拿它做試驗。在這種情況下，我建議你下載Tomcat的最新版本（寫作本文時，最新版本是3.1）（參見“參考資源”中的鏈接）。Tomcat是Apache創建和免費提供給軟件開發者的又一個優秀軟件。下載合適的ZIP文件之后（jakarta-tomcat-3.1.1.zip），解開壓縮時創建一個jakarta-tomcat子目錄。和前面相似，我把解壓縮得到的文件放入E盤的根目錄之下。在jakarta-tomcat\conf\server.xml配置文件中增加一個新的<Context>標記，如下所示：
<Context path="/apache-soap" docBase="E:/soap-2_0/webapps/soap"
debug="1" reloadable="true">
</Context> |
在Context元素的docBase屬性中，你應該在指定soap-2_0目錄時把E:替換成合適的盤符。要啟動Tomcat，執行startup.bat（對于Unix，執行startup.sh）。要關閉Tomcat，執行shutdown.bat（對于Unix，執行shutdown.sh）。但請稍等——現在請不要啟動Tomcat。
- 設置Web服務器classpath：Apache SOAP要求有1.1.2版本或更高的Apache Xerces（Java），它支持DOM（文檔對象模型）Level 2規范，支持名稱空間。我使用1.2版本的Xerces，即Apache網站的Xerces-J-bin.1.2.0.zip。解開這個壓縮文件，得到xerces-1_2_0子目錄。和前面一樣，我把解壓縮得到的文件放到了E:盤的根目錄之下。你應該配置Web服務器，使它能夠用xerces.jar（它在xerces-1_2_0子目錄下）進行所有XML解析——而不是用服務器附帶的庫或jar解析XML。例如，Tomcat附帶了一個XML解析器（jakarta-tomcat\lib\xml.jar），支持DOM Level 1接口。即使你把xerces.jar放入了classpath，Tomcat下運行的Java代碼也可能找錯接口，因為在用來啟動Tomcat的Shell腳本/批命令文件中，xerces.jar被放到了classpath的最后。因此，必須編輯jakarta-tomcat\bin目錄下的tomcat.bat（對于Unix，則是tomcat.sh），把xerces.jar放到classpath的前面。下面是我在jakarta-tomcat\bin\tomcat.bat文件中所作的修改：
| set CLASSPATH=E:\xerces-1_2_0\xerces.jar;%CLASSPATH%;%cp% |
如果你在第二個步驟中屬于情況2，也必須配置服務器，使它能夠使用xerces.jar。
不管你屬于哪一種情況，除了配置xerces.jar之外，你還必須配置Web服務器的classpath使它能夠使用soap-2_0\lib\目錄下的soap.jar。
1.2、檢查安裝是否成功
現在，啟動Web服務器，用瀏覽器打開http://localhost:8080/apache-soap/admin，驗證安裝是否成功。這時，你應該看到下圖所示的管理屏幕。
圖一：Web界面的Apache SOAP管理工具
現在你已經設置好了Apache SOAP，我們來實際使用一下，構造一個簡單的HelloWorld應用。在SOAP術語中，應用稱為服務。一般地，創建服務分兩個步驟，這兩個步驟可能由同一個人或組織實施，也可能不是。第一個步驟是在選定的語言中定義和實現服務本身，這里我們選擇Java語言。第二個步驟是創建實際調用服務的客戶程序。首先我們來看HelloWorld服務。
2.1、HelloWorld服務
我在第一篇文章中討論了一個用SOAP實現的HelloWorld服務實例。這個服務要求輸入一個用戶名字，返回一個定制的Hello消息給調用者。下面的代碼顯示了HelloWorld服務的完整Java代碼。
|
package hello;
public class HelloServer
{
public String sayHelloTo(String name)
{
System.out.println("sayHelloTo(String name)");
return "Hello " + name + ", How are you doing?";
}
}
|
這就是全部的代碼嗎？如果這是真的話，實在太簡單了！
Apache SOAP使創建服務變得極其簡單。服務主要由業務邏輯構成，不管服務以哪種方式提供給外界使用，業務邏輯代碼都是必須編寫的。換句話說，服務不會和任何SOAP相關的代碼混合，因為Apache SOAP底層體系——它由rpcrouter Servlet和soap.jar構成——幫助我們完成了所有錯綜復雜的工作。我們來簡要地探討一下這些錯綜復雜的工作究竟包含些什么，例如，Apache SOAP如何處理HTTP上的遠程過程調用（RPC）請求？理解這一點將給創建客戶程序帶來方便（不錯，是客戶程序）。
在Apache SOAP中，org.apache.soap.rpc包支持在SOAP上進行RPC調用。Apache RPC支持的關鍵在于對象ID。所有的Apache SOAP服務必須有一個唯一的ID，它被視為服務的對象ID。眾所周知，唯一性是一個相對的概念；在Apache SOAP中，對象ID的唯一性相對于服務所部署的Apache SOAP服務器而言。也就是說，部署在不同Apache SOAP服務器上的兩個服務可能有同樣的對象ID。
想要使用服務的客戶程序設置一個org.apache.soap.rpc.Call對象，指定目標服務的對象ID、待調用方法的名字以及提供給方法的參數（如果有的話）。設置好Call對象之后，客戶程序調用它的invoke()方法。invoke()方法需要兩個參數，第一個參數是一個執行rpcrouter Servlet的URL，如http://localhost:8080/apache-soap/servlet/rpcrouter；第二個參數是SOAPAction頭（請參考本系列的第一篇文章，了解SOAPAction頭的重要性和可能的取值）。
invoke()方法把Call對象轉換成XML SOAP請求（類似第一篇文章所提供的示例），把請求發送給第一個參數中的URL所指定的rpcrouter Servlet。當Servlet返回應答，invoke()方法返回一個org.apache.soap.rpc.Response對象，這個對象包含了服務的應答（如果有的話）或錯誤信息（如果出現了錯誤）。HTTP規定每一個請求都必須有一個應答；因此，即使服務本身不返回任何東西，rpcrouter Servlet總是會返回一些內容。因此，invoke()方法總是返回一個Response對象。
在服務端，Apache SOAP服務器（也就是rpcrouter Servlet）接收客戶程序發送的SOAP請求，重新構造出Call對象。Servlet使用重新構造得到的Call對象中的對象ID在服務管理器中確定具體的對象。
接下來，Servlet在已經確定的對象上檢驗被調用方法的名字并調用方法。完成后，Servlet串行化該調用的返回值，在HTTP應答中把它發送給客戶程序。
從上述討論中，我們可以發現一個有趣的問題：Apache SOAP如何知道串行化某種給定數據類型的方法？Apache SOAP通過一個類型注冊器（org.apache.soap.encoding.SOAPMappingRegistry），以及通過所有裝配器（marshaller）和反裝配器（marshaller）分別必須實現的串行化（org.apache.soap.util.xml.Serializer）和反串行化（org.apache.soap.util.xml.Deserialization）接口，實現Java數據類型和XML之間的裝配和反裝配。Apache SOAP提供了許多實現這些接口的內建的裝配器和反裝配器。例如，我們可以用org.apache.soap.encoding.soapenc.BeanSerializer類裝配和反裝配JavaBean。本文后面我將介紹如何使用這個類。
對于Java基本數據類型（int，long，double，等等）及其對應的對象化形式（Integer，Long，Double，等等）來說，它們的串行化器和反串行化器已經預先在類型映射注冊器中注冊。因此，對于客戶程序來說，用Java基本數據類型及其對象形式作為方法參數是無縫的。然而，如果服務所要求的參數是一個JavaBean，則必須手工在類型映射注冊器中注冊BeanSerializer。服務永遠不會做任何額外的工作，最后客戶程序的負擔總是較多。在這個系列的第四篇文章中，我將介紹用動態代理構造的框架，它將使創建客戶程序和創建服務程序一樣簡單。
2.2、部署HelloWorld服務
部署Apache SOAP服務有兩種方法：使用Web界面的管理工具，或通過命令行進行部署。所有這兩種方法都可以部署服務，使服務可被客戶程序訪問。
■ 使用管理工具部署服務
要使用管理工具，用瀏覽器打開http://localhost:8080/apache-soap/admin。瀏覽器將顯示出圖一所示的界面。點擊窗口左邊的Deploy按鈕，一個帶有許多輸入框的窗口就會出現。并非所有的輸入框現在都要用到。我將在用到這些輸入框的時候介紹它們的含義。由于本文無需用到所有的輸入框，所以我們將忽略部分輸入框的含義。但不用擔心，到第三篇文章結束時，我將介紹完所有的輸入框。
ID輸入框用來設置對象ID；如前所述，SOAP基礎設施利用對象ID把RPC請求綁定到SOAP服務。我在前面已經提到，所有Apache SOAP服務必須有一個對象ID，這個對象ID在該服務器上部署的所有服務之間唯一。我通常使用“urn:<UniqueServiceID>”格式，其中UniqueServiceID是服務的唯一對象ID。在本例中，把ID設置成“urn:hello”。
Scope輸入框用來定義響應調用請求的服務實例的生存范圍和時間。Scope可以是下列值之一：
page：服務實例一直有效，直至應答發送完畢或把請求傳遞給了另一個頁面——如果使用標準的部署機制，向前傳遞請求不太可能發生。
request：服務實例在請求處理期間一直有效，不管是否出現請求傳遞。
session：服務實例對于整個會話都有效。
application：服務實例被用于所有對服務的調用請求。
Scope的值對安全有著重要的影響，記住這一點很重要。page和request值確保了連續調用之間的隔離。在另一個極端，application值意味著所有SOAP的用戶共享服務實例。細心的讀者可能已經注意到，JSP的<jsp:useBean>標記同樣要用到這些值。事實上，rpcrouter Servlet曾經就是一個JSP頁面，這也許是這些值被選用的原因。在本例中，我們把Scope的值設置成application。
在Methods輸入框中，輸入用空白字符分隔的方法名字，這些方法名字指示出當前部署的服務上允許調用的方法。我們的服務示例只支持一個方法，即sayHelloTo()。
把Provider Type設置成Java。它意味著服務用Java實現，而且你必須為Apache SOAP提供服務完整的類名。這個任務在Provider Class輸入框完成，我們把它設置成hello.HelloServer。由于sayHelloTo()方法不是靜態的，保持Static輸入框原來的值，即no。
現在滾動到頁面的下方，點擊表單下面的Deploy按鈕（不是左邊的Deploy按鈕）。要驗證服務已經部署完畢，點擊左邊的List按鈕，這時列表所顯示的服務中應該包含一個urn:Hello服務。
■ 從命令行部署服務
部署服務除了可以用Web界面的管理工具，還可以用命令行Java工具org.apache.soap.server.ServiceManagerClient，它是一個Apache SOAP附帶的類。這個類要求有兩個必不可少的參數，一個指向Apache SOAP路由Servlet（即rpcrouter）的URL，以及一個動作。這個動作可以是以下四者之一：deploy，undeploy，list，或query。根據指定動作的不同，有時候還要提供額外的參數。例如，如果動作是deploy，則必須提供XML部署描述器文件的名字。部署描述器文件應該包含Apache SOAP服務器成功部署服務所需要的全部信息。例如，描述HelloWorld部署細節的部署XML文件可以如下：
|
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
id="urn:Hello">
<isd:provider type="java" scope="Application" methods="sayHelloTo">
<isd:java class="hello.HelloServer" static="false"/>
</isd:provider>
</isd:service>
|
上述XML代碼所包含的信息和我們在Web界面的管理工具中所輸入的信息一樣。接下來，輸入下面的命令，從命令行部署HelloWorld服務：
|
java org.apache.soap.server.ServiceManagerClient
http://localhost:8080/apache-soap/servlet/rpcrouter
deploy DeploymentDescriptor.xml
|
DeploymentDescriptor.xml是上面顯示的描述部署信息的XML文件名字。要驗證服務是否部署成功，輸入以下命令：
|
java org.apache.soap.server.ServiceManagerClient
http://localhost:8080/apache-soap/servlet/rpcrouter query urn:Hello
|
這時，我們應該看到和DeploymentDescriptor.xml文件內一樣的XML。
2.3、HelloWorld客戶程序
編寫客戶程序要比編寫HelloWorld服務復雜得多。不過，你應該不會對此感到奇怪，因為前面已經提到，客戶程序（至少）必須負責設置Call對象，這需要不少工作。順便說一下，本系列文章的第四篇將介紹一個框架，這個框架以Java 2 1.3版新引入的動態代理類為基礎，使創建客戶程序和創建服務一樣簡單。
Listing 1顯示了完整的客戶程序。接下來我們一步一步地仔細看看這個程序。這個程序需要一個必不可少的參數：程序要向他說Hello信息的用戶名字。
|
Listing 1: Client.java
package hello;
import java.net.URL;
import java.util.Vector;
import org.apache.soap.SOAPException;
import org.apache.soap.Constants;
import org.apache.soap.Fault;
import org.apache.soap.rpc.Call;
import org.apache.soap.rpc.Parameter;
import org.apache.soap.rpc.Response;
public class Client
{
public static void main(String[] args) throws Exception
{
if(args.length == 0)
{
System.err.println("Usage: java hello.Client [SOAP-router-URL] ");
System.exit (1);
}
try
{
URL url = null;
String name = null;
if(args.length == 2)
{
url = new URL(args[0]);
name = args[1];
}
else
{
url = new URL("http://localhost:8080/apache-soap/servlet/rpcrouter");
name = args[0];
}
// 構造Call對象
Call call = new Call();
call.setTargetObjectURI("urn:Hello");
call.setMethodName("sayHelloTo");
call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);
Vector params = new Vector();
params.addElement(new Parameter("name", String.class, name, null));
call.setParams(params);
// 發出調用
Response resp = null;
try
{
resp = call.invoke(url, "");
}
catch( SOAPException e )
{
System.err.println("Caught SOAPException (" + e.getFaultCode() + "): " +
e.getMessage());
System.exit(-1);
}
// 檢查應答
if( !resp.generatedFault() )
{
Parameter ret = resp.getReturnValue();
Object value = ret.getValue();
System.out.println(value);
}
else
{
Fault fault = resp.getFault();
System.err.println("Generated fault: ");
System.out.println (" Fault Code = " + fault.getFaultCode());
System.out.println (" Fault String = " + fault.getFaultString());
}
}
catch(Exception e)
{
e.printStackTrace();
}
}
}
|
客戶程序首先設置Call對象，它需要如下信息：
被調用服務的對象ID，它通過Call對象的setTargetObjectURI()方法設置。本例的對象ID是urn:Hello。
待調用方法的名字，它通過Call對象的setMethodName()方法設置。本例的方法名字是sayHelloTo()。
參數的編碼方式，它通過Call對象的setEncodingStyleURI()方法設置。本例我們使用標準的SOAP編碼方式，這種編碼方式由名稱空間http://schemas.xmlsoap.org/soap/encoding/定義。
方法調用的參數通過Call對象的setParams()方法設置。setParams()方法的參數是一個Java Vector（向量）。這個向量包含所有的參數，向量中索引為0的參數是被調用方法從左邊數起的第一個參數，索引為1的參數是被調用方法從左邊數起的第二個參數，依此類推。向量中的每一個元素都是一個org.apache.soap.rpc.Parameter的實例。Parameter構造函數要求指定參數的名字、Java類型和值，還有一個可選的編碼方式。如果指定了null編碼方式（正如本例所做的那樣），則默認使用Call對象的編碼方式。雖然每一個參數對應著一個名字，但這個名字可以設置成任何內容，Apache SOAP服務器調用方法時不會用到這個名字。因此，絕對有必要讓向量中參數的次序和被調用方法的參數次序一致。
下面的代碼片斷顯示了客戶程序創建Call對象的過程：
|
// 構造Call對象
Call call = new Call();
call.setTargetObjectURI("urn:Hello");
call.setMethodName("sayHelloTo");
call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);
Vector params = new Vector();
params.addElement(new Parameter("name", String.class, name, null));
call.setParams(params);
|
現在，該是實際調用HelloWorld遠程服務所提供方法的時候了。為此，客戶程序調用了Call對象的invoke()方法，這個方法返回一個org.apache.soap.rpc.Response對象，如下所示：
|
// 發出調用
Response resp = null;
try
{
resp = call.invoke(url, "");
}
catch( SOAPException e )
{
System.err.println("Caught SOAPException (" + e.getFaultCode() + "): " +
e.getMessage());
System.exit(-1);
}
|
接下來，客戶程序檢查Response對象。如果方法調用過程中出現了錯誤，generateFault()方法返回一個true值，客戶程序提取并顯示實際的錯誤信息：
|
Fault fault = resp.getFault();
System.err.println("Generated fault: ");
System.out.println (" Fault Code = " + fault.getFaultCode());
System.out.println (" Fault String = " + fault.getFaultString());
|
如果方法調用成功，則客戶程序提取并顯示Hello信息：
|
// 檢查應答
if( !resp.generatedFault() )
{
Parameter ret = resp.getReturnValue();
Object value = ret.getValue();
System.out.println(value);
}
|
三、帶有JavaBean的HelloWorld實例
如前所述，Apache SOAP提供了許多預先構造的串行化和反串行化方法，其中包括為利用Java Vector、Enumeration、數組、JavaBean作為參數和返回值而提供的串行化器和反串行化器。在這一部分，我將修改HelloWorld服務，通過一個JavaBean傳入接收Hello信息的用戶名。
3.1、HelloWorld服務
改寫后的HelloWorld服務完整代碼如下：
|
package hello;
public class HelloServer
{
public String sayHelloTo(String name)
{
System.out.println("sayHelloTo(String name)");
return "Hello " + name + ", How are you doing?";
}
public String sayHelloTo(Name theName)
{
System.out.println("sayHelloTo(Name theName)");
return "Hello " + theName.getName() + ", How are you doing?";
}
}
|
服務的代碼仍舊很簡單，仍舊類似于不用JavaBean時的HelloWorld服務。不過，這意味著最復雜的工作都轉移到了客戶端。事實上，這個版本的服務與以前版本的唯一差別在于，現在出現了一個重載的sayHelloTo()方法。上面的代碼中重載后的方法用粗體字顯示。
重載的方法需要一個對Name JavaBean的引用。Name JavaBean的定義如下：
|
package hello;
public class Name
{
private String name;
public String getName()
{
return name;
}
public void setName(String name)
{
this.name = name;
}
}
|
3.2、部署服務
部署一個使用了JavaBean的服務時，需要為Apache SOAP服務器提供一些額外的信息。因此，現在部署服務的過程稍微復雜一點。
■ 使用管理工具部署服務
要使用管理工具部署這個新版的HelloWorld服務，首先按照前面所介紹的步驟進行，但這一次不要點擊Deploy按鈕。現在，在Number of Mappings輸入框輸入1，它表示我們將給出一個映射（即Name JavaBean）的信息。緊接Mappings之下有一個表格，我們要用到這個表格的第一行。保留Encoding Style的值為SOAP，把NameSpace URI設置成對象的ID：在本例中，它是urn:Hello。接下來，把Local Part和Java Type輸入框設置成Name JavaBean的完整名字，即hello.Name。最后，把Java to XML Serializer和XML to Java Deserializer輸入框設置成org.apache.soap.encoding.soapenc.BeanSerializer，這是一個實現了Serializer和Deserializer接口的類，用來串行化和反串行化Name JavaBean。如果你用到了更多的JavaBean（比如還有一個Address Bean），則應該在這個表格中輸入其他Bean的信息，同時還應該更新Number of Mappings輸入框的值，使之反映出表格中實際被使用的行數。
■ 從命令行部署服務
要從命令行進行部署，我們只需修改作為命令行參數傳入的XML部署描述器文件。修改后的XML文件如下所示：
|
<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="urn:Hello">
<isd:provider type="java" scope="Application" methods="sayHelloTo">
<isd:java class="hello.HelloServer" static="false"/>
</isd:provider>
<isd:mappings>
<isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:x="urn:Hello" qname="x:hello.Name"
javaType="hello.Name"
java2XMLClassName="org.apache.soap.encoding.soapenc.BeanSerializer"
xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer"/>
</isd:mappings>
</isd:service>
|
正如在前一個例子中，這些XML代碼所包含的信息和通過Web界面的管理工具所提供的信息一樣。
3.3、HelloWorld客戶程序
和第一個例子一樣，客戶程序更復雜，也更令人感興趣。這里我不再仔細分析整個客戶程序，而是介紹兩個客戶程序版本的不同之處。由于調用方法的一個參數（在本例中，它是唯一的參數）是一個JavaBean，所以必須手工設置一個類型映射注冊項。這個任務通過如下步驟完成：先創建org.apache.soap.encoding.SOAPMappingRegistry類的一個實例，然后調用它的mapTypes()方法。正如mapTypes()方法名字所預示的，它用來注冊一個以前未知的類型，比如定制的JavaBean。mapTypes()方法的參數包括要使用的編碼方式、限定的JavaBean名字、類型的完整類名、串行化器和反串行化器。在本例中，執行串行化任務的是標準的Bean串行化器。限定的JavaBean名字包含一個元素的名字，包括它所屬的名稱空間。在本例中，Name JavaBean的限定名字由名稱空間URI（urn:Hello）和本地名字（hello.Name）結合構成。請看下面的代碼片斷：
|
// 創建類型映射注冊器
SOAPMappingRegistry smr = new SOAPMappingRegistry();
BeanSerializer beanSer = new BeanSerializer();
// 映射類型
smr.mapTypes(Constants.NS_URI_SOAP_ENC,
new QName("urn:Hello", "hello.Name"),hello.Name.class, beanSer, beanSer);
|
接下來，客戶程序必須告訴Call對象使用新的注冊器而不是默認的注冊器。為此，我們要調用Call對象的setSOAPMappingRegistry()方法，如下所示：
| call.setSOAPMappingRegistry(smr); |
手工設置好類型映射注冊器之后，接下來還必須為Call對象設置參數。這一步驟可以按前面介紹的方法完成，不同之處在于，現在我們不再用字符串類型的名字作為參數，而是用JavaBean作為參數，如下所示：
|
// 設置調用參數
Vector params = new Vector();
Name theName = new Name();
theName.setName(name);
params.addElement(new Parameter("name", hello.Name.class, theName, null));
call.setParams(params);
|
客戶程序剩下的部分和原來的版本一樣。Listing 3顯示了完整的客戶程序代碼：
|
Listing 3: Client2.java
package hello;
import java.net.URL;
import java.util.Vector;
import org.apache.soap.SOAPException;
import org.apache.soap.Constants;
import org.apache.soap.Fault;
import org.apache.soap.rpc.Call;
import org.apache.soap.rpc.Parameter;
import org.apache.soap.rpc.Response;
import org.apache.soap.encoding.SOAPMappingRegistry;
import org.apache.soap.encoding.soapenc.BeanSerializer;
import org.apache.soap.util.xml.QName;
public class Client2
{
public static void main(String[] args) throws Exception
{
if(args.length == 0)
{
System.err.println("Usage: java hello.Client [SOAP-router-URL] ");
System.exit (1);
}
try
{
URL url = null;
String name = null;
if(args.length == 2)
{
url = new URL(args[0]);
name = args[1];
}
else
{
url = new URL("http://localhost:8080/apache-soap/servlet/rpcrouter");
name = args[0];
}
// 構造調用對象
Call call = new Call();
call.setTargetObjectURI("urn:Hello");
call.setMethodName("sayHelloTo");
call.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);
// 創建類型映射注冊器
SOAPMappingRegistry smr = new SOAPMappingRegistry();
BeanSerializer beanSer = new BeanSerializer();
// 映射類型
smr.mapTypes(Constants.NS_URI_SOAP_ENC,
new QName("urn:Hello", "hello.Name"),
hello.Name.class, beanSer, beanSer);
call.setSOAPMappingRegistry(smr);
// 設置參數
Vector params = new Vector();
Name theName = new Name();
theName.setName(name);
params.addElement(new Parameter("name", hello.Name.class,
theName, null));
call.setParams(params);
// 發出調用
Response resp = null;
try
{
resp = call.invoke(url, "");
}
catch( SOAPException e )
{
System.err.println("Caught SOAPException (" +
e.getFaultCode() + "): " + e.getMessage());
System.exit(-1);
}
// 檢查應答
if( !resp.generatedFault() )
{
Parameter ret = resp.getReturnValue();
Object value = ret.getValue();
System.out.println(value);
}
else
{
Fault fault = resp.getFault();
System.err.println("Generated fault: ");
System.out.println (" Fault Code = " + fault.getFaultCode());
System.out.println (" Fault String = " + fault.getFaultString());
}
}
catch(Exception e)
{
e.printStackTrace();
}
}
}
|
四、編譯和運行程序
現在整個程序的開發工作已經完成，該是運行它的時候了。不過，我們首先要編譯服務程序和客戶程序。
創建一個hello目錄，把Client1.java、Client2.java和HelloServer.java復制到這個目錄。我把hello目錄放到了Apache SOAP的示例目錄（即E:\soap-2_0\samples）之下。編譯程序時，classpath中只需包含hello目錄的父目錄（即E:\soap-2_0\samples）、soap.jar和xerces.jar。我用下面的批命令編譯程序：
|
set CLASSPATH=E:\soap-2_0\samples\;E:\soap-2_0\lib\soap.jar;E:\xerces-1_2_0\xerces.jar
javac -d .. HelloServer.java Client.java Client2.java
|
注意：從hello目錄執行這個批命令文件。
要使用這個服務，除了部署它之外，還需要修改Web服務器的classpath，確保Web服務能夠找到hello.HelloServer類——對于本例，這是指把E:\soap-2_0\samples加入到Web服務器的classpath。對classpath進行必要的修改之后，重新啟動Web服務器。接下來就可以運行客戶程序了。下面是我運行hello.Client的批命令文件：
set CLASSPATH=E:\soap-2_0\samples\;E:\soap-2_0\lib\soap.jar;E:\xerces-1_2_0\xerces.jar
java hello.Client Tarak |
這里的classpath和編譯程序時用的classpath相同。
最后，運行hello.Client2的批命令文件可以如下：
set CLASSPATH=E:\soap-2_0\samples\;E:\soap-2_0\lib\soap.jar;E:\xerces-1_2_0\xerces.jar
java hello.Client2 Tarak |
觀察Web服務器的控制臺窗口，看看在運行兩個不同的客戶程序時，HelloWorld服務的哪些方法正在被調用。
■ 結束語
在這篇文章中，我介紹了如何用Apache SOAP實現來創建簡單的基于SOAP的服務。在SOAP實現方面，另一個重要的競爭者是Microsoft。遺憾的是，“純”Java開發者在使用Microsoft實現的時候會有一段艱苦的時光，因為它的實現包含了COM對象。
在下一篇文章中，我將介紹Apache SOAP支持的另一種創建服務的方式：使用JavaScript之類的腳本語言，而不是Java。另外，我還要介紹一個很不錯的JavaScript引擎，即Rhino。