（仙人掌工作室2001年09月21日 14:53）
width="360" scrolling="no" height="300" frameborder="0" align="right" src="/servlets/ad?Pool=tech_pip" marginwidth="0" marginheight="0" noresize=""> 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 元素的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文件中所作的修改： 如果你在第二个步骤中属于情况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管理工具
二、实例：HelloWorld
现在你已经设置好了Apache SOAP，我们来实际使用一下，构造一个简单的HelloWorld应用。在SOAP术语中，应用称为服务。一般地，创建服务分两个步骤，这两个步骤可能 由同一个人或组织实施，也可能不是。第一个步骤是在选定的语言中定义和实现服务本身，这里我们选择Java语言。第二个步骤是创建实际调用服务的客户程 序。首先我们来看HelloWorld服务。
2.1、HelloWorld服务
我在第一篇文章中讨论了一个用SOAP实现的HelloWorld服务实例。这个服务要求输入一个用户名字，返回一个定制的Hello消息给调用者。下面的代码显示了HelloWorld服务的完整Java代码。
这就是全部的代码吗？如果这是真的话，实在太简单了！
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文件可以如下：
上述XML代码所包含的信息和我们在Web界面的管理工具中所输入的信息一样。接下来，输入下面的命令，从命令行部署HelloWorld服务：
DeploymentDescriptor.xml是上面显示的描述部署信息的XML文件名字。要验证服务是否部署成功，输入以下命令：
这时，我们应该看到和DeploymentDescriptor.xml文件内一样的XML。
2.3、HelloWorld客户程序
编写客户程序要比编写HelloWorld服务复杂得多。不过，你应该不会对此感到奇怪，因为前面已经提到，客户程序（至少）必须负责设置 Call对象，这需要不少工作。顺便说一下，本系列文章的第四篇将介绍一个框架，这个框架以Java 2 1.3版新引入的动态代理类为基础，使创建客户程序和创建服务一样简单。
Listing 1显示了完整的客户程序。接下来我们一步一步地仔细看看这个程序。这个程序需要一个必不可少的参数：程序要向他说Hello信息的用户名字。
客户程序首先设置Call对象，它需要如下信息：
被调用服务的对象ID，它通过Call对象的setTargetObjectURI()方法设置。本例的对象ID是urn:Hello。 待调用方法的名字，它通过Call对象的setMethodName()方法设置。本例的方法名字是sayHelloTo()。 参数的编码方式，它通过Call对象的setEncodingStyleURI()方法设置。本例我们使用标准的SOAP编码方式，这种编码方式由名称空间/soap/encoding/定义。 方法调用的参数通过Call对象的setParams()方法设置。setParams()方法的参数是一个Java Vector（向量）。这个向量包含所有的参数，向量中索引为0的参数是被调用方法从左边数起的第一个参数，索引为1的参数是被调用方法从左边数起的第二 个参数，依此类推。向量中的每一个元素都是一个org.apache.soap.rpc.Parameter的实例。Parameter构造函数要求指定 参数的名字、Java类型和值，还有一个可选的编码方式。如果指定了null编码方式（正如本例所做的那样），则默认使用Call对象的编码方式。虽然每 一个参数对应着一个名字，但这个名字可以设置成任何内容，Apache SOAP服务器调用方法时不会用到这个名字。因此，绝对有必要让向量中参数的次序和被调用方法的参数次序一致。 下面的代码片断显示了客户程序创建Call对象的过程：
现在，该是实际调用HelloWorld远程服务所提供方法的时候了。为此，客户程序调用了Call对象的invoke()方法，这个方法返回一个org.apache.soap.rpc.Response对象，如下所示：
接下来，客户程序检查Response对象。如果方法调用过程中出现了错误，generateFault()方法返回一个true值，客户程序提取并显示实际的错误信息：
如果方法调用成功，则客户程序提取并显示Hello信息：
三、带有JavaBean的HelloWorld实例
如前所述，Apache SOAP提供了许多预先构造的串行化和反串行化方法，其中包括为利用Java Vector、Enumeration、数组、JavaBean作为参数和返回值而提供的串行化器和反串行化器。在这一部分，我将修改 HelloWorld服务，通过一个JavaBean传入接收Hello信息的用户名。
3.1、HelloWorld服务
改写后的HelloWorld服务完整代码如下：
服务的代码仍旧很简单，仍旧类似于不用JavaBean时的HelloWorld服务。不过，这意味着最复杂的工作都转移到了客户端。事实上，这 个版本的服务与以前版本的唯一差别在于，现在出现了一个重载的sayHelloTo()方法。上面的代码中重载后的方法用粗体字显示。
重载的方法需要一个对Name JavaBean的引用。Name JavaBean的定义如下：
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文件如下所示：
正如在前一个例子中，这些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）结合构成。请看下面的代码片断：
接下来，客户程序必须告诉Call对象使用新的注册器而不是默认的注册器。为此，我们要调用Call对象的setSOAPMappingRegistry()方法，如下所示：
手工设置好类型映射注册器之后，接下来还必须为Call对象设置参数。这一步骤可以按前面介绍的方法完成，不同之处在于，现在我们不再用字符串类型的名字作为参数，而是用JavaBean作为参数，如下所示：
客户程序剩下的部分和原来的版本一样。Listing 3显示了完整的客户程序代码：
四、编译和运行程序
现在整个程序的开发工作已经完成，该是运行它的时候了。不过，我们首先要编译服务程序和客户程序。
创建一个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。我用下面的批命令编译程序：
注意：从hello目录执行这个批命令文件。
要使用这个服务，除了部署它之外，还需要修改Web服务器的classpath，确保Web服务能够找到 hello.HelloServer类——对于本例，这是指把E:/soap-2_0/samples加入到Web服务器的classpath。对 classpath进行必要的修改之后，重新启动Web服务器。接下来就可以运行客户程序了。下面是我运行hello.Client的批命令文件：
这里的classpath和编译程序时用的classpath相同。
最后，运行hello.Client2的批命令文件可以如下：
观察Web服务器的控制台窗口，看看在运行两个不同的客户程序时，HelloWorld服务的哪些方法正在被调用。
■ 结束语
在这篇文章中，我介绍了如何用Apache SOAP实现来创建简单的基于SOAP的服务。在SOAP实现方面，另一个重要的竞争者是Microsoft。遗憾的是，“纯”Java开发者在使用 Microsoft实现的时候会有一段艰苦的时光，因为它的实现包含了COM对象。
在下一篇文章中，我将介绍Apache SOAP支持的另一种创建服务的方式：使用JavaScript之类的脚本语言，而不是Java。另外，我还要介绍一个很不错的JavaScript引擎，即Rhino。
如果觉得《SOAP协议（二）：Apache SOAP介绍》对你有帮助，请点赞、收藏，并留下你的观点哦！
