SOAP對于Java開發(fā)者來說尤其重要，因為它讓平臺無關(guān)和可移植的Java程序更容易協(xié)同操作，使得Java的寶貴特性進一步增值。事實上，如果Java 2平臺企業(yè)版(J2EE)的下一個版本讓SOAP成為一種必須遵循的有線協(xié)議，規(guī)定所有遵從J2EE規(guī)范的應(yīng)用服務(wù)器都必須支持SOAP協(xié)議，我也不會感到奇怪。不過就現(xiàn)在來說，我想我的猜想應(yīng)該暫停了。

　　這個系列的文章總共四篇，這是第二篇。在這里，我要介紹的是Apache SOAP實現(xiàn)。

　　一、Apache SOAP概述

　　Apache SOAP，即Apache Software Foundation對SOAP規(guī)范的實現(xiàn)，建立在IBM的SOAP4J的基礎(chǔ)上。和所有其他Apache工程類似，Apache SOAP源代碼開放，按照Apache許可協(xié)議發(fā)行。我覺得這是當前最好的SOAP實現(xiàn)之一。然而，雖然Apache SOAP遵從SOAP規(guī)范1.1版本，但它缺乏SOAP 1.1所包含的某些功能。

　　1.1、下載和安裝Apache SOAP

　　如前所述，Apache SOAP可以免費下載(參見“參考資源”中提供的下載鏈接)。我為我的Windows NT便攜機下載了soap-bin-2.0.zip文件，該文件包含Apache SOAP 2.0，這是寫作本文時的最新版本。安裝Apache SOAP可謂輕而易舉，共包含如下三個簡單的步驟:

　　1. 解開下載所得文件的ZIP壓縮:解開壓縮之后就得到了一個soap-2_0子目錄。我把ZIP文件的內(nèi)容解壓縮到E盤的根目錄下，因此有了一個包含Apache SOAP的E:\soap-2_0目錄。

　　2. 配置Web環(huán)境:要有一個支持Servlet和JSP的Web服務(wù)器。至此，你可能遇到下面兩種情況之一:

　　o 情況1:已經(jīng)有一個支持Servlet和JSP的Web服務(wù)器，而且你覺得配置這個服務(wù)器沒有問題。在這種情況下，請配置服務(wù)器，使得瀏覽器可以訪問http://localhost:8080/apache-soap/，打開soap-2_0 \webapps\soap\目錄下面的index.html文件。
　　o 情況2:沒有支持Servlet和JSP的Web服務(wù)器，或者雖然有這樣一個服務(wù)器，卻不想拿它做試驗。在這種情況下，我建議你下載Tomcat的最新版本（寫作本文時，最新版本是3.1）（參見“參考資源”中的鏈接）。Tomcat是Apache創(chuàng)建和免費提供給軟件開發(fā)者的又一個優(yōu)秀軟件。下載合適的ZIP文件之后（jakarta-tomcat-3.1.1.zip），解開壓縮時創(chuàng)建一個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>
　　o 在Context元素的docBase屬性中，你應(yīng)該在指定soap-2_0目錄時把E:替換成合適的盤符。要啟動Tomcat，執(zhí)行startup.bat(對于Unix，執(zhí)行startup.sh)。要關(guān)閉Tomcat，執(zhí)行shutdown.bat(對于Unix，執(zhí)行shutdown.sh)。但請稍等——現(xiàn)在請不要啟動Tomcat。

　　3. 設(shè)置Web服務(wù)器classpath:Apache SOAP要求有1.1.2版本或更高的Apache Xerces(Java)，它支持DOM(文檔對象模型)Level 2規(guī)范，支持名稱空間。我使用1.2版本的Xerces，即Apache網(wǎng)站的Xerces-J-bin.1.2.0.zip。解開這個壓縮文件，得到xerces-1_2_0子目錄。和前面一樣，我把解壓縮得到的文件放到了E:盤的根目錄之下。你應(yīng)該配置Web服務(wù)器，使它能夠用xerces.jar(它在xerces-1_2_0子目錄下)進行所有XML解析——而不是用服務(wù)器附帶的庫或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，也必須配置服務(wù)器，使它能夠使用xerces.jar。

　　現(xiàn)在，啟動Web服務(wù)器，用瀏覽器打開http://localhost:8080/apache-soap/admin，驗證安裝是否成功。這時，你應(yīng)該看到所示的管理屏幕。

　　二、實例:HelloWorld

　　現(xiàn)在你已經(jīng)設(shè)置好了Apache SOAP，我們來實際使用一下，構(gòu)造一個簡單的HelloWorld應(yīng)用。在SOAP術(shù)語中，應(yīng)用稱為服務(wù)。一般地，創(chuàng)建服務(wù)分兩個步驟，這兩個步驟可能由同一個人或組織實施，也可能不是。第一個步驟是在選定的語言中定義和實現(xiàn)服務(wù)本身，這里我們選擇Java語言。第二個步驟是創(chuàng)建實際調(diào)用服務(wù)的客戶程序。首先我們來看HelloWorld服務(wù)。

　　2.1、HelloWorld服務(wù)

　　我在第一篇文章中討論了一個用SOAP實現(xiàn)的HelloWorld服務(wù)實例。這個服務(wù)要求輸入一個用戶名字，返回一個定制的Hello消息給調(diào)用者。下面的代碼顯示了HelloWorld服務(wù)的完整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使創(chuàng)建服務(wù)變得極其簡單。服務(wù)主要由業(yè)務(wù)邏輯構(gòu)成，不管服務(wù)以哪種方式提供給外界使用，業(yè)務(wù)邏輯代碼都是必須編寫的。換句話說，服務(wù)不會和任何SOAP相關(guān)的代碼混合，因為Apache SOAP底層體系——它由rpcrouter Servlet和soap.jar構(gòu)成——幫助我們完成了所有錯綜復(fù)雜的工作。我們來簡要地探討一下這些錯綜復(fù)雜的工作究竟包含些什么，例如，Apache SOAP如何處理HTTP上的遠程過程調(diào)用(RPC)請求?理解這一點將給創(chuàng)建客戶程序帶來方便(不錯，是客戶程序)。

　　在Apache SOAP中，org.apache.soap.rpc包支持在SOAP上進行RPC調(diào)用。Apache RPC支持的關(guān)鍵在于對象ID。所有的Apache SOAP服務(wù)必須有一個唯一的ID，它被視為服務(wù)的對象ID。眾所周知，唯一性是一個相對的概念;在Apache SOAP中，對象ID的唯一性相對于服務(wù)所部署的Apache SOAP服務(wù)器而言。也就是說，部署在不同Apache SOAP服務(wù)器上的兩個服務(wù)可能有同樣的對象ID。

　　想要使用服務(wù)的客戶程序設(shè)置一個org.apache.soap.rpc.Call對象，指定目標服務(wù)的對象ID、待調(diào)用方法的名字以及提供給方法的參數(shù)(如果有的話)。設(shè)置好Call對象之后，客戶程序調(diào)用它的invoke()方法。invoke()方法需要兩個參數(shù)，第一個參數(shù)是一個執(zhí)行rpcrouter Servlet的URL，如http://localhost:8080/apache-soap/servlet/rpcrouter;第二個參數(shù)是SOAPAction頭(請參考本系列的第一篇文章，了解SOAPAction頭的重要性和可能的取值)。

　　invoke()方法把Call對象轉(zhuǎn)換成XML SOAP請求(類似第一篇文章所提供的示例)，把請求發(fā)送給第一個參數(shù)中的URL所指定的rpcrouter Servlet。當Servlet返回應(yīng)答，invoke()方法返回一個org.apache.soap.rpc.Response對象，這個對象包含了服務(wù)的應(yīng)答(如果有的話)或錯誤信息(如果出現(xiàn)了錯誤)。HTTP規(guī)定每一個請求都必須有一個應(yīng)答;因此，即使服務(wù)本身不返回任何東西，rpcrouter Servlet總是會返回一些內(nèi)容。因此，invoke()方法總是返回一個Response對象。

　　在服務(wù)端，Apache SOAP服務(wù)器(也就是rpcrouter Servlet)接收客戶程序發(fā)送的SOAP請求，重新構(gòu)造出Call對象。Servlet使用重新構(gòu)造得到的Call對象中的對象ID在服務(wù)管理器中確定具體的對象。

　　對于Java基本數(shù)據(jù)類型(int，long，double，等等)及其對應(yīng)的對象化形式(Integer，Long，Double，等等)來說，它們的串行化器和反串行化器已經(jīng)預(yù)先在類型映射注冊器中注冊。因此，對于客戶程序來說，用Java基本數(shù)據(jù)類型及其對象形式作為方法參數(shù)是無縫的。然而，如果服務(wù)所要求的參數(shù)是一個JavaBean，則必須手工在類型映射注冊器中注冊BeanSerializer。服務(wù)永遠不會做任何額外的工作，最后客戶程序的負擔總是較多。在這個系列的第四篇文章中，我將介紹用動態(tài)代理構(gòu)造的框架，它將使創(chuàng)建客戶程序和創(chuàng)建服務(wù)程序一樣簡單。

　　2.2、部署HelloWorld服務(wù)

　　部署Apache SOAP服務(wù)有兩種方法:使用Web界面的管理工具，或通過命令行進行部署。所有這兩種方法都可以部署服務(wù)，使服務(wù)可被客戶程序訪問。

　　■ 使用管理工具部署服務(wù)

　　要使用管理工具，用瀏覽器打開http://localhost:8080/apache-soap/admin。瀏覽器將顯示出圖一所示的界面。點擊窗口左邊的Deploy按鈕，一個帶有許多輸入框的窗口就會出現(xiàn)。并非所有的輸入框現(xiàn)在都要用到。我將在用到這些輸入框的時候介紹它們的含義。由于本文無需用到所有的輸入框，所以我們將忽略部分輸入框的含義。但不用擔心，到第三篇文章結(jié)束時，我將介紹完所有的輸入框。

　　ID輸入框用來設(shè)置對象ID;如前所述，SOAP基礎(chǔ)設(shè)施利用對象ID把RPC請求綁定到SOAP服務(wù)。我在前面已經(jīng)提到，所有Apache SOAP服務(wù)必須有一個對象ID，這個對象ID在該服務(wù)器上部署的所有服務(wù)之間唯一。我通常使用“urn:<UniqueServiceID>”格式，其中UniqueServiceID是服務(wù)的唯一對象ID。在本例中，把ID設(shè)置成“urn:hello”。

　　Scope輸入框用來定義響應(yīng)調(diào)用請求的服務(wù)實例的生存范圍和時間。Scope可以是下列值之一:

　　· page:服務(wù)實例一直有效，直至應(yīng)答發(fā)送完畢或把請求傳遞給了另一個頁面——如果使用標準的部署機制，向前傳遞請求不太可能發(fā)生。
　　· request:服務(wù)實例在請求處理期間一直有效，不管是否出現(xiàn)請求傳遞。
　　· session:服務(wù)實例對于整個會話都有效。
　　· application:服務(wù)實例被用于所有對服務(wù)的調(diào)用請求。

　　Scope的值對安全有著重要的影響，記住這一點很重要。page和request值確保了連續(xù)調(diào)用之間的隔離。在另一個極端，application值意味著所有SOAP的用戶共享服務(wù)實例。細心的讀者可能已經(jīng)注意到，JSP的標記同樣要用到這些值。事實上，rpcrouter Servlet曾經(jīng)就是一個JSP頁面，這也許是這些值被選用的原因。在本例中，我們把Scope的值設(shè)置成application。

　　在Methods輸入框中，輸入用空白字符分隔的方法名字，這些方法名字指示出當前部署的服務(wù)上允許調(diào)用的方法。我們的服務(wù)示例只支持一個方法，即sayHelloTo()。

　　把Provider Type設(shè)置成Java。它意味著服務(wù)用Java實現(xiàn)，而且你必須為Apache SOAP提供服務(wù)完整的類名。這個任務(wù)在Provider Class輸入框完成，我們把它設(shè)置成hello.HelloServer。由于sayHelloTo()方法不是靜態(tài)的，保持Static輸入框原來的值，即no。

　　部署服務(wù)除了可以用Web界面的管理工具，還可以用命令行Java工具org.apache.soap.server.ServiceManagerClient，它是一個Apache SOAP附帶的類。這個類要求有兩個必不可少的參數(shù)，一個指向Apache SOAP路由Servlet(即rpcrouter)的URL，以及一個動作。這個動作可以是以下四者之一:deploy，undeploy，list，或query。根據(jù)指定動作的不同，有時候還要提供額外的參數(shù)。例如，如果動作是deploy，則必須提供XML部署描述器文件的名字。部署描述器文件應(yīng)該包含Apache SOAP服務(wù)器成功部署服務(wù)所需要的全部信息。例如，描述HelloWorld部署細節(jié)的部署XML文件可以如下:

<isd:service xmlns:isd="http://xml./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服務(wù):

java org.apache.soap.server.ServiceManagerClient
http://localhost:8080/apache-soap/servlet/rpcrouter
deploy DeploymentDescriptor.xml

　　DeploymentDescriptor.xml是上面顯示的描述部署信息的XML文件名字。要驗證服務(wù)是否部署成功，輸入以下命令:

java org.apache.soap.server.ServiceManagerClient
http://localhost:8080/apache-soap/servlet/rpcrouter query urn:Hello

　　這時，我們應(yīng)該看到和DeploymentDescriptor.xml文件內(nèi)一樣的XML。

　　2.3、HelloWorld客戶程序

　　編寫客戶程序要比編寫HelloWorld服務(wù)復(fù)雜得多。不過，你應(yīng)該不會對此感到奇怪，因為前面已經(jīng)提到，客戶程序(至少)必須負責設(shè)置Call對象，這需要不少工作。順便說一下，本系列文章的第四篇將介紹一個框架，這個框架以Java 2 1.3版新引入的動態(tài)代理類為基礎(chǔ)，使創(chuàng)建客戶程序和創(chuàng)建服務(wù)一樣簡單。

　　Listing 1顯示了完整的客戶程序。接下來我們一步一步地仔細看看這個程序。這個程序需要一個必不可少的參數(shù):程序要向他說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];
}
// 構(gòu)造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);
// 發(fā)出調(diào)用
Response resp = null;
try
{
resp = call.invoke(url, "");
}
catch( SOAPException e )
{
System.err.println("Caught SOAPException (" + e.getFaultCode() + "): " +
e.getMessage());
System.exit(-1);
}

　　· 被調(diào)用服務(wù)的對象ID，它通過Call對象的setTargetObjectURI()方法設(shè)置。本例的對象ID是urn:Hello。
　　· 待調(diào)用方法的名字，它通過Call對象的setMethodName()方法設(shè)置。本例的方法名字是sayHelloTo()。
　　· 參數(shù)的編碼方式，它通過Call對象的setEncodingStyleURI()方法設(shè)置。本例我們使用標準的SOAP編碼方式，這種編碼方式由名稱空間http://schemas./soap/encoding/定義。
　　· 方法調(diào)用的參數(shù)通過Call對象的setParams()方法設(shè)置。setParams()方法的參數(shù)是一個Java Vector(向量)。這個向量包含所有的參數(shù)，向量中索引為0的參數(shù)是被調(diào)用方法從左邊數(shù)起的第一個參數(shù)，索引為1的參數(shù)是被調(diào)用方法從左邊數(shù)起的第二個參數(shù)，依此類推。向量中的每一個元素都是一個org.apache.soap.rpc.Parameter的實例。Parameter構(gòu)造函數(shù)要求指定參數(shù)的名字、Java類型和值，還有一個可選的編碼方式。如果指定了null編碼方式(正如本例所做的那樣)，則默認使用Call對象的編碼方式。雖然每一個參數(shù)對應(yīng)著一個名字，但這個名字可以設(shè)置成任何內(nèi)容，Apache SOAP服務(wù)器調(diào)用方法時不會用到這個名字。因此，絕對有必要讓向量中參數(shù)的次序和被調(diào)用方法的參數(shù)次序一致。

　　下面的代碼片斷顯示了客戶程序創(chuàng)建Call對象的過程:

// 構(gòu)造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);

　　現(xiàn)在，該是實際調(diào)用HelloWorld遠程服務(wù)所提供方法的時候了。為此，客戶程序調(diào)用了Call對象的invoke()方法，這個方法返回一個org.apache.soap.rpc.Response對象，如下所示:

// 發(fā)出調(diào)用
Response resp = null;
try
{
resp = call.invoke(url, "");
}
catch( SOAPException e )
{
System.err.println("Caught SOAPException (" + e.getFaultCode() + "): " +
e.getMessage());
System.exit(-1);
}

　　接下來，客戶程序檢查Response對象。如果方法調(diào)用過程中出現(xiàn)了錯誤，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());

　　如果方法調(diào)用成功，則客戶程序提取并顯示Hello信息:

　　如前所述，Apache SOAP提供了許多預(yù)先構(gòu)造的串行化和反串行化方法，其中包括為利用Java Vector、Enumeration、數(shù)組、JavaBean作為參數(shù)和返回值而提供的串行化器和反串行化器。在這一部分，我將修改HelloWorld服務(wù)，通過一個JavaBean傳入接收Hello信息的用戶名。

　　3.1、HelloWorld服務(wù)

　　改寫后的HelloWorld服務(wù)完整代碼如下:

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?";
}
}

　　服務(wù)的代碼仍舊很簡單，仍舊類似于不用JavaBean時的HelloWorld服務(wù)。不過，這意味著最復(fù)雜的工作都轉(zhuǎn)移到了客戶端。事實上，這個版本的服務(wù)與以前版本的唯一差別在于，現(xiàn)在出現(xiàn)了一個重載的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、部署服務(wù)

　　部署一個使用了JavaBean的服務(wù)時，需要為Apache SOAP服務(wù)器提供一些額外的信息。因此，現(xiàn)在部署服務(wù)的過程稍微復(fù)雜一點。

　　使用管理工具部署服務(wù)