30分钟内创建Web Service

你已经听到过有关Web Service的某些宣传，可能这些宣传将你弄得头昏脑胀。在你的心中或许一直有一个疑团：到底什么是Web Service,我怎样才能使用它们？我们写的这个系列文章将揭开Web Services的神秘面纱，一步步地向你展示怎样去创建、发布、使用及发现它们。
    创建一个基础的Web Services并非难事。为了证实这一点，我们将在这篇文章中向你展示如何在30分钟内构建一个Web Service。在后续的文章中，我们将就Web Services做深入的研究，就以下主题做充分诠释：

    
• SOAP 消息
      
• WSDL 定义项及它们与代码的关系
      
• 发布服务至UDDI目录
      
• 将先前遗留的应用程序做为Web Services发布出去
      
• 部分高级话题(如安全问题)
  

    在这篇介绍性的文章中，我们先就Web Services做一些简单的介绍，紧接着向各位演示一个调用及执行Web Service的java类。我们所有的例子程序都是用java写的。我们使用Systinet提供的免费的工具及运行环境(有关访问及下载此软件的详细信息请参看软件安装这一节)来创建例子程序。并非完全必要使用这一工具来理解这些示例程序，但我们强烈建议你使用它。这里介绍的概念及创建的代码是通用的，它们与工具相对独立。我们假设你具备XML的知识，但对Web Services还无所知。
    我们认为J2EE是实施商业逻辑的最成熟的框架，我们的目标就是使Web Services 作为J2EE的一个扩展模块，以提供基于XML协议的一致的描述及发现机制。这样就可使得现有的基于J2EE的系统能被更广泛的应用所调用，并提供在异种环境下创建核心商业应用的更强的适应能力。

Web Service - 基本概念

    Web Service是具备下列特性的组件：
    1.它通过一个SOAP(Simple Object Access Protocol)接口被访问
    2.它的接口定义在一个WSDL (Web Service Description Language)文档里。

    SOAP是Web Services的根本。它是一种具有扩展性的XML消息协议。SOAP提供了一个应用程序向另一个应用程序发送XML消息的简单而一致的机制。一个SOAP消息是从SOAP发送者传至SOAP接收者的单路消息，任何应用程序均可作为发送者或接收者。SOAP能够支持许多通讯行为，包括请求/响应(request/resposne)、solicit response、单路异步消息，甚至简单讯息(notification)。SOAP是一个仅定义消息结构及一些消息处理规则的高层协议。它完全与底层的协议独立，因此SOAP消息能通过HTTP、JMS或邮件通讯协议来传输。但在当前，通常使用HTTP协议来传送SOAP消息。在这篇文章的后面我们将展示一些SOAP消息的例子。
    WSDL是一份包含Web Service描述信息的XML文档，它包含了访问和使用一个Web Service所需要的所有信息，包括这个Web Service的功能、怎样与其通信及它的位置。在开发阶段，你使用WSDL文档创建你的服务接口。一些SOAP的实现(包括Systinet WASP)会在运行时使用WSDL支持动态通信。

安装此软件

    [i]环境要求：a Java 1.3.x SDK，a standard HTTP browser。JAVA_HOME环境变量指向你Java 1.3.x SDK的安装目录。[/i]
    如果你想跟着练习这些示例，需要你从Systinet下载WASP Advanced。解压缩下载的文件包到一个本地磁盘(解压至C盘会更好些)。从bin子目录下找到名为install的脚本文件，执行之以完成安装。在我们的例子中，我们假设将下载的文件解压缩至c:\wasp-advanced 目录下。还需要你下载示例代码 并解压缩至c:\wasp_demo目录下。如果你选择了不同的目录，请相应更新env.bat脚本文件(更改WASP_HOME及WASP_DEMO的值以使其指向WASP的安装目录及示例代码所在目录)。

实现一个简单的Web Service

    我们将按如下步骤来创建一个简单的Web Service:
    1.创建实现Web Service的商业逻辑的类。 首先我们需要创建一个实现这个Web Service商业逻辑的java类。在这个例子中，我们将创建一个模拟股票报价的java类。
    2.将这个java类发布至SOAP服务器上。我们将演示怎样使用WASP的发布工具发布一个java类至一个SOAP服务器
    3.生成访问此服务的客户端代理类。一个客户端应用程序使用一个代理对象来访问Web Service。在请求阶段，这个代理对象接收到一个从客户端应用程序发出来的方法调用，并将此调用转化成一个XML消息。在响应阶段，这个代理对象接收到一个回复消息，随后将其转化成java的对象，并将结果返回给客户端应用程序。
    4.客户端应用程序的开发。客户端应用程序将代理对象看作是一个便利于与Web Service交互的普通的java对象。

    提示：我们使用微软Windows平台的一些语法来创建我们的脚本文件，如果你使用的是一个基于Unix的环境，请相应更新这些脚本。现在让我们开始编写这个具备股价查找功能的简单java类。请看如下的java代码：
    提示：这个示例中的所有代码均可在解压缩之后的示例代码子目录下找到。它们位于com.systinet.demos.stock包中。

/*
 * StockQuoteService.java
 *
 * Created on Sat 13th Oct 2001, 15:25
 */

package com.systinet.demos.stock;

/**
 * Simple stock quote service
 * @author  zdenek
 * @version 1.0
 */
public class StockQuoteService {

    
    public double getQuote(String symbol) {
        if(symbol!=null && symbol.equalsIgnoreCase("SUNW"))
            return 10;
        if(symbol!=null && symbol.equalsIgnoreCase("MSFT"))
            return 50;
        if(symbol!=null && symbol.equalsIgnoreCase("BEAS"))
            return 11;
        return 0;    
    }
    
    public java.util.LinkedList getAvailableStocks() {
        java.util.LinkedList list = new java.util.LinkedList();
        list.add("SUNW");
        list.add("MSFT");
        list.add("BEAS");
        return list;
    }

}

Figure 1: Web Service code (StockQuoteService.java)

我们的例子不过是又一个简单的股标报价系统而已(我们已经看到许多这样的系统，开发者必须是已登记的而被授权的卖主)，但它说明了创建及部署Web Service是多么容易。在我们的例子中，我们将去获取三种股票的市价(BEAS,MSFT,及SUNW)。
    将我们开发的类转化成一个Web Service的最便捷的方式是：编译我们开发的java类，然后用部署工具将这些类发布至Web Service的运行环境。
    提示：你可以在示例源代码bin子目录下找到所有的脚本文件。提示：在你运行此示例之前，你需先安装Systinet的SOAP框架。请参考安装这一节。
    首先，运行startservcer.bat脚本以起动Web Service运行环境。然后我们编译StockQuoteService.java文件，并使用deploy.bat将编译后的类发布至SOAP运行时环境。
    接下来，我们需要通过在HTTP浏览器开启管理控制台 来确认是否一切都工作正常了。请按刷新按钮以显示发布至服务器上的服务包列表。你应当看到包含StockQuoteService服务的StockService包已发布至服务器上。Web Service运行环境会自动产生WSDL文件，外部可通过http://localhost:6060/StockQuoteService/链接获取此文件。

<?xml version='1.0'?>
<wsdl:definitions name='com.systinet.demos.stock.StockQuoteService' 
targetNamespace='http://idoox.com/wasp/tools/java2wsdl/output/com/systinet/demos/stock/'
    xmlns:mime='http://schemas.xmlsoap.org/wsdl/mime/'
    xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'
    xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'
    xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
    xmlns:xsd='http://www.w3.org/2001/XMLSchema'
    xmlns:ns0='http://idoox.com/containers'
    xmlns:http='http://schemas.xmlsoap.org/wsdl/http/'
    xmlns:tns='http://idoox.com/wasp/tools/java2wsdl/output/com/systinet/demos/stock/'
    xmlns:SOAP-ENC='http://schemas.xmlsoap.org/soap/encoding/'>
    <wsdl:message name='StockQuoteService_getQuote_Request'>
        <wsdl:part name='p0' type='xsd:string'/>
    </wsdl:message>
    <wsdl:message name='StockQuoteService_getQuote_Response'>
        <wsdl:part name='response' type='xsd:double'/>
    </wsdl:message>
    <wsdl:message name='StockQuoteService_getAvailableStocks_Request'/>
    <wsdl:message name='StockQuoteService_getAvailableStocks_Response'>
        <wsdl:part name='response' type='ns0:LinkedList'/>
    </wsdl:message>
    <wsdl:portType name='StockQuoteService'>
        <wsdl:operation name='getAvailableStocks'>
            <wsdl:input name='getAvailableStocks' message='tns:StockQuoteService_getAvailableStocks_Request'/>
            <wsdl:output name='getAvailableStocks' message='tns:StockQuoteService_getAvailableStocks_Response'/>
        </wsdl:operation>
        <wsdl:operation name='getQuote' parameterOrder='p0'>
            <wsdl:input name='getQuote' message='tns:StockQuoteService_getQuote_Request'/>
            <wsdl:output name='getQuote' message='tns:StockQuoteService_getQuote_Response'/>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name='StockQuoteService' type='tns:StockQuoteService'>
        <soap:binding transport='http://schemas.xmlsoap.org/soap/http' style='rpc'/>
        <wsdl:operation name='getAvailableStocks'>
            <soap:operation soapAction='' style='rpc'/>
            <wsdl:input name='getAvailableStocks'>
                <soap:body use='encoded' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' 
            namespace='http://idoox.com/wasp/tools/java2wsdl/output/com/systinet/demos/stock/'/>
            </wsdl:input>
            <wsdl:output name='getAvailableStocks'>
                <soap:body use='encoded' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' 
            namespace='http://idoox.com/wasp/tools/java2wsdl/output/com/systinet/demos/stock/'/>
            </wsdl:output>
        </wsdl:operation>
        <wsdl:operation name='getQuote'>
            <soap:operation soapAction='' style='rpc'/>
            <wsdl:input name='getQuote'>
                <soap:body use='encoded' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' 
            namespace='http://idoox.com/wasp/tools/java2wsdl/output/com/systinet/demos/stock/'/>
            </wsdl:input>
            <wsdl:output name='getQuote'>
                <soap:body use='encoded' encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' 
            namespace='http://idoox.com/wasp/tools/java2wsdl/output/com/systinet/demos/stock/'/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name='JavaService'>
        <wsdl:port name='StockQuoteService' binding='tns:StockQuoteService'>
            <soap:address location='http://localhost:6061/StockQuoteService/'/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

Figure 2: Generated WSDL file (StockQuoteService.wsdl)

这个WSDL文件包含了刚才发布的Web Service的完整描述信息。一般地，WSDL文件会包含三部分：

    
• WHAT部分，包括类型(types)、消息(message)、portType元素，它们定义了客户端及服务器端交互的消息及数据类型。消息是SOAP基本的交互元素。一个消息能包含一个或多个部分(parts)，每个部件代表了一种类型的参数。在我们的股标报价类中,每一个方法有两个消息(input及output)。因为我们的例子中没有复杂的或复合的类型，所以在WSDL中没有复合类型定义(不要担心，在未来我们会看到不少这有关复合类型的例子)。所有的消息都被组合于操作(operations)元素中,而这些操作元素位于一个名为portType的实体(entity)内。一个portType代表了一个接口 -- 一个Web Service支持的所有操作的集合。请看示例WSDL文件的StockQuoteService portType。它包含两个操作：getAvailableStocks及getQuote。为了调用getQuote方法，客户端需要发送一个StockQuote_getQuote_Request消息 。(在这份WSDL的前部分你可看到有关此消息的定义。)StockQuote_getQuote_Request消息包含有一个被定义成string类型的名为p0的part(输入参数)。Web Service响应时会返回StockQuote_getQuote_Response消息，它也包含一个double类型的名为response的part(返回值)。
      
• HOW 部分，包含binding元素，用于描述Web Service的实现细节。binding元素将一个portType秘一种特定的协议(在我们的例子中，是基于HTTP的SOAP协议)相绑定。因为我们用的是SOAP，故我们用WSDL对SOAP的扩展元素来定义我们的SOAP绑定。(注意到这部分中许多元素都用到soap:这个名称空间前缀，这些元素是SOAP对WSDL的扩展。) soapAction是特定于HTTP协议的soap:operation元素的属性，可用它来指定SOAP消息的目的。它可以是一个路由参数信息，或者包含有助于SOAP运行环境判断哪个应用程序或方法将被执行的信息。指定的这个属性(soapAction)将相应地包含在SOAP请求消息的HTTP头SOAPAction:属性中。在我们的例子中，这个属性没有值。SOAP绑定部分需要我们为每一个在portType中的操作(operation)指定通讯方式。SOAP支持两种通讯方式：RPC及文档(Document)方式。RPC方式支持对消息的自动调度及反调度，允许开发者将一个带参的方法调用作为一个请求发送出去，然后获取带有返回值的响应。文档(Document)方式不支持消息的自动调度及反调度。它假定SOAP消息包含的内容是XML良构的。SOAP绑定同时需要我们详细说明消息的XML表达。我们可以使用文本的或编码的数据类型。use='literal'属性告诉SOAP运行时直接将提供的XML发送出去，而use='encoded'属性则告诉SOAP运行时用一种指定的编码方式将数据序列化之后再发送出去。一种编码方式定义一组如何用XML表达一种语言类型的规则。在我们的例子中，我们使用在SOAP规范书第五部分中定义的编码方式。你也可以使用其它的编码方式。
•     最后是WHERE部分，包括service元素，它将端口类型元素，绑定(binding)元素及Web Service实际的地址(一个URI)放在一起。可在WSDL文档的最后看到service元素。
      

    可以看到，一个WSDL文件完整地定义了一个Web Service。我们可以从这个文件中获取到客户端访问股标报价Web Service的所有信息。

实现Web Service客户端(java)

    客户端使用一个java的代理类来调用远程的Web Service。当使用Systinet WASP时,这个代理是在运行时根据WSDL文件生成的。我们需要一个java接口来保持与这个动态生成的对象的引用。可以自己创建这个接口文件，或者也可使用WASP提供的WSDLCompiler来替我们生成一个。创建这样一个接口文件是比较容易的，因为它唯一的要求是在此接口中的方法必须是定义在Web Service中的商业逻辑方法的一个子集。让我们看如下的代码。首先，这个客户程序创建了一个WebServiceLookup对象，然后这个对象调用lookup方法创建Web Service的代理。lookup方法需要两个参数：一个是对WSDL文件的引用，另一个是代理类。此方法返回Web Service的代理，可以用此代理对Web Service进行调用。

/**
 * Stock Client
 *
 * @created July 17, 2001
 * @author zdenek
 */

package com.systinet.demos.stock;

import org.idoox.wasp.Context;
import org.idoox.webservice.client.WebServiceLookup;

public class StockClient {

  /**
   * Web service client main method.
   * Finds the web service and 
   * @param args  not used.
   */
    public static void main( String[] args ) throws Exception {
        
      // lookup service
      WebServiceLookup lookup = (WebServiceLookup)Context.getInstance(Context.WEBSERVICE_LOOKUP);
      // bind to StockQuoteService
      StockQuoteServiceProxy quoteService = (StockQuoteServiceProxy)lookup.lookup(
        "http://localhost:6060/StockQuoteService/",
        StockQuoteServiceProxy.class
      );
      

      // use StockQuoteService
      System.out.println("Getting available stocks");
      System.out.println("------------------------");
      java.util.LinkedList list = quoteService.getAvailableStocks();
      java.util.Iterator iter = list.iterator();
      while(iter.hasNext()) {
         System.out.println(iter.next());
      }
      System.out.println("");
      
      System.out.println("Getting SUNW quote");
      System.out.println("------------------------");
      System.out.println("SUNW "+quoteService.getQuote("SUNW"));
      System.out.println("");
      
    }

}

Figure 3: Web Service client code (StockClient.bat)

运行runJavaclient.bat脚本文件。这个脚本文件将运行WSDLCompiler以生成java接口，然后它会编译及运行客户端程序。你可在控制台看到getAvailableStocks及getQuote方法调用后的输出。

开发及运行Web Service客户端(JavaScript)

提示：请注意Web Service 的javascript客户端版本需要安装了MSXML3.0 SP2及后续版本的IE6或IE5的支持。
    我们可以使用runJScriptClient.bat生成一个基于浏览器的javascript客户端。这个脚本会在IE中打开一个HTML页面，然后你便可在此页面调用Web Service的方法了。

粗看SOAP消息

    现在我们可以通过WASP的管理控制平台来查看交互于客户端及服务器端的SOAP消息了。在浏览器中开发管理控制平台，然后点击刷新按钮在查看所有发布了的Web Service包。你应当看到StockQuoteService服务已发布在此服务器上了。点击"enable"链接(在在StockQuoteService区"Debig is OFF:"标签的旁边),使调试SOAP请求的功能生效，然后重新运行runJAvaclient.bat，在管理控制平台点击"show SOAP conversation"链接，一个新浏览器窗口将打开，其中显示了两组输入、输出的SOAP消息：

==== INPUT ==== http://localhost:6060/StockQuoteService/ ==== 11/7/01 3:45 PM =
<?xml version="1.0" encoding="UTF-8"?>
<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/">
  <ns0:Body 
    ns0:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
    <ns0:getAvailableStocks xmlns:ns0="http://idoox.com/wasp/tools/java2wsdl/output/com/systinet/demos/stock/"/>
  </ns0:Body>
</ns0:Envelope>
==== CLOSE ===================================================================== 

==== OUTPUT ==== http://localhost:6060/StockQuoteService/ ======================
<?xml version="1.0" encoding="UTF-8"?>
<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/">
  <ns0:Body 
    ns0:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
    <ns0:getAvailableStocksResponse xmlns:ns0="http://idoox.com/wasp/tools/java2wsdl/output/com/systinet
        /demos/stock/">
    <response xsi:type="ns1:LinkedList" xmlns:ns1="http://idoox.com/containers">
        <item xsi:type="xsd:string">SUNW</item>
        <item xsi:type="xsd:string">MSFT</item>
        <item xsi:type="xsd:string">BEAS</item>
    </response>
    </ns0:getAvailableStocksResponse>
  </ns0:Body>
</ns0:Envelope>
==== CLOSE ===================================================================== 

==== INPUT ==== http://localhost:6060/StockQuoteService/ ==== 11/7/01 3:45 PM =
<?xml version="1.0" encoding="UTF-8"?>
<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/">
  <ns0:Body 
    ns0:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
    <ns0:getQuote xmlns:ns0="http://idoox.com/wasp/tools/java2wsdl/output/com/systinet/demos/stock/">
      <p0 xsi:type="xsd:string">SUNW</p0>
    </ns0:getQuote>
  </ns0:Body>
</ns0:Envelope>
==== CLOSE ===================================================================== 

==== OUTPUT ==== http://localhost:6060/StockQuoteService/ ======================
<?xml version="1.0" encoding="UTF-8"?>
<ns0:Envelope xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/">
  <ns0:Body 
    ns0:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">
    <ns0:getQuoteResponse xmlns:ns0="http://idoox.com/wasp/tools/java2wsdl/output/com/systinet/demos/stock/">
      <response xsi:type="xsd:double">10.0</response>
    </ns0:getQuoteResponse>
  </ns0:Body>
</ns0:Envelope>
==== CLOSE ===================================================================== 


Figure 4: SOAP messages

以下是SOAP消息的基本结构：<ENVELOPE attrs>

  <HEADER attrs>
    <directives/>
  </HEADER>
  <BODY attrs>
    <payload/>
  </BODY>
  <FAULT attrs>
    <errors/>
  </FAULT>
</ENVELOPE>

消息的内容包含在ENVELOPE元素中。在这个简单的例子中，我们的SOAP消息仅包含了BODY部分。SOAP消息还可包含其它两部分，即HEADER部分和FAULT部分。HEADER部分常用于传递与环境有关的信息(如付款细节、事务环境、安全证书等)。如果有错误产生，FAULT部分将包含有关此错误的信息。BODY部分包含主要信息(在我们的例子中，如股票值及相关数据)。一般情况下，SOAP对BODY部分没有做任何规则上的要求。我们曾提到BODY部分的两种方式：文档(Document)方式及RPC方式。除了XML的规则外，Document方式对BODY的格式没有严格的要求，而RPC方式则对消息中的方法及参数的格式定义了一些规则。SOAP规范虽然推荐但没有强制要求为数据指定编码规则。SOAP的编码规则是基于XML Schema的(XML Schema第二部分推荐书中包含了主要编程语言的数据类型如int、float、double或string)。SOAP的编码规则还定义了复杂类型(如数据、结构等)的定义规则。在我们的例子中(我们使用RPC方式)，输入消息的BODY部分包含了被调用方法的已编码了的参数：

<ns0:getQuoteResponse xmlns:ns0="http://idoox.com/wasp/tools/java2wsdl/output/com/systinet/demos/stock/">
  <response xsi:type="xsd:double">10.0</response>
</ns0:getQuoteResponse>

输出消息包含方法调用的结果：

<ns0:getQuoteResponse xmlns:ns0="http://idoox.com/wasp/tools/java2wsdl/output/com/systinet/demos/stock/">
  <response xsi:type="xsd:double">10.0</response>
</ns0:getQuoteResponse>

清洁一下

在结尾我们可以运行undeploy.bat以解除我们示例服务的部署。

小结

在这篇文章中我们向你演示了创建一个简单的Web Service并非难事 -- 事实上，使用Web Service的一个好处是他们相对容易创建和布署。我们介绍了一些基本的概念，包括SOAP及WSDL，还演示了SOAP消息的结构。同时还创建及分析了与Web Service交互信息的WSDL文件。