webservice学习笔记
Web Service概述 Web Service的定义 这里我们从一个程序员的视角来观察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的命名空间http://www.w3.org/2001/12/soap-envelope中声明; SOAP 消息的基本结构 <? 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 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">
...
Message information goes here
...
</soap:Envelope>
SOAP Header 元素 actor 属性,语法soap:actor=”URI” 通过沿着消息路径经过不同的端点,SOAP 消息可从某个发送者传播到某个接收者。并非 SOAP 消息的所有部分均打算传送到 SOAP 消息的最终端点,不过,另一个方面,也许打算传送给消息路径上的一个或多个端点。SOAP 的 actor 属性可被用于将 Header 元素寻址到一个特定的端点。 mustUnderstand 属性 ,语法soap:mustUnderstand=”0|1” SOAP 的 mustUnderstand 属性可用于标识标题项对于要对其进行处理的接收者来说是强制的还是可选的。假如您向 Header 元素的某个子元素添加了 “mustUnderstand=”1”,则要求处理此头部的接收者必须认可此元素。 <? 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.jsoso.net/transaction/"
soap:mustUnderstand="1"
soap:actor="http://www.w3schools.com/appml/ “ >234</m:Trans> </soap:Header> ... ... </soap:Envelope>
SOAP Body 元素 <? 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:Body>
<m:GetPrice xmlns:m="http://www.jsoso.net/prices">
<m:Item>Apples</m:Item>
</m:GetPrice>
</soap:Body>
</soap:Envelope>
上面的例子请求苹果的价格。请注意,上面的 m:GetPrice 和 Item 元素是应用程序专用的元素。它们并不是 SOAP 标准的一部分。而对应的 SOAP 响应应该类似这样: <?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:Body>
<m:GetPriceResponse xmlns:m="http://www.jsoso.net/prices">
<m:Price>1.90</m:Price>
</m:GetPriceResponse>
</soap:Body>
</soap:Envelope>
SOAP Fault 元素 常用的SOAP Fault Codes HTTP协议中的SOAP 实例 下面的例子中,一个 GetStockPrice 请求被发送到了服务器。此请求有一个 StockName 参数,而在响应中则会返回一个 Price 参数。此功能的命名空间被定义在此地址中: “http://www.jsoso.net/stock” SOAP 请求:(注意HTTP的Head属性) POST /InStock HTTP/1.1
Host: www.jsoso.net
Content-Type: application/soap+xml; charset=utf-8
Content-Length: XXX
<? 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:Body xmlns:m="http://www.jsoso.net/stock"> <m:GetStockPrice> <m:StockName>IBM</m:StockName> </m:GetStockPrice> </soap:Body> </soap:Envelope>
SOAP 响应:(注意HTTP的Head属性) HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: XXX
<? 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:Body xmlns:m="http://www.jsoso.net/stock"> <m:GetStockPriceResponse> <m:Price>34.5</m:Price> </m:GetStockPriceResponse> </soap:Body> </soap:Envelope>
WSDL简介 WSDL文档可以分为两部分。顶部分由抽象定义组成,而底部分则由具体描述组成。抽象部分以独立于平台和语言的方式定义SOAP消息,它们并不包含任何随机器或语言而变的元素。这就定义了一系列服务,截然不同的应用都可以实现。具体部分,如数据的序列化则归入底部分,因为它包含具体的定义。在上述的文档元素中,、、属于抽象定义层,、属于具体定义层。所有的抽象可以是单独存在于别的文件中,也可以从主文档中导入。 WSDL文档的结构实例解析 <?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://www.jsoso.com/wstest" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.xmlsoap.org/wsdl/" targetNamespace="http://www.jsoso.com/wstest" name="Example">
<types>
<xsd:schema>
<xsd:import namespace="http://www.jsoso.com/wstest" schemaLocation="http://localhost:8080/hello?xsd=1"></xsd:import>
</xsd:schema>
</types>
<message name="toSayHello">
<part name="userName" type="xsd:string"></part>
</message>
<message name="toSayHelloResponse">
<part name="returnWord" type="xsd:string"></part>
</message>
<message name="sayHello">
<part name="person" type="tns:person"></part>
<part name="arg1" type="xsd:string"></part>
</message>
<message name="sayHelloResponse">
<part name="personList" type="tns:personArray"></part>
</message>
<message name="HelloException">
<part name="fault" element="tns:HelloException"></part>
</message>
<portType name="Example">
<operation name="toSayHello" parameterOrder="userName">
<input message="tns:toSayHello"></input>
<output message="tns:toSayHelloResponse"></output>
</operation>
<operation name="sayHello" parameterOrder="person arg1">
<input message="tns:sayHello"></input>
<output message="tns:sayHelloResponse"></output>
<fault message="tns:HelloException" name="HelloException"></fault>
</operation>
</portType>
<binding name="ExamplePortBinding" type="tns:Example">
<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"></soap:binding>
<operation name="toSayHello">
<soap:operation soapAction="sayHello"></soap:operation>
<input>
<soap:body use="literal" namespace="http://www.jsoso.com/wstest"></soap:body>
</input>
<output>
<soap:body use="literal" namespace="http://www.jsoso.com/wstest"></soap:body>
</output>
</operation>
<operation name="sayHello">
<soap:operation soapAction="sayHello"></soap:operation>
<input>
<soap:body use="literal" namespace="http://www.jsoso.com/wstest"></soap:body>
</input>
<output>
<soap:body use="literal" namespace="http://www.jsoso.com/wstest"></soap:body>
</output>
<fault name="HelloException">
<soap:fault name="HelloException" use="literal"></soap:fault>
</fault>
</operation>
</binding>
<service name="Example">
<port name="ExamplePort" binding="tns:ExamplePortBinding">
<soap:address location="http://localhost:8080/hello"></soap:address>
</port>
</service>
</definitions>
由于上面的事例XML较长,我们将其逐段分解讲解 WSDL文档的根元素:<definitions> <definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://www.jsoso.com/wstest" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://schemas.xmlsoap.org/wsdl/" targetNamespace="http://www.jsoso.com/wstest" name="Example">
……
……
</definitions>
<definitions>定义了文档中用到的各个xml元素的namespace缩写,也界定了本文档自己的targetNamespace=”http://www.jsoso.com/wstest”,这意味着其它的XML要引用当前XML中的元素时,要声明这个namespace。注意xmlns:tns=”http://www.jsoso.com/wstest”这个声明,它标示了使用tns这个前缀指向自身的命名空间。 引用 <types>
<xsd:schema>
<xsd:import namespace="http://www.jsoso.com/wstest" schemaLocation="http://localhost:8080/hello?xsd=1"></xsd:import>
</xsd:schema>
</types>
标签定义了当前的WSDL文档用到的数据类型。要说明的是,为了最大程度的平台中立性,WSDL 使用 XML Schema 语法来定义数据类型。这些数据类型用来定义web service方法的参数和返回指。对于通用的原生数据类型如:integer,boolean,char,float等,在W3C的标准文档http://www.w3.org/2001/XMLSchema中已经做了定义。这里我们要引入的schema定义schemaLocation=”http://localhost:8080/hello?xsd=1”是我们自定义的Java对象类型。 WSDL文档消息体定义元素:< message > <message name="toSayHello">
<part name="userName" type="xsd:string"></part>
</message>
<message name="toSayHelloResponse">
<part name="returnWord" type="xsd:string"></part>
</message>
<message name="sayHello">
<part name="person" type="tns:person"></part>
<part name="arg1" type="xsd:string"></part>
</message>
<message name="sayHelloResponse">
<part name="personList" type="tns:personArray"></part>
</message>
<message name="HelloException">
<part name="fault" element="tns:HelloException"></part>
</message>
<message>元素定义了web service函数的参数。<message>元素中的每个<part>子元素都和某个参数相符。输入参数在<message>元素中定义,与输出参数相隔离,输出参数有自己的<message>元素。兼作输入、输出的参数在输入输出的<message>元素中有它们相应的<part>元素。输出<message>元素以”Response”结尾,对Java而言方法得返回值就对应一个输出的<message>。每个<part>元素都有名字和类型属性,就像函数的参数有参数名和参数类型。 在上面的文档中有两个输入参数、两个输出参数和一个错误参数(对应Java中的Exception)。 ? 输入参数<message>的name属性分别命名为toSayHello,sayHello。 ? 输出参数<message>的name属性分别命名为toSayHelloResponse和sayHelloResponse。 ? 错误参数<message>的name属性为HelloException。 以上的message标签的name属性通常使用web service函数方法名作为参照,错误参数标签则使用异常类名为参照。标签中的参数名称,即part子元素的name属性是可自定义的(下一章节详细说明)。message标签的参数类型将引用types标签的定义。 WSDL文档函数体定义元素:< portType > <portType name="Example">
<operation name="toSayHello" parameterOrder="userName">
<input message="tns:toSayHello"></input>
<output message="tns:toSayHelloResponse"></output>
</operation>
<operation name="sayHello" parameterOrder="person arg1">
<input message="tns:sayHello"></input>
<output message="tns:sayHelloResponse"></output>
<fault message="tns:HelloException" name="HelloException"></fault>
</operation>
</portType>
元素是最重要的 WSDL 元素。它可描述一个 web service、可被执行的操作,以及相关的消息。portType的name属性对应Java中的一个服务类的类名。 元素使用其子元素< operation>描述一个web service的服务方法。 在元素中,name属性表示服务方法名,parameterOrder属性表示方法的参数顺序,使用空格符分割多个参数,如:“parameterOrder=”person arg1”。元素的子标签表示输入参数说明,它引用<message>标签中的输入参数。表示输出参数说明,它引用<message>标签中的输出参数。标签在Java方法中的特别用来表示异常(其它语言有对应的错误处理机制),它引用<message>标签中的错误参数。 WSDL绑定实现定义元素:< binding > <binding name="ExamplePortBinding" type="tns:Example">
<soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"></soap:binding>
<operation name="toSayHello">
<soap:operation soapAction="sayHello"></soap:operation>
<input>
<soap:body use="literal" namespace="http://www.jsoso.com/wstest"></soap:body>
</input>
<output>
<soap:body use="literal" namespace="http://www.jsoso.com/wstest"></soap:body>
</output>
</operation>
<operation name="sayHello">
<soap:operation soapAction="sayHello"></soap:operation>
<input>
<soap:body use="literal" namespace="http://www.jsoso.com/wstest"></soap:body>
</input>
<output>
<soap:body use="literal" namespace="http://www.jsoso.com/wstest"></soap:body>
</output>
<fault name="HelloException">
<soap:fault name="HelloException" use="literal"></soap:fault>
</fault>
</operation>
</binding>
标签是完整描述协议、序列化和编码的地方,,和标签处理抽象的数据内容,而标签是处理数据传输的物理实现。 首先标签使用的transport和style属性定义了Web Service的通讯协议HTTP和SOAP的请求风格RPC。其次子标签将portType中定义的operation同SOAP的请求绑定,定义了操作名称soapAction,输出输入参数和异常的编码方式及命名空间。 WSDL服务地址绑定元素:< service > <service name="Example">
<port name="ExamplePort" binding="tns:ExamplePortBinding">
<soap:address location="http://localhost:8080/hello"></soap:address>
</port>
</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 但不是所有的Java类都可以发布成Web Service。Java类若要成为一个实现了Web Service的bean,它需要遵循下边这些原则: 下面我们将通过一个具体的Java Web Service代码例子,配合上述的WSDL文件,讲述如何编写JavaSE6.0的原生Web Service应用。 完整的Java Web Service类代码 package org.jsoso.jws.server;
import java.util.ArrayList;
import javax.jws.WebMethod;
import javax.jws.WebParam;
import javax.jws.WebResult;
import javax.jws.WebService;
import javax.jws.WebParam.Mode;
import javax.jws.soap.SOAPBinding;
/
* 提供WebService服务的类
*/
@WebService(name="Example",targetNamespace="http://www.jsoso.com/wstest",serviceName="Example")
@SOAPBinding(style=SOAPBinding.Style.RPC)
public class Example {
private ArrayList<Person> persons = new ArrayList<Person>();;
/** * * 返回一个字符串 * @param userName * @return */
@WebMethod(operationName="toSayHello",action="sayHello",exclude=false)
@WebResult(name="returnWord")//自定义该方法返回值在WSDL中相关的描述
public String sayHello(@WebParam(name="userName")String userName) {
return "Hello:" + userName;
}
/** * web services 方法的返回值与参数的类型不能为接口 * @param person * @return * @throws HelloException */
@WebMethod(operationName="sayHello",action="sayHello")
@WebResult(partName="personList")
public Person[] sayHello(@WebParam(partName="person",mode=Mode.IN)Person person,String userName) throws HelloException {
if (person == null || person.getName() == null) {
throw new HelloException("说hello出错,对像为空。。");
}
System.out.println(person.getName() + " 对 " + userName + " 说:Hello,我今年" + person.getAge() + "岁");
persons.add(person);
return persons.toArray(new Person[0]);
}
}
Annotation 1@WebService(name=”Example”,targetNamespace=”http://www.jsoso.com/wstest”,serviceName=”Example”) Annotation 2:@SOAPBinding(style=SOAPBinding.Style.RPC) Annotation 3:@WebMethod(operationName=”toSayHello”,action=”sayHello”,exclude=false) Annotation 4:@WebResult(name=”returnWord”) Annotation 5:@WebParam(partName=”person”,mode=Mode.IN 这里要着重说明的是,上述Web Service类的sayHello方法中,带有HelloException这个异常声明,造成该服务类不能直接发布成Web Service。需要使用wsgen工具为其生存异常Bean。关于wsgen工具的使用,请参考wsgen与wsimport命令说明 发布一个的Java Web Service package org.jsoso.jws.server;
import java.util.LinkedList;
import java.util.List;
import javax.xml.ws.Binding;
import javax.xml.ws.Endpoint;
import javax.xml.ws.handler.Handler;
/** * @author zsy 启动web services服务 */
public class StartServer {
/** * @param args */
public static void main(String[] args) {
/* * 生成Example 服务实例 */
Example serverBean = new Example();
/* * 发布Web Service到http://localhost:8080/hello地址 */
Endpoint endpoint =
Endpoint.publish("http://localhost:8080/hello",serverBean);
Binding binding = endpoint.getBinding();
/* * 设置一个SOAP协议处理栈 * 这里就简单得打印SOAP的消息文本 */
List<Handler> handlerChain = new LinkedList<Handler>();
handlerChain.add(new TraceHandler());
binding.setHandlerChain(handlerChain);
System.out.println("服务已启动 http://localhost:8080/hello");
}
}
在控制台运行这个类,就可以使用URL :http://localhost:8080/hello?wsdl 浏览到上文所描述的WSDL的全文了。这说明您的第一个Web Service应用发布成功! 构建Web Service客户端 即可在包org.jsoso.jws.client.ref中生成客户端的存根及框架文件。其中我们要使用的类只有两个:服务类Example_Service和本地接口Example。编写如下客户端,即可调用Web Service服务: package org.jsoso.jws.client;
import org.jsoso.jws.client.ref.*;
public class RunClient {
/** * @param args */
public static void main(String[] args) {
//初始化服务框架类
Example_Service service = new Example_Service();
//或者本地服务借口的实例
Example server = (Example) service.getExamplePort();
try {
//调用web service的toSayHello方法
System.out.println("输入toSayHello的返回值——" + server.toSayHello("阿土"));
Person person = new Person();
person.setName("阿土");
person.setAge(25);
//调用web service的sayHello方法
server.sayHello(person,"机器人");
person = new Person();
person.setName("aten");
person.setAge(30);
//调用web service的sayHello方法
PersonArray list = server.sayHello(person,"机器人");
//输出返回值
System.out.println("n以下输入sayHello的返回值——");
for (Person p : list.getItem()) {
System.out.println(p.getName() + ":" + p.getAge());
}
} catch (HelloException_Exception e) {
e.printStackTrace();
}
}
}
届此,本次Web Service的学习暂告一个段落。Java Web Service是一个相当庞大的知识体系,其中涉及的相关技术较多,这里无法一一道来,我们将会在今后的开发和使用中,同大家做进一步深入的探讨和学习。 附录:wsgen与wsimport命令说明 wsgen 命令范例:wsgen -cp ./bin -r ./wsdl -s ./src -d ./bin -wsdl org.jsoso.jws.server.Example wsimport 命令范例:wsimport -d ./bin -s ./src -p org.jsoso.jws.client.ref http://localhost:8080/hello?wsdl (编辑:李大同) 【声明】本站内容均来自网络,其相关言论仅代表作者个人观点,不代表本站立场。若无意侵犯到您的权利,请及时与联系站长删除相关内容! |