WSDL文件简介(附例子)

本文介绍了如何编写一个简单的WSDL文件，并根据WSDL文件编写服务器端和客户端代码，并发布Web Service服务的过程。

首先明确的一点是WSDL现在有两个版本，分别为WSDL 1.1和WSDL 2.0,W3C的官方文档地址分别为：

http://www.w3.org/TR/wsdl

Web Services Description Language (WSDL) 1.1

W3C Note 15 March 2001

和

http://www.w3.org/TR/2007/WD-wsdl20-primer-20070326/

Web Services Description Language (WSDL) Version 2.0 Part 0: Primer

W3C Working Draft 26 March 2007

 

其中很多应用还是以版本1.1为基础实现。下面是2.0与1.1的区别：

Adding further semantics to the description language. 

Removal of message constructs.

No support for operator overloading.

PortTypes renamed to interfaces.

Ports renamed to endpoints.

 

下面是一些常见的命名空间：

prefix          namespace URI

wsdl            http://schemas.xmlsoap.org/wsdl/

soap           http://schemas.xmlsoap.org/wsdl/soap/

http            http://schemas.xmlsoap.org/wsdl/http/

mime           http://schemas.xmlsoap.org/wsdl/mime/

soapenc      http://schemas.xmlsoap.org/soap/encoding/

soapenv      http://schemas.xmlsoap.org/soap/envelope/

xsi             http://www.w3.org/2000/10/XMLSchema-instance

xsd            http://www.w3.org/2000/10/XMLSchema

tns            (various)

 

对于WSDL规范，可以参考以上两个官方文档，本文主要介绍如何编写WSDL文档（其实官方文档中已经给出了很多例子和方法，这里只是简单的翻译与重复介绍）。

 

下面举例说明如何编写WSDL文档：

我们做一个非常简单的加法运算服务：客户端传入SOAP请求消息，包含两个加数，然后在服务器端获取这两个加数，求和，然后返回给客户端。

请求消息和响应消息结构分别如下（有效负载部分，外层的SOAP封装AXIS2会自动添加上去）：

xml 代码

1. request:   
2. <SumRequest>  
3.     <First>15</First>  
4.     <Second>16</Second>  
5. </SumRequest>  

xml 代码

1. response:   
2. <SumResponse>  
3.     <Result>31</Result>  
4. </SumResponse>  

1.首先需要进行定义的就是soap消息的数据类型，无疑，这里需要定义两个复杂的数据类型：

SumRequest

SumResponse

它们分别包含有子元素First、Second和Result.

另外还需要定义一种异常，这里我们定义成为SumFault,比如传入的两个加数的和超出了xsd:int的范围时，抛出该异常。

（注意，很多代码生成器都会根据WSDL生成代码，将SumFault部分生成为后缀为Exception的异常类。）

2.定义数据类型的目的是为传入传出消息做准备的，传入传出消息的定义方式使用message元素来定义。

我们定义三种消息：SumRequest,SumResponse以及SumFault，分别为请求消息，响应消息以及出错时的消息。
 

3.定义好了传入传出消息后，就要定义一个portType，该节点类型定义了主要的业务操作。

4.接着将定义SOAP绑定：

SumSoapBinding：为SumService端口类型所定义的操作和消息指定具体传输中所使用的消息格式和协议细节。绑定的方式为SOAP，传输方式为http，消息的格式为document。

5.定义Web服务：Web服务名为SumService。

6.本Web服务的操作为Sum操作。

7.端口为：为SumSoapBing绑定指定一个地址来定义服务访问点。

根据以上七个部分编写完成的WSDL文件如下：

xml 代码

1. <?xml version="1.0" encoding="UTF-8"?>  
2. <wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"  
3.     xmlns:tns="http://www.zzl.org/Sum"  
4.     xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"  
5.     xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
6.     targetNamespace="http://www.zzl.org/Sum">  
7.     <wsdl:documentation>  
8.        The WSDL file of SumService.   
9.     </wsdl:documentation>  
10.     <wsdl:types>  
11.        <wsdl:documentation>  
12.            Data types that are used for request and response messages.   
13.        </wsdl:documentation>  
14.        <xsd:schema targetNamespace="http://www.zzl.org/Sum">  
15.            <xsd:element name="SumRequest">  
16.               <xsd:complexType>  
17.                   <xsd:sequence>  
18.                      <xsd:element name="First" type="xsd:int" />  
19.                      <xsd:element name="Second" type="xsd:int" />  
20.                   </xsd:sequence>  
21.               </xsd:complexType>  
22.            </xsd:element>  
23.            <xsd:element name="SumResponse">  
24.               <xsd:complexType>  
25.                   <xsd:sequence>  
26.                      <xsd:element name="Result" type="xsd:int" />  
27.                   </xsd:sequence>  
28.               </xsd:complexType>  
29.            </xsd:element>  
30.            <xsd:element name="SumFault">  
31.               <xsd:complexType>  
32.                   <xsd:sequence>  
33.                      <xsd:element name="Code" type="xsd:string" />  
34.                   </xsd:sequence>  
35.               </xsd:complexType>  
36.            </xsd:element>  
37.        </xsd:schema>  
38.     </wsdl:types>  
39.     <wsdl:message name="SumRequest">  
40.        <wsdl:documentation>  
41.            The data that will be transmitted to the service.   
42.        </wsdl:documentation>  
43.        <wsdl:part element="tns:SumRequest" name="request" />  
44.     </wsdl:message>  
45.     <wsdl:message name="SumResponse">  
46.        <wsdl:documentation>  
47.            The data that will be returned to the client.   
48.        </wsdl:documentation>  
49.        <wsdl:part element="tns:SumResponse" name="response" />  
50.     </wsdl:message>  
51.     
52.     <wsdl:message name="SumFault">  
53.        <wsdl:documentation>  
54.            The fault that will be thrown when fault occurs.   
55.        </wsdl:documentation>  
56.        <wsdl:part name="axisFault" element="tns:SumFault" />  
57.     </wsdl:message>  
58.     <wsdl:portType name="SumService">  
59.        <wsdl:documentation>  
60.            The SumService contains the business operation.   
61.        </wsdl:documentation>  
62.        <wsdl:operation name="RevokeCert">  
63.            <wsdl:documentation>  
64.               The operation that do the business work.   
65.            </wsdl:documentation>  
66.            <wsdl:input message="tns:SumRequest" />  
67.            <wsdl:output message="tns:SumResponse" />  
68.            <wsdl:fault name="fault" message="tns:SumFault" />  
69.        </wsdl:operation>  
70.     </wsdl:portType>  
71.     <wsdl:binding name="SumSoapBinding" type="tns:SumService">  
72.        <wsdl:documentation>  
73.            The SumSoapBinding defines the SOAP message format and   
74.            protocol details for Sum operation and messages defined by a   
75.            RevokeService portType.   
76.        </wsdl:documentation>  
77.        <soap:binding style="document"  
78.            transport="http://schemas.xmlsoap.org/soap/http" />  
79.        <wsdl:operation name="Sum">  
80.            <soap:operation soapAction="urn:Sum" />  
81.            <wsdl:input>  
82.               <soap:body use="literal" />  
83.            </wsdl:input>  
84.            <wsdl:output>  
85.               <soap:body use="literal" />  
86.            </wsdl:output>  
87.            <wsdl:fault name="fault">  
88.               <soap:fault use="literal" name="fault" />  
89.            </wsdl:fault>  
90.        </wsdl:operation>  
91.     </wsdl:binding>  
92.     <wsdl:service name="SumService">  
93.        <wsdl:documentation>  
94.            SumService provides the service of summing.   
95.        </wsdl:documentation>  
96.        <wsdl:port binding="tns:SumSoapBinding" name="SumSoapBinding">  
97.            <wsdl:documentation>  
98.               The port defines the endpoint by specifying a soap   
99.               address for SumSoapBinding.   
100.            </wsdl:documentation>  
101.            <soap:address            location="http://www.zzl.org/ExampleService/services/SumService" />  
102.        </wsdl:port>  
103.     </wsdl:service>  
104. </wsdl:definitions>  

服务器端和客户端的代码是根据WSDL文件编写出来的，这才是正确的过程，但是，在国内的软件开发过程，常常是先写代码，再根据代码生成WSDL文件，这是不正确的。

编写服务器端的程序如下：

1.      建立工程ExampleService.如下图所示：

2.      编写服务器端代码：

java 代码

1. SumService.java   
2.     
3. package org.zzl.service;   
4.     
5. import javax.xml.namespace.QName;   
6.     
7. import org.apache.axiom.om.OMAbstractFactory;   
8. import org.apache.axiom.om.OMElement;   
9. import org.apache.axiom.om.OMFactory;   
10. import org.apache.axiom.om.OMNamespace;   
11. import org.apache.axis2.AxisFault;   
12.     
13. /**  
14.  * The Web Service class SumService which implement add two number and return  
15.  * the result.  
16.  *   
17.  * @author zhangzhongl@gmail.com  
18.  * @version 0.7  
19.  */  
20. public class SumService {   
21. /**  
22.  * The request soap message object.  
23.  */  
24. private OMElement requestSoap = null;   
25.     
26. /**  
27.  * First addend.  
28.  */  
29. private static final String FIRST = "First";   
30.     
31. /**  
32.  * Second addend.  
33.  */  
34. private static final String SECOND = "Second";   
35.     
36. /**  
37.  * Sum Response element.  
38.  */  
39. private static final String SUM_RESPONSE = "SumResponse";   
40.     
41. /**  
42.  * Result element.  
43.  */  
44. private static final String SUM = "Result";   
45.     
46. public OMElement Sum(OMElement soap) throws AxisFault {   
47.       requestSoap = soap;   
48.       OMElement first=   
49.  requestSoap.getFirstChildWithName(new QName(FIRST));   
50.       OMElement second =   
51.  requestSoap.getFirstChildWithName(new QName(SECOND));   
52.       int sum = Integer.parseInt(first.getText())   
53.                   + Integer.parseInt(second.getText());   
54.       return getResponse(sum);   
55. }   
56.     
57. /**  
58.  * Get the SOAP response message.  
59.  *   
60.  * @param sum  
61.  *            The adding result.  
62.  * @return The SOAP response message.  
63.  */  
64. private OMElement getResponse(int sum) {   
65.       OMFactory factory = OMAbstractFactory.getOMFactory();   
66.       OMNamespace omNs = factory.createOMNamespace("", "");   
67.       OMElement response = factory.createOMElement(SUM_RESPONSE, omNs);   
68.       OMElement sumElement = factory.createOMElement(SUM, omNs);   
69.       sumElement.setText(String.valueOf(sum));   
70.       response.addChild(sumElement);   
71.       return response;   
72. }   
73. }   

编写客户端代码：

java 代码

1. TestSumService.java   
2.     
3. package org.zzl.service.test;   
4.     
5. import java.io.FileInputStream;   
6. import java.io.FileNotFoundException;   
7.     
8. import javax.xml.stream.FactoryConfigurationError;   
9. import javax.xml.stream.XMLInputFactory;   
10. import javax.xml.stream.XMLStreamException;   
11. import javax.xml.stream.XMLStreamReader;   
12.     
13. import org.apache.axiom.om.OMElement;   
14. import org.apache.axiom.om.impl.builder.StAXOMBuilder;   
15. import org.apache.axis2.AxisFault;   
16. import org.apache.axis2.addressing.EndpointReference;   
17. import org.apache.axis2.client.Options;   
18. import org.apache.axis2.client.ServiceClient;   
19.     
20. public class TesSumService{   
21.       private static EndpointReference targetEPR = new EndpointReference(   
22.                  "http://localhost/axis2/services/SumService");   
23.     
24.       public static void main(String[] args) throws FileNotFoundException,   
25.                  FactoryConfigurationError, XMLStreamException {   
26.            OMElement requestSoapMessage =    
27. getSoapRequestMessage("data/request.xml");   
28.            Options options = new Options();   
29.            options.setAction("urn:Sum");   
30.            options.setTo(targetEPR);   
31.            ServiceClient sender = null;   
32.            try {   
33.                  sender = new ServiceClient();   
34.                  sender.setOptions(options);   
35.                  System.out.println(sender.sendReceive(requestSoapMessage)   
36.                             .toStringWithConsume());   
37.            } catch (AxisFault e) {   
38.                  System.out.println(e.getMessage());   
39.            }   
40.       }   
41.     
42.       public static OMElement getSoapRequestMessage(String filePath)   
43.                  throws FileNotFoundException, XMLStreamException,   
44.                  FactoryConfigurationError {   
45.            XMLStreamReader reader = XMLInputFactory.newInstance()   
46.                       .createXMLStreamReader(new FileInputStream(filePath));   
47.            StAXOMBuilder builder = new StAXOMBuilder(reader);   
48.            OMElement requestMessage = builder.getDocumentElement();   
49.            return requestMessage;   
50.       }   
51. }   

每个Axis2服务都有一个services.xml来描述这个服务，本文的Web Service的描述文件内容如下：

xml 代码

1. <serviceGroup>  
2.     <service name="SumService">  
3.        <description>  
4.            This is the service for revoking certificate.   
5.        </description>  
6.        <parameter name="ServiceClass" locked="false">  
7.            org.zzl.service.SumService   
8.        </parameter>  
9.        <operation name="Sum">  
10.            <messageReceiver  
11.               class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver" />  
12.            <actionMapping>urn:Sum</actionMapping>  
13.        </operation>  
14.     </service>  
15. </serviceGroup>  

可以在 serviceGroup 中定义多个 service, 在一个 service 中定义多个 operation.

 

然后将SumService.class,META-INF/SumService.wsdl,services.xml一起打包成为aar文件，放置在AXIS2_HOME目录下，启动Tomcat(本文使用的服务器)，即可运行TestSumService来获取响应。 

 

至此，编写WSDL并根据WSDL编写服务器端和客户端代码，并发布Web Service服务完毕。

由于只是一个示例程序，并没有编写抛出AxisFault部分的处理。

有关WSDL文件的主要内容，请参考WSDL官方规范。