jdk6 WebService入门

 

一、            Web Services简介

什么是Web Services

Web service 就是一个应用程序，它向外界暴露出一个能够通过Web进行调用的API。这就是说，你能够用编程的方法通过Web来调用这个应用程序。

基于浏览器的瘦客户应用程序，即BS结构，是目前流行的，使得Web Services的应用越来越广泛。Web Services 是一种构建应用程序的模型，并能在所有支持 Internet 通讯的操作系统上实施运行。Web Services 令基于组件的开发和 Web 的结合达到最佳，基于组件的对象模型，利用 SOAP 和 XML对这些模型在通讯方面作了进一步的扩展以消除特殊对象模型的障碍。因为是使用XML作为传输的介质，所以可以跨平台跨语言。

Web Services 实现远程访问，有点类似RMI（远程方法调用）。 但它是利用 HTTP 和 SOAP 协议是商业数据在 Web 上传输，SOAP通过 HTTP 调用商业对象执行远程功能调用，Web 用户能够使用 SOAP 和 HTTP通过 Web 调用的方法来调用远程对象。

Web Services 结构

客户根据 WSDL描述文档，会生成一个 SOAP 请求消息。Web Services 都是放在Web服务器上面，客户生成的SOAP请求会被嵌入在一个HTTP POST请求中，发送到 Web 服务器来。Web 服务器再把这些请求转发给 Web Services 请求处理器。请求处理器的作用在于，解析收到的 SOAP 请求，调用 Web Services，然后再生成相应的 SOAP 应答。Web 服务器得到 SOAP 应答后，会再通过 HTTP应答的方式把信息送回到客户端。

什么是WSDL

WSDL是Web Services Description Language的缩写，是一个用来描述Web服务和说明如何与Web服务通信的XML语言。Web Services服务器把一个对像绑定到一个URL 上（如http://localhost:8080/webservices/hello），客户端就可以能过绑定的地址（如：http://localhost:8080/webservices/hello?wsdl）取得WSDL文件，该文件是标准的XML 格式，描述了被绑定对像的信息，包括可调用的方法，参数，及参数类型，返回值类型，异常类型等。客户端就是通过这些信息调用服务器的方法。

 

二、            JKD6 对Web Services的支持

JDK6提供了对Web Service原生的支持，对Web Service进行了完美的封装，完全隐藏了底层内容，甚至可以不用了解wsdl的具体规范。使用Web Service就像使用本地方法一样简单。下面来举个例子，依然从最简单的HelloWorld入手。

HelloWorld例子

STEP 1，服务器端Bean说明

服务器端的Java类若要成为一个实现了Web Service的bean，它需要遵循下边这些原则：这个类必须是public类、不能是final的或者abstract、必须有一个公共的默认构造函数、绝对不能有finalize()方法。若要成为一个实现了Web Service的Bean的方法必须遵循这些原则：
这个方法必须是public，它的参数、返回值、和异常在每个JAX RPC规范中都描述了Java转化成XML/WSDL映射文件的规则，参数和返回值可以是原始类型、数组等等。

 

下面是服务器端的类HelloWorld.java：

package test.jws.service;

 

import javax.jws.WebMethod;

import javax.jws.WebParam;

import javax.jws.WebResult;

import javax.jws.WebService;

import javax.jws.soap.SOAPBinding;

 

@WebService(targetNamespace = "http://www.jwstest.org")

@SOAPBinding(style = SOAPBinding.Style.RPC)

publicclass HelloWorld {

    @WebMethod(action="toSayHello",operationName="toSayHello",exclude=false)

    @WebResult(name="returnWord")//自定义该方法返回值在WSDL中相关的描述

    public String sayHello(@WebParam(name="userName")String userName) {

        return"Hello:" + userName;

    }

    @WebMethod

    publicint getExp(int i, int j) {

        return i / j;

    }

}

 

 

这是服务器端普通的业务类，通过@WebService、@WebMethod等注释描述来生成WSDL文件。

 

STEP 2，执行wsgen命令

本例中到HelloWorld类所在的目录中新建一个命名为wsdl的文件夹，运行：wsgen -cp ./bin -r ./wsdl -s ./src -d ./bin -wsdl test.jws.service.HelloWorld。执行后会在wsdl文件夹中生成HelloWorld的wsdl描述文件，src文件夹中生成依赖类，如异常说明类，bin中生成依赖类的class文件

 

STEP 3，发布Web Service Bean

启动服务类StartService.java：

package test.jws.service;

 

import javax.xml.ws.Endpoint;

 

publicclass StartService {

    publicstaticvoid main(String[] args) {

        Endpoint.publish("http://localhost:8080/webservice/hws", new HelloWorld());

    }

}

 

 

此类很简单，能过Endpoint类的publish()方法发布实例发布地址为：

http://localhost:8080/webservice/hws，必需明确指明http协议，主机IP 地址及端口号，在IE上输入 http://localhost:8080/webservice/hws?wsdl返回以下内容说明发布成功

<?xml version="1.0" encoding="UTF-8" ?>

<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"

xmlns:tns="http://www.jwstest.org"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"

targetNamespace="http://www.jwstest.org"

name="HelloWorldService">

<types />

<message name="toSayHello">

  <part name="userName" type="xsd:string" />

   </message>

 <message name="toSayHelloResponse">

  <part name="returnWord" type="xsd:string" />

   </message>

<message name="getExp">

  <part name="arg0" type="xsd:int" />

  <part name="arg1" type="xsd:int" />

   </message>

<message name="getExpResponse">

  <part name="return" type="xsd:int" />

   </message>

<portType name="HelloWorld">

<operation name="toSayHello" parameterOrder="userName">

  <input message="tns:toSayHello" />

  <output message="tns:toSayHelloResponse" />

  </operation>

<operation name="getExp" parameterOrder="arg0 arg1">

  <input message="tns:getExp" />

  <output message="tns:getExpResponse" />

  </operation>

   </portType>

<binding name="HelloWorldPortBinding" type="tns:HelloWorld">

  <soap:binding style="rpc"

transport="http://schemas.xmlsoap.org/soap/http" />

<operation name="toSayHello">

  <soap:operation soapAction="toSayHello" />

<input>

  <soap:body use="literal"

namespace="http://www.jwstest.org" />

  </input>

<output>

  <soap:body use="literal"

namespace="http://www.jwstest.org" />

   </output>

   </operation>

<operation name="getExp">

  <soap:operation soapAction="" />

<input>

  <soap:body use="literal"

namespace="http://www.jwstest.org" />

   </input>

<output>

  <soap:body use="literal"

namespace="http://www.jwstest.org" />

   </output>

   </operation>

  </binding>

<service name="HelloWorldService">

 <port name="HelloWorldPort"

binding="tns:HelloWorldPortBinding">

  <soap:address

location="http://localhost:8080/webservice/hws" />

  </port>

  </service>

</definitions>

 

STEP 4，生成客户端执行类

在cmd命令中执行 wsimport  -d  ./bin  -s  ./src - p test.jws.client.ref

http://10.168.189.182:8080/webservice/hws?wsdl 后在在src目录下生成客户端调用的两个类：

       test.jws.client.ref.HelloWorld.java 根据wsdl描述生成的客户端执行类

test.jws.client.ref.HelloWorldServices.java 通过此类负责解悉wsdl初始化客户端HelloWorld实例

在bin目录下生成对应的类文件。

       注意：执行wsimport命令时STEP 3的服务必需启动，否则无法生成

 

STEP 4，客户端调用

客户端调用过程ClientRun.java：

package test.jws.client;

 

import test.jws.client.ref.*;

 

publicclass ClientRun {

 

    /**

     *@paramargs

     */

    publicstaticvoid main(String[] args) {

        HelloWorldService hws = new HelloWorldService();

        HelloWorld hw = hws.getHelloWorldPort();

        System.out.println(hw.getExp(9, 3));

        System.out.println(hw.toSayHello("zhuoshiyao"));

    }

 

}

 

启动STEP 3中的服务，运行ClientRun后，制控台输出：

3

Hello:zhuoshiyao

 

注意：经测试，用Endpoint.publish("http://localhost:8080/webservice/hws", new HelloWorld())方式在Tomcat6中发布，不会存在端口号与路径冲突。

JKD6 中定义的Web Service注释

 

1.        @WebService 标注要暴露为Web Services的类或接口 ，用于申修饰类或接口，包含属性

targetNamespace 定义命名空间，默认为”http://”+”包名倒排”

name Web Service 的名称，默认为类名，例如：

<definitions targetNamespace="http://service.jws.test/"

name="HelloWorldService">

portName Web Service 的端口名称

serviceName Web Service 的服务名称，例如

                    <service name="HelloWorldService">

<port name="HelloWorldPort"

binding="tns:HelloWorldPortBinding">

       ...

                    </port>

              </service>

wsdlLocation描述服务的预定义 WSDL 的位置  

endpointInterface定义服务抽象 Web Service 协定的服务端点接口的完整名称    

2.        @SOAPBinding 定义Web Service 在SOAP中的消息协议，用于申修饰类或接口，包含属性

style 定义消息的编码类型

user 定义消息的格式化类型

3.        @WebMethod 定义Web Service运作的方法，包含属性

action 操作的活动

operationName与此方法匹配的 wsdl:operation 的名称

exclude 标注此方法是否被暴露，默认为false

4.        @WebResult 定义返回值，返回值类型不能为接口类或抽象类，而且必须有个不带参的构造函数，包含属性

name返回值的名称

partName表示此返回值的 wsdl:part 的名称

targetNamespace返回值的 XML 名称空间

header如果为 true，则结果是从消息头而不是消息正文获取的

5.        @WebParam 定义方法的参数，参数类型不能为接口类或抽象类，而且必须有个不带参的构造函数，包含属性

name参数名称

partName表示此参数的 wsdl:part 的名称

targetNamespace参数的 XML 名称空间

header如果为 true，则结果是从消息头而不是消息正文获取的

mode参数的流向（IN、OUT 或 INOUT 之一）

 

wsgen与wsimport命令说明

wsgen命令的主要功能是用来生成合适的JAX-WS。它读取Web Service的终端类文件，在我们的例子中就是test.jws.service.HelloWorld，同时生成所有用于发布Web Service所依赖的源代码文件和经过编译过的二进制类文件，通常Web Service Bean中用到的异常类会另外生成一个描述Bean。它还能生成WSDL和符合规范的HelloWorld类Web Service。wsgen从资源文件生成一个完整的操作列表并验证是合法的。如果Web Service Bean中的主法有申明抛出异常，这一步是必需的，否则服务器无法绑定该对像。

命令参数说明：

-cp 定义classpath

-r 生成 bean的wsdl文件的存放目录

-s 生成发布Web Service的源代码文件的存放目录（如果方法有抛出异常，则会生成该异常的描述类源文件）

-d 生成发布Web Service的编译过的二进制类文件的存放目录（该异常的描述类的class文件）

 

       wsimport命令的主要功能是根据wsdl文件生成客户端存根及框架，负责与Web Service 服务器通信，并在将其封装成实例，客户端可以直接使用，就像使用本地实例一样。

命令参数说明：

-d 生成客户端执行类的class文件的存放目录

-s 生成客户端执行类的源文件的存放目录

-p 定义生成类的包名

 

三、            附录：WSDL说明

1、WSDL 文档结构

WSDL 文档是利用这些主要的元素来描述某个 web service 的：

元素	定义
<portType>	web service 执行的操作
<message>	web service 使用的消息
<types>	web service 使用的数据类型
<binding>	web service 使用的通信协议

一个 WSDL 文档的主要结构是类似这样的：

<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 文档可包含其它的元素，比如 extension 元素，以及一个 service 元素，此元素可把若干个 web services 的定义组合在一个单一的 WSDL 文档中。

WSDL 端口

<portType> 元素是最重要的 WSDL 元素。

它可描述一个 web service、可被执行的操作，以及相关的消息。

可以把 <portType> 元素比作传统编程语言中的一个函数库（或一个模块、或一个类）。

WSDL 消息

<message> 元素定义一个操作的数据元素。

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

WSDL types

<types> 元素定义 web service 使用的数据类型。

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

WSDL Bindings

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

WSDL 实例

这是某个 WSDL 文档的简化的片段：

<message name="getTermRequest">

   <part name="term" type="xs:string"/>

</message>

 

<message name="getTermResponse">

   <part name="value" type="xs:string"/>

</message>

 

<portType name="glossaryTerms">

 <operation name="getTerm">

        <input message="getTermRequest"/>

        <output message="getTermResponse"/>

 </operation>

</portType>

在这个例子中，<portType> 元素把 "glossaryTerms" 定义为某个端口的名称，把 "getTerm" 定义为某个操作的名称。

操作 "getTerm" 拥有一个名为 "getTermRequest" 的输入消息，以及一个名为 "getTermResponse" 的输出消息。

<message> 元素可定义每个消息的部件，以及相关联的数据类型。

对比传统的编程，glossaryTerms 是一个函数库，而 "getTerm" 是带有输入参数 "getTermRequest" 和返回参数 getTermResponse 的一个函数。

2、WSDL 端口

<portType> 元素是最重要的 WSDL 元素。

它可描述一个 web service、可被执行的操作，以及相关的消息。

端口定义了指向某个 web service 的连接点。可以把它元素比作传统编程语言中的一个函数库（或一个模块、或一个类），而把每个操作比作传统编程语言中的一个函数。

操作类型

请求-响应是最普通的操作类型，不过 WSDL 定义了四种类型：

类型	定义
One-way	此操作可接受消息，但不会返回响应。
Request-response	此操走可接受一个请求并会返回一个响应
Solicit-response	此操作可发送一个请求，并会等待一个响应。
Notification	此造作可发送一条消息，但不会等待响应。

One-Way 操作

一个 one-way 操作的例子：

<message name="newTermValues">

   <part name="term" type="xs:string"/>

   <part name="value" type="xs:string"/>

</message>

 

<portType name="glossaryTerms">

   <operation name="setTerm">

      <input name="newTerm" message="newT

评论

1 楼 ytfei 2009-01-04  

文章中 wsgen 生成代码那里有错误。 可以参考命令帮助。 另外注意，JAVA源文件要先编译成class才能生成。

另外请教一个问题：用wsgen生成的文件中， jaxws目录下的几个JAVA；类是用来做什么的啊？
我看没有任何类引用到几个类。发布到服务器上的时候，我把这几个类删除了，也没有报错。WS正常运行。这是为什么？
谢谢！