实例讲解：JAVA SOAP技术

Very Simple Object Access Protocol with JavaBy Olexiy & Alexander Prokhorenko

著名国外开发者网站developer.com在2004年1月15日发表的文章

开始之前，我想就本文即将讨论的主题和读者需要具备的起点知识做一些必需的描叙。本文的主题是讨论SOAP技术，我们将尽可能的讲得通俗易懂一些，所以，我们引入了一个普通的“Hello World”范例来给读者说明它们是怎么运作的，让读者知道它们的运作方式。我认为，如果光看官方文档是很难开始学习这门新技术的，官方文档中包含大量的范例，并解释了所有的特性和优点，但是没解释它们的运作方式。在这篇文章中，我不打算只肤浅的解释SOAP技术的定义，我们假设读者熟悉JAVA语言，Web技术，具有XML语言，XML Namespaces，XML Schema的基础。在这种情况下，理解本文将不存在任何困难。然而，即使没有这些知识，你也不必担心，我们将尽可能的解释得简单，但是当你开始做自己的SOAP应用程序时会遇到一些问题和麻烦。因此，花费一定时间来学习上面的知识是很有必要的。

从技术的角度来说，有必要提一下我们的调试环境。我们使用的是Windows XP操作系统，安装有JAVA 2 SDK 1.4.1，Apache SOAP 2.3.1，JAF 1.0.2，JavaMail 1.3.1和Xerces 2.6.0。上面所提及的都能在Tcomcat 4.1.29 JSP/Servlet容器中正常运行。所有的软件都是免费自由软件，因此你能够很容易的下载它们并自己在任何你喜欢的平台如Windows或Unix上安装它们。Java SDK，JAF和JAVAMAIL位于SUN的官方网站（http://java.sun.com），其他的软件在Jakarta项目组的官方网站（http://jakarta.apache.org）上有down的。可能你在看到我们需要这么多不同的包（package）时已经有点担心和不安了，但是实际上你不应该担心这些的。一旦你懂了基础，那么对你将相当容易。安装不是一件很难的事情，你只需要在设置环境变量的时候仔细些，比如CATALINA_HOME, CLASSPATH, JAVA_HOME 等等，所有这些步骤都是手工的。由于我仅仅是想将你的注意力再次集中到它们身上，所以你能很快的就完成以上配置过程。我只是添加下面的一些字符串到Tomcat的bin/setclasspath.bat文件中：

...
set CATALINA_HOME=C:\Tomcat4.1.29
set CLASSPATH=%JAVA_HOME%\lib\tools.jar
set CLASSPATH=%JAVA_HOME%\soap-2.3.1\lib\soap.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\javamail-1.3.1\mail.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\jaf-1.0.2\activation.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\xerces-2_6_0\xercesImpl.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\xerces-2_6_0\xercesSamples.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\xerces-2_6_0\xml-apis.jar
set CLASSPATH=%CLASSPATH%;%JAVA_HOME%\xerces-2_6_0\xmlParserAPIs.jar
set CLASSPATH=%CLASSPATH%;%CATALINA_HOME%\common\lib\servlet.jar
set CLASSPATH=%CLASSPATH%;%CATALINA_HOME%\common\lib\tools.jar
...

如果你的安装路径（installation paths）和上面使用的不同，你需要更正它们，然后关闭和重启Tomcat以使它们生效。这样，你就有为运行SOAP作好了准备。但是现在，我要忘记有关的技术部分，来学一点理论知识。

SOAP意思是简单对象访问协议（Simple Object Access Protocol）。的确如它的名字一样，SOAP是很简单的。它是一个基于XML的协议，允许程序组件和应用程序彼此使用一种标准的Internet协议--HTTP来通讯。SOAP是一种独立的平台，它不依赖程序语言，它是简单的，弹性的，很容易扩展的。目前，应用程序能够彼此使用一种基于DCOM和CORBA技术的远程过程调用（RPC）来进行相互通讯，但HTTP不被设计为这个目的。RPC在Internet上应用是非常困难的，它们会出现许多兼容性和安全性的问题，因为防火墙和代理服务器通常都会阻断（block）这些类型的流量。应用程序之间最好的通讯方式是通过HTTP协议，因为HTTP是支持所有Internet浏览器和服务器的。基于这个目的，SOAP协议被创建出来。

那么，它们是如何运作的呢？比如，一个应用程序（A）需要和另一个应用程序（B）在SOAP的帮助下进行彼此通讯。它们将使用下面的框架图来完成这个过程：

这个SOAP信封（SOAP envelope）是一个包含以下内容的XML文档：

正如你看到的，它是非常简单的。它看起来确实就象一个普通的信封或者你的email。你想看看它们是如何动作的吗？下面跟我们一起来吧。其实我们有很多方法是不用SOAP来在创建和运行我们自己的“Hello World”应用程序的，但是因为我们要保持它的简单性，我会给你一个它运作方式的框架图（scheme）。

我们的“Hello World”范例会包含一个SOAP Service。我们的SOAP Client将发送它们的名字到该SOAP Service，并试图得到一些答复或响应。这个SOAP Service需要部署到一个SOAP Admin的工具，以至重定位所有请求的SOAP（Proxy） RPC Router能够知道它们应该使用哪种服务来运作。总而言之，这个是以下面的方式来运作的：

Translated by caiyi0903(Willpower),2004.1.17

现在，我们来一步步的看看到底发生了什么。在Step 1里，HelloWorldClient将连接一个SOAP RPC Router，请求我们的SOAP Service并将包含我们名字的一个字符串传递给它。该SOAP RPC Router会检查是否它已经部署了这个SOAP Service。如果它被发现是被部署的，那么它将传递数据到这个SOAP Service并调用特定的方法，这个是Step 2。然后SOAP Service方法会被执行，将返回某个字符串值（该值就是SOAP Client的答复或者响应）（Step 3）。在Step4中，SOAP RPC Router将仅仅只是重定向这个数据到SOAP Client。所有在Step1和Step4里传输的数据是通过SOAP Envelope来完成的。正如你所看到的，算法是相当简单的，因此我们只准备关心实际的代码。

首先，我们要创建一个SOAP Service。下面是它的代码，请不要忘记将它放入HelloWorld/ 目录中（必须被包含在你的CLASSPATH中）：

1: // SOAPService.java
2: package HelloWorld;
3: public class SOAPService {
4:   public String sayHi(String x) {
5:     return("Hello my friend, " + x + "! Glad to see you!");
6:   }
7: }

添加任何注释也是很容易的。要编译它，只需要用下列命令：

javac SOAPService.java

第二步，一旦我们准备好了SOAP Service，我们需要用SOAP Service Manager来部署它。这个可以通过很多方式来实现，但是为了能让初学SOAP的读者更容易理解SOAP，我提供了一个最容易的方式。我们假设你的Web Server（Tomcat或其他）已经正常运行，并且你已经正确安装了SOAP。那么当浏览器访问http://localhost:8080/soap/，你会看见Apache SOAP的欢迎页面。点击Run the admin client ，然后 Deploy。你会得到一个屏幕显示，在那里你需要填入ID，Scope，Method，Provider Type和JAVA Provider的信息到表单域中。你能忽略其他所有的表单域，除非你真的需要它们的信息。我们的“HelloWorld”例子不需要它们，所以，我们填的下面的值：

一些注释：ID是我们要从SOAP Client标识我们的SOAP Service的唯一名字。Method包含SOAP Service提供的一系列方法。JAVA Provider-Provider Class是SOAP Service Java类的名字。

现在，点击Deploy 按钮，那么你的服务会被部署。再次强调，请注意正确设置CLASSPATH环境变量。然后，你的HelloWorld.SOAPService类能够被找到，并且所有必需的jar包也能被找到。这是个几乎每个人都会犯的普通错误。现在，你能够点击 List ，将会看见你的服务已经被部署进来。恭喜！

最后，让我们来创建一个SOAP Client。代码看起来有点复杂，但是在现实中不会只有这么点长。

1: // HelloWorldClient.java
 2: import java.io.*;
 3: import java.net.*;
 4: import java.util.*;
 5: import org.apache.soap.*;
 6: import org.apache.soap.rpc.*;
 7: public class HelloWorldClient {
 8:   public static void main(String[] arg) throws Exception {
 9:     Call c = null;
10:     URL url = null;
11:     Vector params = null;
12:     Response rep = null;
13:     String ourName = "Superman";
14:     String ourUrn = "urn:HelloWorld_SOAPService";
15:     String ourMethod = "sayHi";
16:     url = new URL("http://localhost:8080/soap/Servlet/
                       rpcrouter");
17:     System.out.println("Passing to our deployed "+ourUrn+"
                            our name ("+ourName+"): ");
18:     c = new Call();
19:     c.setTargetObjectURI(ourUrn);
20:     c.setMethodName(ourMethod);
21:     c.setEncodingStyleURI(Constants.NS_URI_SOAP_ENC);
22:     params = new Vector();
23:     params.addElement(new Parameter("ourName", String.class,
                                         ourName, null));
24:     c.setParams(params);
25:     System.out.print("and its answer is: ");
26:     rep = c.invoke(url, "");
27:     if (rep.generatedFault()) {
28:       Fault fault = rep.getFault();
29:       System.out.println("\nCall failed!");
30:       System.out.println("Code = " + fault.getFaultCode());
31:       System.out.println("String = " + fault.getFaultString());
32:     } else {
33:       Parameter result = rep.getReturnValue();
34:       System.out.print(result.getValue());
35:       System.out.println();
36:     }
37:   }
38:}

下面我要做一些解释。在第13行，我们设置了我们的名字，这个名字将会传递给SOAP Service。在第14行，我们设置了我们将要调用的服务的ID（service ID），和第15行里设置的服务方法（service method）。有了这个ID，服务能够被部署到SOAP服务管理器（SOAP Service Manager）中。我们没有设置任何其他值，仅仅只用刚才那些基础值就可以正常运作了。你能从SOAP的官方文档上得到相关信息，该文档来自SOAP包中，它们的解释超出了本文的范围。

用以下方式编译这个SOAP Client：

javac HelloWorldClient.java

为了圆满完成它，让我们检查一下针对我们的测试，是否所有事情都准备就绪。Tomcat正在运行，所有的环境变量都正确，SOAP Service被编译和部署，SOAP Client被成功编译。OK，让我们运行它，你将看到这个屏幕：

正如你所看到的，我们的SOAP Client使用SOAP协议成功发送它的名字和接收了一个答复。正如前面所说的，SOAP Service发送和接收的是SOAP envelope。这个是SOAP envelope的源代码。

被发送到SOAP Service的SOAP Envelope

<?XML version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/
                                   soap/envelope/"
                   xmlns:xsi="http://www.w3.org/2001/
                              XMLSchema-instance"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns1:sayHi xmlns:ns1="urn:HelloWorld_SOAPService"
           SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/
                                   soap/encoding/">
<ourName xsi:type="xsd:string">Superman</ourName>
</ns1:sayHi>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>:

从SOAP Service接收的SOAP Envelope

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/
                                   soap/envelope/"
                   xmlns:xsi="http://www.w3.org/2001/
                              XMLSchema-instance"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns1:sayHiResponse xmlns:ns1="urn:HelloWorld_SOAPService"
                   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.
                                           org/soap/encoding/">
<return xsi:type="xsd:string">Hello my friend, Superman!
                              Glad to see you!</return>
</ns1:sayHiResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

要理解SOAP Envelope中的所有标签的含义，我建议你花一点时间阅读 http://www.w3.org/2001/06/soap-envelope 命名空间规范。

我希望本文能够在你理解SOAP技术上有一定帮助。这个技术是简单的，有趣的，强大的，弹性的。它被用在许多Web应用中，这些应用的数量也在不断增加。学习SOAP是值得的，至少你要知道它是什么和它是怎么运作的。