JavaSE6.0 Web Service学习笔记
Web Service概述
Web Service的定义
W3C组织对其的定义如下，它是一个软件系统，为了支持跨网络的机器间相互操作交互而设计。Web Service服务通常被定义为一组模块化的API，它们可以通过网络进行调用，来执行远程系统的请求服务。
这里我们从一个程序员的视角来观察web service。在传统的程序编码中，存在这各种的函数方法调用。通常，我们知道一个程序模块M中的方法A，向其发出调用请求，并传入A方法需要的参数P，方法A执行完毕后，返回处理结果R。这种函数或方法调用通常发生在同一台机器上的同一程序语言环境下。现在的我们需要一种能够在不同计算机间的不同语言编写的应用程序系统中，通过网络通讯实现函数和方法调用的能力，而Web service正是应这种需求而诞生的。
最普遍的一种说法就是，Web Service = SOAP + HTTP + WSDL。其中，SOAP Simple Object Access Protocol）协议是web service的主体，它通过HTTP或者SMTP等应用层协议进行通讯，自身使用XML文件来描述程序的函数方法和参数信息，从而完成不同主机的异构系统间的计算服务处理。这里的WSDL（Web Services Description Language）web 服务描述语言也是一个XML文档，它通过HTTP向公众发布，公告客户端程序关于某个具体的 Web service服务的URL信息、方法的命名，参数，返回值等。
下面，我们先来熟悉一下SOAP协议，看看它是如何描述程序中的函数方法、参数及结果对象的。
SOAP协议简介
什么是SOAP
SOAP 指简单对象访问协议，它是一种基于XML的消息通讯格式，用于网络上，不同平台，不同语言的应用程序间的通讯。可自定义，易于扩展。一条 SOAP 消息就是一个普通的 XML 文档，包含下列元素：
? Envelope 元素，标识XML 文档一条 SOAP 消息
? Header 元素，包含头部信息的XML标签
? Body 元素，包含所有的调用和响应的主体信息的标签
? Fault 元素，错误信息标签。
以上的元素都在 SOAP的命名空间http://www.w3.org/2001/12/soap-envelope中声明；
SOAP的语法规则
?SOAP 消息必须用 XML 来编码
?SOAP 消息必须使用 SOAP Envelope 命名空间
?SOAP 消息必须使用 SOAP Encoding 命名空间
?SOAP 消息不能包含 DTD 引用
?SOAP 消息不能包含 XML 处理指令
SOAP 消息的基本结构
由于上面的事例XML较长，我们将其逐段分解讲解
WSDL文档的根元素：＜definitions＞
＜message＞元素定义了web service函数的参数。＜message＞元素中的每个＜part＞子元素都和某个参数相符。输入参数在＜message＞元素中定义，与输出参数相隔离，输出参数有自己的＜message＞元素。兼作输入、输出的参数在输入输出的＜message＞元素中有它们相应的＜part＞元素。输出＜message＞元素以"Response"结尾，对Java而言方法得返回值就对应一个输出的＜message＞。每个＜part＞元素都有名字和类型属性，就像函数的参数有参数名和参数类型。
在上面的文档中有两个输入参数、两个输出参数和一个错误参数（对应Java中的Exception）。
?输入参数＜message＞的name属性分别命名为toSayHello，sayHello。
toSayHello对应输入参数userName，参数类型为xsd:string，在Java语言中就是String；
sayHello对应两个输入参数person和arg1，类型为tns:person和xsd:string。这里tns:person类型就是引用了< types >标签中的类型定义。
?输出参数＜message＞的name属性分别命名为toSayHelloResponse和sayHelloResponse。
这个名称和输入参数的＜message＞标签name属性对应，在其后面加上Response尾缀。
toSayHelloResponse对应的返回值是returnWord，参数类型为xsd:string；
sayHelloResponse对应的返回值是personList，参数类型为tns:personArray（自定义类型）；
?错误参数＜message＞的name属性为HelloException。
它的<part>子标签element而不是type来定义类型。
以上的message标签的name属性通常使用web service函数方法名作为参照，错误参数标签则使用异常类名为参照。标签中的参数名称，即part子元素的name属性是可自定义的（下一章节详细说明）。message标签的参数类型将引用types标签的定义。
WSDL文档函数体定义元素：< portType >
<portType> 元素是最重要的 WSDL 元素。它可描述一个 web service、可被执行的操作，以及相关的消息。portType的name属性对应Java中的一个服务类的类名。<portType> 元素使用其子元素< operation>描述一个web service的服务方法。
在<operation>元素中，name属性表示服务方法名，parameterOrder属性表示方法的参数顺序，使用空格符分割多个参数，如：“parameterOrder="person arg1”。<operation>元素的子标签<input>表示输入参数说明，它引用＜message＞标签中的输入参数。<output>表示输出参数说明，它引用＜message＞标签中的输出参数。<fault>标签在Java方法中的特别用来表示异常（其它语言有对应的错误处理机制），它引用＜message＞标签中的错误参数。
WSDL绑定实现定义元素：< binding >
<binding>标签是完整描述协议、序列化和编码的地方，<types>,<message>和<portType>标签处理抽象的数据内容，而<binding>标签是处理数据传输的物理实现。
<binding>标签把前三部分的抽象定义具体化。
首先<binding>标签使用<soap:binding>的transport和style属性定义了Web Service的通讯协议HTTP和SOAP的请求风格RPC。其次<operation>子标签将portType中定义的operation同SOAP的请求绑定，定义了操作名称soapAction，输出输入参数和异常的编码方式及命名空间。
WSDL服务地址绑定元素：< service >
service是一套＜port＞元素。在一一对应形式下，每个＜port＞元素都和一个location关联。如果同一个＜binding＞有多个＜port＞元素与之关联，可以使用额外的URL地址作为替换。
一个WSDL文档中可以有多个＜service＞元素，而且多个＜service＞元素十分有用，其中之一就是可以根据目标URL来组织端口。在一个WSDL文档中，＜service＞的name属性用来区分不同的service。在同一个service中，不同端口，使用端口的"name"属性区分。
这一章节，我们简单的描述了WSDL对SOAP协议的支持，以及在Web Service中的作用。在接下来的章节中，我们将学习如何使用Java6.0的Annotation标签来定义和生成对应的WSDL。
JavaSE6.0下的Web Service
从JavaSE6.0开始，Java引入了对Web Service的原生支持。我们只需要简单的使用Java的Annotation标签即可将标准的Java方法发布成Web Service。（PS：Java Annotation资料请参考 JDK5.0 Annotation学习笔记(一) ）
但不是所有的Java类都可以发布成Web Service。Java类若要成为一个实现了Web Service的bean，它需要遵循下边这些原则：
?这个类必须是public类?这些类不能是final的或者abstract?这个类必须有一个公共的默认构造函数?这个类绝对不能有finalize()方法
下面我们将通过一个具体的Java Web Service代码例子，配合上述的WSDL文件，讲述如何编写JavaSE6.0的原生Web Service应用。
完整的Java Web Service类代码
Annotation 1@WebService(name="Example", targetNamespace="http://www.jsoso.com/wstest", serviceName="Example")
@WebService标签主要将类暴露为WebService，其中targetNamespace属性定义了自己的命名空间，serviceName则定义了< definitions >标签和<service>标签的name属性。
Annotation 2：@SOAPBinding(style=SOAPBinding.Style.RPC)
@SOAPBinding标签定义了WSDL文档中SOAP的消息协议，其中style属性对应SOAP的文档类型，可选的有RPC和DOCUMENT
Annotation 3：@WebMethod(operationName="toSayHello",action="sayHello",exclude=false)
@WebMethod定义Web Service运作的方法,
属性action 对应操作的活动 ，如<soap:operation soapAction="sayHello" />
属性operationName匹配的wsdl:operation 的名称，如<operation name="toSayHello" parameterOrder="userName">
属性exclude 用于阻止将某一继承方法公开为web服务，默认为false
Annotation 4：@WebResult(name="returnWord")
@ WebResult定义方法返回值得名称，如<part name="returnWord" type="xsd:string" />
Annotation 5：@WebParam(partName="person", mode=Mode.IN
@WebParam定义方法的参数名称，如<part name="person" type="tns:person" />，其中mode属性表示参数的流向，可选值有IN / OUT / INOUT
这里要着重说明的是，上述Web Service类的sayHello方法中，带有HelloException这个异常声明，造成该服务类不能直接发布成Web Service。需要使用wsgen工具为其生存异常Bean。关于wsgen工具的使用，请参考wsgen与wsimport命令说明
发布一个的Java Web Service
在完成了上述的Web Service Annotation注释后，我们使用wsgen工具为其进行服务资源文件的构造（这里主要是生成一个名为org.jsoso.jws.server.jaxws.HelloExceptionBean的异常bean类），最后使用以下的类发布Web 服务：
届此，本次Web Service的学习暂告一个段落。Java Web Service是一个相当庞大的知识体系，其中涉及的相关技术较多，这里无法一一道来，我们将会在今后的开发和使用中，同大家做进一步深入的探讨和学习。
附录：wsgen与wsimport命令说明
wsgen
wsgen是在JDK的bin目录下的一个exe文件（Windows版），该命令的主要功能是用来生成合适的JAX-WS。它读取Web Service的终端类文件，同时生成所有用于发布Web Service所依赖的源代码文件和经过编译过的二进制类文件。这里要特别说明的是，通常在Web Service Bean中用到的异常类会另外生成一个描述Bean，如果Web Service Bean中的方法有申明抛出异常，这一步是必需的，否则服务器无法绑定该对像。此外，wsgen还能辅助生成WSDL和相关的xsd文件。wsgen从资源文件生成一个完整的操作列表并验证web service是否合法，可以完整发布。
命令参数说明：
?-cp 定义classpath?-r 生成 bean的wsdl文件的存放目录?-s 生成发布Web Service的源代码文件的存放目录（如果方法有抛出异常，则会生成该异常的描述类源文件）?-d 生成发布Web Service的编译过的二进制类文件的存放目录（该异常的描述类的class文件）
命令范例：wsgen -cp ./bin -r ./wsdl -s ./src -d ./bin -wsdl org.jsoso.jws.server.Example
wsimport
wsimport也是在JDK的bin目录下的一个exe文件（Windows版），主要功能是根据服务端发布的wsdl文件生成客户端存根及框架，负责与Web Service 服务器通信，并在将其封装成实例，客户端可以直接使用，就像使用本地实例一样。对Java而言，wsimport帮助程序员生存调用web service所需要的客户端类文件.java和.class。要提醒指出的是，wsimport可以用于非Java的服务器端，如：服务器端也许是C#编写的web service，通过wsimport则生成Java的客户端实现。
命令参数说明：
?-d 生成客户端执行类的class文件的存放目录?-s 生成客户端执行类的源文件的存放目录?-p 定义生成类的包名
命令范例：wsimport -d ./bin -s ./src -p org.jsoso.jws.client.ref http://localhost:8080/hello?wsdl
1 楼 milk_36 2008-03-30 刚刚拜读过你的帖子后 感觉非常值得一读 全文阐述清晰详细！
在这里我想问一个webservices中的问题，希望有所答案。
在对webservices调用时出现了以下异常信息：
SOAP 版本可能不匹配: 出现意外的 Envelope 命名空间 http://schemas.xmlsoap.org/wsdl/。应为 http://schemas.xmlsoap.org/soap/envelope/
我不明白我用的是xfrie为什么会提示命名空间的问题，这个跟我的版本有关吗？
但是我用java client调用的时候不会出问题，用.net client调用的时候就会包上面的异常！在网上搜索很久后没有答案！ 2 楼 linliangyi2007 2008-03-30 你提到的http://schemas.xmlsoap.org/wsdl/是wsdl文件的schema，而http://schemas.xmlsoap.org/soap/envelope/ 是soap的schema，两个是完全不同的描述文件。检查一下是不是配置问题了？
java client调用不出问题，只能说它没有对schema做检查。
3 楼 Joo 2008-04-24 最近正好也在做JAX-WS，很高兴能看到这样一篇详尽的文档
另外有个问题想请教你：
引用
但是Web Services的Best Practies并不推荐Code First这一Web Services的构建方式。原因是什么呢？
这是因为我们在使用Code First构建方式时很少考虑到Web Services之间的交互是以文档方式进行（这样可以大大提高Web Services的互交互性），如果是使用Code First来构建WSDL信息，在描述描述交互信息的XML Schema都是以我们的Code中定义的类型信息来生成的，这样就可能会暴露一些比较细粒度的信息。同时大家知道不同的语言（C＋＋，Java， C＃，PHP）对XML Schema映射是各不相同的，如果我们Code中定义的类型很特殊，就可能产生出一个不能互操作的现象。
所以Best Practies建议你在创建Web Services从交互的消息Schema入手，构建一个中间层来提供一个比较粗粒度的描述，这样可以比较好的解决Web Services的互交互问题。
正好在学习JAX-WS的时候里面不太理解@SOAPBinding注解的意思，里面的Document/Literal或者RPC/literal方式究竟是不是就是这里提到的“Web Services之间的交互是以文档方式进行”？
另外，即便是采用WSDL first的方式，定义文档中仍然会涉及到具体的XSD类型阿，难道这样就不算是细粒度的描述了吗？ 4 楼 mfc42d 2008-04-24 soap 某种程度来说是种失败的设计 5 楼 jeff_yuchang 2008-04-24 Joo 写道最近正好也在做JAX-WS，很高兴能看到这样一篇详尽的文档
另外有个问题想请教你：
引用
但是Web Services的Best Practies并不推荐Code First这一Web Services的构建方式。原因是什么呢？
这是因为我们在使用Code First构建方式时很少考虑到Web Services之间的交互是以文档方式进行（这样可以大大提高Web Services的互交互性），如果是使用Code First来构建WSDL信息，在描述描述交互信息的XML Schema都是以我们的Code中定义的类型信息来生成的，这样就可能会暴露一些比较细粒度的信息。同时大家知道不同的语言（C＋＋，Java， C＃，PHP）对XML Schema映射是各不相同的，如果我们Code中定义的类型很特殊，就可能产生出一个不能互操作的现象。
所以Best Practies建议你在创建Web Services从交互的消息Schema入手，构建一个中间层来提供一个比较粗粒度的描述，这样可以比较好的解决Web Services的互交互问题。
正好在学习JAX-WS的时候里面不太理解@SOAPBinding注解的意思，里面的Document/Literal或者RPC/literal方式究竟是不是就是这里提到的“Web Services之间的交互是以文档方式进行”？
另外，即便是采用WSDL first的方式，定义文档中仍然会涉及到具体的XSD类型阿，难道这样就不算是细粒度的描述了吗？
Document就是以文档方式交互, RPC就是最早的那种调用，不是文档. 具体的有Document/Literal, Document/Wrapper.这2个属于文档的，现在JAX-WS不推荐用RPC的了.
6 楼 Joo 2008-04-24 不明白你说的以文档方式交互式什么意思
通过SOAP进行交互不都是通过XML文档形式么? 只是我现在手头有一个任务是需要通过web服务来在两个异构的系统之间(Biztalk and JavaEE)传递XML文档.注意,是要传输的数据本身是XML文档
7 楼 melin 2008-04-24 看看这篇文章就明白了
我应该采用哪一种 WSDL 样式？
http://www-128.ibm.com/developerworks/cn/webservices/ws-whichwsdl/ 8 楼 Joo 2008-04-24 melin 写道看看这篇文章就明白了
我应该采用哪一种 WSDL 样式？
http://www-128.ibm.com/developerworks/cn/webservices/ws-whichwsdl/
看了,类似这样比较的文章也看了有几个 说实话 还是懵懵懂懂的 感觉貌似跟我的问题牛头不对马嘴阿
妈的发现IDE的代码生成害死人
一个ws项目作下来竟然还有人不知道wsgen和wsimport ... 9 楼 点子二木 2008-11-04 如此详细，一定拜读多次 10 楼 ShowNothing 2009-02-25 刚看到您的帖子，还希望你能再回首，呵呵 想请教您学习的时候用的是什么资料（教材等），谢谢。因为现在感觉不好找WEB SERVICES的教材。
