SOAP and JDOM

        看完上一篇 blog: Web 服务搜索与执行引擎 ( 九 )—— 初看客户端如何调用 Web 服务 , 我想我们对当前客户端如何调用 Web 服务的现状 , 无论是从高层接口的利用还是低层接口自己手动构建 SOAP 消息都有了最初步的印象了 . 接下来将要进行的是整个项目最核心的部分之一 : 服务的执行 . 我将为大家展示我们在项目中如何使用 SOAP with Attachments API for Java (SAAJ) ，简化创建和发送 SOAP 消息的详细过程。

Web 服务的基础是以标准格式发送和接收消息，这样所有系统都可以理解消息。通常情况下，这种标准格式是 SOAP 。 SOAP 消息可以手工生成和发送，但是如果说我们按上篇 blog 那样 : 在客户端，首先创建一个 HttpConnector 对象，负责 HTTP 连接。设定 Connector 的一些头部信息，比如 EndPoinURL 和 SoapAction 等。如果网络连接需要使用代理服务器，那也要在这里设定相关的信息。接着创建 SoapSerializer 对象，用于生成 Soap 消息。按照 WSDL 里定义，把所有参数按顺序序列化，得到一个完整的 SOAP 请求消息。该 Soap 消息，作为 Payload 通过 HttpConnector 被发送到服务端。最后，生成一个 SoapReader 对象，负责读取服务端返回的 SOAP 消息，取得其中的返回值。

按上面这种 SOAP 消息的构建方法的话就会变得复杂起来 , 所以说有必要借助于一些 API 来简化我们的操作 . 有几个基于 Java 的 API 可以用来构建低层 SOAP 消息来访问 Web 服务。这些 API 包括 SAAJ 、 Web 服务调用框架（ WSIF ）、上篇 blog 里提到的 Axis 等。

Ø              选择 SAAJ 的理由

我们最终选择了 SAAJ, 因为基于简单及适用性来考虑 .SAAJ 无疑很适合基于文档的同步或者异步 Web Service 。 SAAJ 使用简单，有助于在 Java 环境中集成各种 Web Service ，它扩展了对文档风格的 Web Service 通信的自然支持（ natural support ）。 SAAJ 还支持基于标准接口上的 XML 消息传递，并且这一点得到了供应商的广泛支持。另外 SOAP with Attachments API for Java (SAAJ)—— Java API for XML Messaging (JAXM) 的一个分支 —— 能够使许多必需的步骤变得自动化，例如创建上面所说的连接，或者创建和发送实际消息。

Ø              什么是 SAAJ

SAAJ 是在松散耦合软件系统中利用 SOAP 协议实现的基于 XML 消息传递的 API 规范。顾名思义， SAAJ 支持带附件的 SOAP 消息。
　　对于 Java API for XML Messaging (JAXM) ， JAXM 1.0 的理念是通过提供消息传递和 SOAP API ，允许开发人员根据 SOAP 编写支持消息传递标准的业务应用程序。随着 JAXM 1.1 版的推出， SOAP API (javax.xml.soap) 被分割成了 SAAJ1.1 规范和 JAXM1.1 ， JAXM1.1 只包含基于消息传递的 API （ javax.xml.messaging ）。目前，正在使用的 SAAJ 版本是 1.2 。

Ø              如何使用

回想那篇 blog, Web 服务搜索与执行引擎 ( 八 )——WSDL 解析精髓 , 提到了为了使用 SAAJ 构建 SOAP 消息调用该服务，我们将需要从 WSDL 收集下列最基本的信息：

目标名称空间

服务名称

端口名称

操作名称

操作输入参数  

SOAP 文档结构简单，利用 SAAJ 构建起来也比较方便。但我们需要将用户从网页中输入的数据作为 SOAP 的有效负载发送至异构平台的服务，如何来构建这个有效负载呢？按照什么样的格式将用户输入的数据放入 SOAP 的有效负载中呢？格式可以从解析 WSDL 文档过程中知道，即上面说的那些基本信息 , 但怎么来匹配用户的输入数据呢？这时就需要以 WSDL 中解析出来的参数名称作为用户从网页中输入的文本框的名字，从而匹配了每一个子参数的值，然后即可构建 SOAP 消息的有效负载。然后将 SOAP 消息发送至远程平台。

调用后，将返回一个 SOAP 消息返回值，我们需要解析，并将结果在网页中呈现给客户，我们利用了 JDOM 技术，根据从 WSDL 中解析出的返回信息来提取 SOAP 中的返回值，最终呈现给用户。

具体过程 包括 5 个步骤：

1.        创建 SOAP 连接

2.        生成 SOAP 消息

3.        填充消息

4.        发送消息

5.        检索响应

SOPA 消息的结构

大家也可以去看看我的那篇 blog: Web 服务搜索与执行引擎 ( 七 )—— 重温 WSDL 与 SOAP , 再次复习下 WSDL 跟 SOAP 的有关知识 . 首先来看看消息自身的结构。一条基本的 SOAP 消息由带有两个主要部分的信封（ envelope ）构成：头部和主体。应用程序确定如何使用这些部分，但整个消息必须遵循特定的 XML 结构，例如：
清单 1. 一条示例 SOAP 消息

 这里，头部是空的，而主体包含了有效信息，或要传递的消息。在本例中，它是请求某本书价格的消息。

< SOAP-ENV:Envelope  xmlns:SOAP-ENV ="http://schemas.xmlsoap.org/soap/envelope/"  xmlns:xsi ="http://www.w3.org/1999/XMLSchema-instance"  xmlns:xsd ="http://www.w3.org/1999/XMLSchema" >  
  < SOAP-ENV:Header  />
  

      < SOAP-ENV:Body >  

         < ns1:getPrice  xmlns:ns1 ="urn:Book"  

             SOAP-ENV:encodingStyle ="http://schemas.xmlsoap.org/soap/encoding/" >  

                   < isbn  xsi:type ="xsd:string" > 123544111 </ isbn >  

         </ ns1:getPrice >  

     </ SOAP-ENV:Body >  

</ SOAP-ENV:Envelope >  

 

注意消息的结构。 Envelope 包含 Header 和 Body 元素，这三者都是 http://schemas.xmlsoap.org/soap/envelope/ namespace 的一部分。应用程序使用 SOAPConnection 来发送消息。

创建连接和消息

清单 2. 创建连接

import javax.xml.soap.SOAPConnectionFactory;

import javax.xml.soap.SOAPConnection;

public   class  DynamicInvokeInterce ...{

......

public   List invokeOperation(Operation operation)  throws  Exception ...{

       try   ...{

         SOAPConnectionFactory soapConnFactory  = 

                            SOAPConnectionFactory.newInstance();

         SOAPConnection connection  = 

                             soapConnFactory.createConnection();         

         connection.close();

        }   catch (Exception e)  ...{

            System.out.println(e.getMessage());

        }

}

}

……

 

     创建一个 SOAP 连接 , 如上清单 2 所示。 SAAJ 客户机可以利用 SOAP Connection Factory ，通过创建 SOAPConnection 来建立点到点的同步连接。该连接提供了同步调用服务的方法。

其次 , 工厂还创建了消息自身：

清单 3. 创建消息对象

import  javax.xml.soap.SOAPConnectionFactory;

import  javax.xml.soap.SOAPConnection;

  import  javax.xml.soap.MessageFactory;

import  javax.xml.soap.SOAPMessage;

import  javax.xml.soap.SOAPPart;

import  javax.xml.soap.SOAPEnvelope;

import  javax.xml.soap.SOAPBody;

public   class  DynamicInvokeInterce  ... {

   ……

public   List invokeOperation(Operation operation)  throws  Exception

       try   ... {

         SOAPConnectionFactory soapConnFactory  =  

                            SOAPConnectionFactory.newInstance();

         SOAPConnection connection  =  

                             soapConnFactory.createConnection();

         MessageFactory messageFactory  =  MessageFactory.newInstance();

         SOAPMessage message  =  messageFactory.createMessage();         

         SOAPPart soapPart  =  message.getSOAPPart();

         SOAPEnvelope envelope  =  soapPart.getEnvelope();

         SOAPBody body  = envelope.getBody();      

         connection.close();

   …

}

 

    如清单 3 所示 , 使用 MessageFactory 创建消息自身。这一消息已经包含了空的基本部分，比如 envelope 和 header 。 SOAPPart 包含了 envelope ，而 envelope 又包含了主体。从而创建了对所需对象（比如 SOAPBody ）的引用。

接着，填充 SOAPBody ：
清单 4. 填充主体

...

import  javax.xml.soap.SOAPBody;

import  javax.xml.soap.SOAPElement;

public   class  DynamicInvokeInterce  ... {

   public   static   final  String XSI_NAMESPACE_PREFIX  =   " xsi " ;

public   static   final  String XSI_NAMESPACE_URI  =   " http://www.w3.org/2001/XMLSchema-instance " ;

public   static   final  String XSD_NAMESPACE_PREFIX  =   " xsd " ;

        public   static