Axis + Tomcat + Eclipse 发布 WebService

一、搭建 Axis + Tomcat + Eclipse 平台：

       见 《Axis + Tomcat + Java Eclipse 配置方法》。

二、SOAP & AXIS：

       SOAP 是种基于 XML 的通信协议，通过编码格式以方便跨平台程序间通信。Axis 包括 SOAP 引擎，即一种构建客户端、服务端、网关等 SOAP 流程的框架。AXIS 扩展支持 WSDL，即网络服务描述语言，并支持 java2wsdl 和 wsdl2java，即通过 WSDL 描述生成 JAVA 类，并包含监视 TCP/IP 包的工具。

三、服务器端开发：

       建立工程，服务器端代码如下，最简单的服务中代码只需要包含一个服务类，一个方法：

package com.libo.WebService;
public class WebServiceWork {
       public String SayHello (String UserName ) {
              return “Hello “ + UserName;
       }
}

1、人工生成 AAR 包：

       在工程上建 META-INF 文件夹，下建 services.xml 文件：

<service name = “LiBoWebServ”>
       <description>
              This is a Web Service with SayHello Method.
       </description>
       <parameter name = “ServiceClass” locked = “false”>
              com.libo.WebService.WebServiceWork
       </parameter>
       <operation name = “SayHello”>
              <messageReceiver class = “org.apache.axis2.rpc.receivers.RPCMessageReceiver” />
       </operation>
</service>

       其中 Service Name 定义服务名称，description 是服务的文本描述，名称为 ServiceClass 的 parameter 指明提供服务的类，类名称要包名加类名写完整，operation 指明服务方法，并指定用 RPC 方式接收 SOAP 请求，并与 SOAP 响应通信。

图 1 Axis2 体系

       将工程导出为 JAR 包，导出后后缀名改为 aar

2、Axis2 Service Archiver 生成 AAR 包：

       Eclipse，File -> New -> Other -> Axis2 Wizards -> Axis2 Service Archiver。Class File Location 处指定到代码中 packagename 生成的目录的上一级，比如 com 文件夹的上一级，如 bin。后面都让它自动生成，到 Generate the Service XML file 步，服务名称自定，Class name 填写完整的 packagename.classname，然后点 load，读出方法列表，勾选要暴露的方法。而后指定 AAR 文件生成后存放的位置，选择 %tomcat%/webapps/axis2/WEB-INF/services，完成。注意一个完整的 AAR 包文件结构如下：

./packagename/classname.class
./META-INF/services.xml
./META-INF/services.wsdl

四、服务器端部署：

       若是使用 ASA 工具生成 AAR 包，则部署完成。若是人工生成 AAR 包，则需要本步部署。部署时，将 AAR 文件放入 %tomcat%/webapps/axis2/WEB-INF/services 下，也可使用 Axis2 的 Upload Service 工具，到 http://localhost:8080/axis2，进 Administration，工具选择 Upload Service，选择该 AAR 文件，后 Upload。

五、检查服务：

       启动 Tomcat，输入 http://localhost:8080/axis2/services，即可看到服务名，也即工程 AAR 包名。其中Service EPR（Endpoint Reference）为 http://<host>/axis2/services/<service-name>，即该服务的指定 URL，该 URL 通过 SOAP 访问。

       输入 http://localhost:8080/axis2/services/<service-name>?wsdl，出现 xml 内容即成功，XML 内容为服务器端框架描述信息，重点关注发布出来的服务的命名空间、服务的 URL、服务类名、方法及其参数、返回值等，以便客户端开发调用。链接中的 <service-name> 即 services.xml中指定的服务名。

六、JAVA2WSDL & WSDL2JAVA：

       AXIS2 提供的转换工具，在 %axis2%/bin 下。WSDL（Web Service Description Language）是 IBM 和微软开发的规范，以 XML 形式即结构化描述若干 Web Services，内容包括：服务的接口、所用数据类型、所在位置。JAVA2WSDL 工具用于从 Java 类生成 WSDL；WSDL2JAVA 工具用于从 WSDL 描述为服务建立 JAVA 代理和框架。

1、JAVA2WSDL：

NAME
Java2WSDL.sh or Java2WSDL.bat - Generates the appropriate WSDL file for a given java class.
These scripts can be found under the bin directory of the Axis2 distribution.
SYNOPSIS
Java2WSDL.sh [OPTION]... -cn <fully qualified class name>
DESCRIPTION
Given a java class generates a WSDL file for the given java class.
-o    <output location> output directory
-of   <output file name> output file name for the WSDL
-sn   <service name> service name
-l      <soap address> address of the port for the WSDL
-cp   <class path uri> list of classpath entries - (urls)
-tn    <target namespace> target namespace for service
-tp    <target namespace prefix> target namespace prefix for service
-stn  <schema target namespace> target namespace for schema
-stp  <schema target namespace prefix> target namespace prefix for schema
-st    <binding style> style for the WSDL
-u    <binding use> use for the WSDL
-nsg  <class name> fully qualified name of a class that implements NamespaceGenerator
-sg    <class name> fully qualified name of a class that implements SchemaGenerator
-p2n [<java package>,<namespace] [<java package>,<namespace]...
           java package to namespace mapping for argument and return types
-p2n [all, <namespace>] to assign all types to a single namespace
-efd   <qualified/unqualified> setting for elementFormDefault (defaults to qualified)
-afd   <qualified/unqualified> setting for attributeFormDefault (defaults to qualified)
-xc class1 -xc class2... extra class(es) for which schematype must be generated.
-wv   <1.1/2.0> wsdl version - defaults to 1.1 if not specified
-dlb   generate schemas conforming to doc/lit/bare style

       使用时，将目标 .class 文件，整个包目录（比如完整包+类路径是 com.libo.hikaliv.myclass，则应上溯到 com 文件夹）复制到 %axis_home%/bin 下，也即与 java2wsdl.bat 处于同一目录，而后在 cmd 下使用 java2wsdl 命令。例如：

java2wsdl –o “d:” –of “libo.wsdl” –sn “Hikaliv” –l “http://localhost:8080/axis2/services/LiBoWebServ”-wv 2.0 -cn “com.libo.WebService.WebServiceWork”

       此例中，指定输出文件为 d:/libo.wsdl，服务名为 Hikaliv，-l 指定服务所在路径，-cn 为 java 类的完整类名。

2、WSDL2JAVA：

NAME
wsdl2java.sh or wsdl2java.bat - Generates java code according to a given WSDL file to handle Web service invocation.
These scripts can be found under the bin directory of the Axis2 distribution.
SYNOPSIS
wsdl2java.sh [OPTION]... -uri <Location of WSDL>
DESCRIPTION
Given a WSDL file, this generates java code to handle Web service invocations.
-o <path>          Specify a directory path for the generated code.
-a                       Generate async style code only (Default: off).
-s                       Generate sync style code only (Default: off). Takes precedence over -a.
-p <pkg1>         Specify a custom package name for the generated code.
-l <language>    Valid languages are java and c (Default: java).
-t                       Generate a test case for the generated code.
-ss                     Generate server side code (i.e. skeletons) (Default: off).
-sd                     Generate service descriptor (i.e. services.xml). (Default: off). Valid with -ss.
-d <databinding>   Valid databinding(s) are adb, xmlbeans, jibx and jaxbri (Default: adb).
-g                      Generates all the classes. Valid only with -ss.
-pn <port_name>    Choose a specific port when there are multiple ports in the wsdl.
-sn <service_name> Choose a specific service when there are multiple services in the wsdl.
-u                     Unpacks the databinding classes
-r <path>         Specify a repository against which code is generated.
-ns2p ns1=pkg1,ns2=pkg2  Specify a custom package name for each namespace specified in the wsdls schema.
-ssi                   Generate an interface for the service implementation (Default: off).
-wv <version>  WSDL Version. Valid Options : 2, 2.0, 1.1
-S                     Specify a directory path for generated source
-R                     Specify a directory path for generated resources
-em                  Specify an external mapping file
-f                     Flattens the generated files
-uw                  Switch on un-wrapping.
-xsdconfig <file path>   Use XMLBeans .xsdconfig file. Valid only with -d xmlbeans.
-ap                  Generate code for all ports
-or                  Overwrite the existing classes
-b                 Generate Axis 1.x backword compatible code.
-sp                Suppress namespace prefixes (Optimzation that reduces size of soap request/response)
-E<key> <value>    Extra configuration options specific to certain databindings. Examples:
-Ebindingfile <path>                   (for jibx) - specify the file path for the binding file
-Etypesystemname <my_type_system_name> (for xmlbeans) - override the randomly generated type system name
-Ejavaversion 1.5                      (for xmlbeans) - generates Java 1.5 code (typed lists instead of arrays)
-Emp <package name> (for ADB) - extension mapper package name
-Eosv (for ADB) - turn off strict validation.
-Ewdc (for xmlbeans) - Generate code with a dummy schema. if someone use this option
they have to generate the xmlbeans code seperately with the scomp command comes with the
xmlbeans distribution and replace the Axis2 generated classes with correct classes
--noBuildXML             Dont generate the build.xml in the output directory
--noWSDL                 Dont generate WSDLs in the resources directory
--noMessageReceiver      Dont generate a MessageReceiver in the generated sources
--http-proxy-host        Proxy host address if you are behind a firewall
--http-proxy-port        Proxy prot address if you are behind a firewall
-ep                      Exclude packages - these packages are deleted after codegeneration

       使用时，例如针对 d:/libo.wsdl，有：

wsdl2java –o “d:” –p “com.libo” –t –ss –sd –g –uri “d:/libo.wsdl”

       注意，若指定 –wv 版本（2.0、1.1），则须与 wsdl 文件的版本一致。完成后，在 d: 下看到生成的 resources、src、test 目录和 build.xml 文件。

3、WSDL2JAVA 用法示例：

       主要关注客户端调用 WEB 服务的方法，很多时候，服务商架好服务并准备好服务描述文件 wsdl，客户根据 wsdl 文件描述的接口编写客户端以调用服务端提供的服务。

      使用 wsdl2java 命令生成 java 文件（此处不用 -ss 选项生成服务端代码），主要关注 com/libo/ 目录下的 HikalivStub.java 和 HikalivCallBackHandler.java 文件。这两个文件是客户端需要调用的 类代码文件，一个是同步调用方式，一个是异步调用方式。注意，之所以是 Hikaliv*.java 文件，是因为 WSDL 的服务名指定的是 Hikaliv。Stub 是桩，也即基础，Stub 的作用是，将服务暴露的所有方法都封装成类；因此，客户端对服务方法的调用与服务端通信的过程是通过对类的操作完成的。客户端在 Stub 的基础上构建客户端逻辑。

       新建客户端工程，导入（Import）文件系统（整个 com 目录），于是工程组织里看到 com.libo 包，新建主函数类，例如 LiBoTest.java，代码如下：

package com.libo;
import com.libo.HikalivStub.SayHello;
public class LiBoTest {
       public static void main(String[] args) {
              try {
                     HikalivStub stub = new HikalivStub();
                     SayHello sh = new SayHello();
                     sh.setUname("hikaliv");
                     HikalivStub.SayHelloResponse shr = stub.sayHello(sh);
                     System.out.println(shr.get_return());
              }
              catch (java.lang.Exception e) {
                     System.out.println(e.getMessage());
              }
       }
}

       运行之，看到 “Hello hikaliv”。

       通过 SayHello 类对像（对应服务端 SayHello 方法）的方法设置参数 uname，通过 HikalivStub 类对像的 sayHello 方法传递客户端消息，并提取将服务端反馈信息封装起来的 Response 类对像，并从该对像中提取反馈信息。

       若通过 -ss 选项一起生成了服务端和客户端代码，此时的 wsdl 文件即视为纯粹的服务模型的描述，并依此建立 C/S 两端。服务端的代码主要关注 Skeleton.java 文件，填充里面的函数体即可。

       注意到使用 -ss 选项后，生成的文件里面有 services.xml 和 wsdl 文件，与填充好的服务端代码生成的 .class 文件刚好可以打包成 aar 文件发布到 axis2 上。

七、服务风格 – RPC、Document、Wrapped、Message：

       AXIS 默认的是 RPC 服务。可通过< ... provider="java:RPC">或< ... style="RPC">两种方式指定。RPC 方式的好处在于，每个 RPC 都包括一个匹配名称的外部元素（element）和一些匹配参数的内部元素（相当于一个 RPC 描述了一个函数方法），并通过这些信息自动完成 XML 到 JAVA 对像的反序列化以用于服务，且可将从服务获取的 JAVA 对像序列化回 XML。

       Document/Wrapped 风格针对旧 XML Schema。通过 style = “document” 和 “style = wrapped” 指定。

       Message 服务。直接操作 XML 而非转换出来的 JAVA 对像。有四种有效操作方式：

public Element [] method(Element [] bodies);
public SOAPBodyElement [] method (SOAPBodyElement [] bodies);
public Document method(Document body);
public void method(SOAPEnvelope req, SOAPEnvelope resp);

       前两种方式参数为 DOM 元素序列和 SOAPBody 元素序列，序列中的每个对像都对应着信封中 <soap:body> 里面的 XML 元素。

       第三种方式参数为表示 <soap:body> 的 DOM Document。

       第四种方式参数为两个 SOAPEnvelope 对像，表示请求和响应 Message。该方法用于在服务方法中操作信封头。若操作响应信封对像会在函数返回时自动回馈 caller。

八、调用 TCP MONITOR：

       命令行窗口里面键入：

java –cp %AXIS2_HOME%/lib/axis.jar org.apache.axis.utils.tcpmon

       运行之前，需要先设环境变量 AXIS2_HOME 为 axis2 目录之所在，再者，将axis.jar 文件复制到 %AXIS2_HOME%/lib 下。axis.jar 文件原本应在 %Eclipse% 的 plugins 目录下搜索。

九、调用 SOAP MONITOR：

       在 %TOMCAT%/webapps/axis2/WEB-INF/lib 下，或 %AXIS2_HOME%/lib 下找到 soapmonitor 的 jar 包儿。把该 jar 包解压，提取出里面的 org 文件夹，其余扔掉。将 org 到 applet 的目录部分复制到 %TOMCAT%/webapps/axis2 中（保持目录结构 …/webapps/axis2/org/apache/...），将 org 到 servlet 的目录部分复制到%TOMCAT%/webapps/axis2/WEB-INF/classes 中（保持目录结构 …/webapps/axis2/WEB-INF/classes/org/apache/axis2/soapmonitor/servlet/...）。

       打开 %TOMCAT%/webapps/axis2/WEB-INF/web.xml 文件，注意到里面有两段代码是被注释掉的：

    <servlet>
        <servlet-name>SOAPMonitorService</servlet-name>
        <display-name>SOAPMonitorService</display-name>
        <servlet-class>org.apache.axis2.soapmonitor.servlet.SOAPMonitorService</servlet-class>
        <init-param>
            <param-name>SOAPMonitorPort</param-name>
            <param-value>5001</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>SOAPMonitorService</servlet-name>
        <url-pattern>/SOAPMonitor</url-pattern>
    </servlet-mapping>

       将这两段代码恢复，保存。

       启动 TOMCAT，http://localhost:8080/axis2/SOAPMonitor，即可启动 soap monitor。

       另，注意到 %TOMCAT%/webapps/axis2/WEB-INF/modules/ 下的 modules.list 文件里应该已经写有 soapmonitor 模块，同目录下也有该模块的引用。

       打开 %AXIS2_HOME%/conf/axis2.xml，找到 <module … 处，添加一行：

<module ref = “soapmonitor” />

       以使监视 AXIS2 里所有 webservice。

资源：

http://ws.apache.org/axis/java/user-guide.html

其它：

JWS (Java WebService) 部署和 WSDD 自定义部署，见资源