Introduction to SOAP and Web Service

1. What is WebService and SOAP?

1.1 Web Service

Web Service，是为了不同的平台的不同语言写成的不同服务进行的通信的一个标准，一个Web应用，可以生成Web Service的Server端，其他应用通过某种协议来调用该应用的API，从而获取所需的数据。

而SOAP就是Web Service早期所设想的用来应用间通信的标准。广义来讲，如今的RPC和REST实际上也能实现不同应用间的通信。

1.2 Simple Object Access Protocol

WebService通过HTTP协议发送请求和接收结果时，发送的请求内容和结果内容都采用XML格式封装，并增加了一些特定的HTTP消息头，以说明HTTP消息头的内容格式，这些特定的HTTP消息头和XML内容格式就是SOAP协议。SOAP提供了标准的RPC方法来调用WebService。

SOAP协议= HTTP协议+ XML数据格式

SOAP协议定义了SOAP消息的格式，SOAP协议是基于HTTP协议的，SOAP也是基于XML和XSD的，XML是SOAP的数据编码方式。

2. SOAP Request/Response

Refer to: https://www.cnblogs.com/JeffreySun/archive/2009/12/14/1623766.html

POST /WebServices/WeatherWebService.asmx HTTP/1.1

User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; MS Web Services Client Protocol 2.0.50727.3603)
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://WebXml.com.cn/getSupportCity"
Host: www.webxml.com.cn
Content-Length: 348
Expect: 100-continue
Connection: Keep-Alive

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">        
	<soap:Body>
	    <getSupportCity xmlns="http://WebXml.com.cn/">
	        <byProvinceName>广东</byProvinceName>
	    </getSupportCity>
	</soap:Body>
</soap:Envelope>

一个SOAP请求其实就是一个HTTP请求，所有的SOAP 消息发送都使用HTTP POST 方法。但需要加入SOAPAction: "http://WebXml.com.cn/getSupportCity"的请求头

可以用上面指定SOAPAction头来表示内容是SOAP的内容，也可以指定 Content-Type: application/soap+xml 来表示内容是SOAP的内容。SOAP请求中最后的那段XML数据，这个就是请求的具体内容，这个就是SOAP规定的请求的数据格式，下面再详细对格式进行说明。

其中的<soap:Body>里面的内容就是请求的内容，请求的方法为getSupportCity，该方法有一个名为byProvinceName的参数，参数的值为“广东”这个字符串。再看一下返回的内容：

HTTP/1.1 200 OKDate: Mon, 14 Dec 2009 05:55:39 GMTServer: Microsoft-IIS/6.0X-Powered-By: ASP.NETX-AspNet-Version: 2.0.50727Cache-Control: private, max-age=0Content-Type: text/xml; charset=utf-8Content-Length: 1052<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <getSupportCityResponse xmlns="http://WebXml.com.cn/">
        <getSupportCityResult>
<string>广州 (59287)</string><string>深圳 (59493)</string><string>潮州 (59312)</string><string>韶关 (59082)</string><string>湛江 (59658)</string><string>惠州 (59298)</string><string>清远 (59280)</string><string>东莞 (59289)</string><string>江门 (59473)</string><string>茂名 (59659)</string><string>肇庆 (59278)</string><string>汕尾 (59501)</string><string>河源 (59293)</string><string>揭阳 (59315)</string><string>梅州 (59117)</string><string>中山 (59485)</string><string>德庆 (59269)</string><string>阳江 (59663)</string><string>云浮 (59471)</string><string>珠海 (59488)</string><string>汕头 (59316)</string><string>佛山 (59279)</string>
        </getSupportCityResult>
    </getSupportCityResponse>
  </soap:Body>
</soap:Envelope>

<?xml version="1.0"?><soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope"soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
<soap:Header>  
	<m:Trans xmlns:m="http://www.w3schools.com/transaction/"  soap:mustUnderstand="1">234  </m:Trans>
</soap:Header>
<soap:Body>  
	<m:GetPrice xmlns:m="http://www.w3schools.com/prices">    <m:Item>Apples</m:Item>  </m:GetPrice>
</soap:Body>
</soap:Envelope>

2.1 Envelope

SOAP的请求内容必须以Envelope做为根节点。

xmlns:soap="http://www.w3.org/2001/12/soap-envelope"，不能修改，否则会出错。http://www.w3.org/2001/12/soap-envelope里面有Envelope的schema的相关定义。有兴趣的可以去这个链接的内容。

soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding"，这个指定了数据元素的类型。

2.2 Header

这个是可选的，如果需要添加Header元素，那么它必须是Envelope的第一个元素。

Header的内容并没有严格的限制，我们可以自己添加一些和应用程序相关的内容，但是客户端一定要记得处理这些Header元素，可以加上mustUnderstand强制进行处理。

2.3 Body

这个就是请求的主题内容了，请求什么函数，参数是什么类型等等都在这里面指定。

用标签表示一个函数，然后用子元素表示它的参数。

在调用中没有指定参数和返回类型，这里不需要指定，因为提供服务的一方自己已经规定好了数据类型，在调用时指定数据类型没有任何意义。

3. WSDL

Web Services Description Language: 基于XML的，相当于接口文档，可以用来生成 WebService客户端，用于描述Web Service及其函数、参数和返回值。

WSDL是用来描述WebService的，它用XML的格式描述了WebService有哪些方法、参数类型、访问路径等等。我们要使用一个WebService肯定首先要获取它的WSDL，然后可以生成可以使用的代理类。

3.1 What is WSDL?

WSDL文件保存在Web服务器上，通过一个url地址就可以访问到它。客户端要调用一个WebService服务之前，要知道该服务的WSDL文件的地址。WebService服务提供商可以通过两种方式来暴露它的WSDL文件地址：

1.注册到UDDI服务器，以便被人查找；

2.直接告诉给客户端调用者。

1 <?xml version="1.0" encoding="utf-8"?>
 2 <wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" xmlns:tns="http://tempuri.org/" xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" targetNamespace="http://tempuri.org/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
 3   <wsdl:types>
 4     <s:schema elementFormDefault="qualified" targetNamespace="http://tempuri.org/">
 5       <s:element name="HelloWorld">
 6         <s:complexType>
 7           <s:sequence>
 8             <s:element minOccurs="1" maxOccurs="1" name="i" type="s:int" />
 9           </s:sequence>
10         </s:complexType>
11       </s:element>
12       <s:element name="HelloWorldResponse">
13         <s:complexType>
14           <s:sequence>
15             <s:element minOccurs="1" maxOccurs="1" name="HelloWorldResult" type="s:dateTime" />
16           </s:sequence>
17         </s:complexType>
18       </s:element>
19     </s:schema>
20   </wsdl:types>
21   <wsdl:message name="HelloWorldSoapIn">
22     <wsdl:part name="parameters" element="tns:HelloWorld" />
23   </wsdl:message>
24   <wsdl:message name="HelloWorldSoapOut">
25     <wsdl:part name="parameters" element="tns:HelloWorldResponse" />
26   </wsdl:message>
27   <wsdl:portType name="ServiceSoap">
28     <wsdl:operation name="HelloWorld">
29       <wsdl:input message="tns:HelloWorldSoapIn" />
30       <wsdl:output message="tns:HelloWorldSoapOut" />
31     </wsdl:operation>
32   </wsdl:portType>
33   <wsdl:binding name="ServiceSoap" type="tns:ServiceSoap">
34     <soap:binding transport="http://schemas.xmlsoap.org/soap/http" />
35     <wsdl:operation name="HelloWorld">
36       <soap:operation soapAction="http://tempuri.org/HelloWorld" style="document" />
37       <wsdl:input>
38         <soap:body use="literal" />
39       </wsdl:input>
40       <wsdl:output>
41         <soap:body use="literal" />
42       </wsdl:output>
43     </wsdl:operation>
44   </wsdl:binding>
45   <wsdl:binding name="ServiceSoap12" type="tns:ServiceSoap">
46     <soap12:binding transport="http://schemas.xmlsoap.org/soap/http" />
47     <wsdl:operation name="HelloWorld">
48       <soap12:operation soapAction="http://tempuri.org/HelloWorld" style="document" />
49       <wsdl:input>
50         <soap12:body use="literal" />
51       </wsdl:input>
52       <wsdl:output>
53         <soap12:body use="literal" />
54       </wsdl:output>
55     </wsdl:operation>
56   </wsdl:binding>
57   <wsdl:service name="Service">
58     <wsdl:port name="ServiceSoap" binding="tns:ServiceSoap">
59       <soap:address location="http://localhost:2206/WebSite1/Service.asmx" />
60     </wsdl:port>
61     <wsdl:port name="ServiceSoap12" binding="tns:ServiceSoap12">
62       <soap12:address location="http://localhost:2206/WebSite1/Service.asmx" />
63     </wsdl:port>
64   </wsdl:service>
65 </wsdl:definitions>

一个WSDL文档由几部分组成：

• types　指定了WebService用到的所有数据类型，上面用到了两种数据类型，int和datetime

• message　　指明一个操作所用到的数据类型。

  HelloWorldSoapIn是指HelloWorld的输入操作用到的数据类型，HelloWorldSoapOut是指HelloWorld的输出操作用到的数据类型。二者的element元素指出了与types中对应到的具体类型。

• portType指出了这个WebService所有支持的操作，就是说有哪些方法可供调用。

  这里支持一个HelloWorld调用，它的输入和输出对应到HelloWorldSoapIn和HelloWorldSoapOut这个两个数据类型。

• binding

  soap12:binding元素的transport指明传输协议，这里是http协议。

  operation 指明要暴露给外界调用的操作。

  use属性指定输入输出的编码方式，这里没有指定编码。

• services　　指定服务的一些信息，主要是指定服务的访问路径。

3.2 Principles

WebService的工作调用原理：

• 对客户端而言，我们给这各类WebService客户端API传递WSDL文件的url地址，这些API就会创建出底层的代理类，我调用这些代理，就可以访问到webservice服务。

  代理类把客户端的方法调用变成SOAP格式的请求数据再通过HTTP协议发出去，并把接收到的SOAP数据变成返回值返回。

• 对服务端而言，各类WebService框架的****本质就是一个大大的Servlet，当远程调用客户端给它通过http协议发送过来SOAP格式的请求数据时，它分析这个数据，就知道要调用哪个java类的哪个方法，于是去查找或创建这个对象，并调用其方法，再把方法返回的结果包装成SOAP格式的数据，通过http响应消息回给客户端。

3.3 SoapUI

SoapUI是专门针对webservice接口的测试工具，在对同一个webservice接口进行测试时，SoapUI表现出来的性能更优越、更真实、更接近地反映接口的性能指标，对于SoapUI来说，提供的结果数据分析不如LR那么详细与全面。相当于Postman

4. Call WebService by SOAP in Java

4.1 HTTP Request

使用Apache HTTP Client，模拟发送SOAP请求，需要自己解析XML。

import org.apache.http.HttpEntity;
import org.apache.http.client.config.RequestConfig;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.util.EntityUtils;
import org.dom4j.Document;
import org.dom4j.DocumentException;
import org.dom4j.DocumentHelper;
import org.dom4j.Element;

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.List;

public class WebServiceTest {
    public static void main(String[] args) throws IOException {
        String url = "http://www.webxml.com.cn/WebServices/WeatherWebService.asmx?wsdl";
        // 根据实际情况拼接xml
        StringBuilder xmlData = new StringBuilder("");
        xmlData.append("<?xml version="1.0" encoding="UTF-8"?>");
        xmlData.append("<soapenv:Envelope "
                + "    xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' "
                + " xmlns:q0='http://WebXml.com.cn/' "
                + "    xmlns:xsd='http://www.w3.org/2001/XMLSchema' "
                + " xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/' >");
        xmlData.append("<soapenv:Body>");
        xmlData.append("<q0:getWeatherbyCityName>");
        xmlData.append("<q0:theCityName>上海</q0:theCityName> ");
        xmlData.append("</q0:getWeatherbyCityName>");
        xmlData.append("</soapenv:Body>");
        xmlData.append("</soapenv:Envelope>");

        String postSoap = doPostSoap(url, xmlData.toString(), "");
        // 去除转义字符
        /*String unPostSoap = StringEscapeUtils.unescapeXml(postSoap);
        System.out.println(unPostSoap);*/
    }

    //使用SOAP1.1发送消息
    public static String doPostSoap(String postUrl, String soapXml, String soapAction) throws IOException {
        String retStr = "";
        // 创建HttpClientBuilder
        HttpClientBuilder httpClientBuilder = HttpClientBuilder.create();
        // HttpClient
        CloseableHttpClient closeableHttpClient = httpClientBuilder.build();
        HttpPost httpPost = new HttpPost(postUrl);
        // 设置请求和传输超时时间
        RequestConfig requestConfig = RequestConfig.custom().setSocketTimeout(6000)
                .setConnectTimeout(6000).build();
        //httpPost.setConfig(requestConfig);
        try {
            httpPost.setHeader("Content-Type", "text/xml;charset=utf8");
            //httpPost.setHeader("SOAPAction", soapAction);
            StringEntity requestEntity = new StringEntity(soapXml, StandardCharsets.UTF_8);
            httpPost.setEntity(requestEntity);

            CloseableHttpResponse response = closeableHttpClient.execute(httpPost);
            HttpEntity entity = response.getEntity();

//            InputStream content = entity.getContent();
//            String result = IOUtils.toString(content);
            //Document dc = strXmlToDocument(result);

            if (entity != null) {
                // 打印响应内容
                retStr = EntityUtils.toString(entity, "UTF-8");
                System.out.println("response:" + retStr);
            }
            // 释放资源
            closeableHttpClient.close();
        } catch (Exception e) {
            e.printStackTrace();
        }

        return retStr;
    }
    public static Document strXmlToDocument(String parseStrXml){
        Document document = null;
        try {
            document = DocumentHelper.parseText(parseStrXml);
            Element root = document.getRootElement();
            List<Element> list = root.elements();
            getElement(list);
        } catch (DocumentException e) {
            e.printStackTrace();
        }
        return document;
    }

    // 递归读取子元素
    private static void getElement(List<Element> sonElemetList) {
//        Map<String,String> map = new HashMap<String, String>();
        for (Element sonElement : sonElemetList) {
            if (sonElement.elements().size() != 0) {
                System.out.println(sonElement.getName() + ":");
                getElement(sonElement.elements());
            }else{
                System.out.println(sonElement.getName() + ":"+ sonElement.getText());
            }

        }
    }

}

4.2 Generate Local Client Code

有很多框架可以实现。常见的有Apache CXF，Apache Axis2，Spring-WS

此处使用的是Spring-WS Consuming a SOAP web service

4.2.1 Add dependencies

<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web-services</artifactId>
			<exclusions>
				<exclusion>
					<groupId>org.springframework.boot</groupId>
					<artifactId>spring-boot-starter-tomcat</artifactId>
				</exclusion>
			</exclusions>
		</dependency>	

<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
			<!-- tag::wsdl[] -->
			<plugin>
					<groupId>org.jvnet.jaxb2.maven2</groupId>
					<artifactId>maven-jaxb2-plugin</artifactId>
					<version>0.14.0</version>
					<executions>
						<execution>
							<goals>
								<goal>generate</goal>
							</goals>
						</execution>
					</executions>
					<configuration>
						<schemaLanguage>WSDL</schemaLanguage>
						<generatePackage>com.example.consumingwebservice.wsdl</generatePackage>
						<schemas>
							<schema>
								<url>http://localhost:8080/ws/countries.wsdl</url>
							</schema>
						</schemas>
					</configuration>
			</plugin>
			<!-- end::wsdl[] -->
		</plugins>
	</build>

4.2.2 Generate Domain Objects Based on a WSDL

Use maven-jaxb2-plugin generate code. The generated code is at target/generated-sources

4.2.3 Create a Client

package com.example.consumingwebservice;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import org.springframework.ws.client.core.support.WebServiceGatewaySupport;
import org.springframework.ws.soap.client.core.SoapActionCallback;

import com.example.consumingwebservice.wsdl.GetCountryRequest;
import com.example.consumingwebservice.wsdl.GetCountryResponse;

public class CountryClient extends WebServiceGatewaySupport {

  private static final Logger log = LoggerFactory.getLogger(CountryClient.class);

  public GetCountryResponse getCountry(String country) {

    GetCountryRequest request = new GetCountryRequest();
    request.setName(country);

    log.info("Requesting location for " + country);

    GetCountryResponse response = (GetCountryResponse) getWebServiceTemplate()
        .marshalSendAndReceive("http://localhost:8080/ws/countries", request,
            new SoapActionCallback(
                "http://spring.io/guides/gs-producing-web-service/GetCountryRequest"));

    return response;
  }

}

4.2.4 Configuring Web Service Components

package com.example.consumingwebservice;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.oxm.jaxb.Jaxb2Marshaller;

@Configuration
public class CountryConfiguration {

  @Bean
  public Jaxb2Marshaller marshaller() {
    Jaxb2Marshaller marshaller = new Jaxb2Marshaller();
    // this package must match the package in the <generatePackage> specified in
    // pom.xml
    marshaller.setContextPath("com.example.consumingwebservice.wsdl");
    return marshaller;
  }

  @Bean
  public CountryClient countryClient(Jaxb2Marshaller marshaller) {
    CountryClient client = new CountryClient();
    client.setDefaultUri("http://localhost:8080/ws");
    client.setMarshaller(marshaller);
    client.setUnmarshaller(marshaller);
    return client;
  }

}

4.2.5 Use Client To Call WebService

new Client的实例，和调用本地代码一样，调用WSDL中发布的方法。

可以对Request和Response做一些封装