NO END FOR LEARNING

Writing blog if you feel tired | 学海无涯 苦写博客

Spring Web Service by Example

| Comments

Web Service是一种独立的、低耦合的Web服务，它由几个核心技术组成：XML、XSD、WSDL、SOAP、UDDI。我们根据这些知识点，来一个个的学习。

XML

呵呵，这个太简单了，这个没什么好谈的，跳过。

XSD

XSD（XML Schema Definition）是DTD（Document Type Definition）的替代品，作用是定义XML文档的合法构建模块。

它能够做的事情有很多：

  1. 定义可出现在文档中的元素
  2. 定义可出现在文档中的属性
  3. 定义哪个元素是子元素
  4. 定义子元素的次序
  5. 定义子元素的数目
  6. 定义元素是否为空，或者是否可包含文本
  7. 定义元素和属性的数据类型
  8. 定义元素和属性的默认值以及固定值

….

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           targetNamespace="http://benweizhu.github.io"
           elementFormDefault="qualified">
    <xs:element name="SearchBookRequest">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="name" type="xs:string"/>
                <xs:element name="author" type="xs:string" minOccurs="0"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <xs:element name="SearchBookResponse">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="id" type="xs:int"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

</xs:schema>

我们来分析一下这个schema的含义：

（1）xmlns:xs= “http://www.w3.org/2001/XMLSchema“，它表示在这个schema中使用的元素，例如element，complexType，sequence等，都来自于命名空间”http://www.w3.org/2001/XMLSchema“，并且在使用这些元素时，要以xs最为前缀。

（2）targetNamespace= “http://benweizhu.github.io“，它表示在这个schema中定义的元素，例如SearchBookRequest，name，author等，都是来自于命名空间”http://benweizhu.github.io“。它表示在基于该schema构建XML时，XML中使用的元素来自于该命名空间。

1
2
3
4

<z:SearchBookRequest xmlns:z="http://benweizhu.github.io">
    <z:name>SpringWebService</z:name>
    <z:author>Spring</z:author>
</z:SearchBookRequest>

（3）xmlns=“http://benweizhu.github.io“，指定了一个默认的命名空间，什么意思呢？就是说如果schema中使用的元素，没有xs这样前缀，则都是来自于这个默认的命名空间的。

（4）elementFormDefault=“qualified”，指出任何在XML实例文档所使用的元素，只要在此schema中声明过，就必须被命名空间限定。

（5）<xs:element name=“xxx” type=“yyy”/>，此处 xxx 指元素的名称，yyy 指元素的数据类型。XML Schema 拥有很多内建的数据类型。最常用的类型有：

  • xs:string
  • xs:decimal
  • xs:integer
  • xs:boolean
  • xs:date
  • xs:time

（6）复杂元素，定义复杂元素的方式有两种，例子已经在上面给出，一种是直接在元素内部定义，一种是通过type引用该复杂类型。

（7）属性，element元素包含有很多的属性，例如，minOccurs=“0”，它表示出现最少次数为0，就是说这个元素是optional的，可选的。

SOAP

SOAP（Simple Object Access Protocol，简单对象访问协议），是交换数据的一种协议规范，它是一种通信协议，基于XML，用于发送和接受消息，它是真正在WebService的服务端和客户端传送的信息。

SOAP使用应用层协议作为其传输协议。SMTP以及HTTP协议都可以用来传输SOAP消息，但是由于HTTP在如今的因特网结构中工作得很好，特别是在网络防火墙下仍然正常工作，所以被广泛采纳。

SOAP基于XML，所以归根到底，SOAP发送的消息就是一个XML格式的文档消息。

一条SOAP消息的基本结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<?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>
  ...
</soap:Header>
<soap:Body>
  ...
  <soap:Fault>
    ...
  </soap:Fault>
</soap:Body>
</soap:Envelope>

一条SOAP消息包含下列元素：

  1. 必需的Envelope元素，它是用来将一个XML文档标识为一条SOAP消息。
  2. 可选的Header元素，包含头部信息
  3. 必需的Body元素，包含所有的调用和响应信息
  4. 可选的Fault元素，提供有关在处理此消息所发生错误的信息

所有以上的元素均被声明为，命名空间 http://www.w3.org/2001/12/soap-envelope 中的元素，以及针对SOAP编码和数据类型的命名空间： http://www.w3.org/2001/12/soap-encoding 。

关于 xmlns:soap=“http://www.w3.org/2001/12/soap-envelope” 应该比较容易理解，在上面的XSD介绍中已经解释过了，用于说明该XML的命名空间，相当于该SOAP的XSD中的targetNamespace。

可选的SOAP Header元素可包含有关SOAP消息的应用程序专用信息（比如认证、支付等）。如果Header元素被提供，则它必须是Envelope元素的第一个子元素。

1
2
3

<soap:Header>
<m:Trans xmlns:m="http://www.w3school.com.cn/transaction/" soap:mustUnderstand="1">234</m:Trans>
</soap:Header>

必需的SOAP Body元素包含打算传送到消息最终端点的实际SOAP消息。

1
2
3
4
5
6

<soap:Body>
  <z:SearchBookRequest xmlns:z="http://benweizhu.github.io">
    <z:name>SpringWebService</z:name>
    <z:author>Spring</z:author>
  </z:SearchBookRequest>
</soap:Body>

而可选的SOAP Fault元素用于指示错误消息。

WSDL

WSDL指网络服务描述语言(Web Services Description Language)，也就是WebService的描述语言。

WSDL是一种使用XML编写的文档。这种文档用于描述某个web service，规定服务的位置，以及此服务提供的操作（或方法）。

一个WSDL文档是由如下几种元素组成： 元素定义:\, \, \, \

WSDL类型

\元素定义web service使用的数据类型。为了最大程度的平台中立性，WSDL使用XML Schema语法来定义数据类型。

WSDL消息

\元素定义一个操作的数据元素。每个消息均由一个或多个部件组成。可以把这些部件比作传统编程语言中一个函数调用的参数。

WSDL端口

\元素是最重要的WSDL元素。它可描述一个web service、可被执行的操作，以及相关的消息。可以把\元素比作传统编程语言中的一个函数库（或一个模块、或一个类）。

WSDL绑定协议

\ 元素为每个端口定义消息格式和协议细节。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<definitions>
    <types>
        definition of types........
    </types>
    <message>
        definition of a message....
    </message>
    <portType>
        definition of a port.......
    </portType>
    <binding>
        definition of a binding....
    </binding>
</definitions>

这里要说明一点，WSDL是WebService的描述语言，只是用来描述WebService，当客户端想要使用该WebService时，根据这个描述，可以知道该WebService的服务端口有哪些，服务内容有什么。但对于WebService本身的功能没有任何影响，换句话说，如果是你自己写的WebService，提供给自己使用，你根本不需要关心WSDL是什么，因为你知道自己提供的服务内容和端口。

关于这点，我会在后面的Spring WebService代码中证明。

Spring WebService

OK，到这里几个重要的概念都谈到了，应该开始正题，如果上面的内容没看懂，特别是WSDL，没关系，接下来，我们根据Spring WebService的例子，来一个个分析。

Contract First 契约优先

首先实现WebService的消息通信协议，也就是提供什么样的服务，接收什么消息，返回什么消息。

根据前面的知识：要根据XSD来约束发送和接收的XML长什么样子。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           targetNamespace="http://benweizhu.github.io"
           elementFormDefault="qualified">
    <xs:element name="SearchBookRequest">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="name" type="xs:string"/>
                <xs:element name="author" type="xs:string" minOccurs="0"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <xs:element name="SearchBookResponse">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="id" type="xs:int"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

在这个例子中，我提供了一个图书搜索的服务，传给我书名name和作者author，我返回对应书的id。

根据这个XSD文件，发送出去的请求的XML的应该是长类似下面这个样子：

1
2
3
4

<z:SearchBookRequest xmlns:z="http://benweizhu.github.io">
    <z:name>SpringWebService</z:name>
    <z:author>Spring</z:author>
</z:SearchBookRequest>

JAXB

根据这个定义的XSD文件，可以生成对应的Java类文件，这一步很简单，在Eclipse或者IntellIj中都有提供XSD到Java文件的转换插件。你只需要转换一下，就会生成的两个类SearchBookRequest和SearchBookResponse，它们会在下面的Endpoint中被使用。

Endpoint

实现Endpoint，也就是，这个请求消息给服务端后，有谁来处理，并返回响应结果。

Spring提供了注解的方式来配置一个Endpoint。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

package me.zeph.spring.ws.example.endpoint;

import jaxbgen.SearchBookRequest;
import jaxbgen.SearchBookResponse;
import org.springframework.ws.server.endpoint.annotation.Endpoint;
import org.springframework.ws.server.endpoint.annotation.PayloadRoot;
import org.springframework.ws.server.endpoint.annotation.RequestPayload;
import org.springframework.ws.server.endpoint.annotation.ResponsePayload;

@Endpoint
public class BookEndpoint {

  @PayloadRoot(localPart = "SearchBookRequest", namespace = "http://benweizhu.github.io")
  public @ResponsePayload SearchBookResponse searchBook(@RequestPayload SearchBookRequest searchBookRequest) {
      SearchBookResponse searchBookResponse = new SearchBookResponse();
      searchBookResponse.setId(1);
      return searchBookResponse;
  }
}

第一个注解@Endpoint不用我解释了，就是说明这个类是一个WebService的Endpoint。 第二个注解@PayloadRoot里面有两个参数，localPart和namespace，它们分别匹配到XML中的根元素名字和命名空间，也就是说，如果发送过来消息的满足这两个条件，就交给该函数处理。这样就形成了消息到Endpoint的映射。 第三和第四个注解@RequestPayload和@ResponsePayload就简单了，分别用来指明请求和响应的对象。

Spring的XML配置

配置比较简单，提供组件扫描和对Endpoint注解的支持即可。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:sws="http://www.springframework.org/schema/web-services"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
      http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
      http://www.springframework.org/schema/web-services
      http://www.springframework.org/schema/web-services/web-services-2.0.xsd
      http://www.springframework.org/schema/context
      http://www.springframework.org/schema/context/spring-context.xsd">

    <sws:annotation-driven/>

    <context:component-scan base-package="me.zeph.spring.ws.example"/>

</beans>

web.xml

最后再来看web.xml怎么配置。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4"
         xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
         http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
    <servlet>
        <servlet-name>spring-ws</servlet-name>
        <servlet-class>org.springframework.ws.transport.http.MessageDispatcherServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>spring-ws</servlet-name>
        <url-pattern>/services/*</url-pattern>
    </servlet-mapping>
</web-app>

和SpringMVC一样，WebService也需要一个前端的请求分发的Servlet，MessageDispatcherServlet。你可能会想为什么是Servlet？

其实，这点，我在前面已经提到过，WebService的协议是绑定在Soap上面的，而Soap又是以http协议作为应用层协议的载体，发出去的Request固然是http请求。不配置对应Servlet，不配置对应的URL，那应该怎么做呢？

到此为止，一个Spring Web Service的服务端代码就写完了。你肯定会想，说好的WSDL呢？它去哪了？我这里刻意没有配置WSDL，就是要证明WSDL本身对于WebService没有影响，所以WSDL可以不用配。

我们先把WSDL放在一边，先把客户端代码完成。

Spring WebService Template 客户端

这里的客户端代码使用Spring提供的WebServiceTemplate完成。

在applicationContext中配置WebServiceTemplate，如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

    <bean id="webServiceTemplate" class="org.springframework.ws.client.core.WebServiceTemplate">
        <property name="defaultUri" value="http://localhost:8080/spring-ws/services/"/>
        <property name="marshaller" ref="marshaller"/>
        <property name="unmarshaller" ref="marshaller"/>
    </bean>

    <bean id="marshaller" class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
        <property name="packagesToScan">
            <list>
                <value>jaxbgen</value>
            </list>
        </property>
    </bean>
</beans>

defaultUri用来说明该Template会向哪个URL发出请求。关于这个URL，因为在web.xml配置时，该MessageServlet是接受spring-ws/services/*的任何请求，而Spring WebService的Endpoint映射并不是根据URL来判断，所以这里你可以写任何满足该模式的URL，例如： http://localhost:8080/spring-ws/services/ssss 。

Marshaller用于实现XML到Java和Java到XML的转换。在Template需要配置marshaller和unmarshaller，这里它们用的同一个Marshaller对象。

客户端Java代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

package integration;

import jaxbgen.SearchBookRequest;
import jaxbgen.SearchBookResponse;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.ws.client.core.WebServiceTemplate;

import static org.hamcrest.CoreMatchers.is;
import static org.junit.Assert.assertThat;

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = {"classpath:applicationContext.xml"})
public class BookClientIntegrationTest {

  @Autowired
  private WebServiceTemplate webServiceTemplate;

  @Test
  public void shouldGetResponseFromWebService() {
      //given
      SearchBookRequest searchBookRequest = new SearchBookRequest();

      //when
      SearchBookResponse searchBookResponse = (SearchBookResponse) webServiceTemplate.marshalSendAndReceive(searchBookRequest);

      //then
      assertThat(searchBookResponse.getId(), is(1));
  }
}

OK，到此为止，Spring WebService的服务端和客户端代码完成。

所以，现在我们再回过头来，看看WSDL。

WSDL

Automatic WSDL exposure 自动生成WSDL

在刚才的Spring XML配置中（/WEB-INF/[servlet-name]-servlet.xml）中加一段XML配置：

1
2
3
4

<sws:dynamic-wsdl id="book" portTypeName="SearchBookRequest"
                      locationUri="http://tobereplacedbyws:8080/spring-ws/services/">
        <sws:xsd location="classpath:book.xsd"/>
</sws:dynamic-wsdl>

要注意位置有两点：

  1. 属性id，除了唯一指定一个元素之外，它还有个更重要的作用，是说明该wsdl的名字。当你要访问该wsdl时，访问的url是 http://localhost:8080/spring-ws/services/book.wsdl 。
  2. 属性locationUri，前面已经看到WSDL跟WebService的功能性服务没有半毛钱关系，所以这里的locationUri属性配置也不会影响到WebService的功能，它只是在你在wsdl中看到的一个字段，用来描述服务端的服务端口（URL）是什么。如果你看上面例子中的locationUri，你会发现不是写的localhost，而是tobereplacedbyws。为什么呢？因为MessageDispatcherServlet提供了一个特性，可以在部署时，根据主机的名字，替换这个位置的内容。如何开启这个特性呢？

在web.xml中配置一个initparam即可。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4"
         xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
         http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

    <servlet>
        <servlet-name>spring-ws</servlet-name>
        <servlet-class>org.springframework.ws.transport.http.MessageDispatcherServlet</servlet-class>
        <init-param>
            <param-name>transformWsdlLocations</param-name>
            <param-value>true</param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>spring-ws</servlet-name>
        <url-pattern>/services/*</url-pattern>
    </servlet-mapping>

</web-app>

这个时候，你访问 http://localhost:8080/spring-ws/services/book.wsdl ，就可以看到对应的WSDL信息，然后你就可以用SoapUI等类似软件去测试你的Webservice。

参考资料：

(1) spring webservice reference

(2) http://www.w3school.com.cn/ws.asp

了解war包和ear包

| Comments

上一次，讲到了如何如何手动编译Java，简单的介绍打Jar包（提示：在classpath的基础上，一定将包的目录结构打进去）。Jar包的目的，将编译过的class文件有效合理的组装起来，方便管理和使用。这一次，滕老板继续跟我们讲解了如何打War包。

在本篇文章中，将分别介绍War包和Ear包（在项目中遇到的Ear包的模块，不清楚是什么，所以随便一起弄清楚）。

War包

只要做过Java开发的同志，肯定知道War包，至少听说过。

War包（Web application ARchieve）也是一种Jar包文件，它被用来描述由JSP，Servlet，Java类，XML文件，tag库，静态web页面等资源组成的集合，它们组合在一起成文一个web应用。

从命令上说，打War包的命令和打Jar包的命令一样，比较简单，主要是要了解一个War包的目录结构：

MANIFEST.MF是一个可选文件，用来描述额外的元数据信息。

WEB-INF目录包含了War中的私有文件，也就是说，当web应用被部署之后，该目录下的文件不能够由Web客户端（浏览器）直接访问的。

WEB-INF/lib/用来放置你代码中需要使用的第三方的jar文件。

WEB-INF/classes/用来放置你自己编译的class文件。

WEB-INF/web.xml是web部署描述器，JavaEE配置web模块的标准描述器，这里不详细解释。

最后是公共的静态文件。

那么在打包的时候，按照这个目录结构打包，然后将War包放置到tomcat的webapp目录下，tomcat在运行时就会自动帮你解包并运行，或者你也可以直接将包含该目录结构的目录直接拷贝到tomcat的webapp下，一样可以运行，打包只不过是一个封装和压缩过程。

那什么是Ear包呢？

Ear(Enterprise ARchieve)用于在Java EE中将一个或者多个模块封装到一个文件中，这样，多个不同模块在应用服务器上的部署就可以同时并持续的进行。

Java EE应用以Jar文件，War文件和Ear文件形式呈现。War或者Ear文件都是标准的Jar文件，只不过扩展名是.war和.ear。通过Jar，War和Ear等文件或模块的方式，使得用一些相同组件，来构建不同的JavaEE应用成为可能。不需要额外的编码，只需要将不同的JavaEE模块打包到不同的Java EE的Jar包，War包或Ear包的文件中。

一个Ear文件是由Java EE模块和可选的部署描述器组成。部署描述器是一个带有.xml扩展名的XML文档，描述了一个应用，模块或者组件的部署设置。因为部署描述其的信息是声明式的，所以可以直接修改它，与我们的源代码没有关系。在运行时中，Java EE的服务器会读取部署描述器的内容，并根据描述对应用，模块或者组件做相对应的操作。

上面两个图，分别摘自Jboss at Work(A practice guide)和JavaEE6 Tutorial。

一个Java EE模块是由一个或者多个为同一个容器类型准备的Java EE组件组成，当然还包含一个可选的部署描述器文件。

Java EE模块有以下几种类型：

EJB模块，它包含企业级别的bean类文件，一个EJB的部署描述器（可选），EJB模块会以Jar包形式组装。

Web模块，它包含了servlet类文件，web文件，其他相关class文件，图片，html静态文件，和一个web.xml部署文件（可选），并最终以war包形式组装。

应用客户端模块，包含了class文件，应用客户端部署描述器文件（可选）并以Jar包形式组装。

资源适配模块，包含所有的Java接口，类，原生库，部署描述器（可选）。组合在一起，实现JavaEE的Connector架构。同样是以Jar包方式组装，但是文件以.rar扩展名结尾。

就和War包包含一个web.xml的部署描述器，一个Ear包文件包含一个名字为application.xml的文件。它是一个必要的打包列表，告诉Java EE服务器Ear包种包含什么东西，以及去哪里找。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee             http://java.sun.com/xml/ns/j2ee/application_1_4.xsd"
             version="1.4">
    <display-name>JBossAtWorkEAR</display-name>
    <module>
        <web>
            <web-uri>webapp.war</web-uri>
            <context-root>jaw</context-root>
        </web>
    </module>
    <module>
        <java>common.jar</java>
    </module>
</application>

application.xml中的元素都应该是自解释的。在告诉应用程序服务器每一个Jar包的名字，以及它的作用（功能）。

例如：

1
2
3
4
5
6

<module>
    <web>
        <web-uri>webapp.war</web-uri>
        <context-root>jaw</context-root>
    </web>
</module>

用来告诉你web应用站点名字，如果你是直接打成War包，那么War包的名字就是这个站点名。

总而言之，Ear包是由Java EE多个模块组成，相互配合，完成各自职责，形成完整的Java EE应用。

参考资料：

http://docs.oracle.com/javaee/6/tutorial/doc/bnaby.html

Jboss at work A practice guide(Chapter 3)(http://oreilly.com/catalog/jboss/chapter/ch03.pdf)