自己翻译的《在Apache Axis2中使用POJO Web Service》

原文地址 http://ws.apache.org/axis2/1_4/pojoguide.html
自己简单的翻译了一下，不足之处请多多指教。
如果想要寻求一种快速部署Web Service并且随时运行的方法，那么你应该考虑创建一个使用axis2并且能部署在Tomcat容器下的POJO（Plain Old Java Object）。POJO可以快速创建并且易于维护，这意味着你可以节约好多时间来构建和维护你的代码。这篇文档将告诉你如何来创建一个POJO，并且像Web Service一样的文件格式部署到Apache Tomcat下。你还将学习到如何创建一个基于Spring Framework的POJO，并且打包成AAR文件部署到Tomcat下。
内容：
 简介
 POJO
 在Tomcat下部署和使用POJO Web Service
 定义服务：Service.xml
 用Ant构建POJO Web Service
 POJO的局限性和优势
 基于Spring 的POJO Web service
 简介
 服务定义：ervice.xml
 初始化Spring 应用上下文（Application Context）：SpringInit
 用RPCServiceClient做测试
 POJO Web Service 支持的JSR 181申明
 简单的JSR181 POJO Web Service
 总结
 更深入的学习


简介
构建一个Web service 有时候是一项艰巨的任务，但是这并不包括POJO。旧有的POJO是一种简单和快速的途径来得整理你绝大多数现有的Java Classes使之成为易于访问的Web Service，当然这绝包括所有。这篇文档描述的是怎样使用ApacheAxis2和Tomcat去构建一个POJO-style的Web Service。组织如下：
 POJO：你可以在这篇文档种随时可以使用的一个Java class
 POJO的部署
 在客户端测使用RPC来测试POJO Web Service
 POJO的优势和局限性
 基于Spring的POJO Web service及其部署
如果你解压缩了 Axis2 Standard Distribution，那么文档中包括的代码可以在Axis2_HOME/samples/pojoguide 和Axis2_HOME/samples/pojoguidespring 文件夹下找到。（如果你还没有下载Axis2 Standard Distribution，你最好现在就获取一份，这将很好的帮助你获得更好的深入学习）。那么下来让我开始第一步。
POJO
下面的POJO 是个Weather service POJO 包括两个class：WeatherService 和 Weather。Weather 包括 Weather data: Temperature, forecast, rain (will it rain?), 和 howMuchRain (See Code Listing 1).

Code Listing 1: The Weather POJO 
package sample.pojo.data;

public class Weather{
    float temperature;
    String forecast;
    boolean rain;
    float howMuchRain;

    public void setTemperature(float temp){
        temperature = temp;
    }

    public float getTemperature(){
        return temperature;
    }

    public void setForecast(String fore){
        forecast = fore;
    }

    public String getForecast(){
        return forecast;
    }

    public void setRain(boolean r){
        rain = r;
    }

    public boolean getRain(){
        return rain;
    }

    public void setHowMuchRain(float howMuch){
        howMuchRain = howMuch;
    }

    public float getHowMuchRain(){
        return howMuchRain;
    }
}
And here's the WeatherService class, shown in Code Listing 2.
Code Listing 2: The WeatherService class 
package sample.pojo.service;

import sample.pojo.data.Weather;

public class WeatherService{
    Weather weather;

    public void setWeather(Weather weather){
        this.weather = weather;
    }

    public Weather getWeather(){
        return this.weather;
    }
}

注意：这些POJO都是非常直接的只包括field 及其getter，setter方法。接下来，你将看到如何部署到Apache Axis2和Tomcat下。

在Tomcat下部署和使用POJO Web Service
获取一个POJO ，很好。本章节将会向你展示如何以一种易于部署的可视的的目录格式打包一个POJO。首先你将看到用来定义服务的Service.xml文件，接下来你要用ant来构建这些文件，并且部署Web Service到 Tomcat下。

服务定义：series.xml

在让Axis2懂得如何工作之前，你必须告诉它使用Service.xml文件。让我们来仔细看看它。

Code Listing 3: The service definition file: services.xml 
<service name="WeatherService" scope="application">
    <description>
        Weather POJO Service
    </description>
    <messageReceivers>
        <messageReceiver 
            mep="http://www.w3.org/2004/08/wsdl/in-only"
    class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/>
        <messageReceiver
            mep="http://www.w3.org/2004/08/wsdl/in-out"
    class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
    </messageReceivers>
    <parameter name="ServiceClass">
        sample.pojo.service.WeatherService
    </parameter>
</service>

Service的名字被指定为WeatherService 并且服务的范围定义为application。正如你所见在WeatherService POJO中有两种个方法：IN-ONLY 方法和 IN-OUT方法。因此messageReceiver元素被包含在messageReceivers 标签中间。最后，ServiceClass parameter 指定了Web Service的class ：sample.pojo.service.WeatherService。当你的web Service 操作被调用时，WeatherService中的方法也将被调用。接下来，让我们用一种简单的方法用ant来构建你的应用程序。

用Ant来构建POJO Web Service
Ant是一个有效的构建工具。它将有效地提高构建应用程序的效率，并且axis2有不少的命令行工具来帮助你创建build.xml。（我们并不会论述更多你所使用的关于build.xml的细节）
这里有两个主要的ant task 你将会用到：
• generate.service – 这个ant task将build服务相关的资源，并把这些文件复制build/WeatherService下。
• rpc.client – 这个ant task将build客户端相关文件，build build/lib/rpc-client.jar，并且运行这个客户端。
在build 资源之前，最好从这（here）下载Axis2 1.4-bin and 1.4-war 。在buil.xml中修改下面的内容。（路径为：Axis2_HOME/samples/pojoguide ， 即 Axis2 1.4 Standard Binary (bin) 的解压缩文件）。
<property name="axis2.home" value="c:\apps\axis2" />
Value 是你本机axis2的路径。
本次修改包括你所下载并解压缩axis2 1.4-bin的根目录。现在你将键入ant来build资源。
下面是build/WeatherService 下的文件目录格式：
- WeatherService
- META-INF
- services.xml
- sample
- pojo
- data
- Weather.class
- service
- WeatherService.class
是不是很简单？一条很棒的钻研Web Service开发的方法展现在你的面前。
现在下载一个Tomcat（这里使用的是5.5），安装，并启动。一旦Tomcat开始运行，复制axis2.war到Tomcat的webapps文件夹下。Tomcat可以自动部署axis2并且解压缩axis2.war到webapps文件夹下。现在复制WeatherService 文件夹下那个我们刚才创建并build 的工程到<tomcat-home>/webapps/axis2/WEB-INF/services。
axis将很快部署此服务，下一步你将用RPCServiceClient测试此Web Service。
用RPCServiceClient测试此Web Service
OK，Web Service已经在Tomcat下运行。现在你将build一个简单的RPCServiceClient并且测试这个POJO Web Service。你将从类的结构开始，创建一个RPCServiceClient 并且初始化Weather类中的值。

Code Listing 4: Setting the weather 
package sample.pojo.rpcclient;

import javax.xml.namespace.QName;

import org.apache.axis2.AxisFault;
import org.apache.axis2.addressing.EndpointReference;
import org.apache.axis2.client.Options;
import org.apache.axis2.rpc.client.RPCServiceClient;

import sample.pojo.data.Weather;


public class WeatherRPCClient {

    public static void main(String[] args1) throws AxisFault {

        RPCServiceClient serviceClient = new RPCServiceClient();

        Options options = serviceClient.getOptions();

        EndpointReference targetEPR = new EndpointReference(
                "http://localhost:8080/axis2/services/WeatherService");

        options.setTo(targetEPR);

        // Setting the weather
        QName opSetWeather =
            new QName("http://service.pojo.sample/xsd", "setWeather");

        Weather w = new Weather();

        w.setTemperature((float)39.3);
        w.setForecast("Cloudy with showers");
        w.setRain(true);
        w.setHowMuchRain((float)4.5);

        Object[] opSetWeatherArgs = new Object[] { w };

        serviceClient.invokeRobust(opSetWeather, opSetWeatherArgs);

注意黑体代码部分。你所创建targetEPR的值，设置了http://localhost:8080/axis2/services/WeatherService，这表示你所部署的axis2的位置。你也可以访问http://localhost:8080/axis2/services/listService查看axis2的的服务列表，来确认你部署的web Service的位置。
接下来的opSetWeather 变量，来表示 SetWeather的操作。创建并初始化Weather 数据。最后调用Web Service，初始化Weather 数据，接下来你会得到从服务器反馈回来的Weather数据。

Code Listing 5: Getting the weather data 
...
        serviceClient.invokeRobust(opSetWeather, opSetWeatherArgs);

        // Getting the weather
        QName opGetWeather =
            new QName("http://service.pojo.sample/xsd", "getWeather");

        Object[] opGetWeatherArgs = new Object[] { };
        Class[] returnTypes = new Class[] { Weather.class };

        Object[] response = serviceClient.invokeBlocking(opGetWeather,
                opGetWeatherArgs, returnTypes);

        Weather result = (Weather) response[0];

        if (result == null) {
            System.out.println("Weather didn't initialize!");
            return;
        }

首先你在opWeather中设置操作来获取Weather。接下来创建一个空的对话列表，注意这次你想要从Web Service那里得到什么，所以创建一个有返回值的list。用blocking call调用Web Service，等待Weather数据返给你，and you place it in the result variable。最后，确认不是null并且被setWeather成功的初始化。现在输出数据并确认之。

Code Listing 6: Displaying the data 
...
            return;
        }

        // Displaying the result
        System.out.println("Temperature               : " +
                           result.getTemperature());
        System.out.println("Forecast                  : " +
                           result.getForecast());
        System.out.println("Rain                      : " +
                           result.getRain());
        System.out.println("How much rain (in inches) : " +
                           result.getHowMuchRain());

    }

}

得到的数据如下：
Code Listing 7: Output from running the client
rpc.client.run:
[java] Temperature : 39.3
[java] Forecast : Cloudy with showers
[java] Rain : true
[java] How much rain (in inches) : 4.5
非常好！你现在终于有了一个可以运行的POJO Web Service！Next you'll quickly morph this one into a Spring based POJO.
POJO的优势和局限性
我们已经讲述了使用基于Web Service 的POJO的优势所在，但是局限性呢？一个主要的不足之处就是基于Web Service的POJO 缺乏初始化的支持（这意味着在Web Service完全被使用之前你必须深入你的Web Service并初始化相关数据）。
基于Spring的POJO Web Service
Spring 是当前比较热门的J2EE框架，它使得bean的使用易如反掌。下面将在本章中创建一个基于Spring的POJO Web Service。就本章而言，你还需要Spring.jar。
快速介绍
如果你看过Axis2_HOME/samples/pojoguidespring下的文档编码，可以发现Weather类没有任何的改变，并且WeatherService类也只是把名字改成了WeatherSpringService。
你还可以注意到一个ApplicationContext.xml文件，这个文件我们将在下面论述。它的用处是创建bean。
现在你可能想知道SpringInit.java有何用处，这个服务是用来初始化Spring Framework的Application Context。
客户端也是非常相似，不同的是在WebService中不再初始化Weather数据，因为Spring使用IOC已经做了这一步工作。
服务定义：Service.xml
由于核心的POJO并没有改变，你可以直接关注Service.xml文件，这次文件将比上面的长些，因为要在一个文件里实例化2个服务。

Code Listing 7: Defining the services: services.xml 
<serviceGroup>
  <service name="SpringInit" 
class="sample.spring.service.SpringInit
">
    <description>
      This web service initializes Spring.
    </description>
    <parameter name="ServiceClass">
        sample.spring.service.SpringInit
    </parameter>
    <parameter name="ServiceTCCL">composite</parameter>
    <parameter name="load-on-startup">true</parameter>

    <operation name="springInit">
      <messageReceiver 
      class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
    </operation>
  </service>
  <service name="WeatherSpringService
">
    <description>
      Weather Spring POJO Axis2 AAR deployment
    </description>
    <parameter name="ServiceClass">
        sample.spring.service.WeatherSpringService
    </parameter>
    <parameter name="ServiceObjectSupplier">
org.apache.axis2.extensions.spring.receivers.SpringAppContextAwareObjectSupplier
    </parameter>
    <parameter name="SpringBeanName">
        weatherSpringService
    </parameter>

上面的序列是不是有些熟悉，只是有几处改变。第一，黑体部分的项是非常重要的，SpringInit 下面的ServiceTCCL属性保证Spring 类装载器对Web Service是非常有用的，能让它正确的实例化Spring Application Context。 WeatherSpringService跟之前的WeatherService保持基本一致，只是添加了一部分内容：创建Spring ServiceObjectSupplier 为Spring Application Context提供支持，使之成为“Spring Aware（知晓）”。
最后，SpringBeanNames 指向被分配到Web Service中，并且在Application.xml中定义的Bean的名字。下面我们会提及Application.xml。application Context 是 ApplicationContext.xml文件告诉给Spring Framework 那个bean被定义。例如，你会定义他们中三个。

Code Listing 8: Defining the application context: applicationContext.xml 
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" 
"http://www.springframework.org/dtd/spring-beans.dtd">

<beans>
  <bean id="applicationContext
" class=
"org.apache.axis2.extensions.spring.receivers.ApplicationContextHolder" />

  <bean id="weatherSpringService" 
        class="sample.spring.service.WeatherSpringService">
    <property name="weather" ref="weatherBean"/>
  </bean>

  <bean id="weatherBean" class="sample.spring.bean.Weather">
    <property name="temperature" value="89.9"/>
    <property name="forecast" value="Sunny"/>
    <property name="rain" value="false"/>
    <property name="howMuchRain" value="0.2"/>
  </bean>

</beans>

第一个是Axis2 hook into（注入到）Spring的 Application Context（需要注意的是aar部署跟war部署有着非常大的差异）。第二个，你在Service.xml文件中定义的bean，也就是WeatherSpringService bean 指向的WeatherSpringService类。它是一个被Spring Framework初始化的类变量（field property）-Weather。这将被set进WeatherBean。 WeatherBean 是一个包含信息的Weather类的实例。Spring会初始化WeatherBean 到上面的值，并且在WernerSpringService 类中set Weather对象到WeatherBean实例中。如此这般，当你部署Web Service的时候，你不需要自己去初始化这些值，因为Spring Framework 已经做好了这些工作。
接下来的是SpringInit 类。
初始化Spring Context的类：SpringInit
除了能快速初始化Spring Application Context，你还有可能遇到一些问题。SprintInit类在启动时初始化Spring Application Context 是因为，它是一个在装载类的过程中被调用的方法，可以称之为启动方法的ServiceLifeCycle（服务生命周期） 类（因为它的启动时调用的属性已经在Service.xml文件被定义）。这个类中唯一需要注意的代码是：

Code Listing 9: SpringInit's startUp method 
    public void startUp(ConfigurationContext ignore,
                        AxisService service) {
        ClassLoader classLoader = service.getClassLoader();
        ClassPathXmlApplicationContext appCtx = new
            ClassPathXmlApplicationContext
(new String[]
                                           {"applicationContext.xml
"}, 
                                           false);
        appCtx.setClassLoader(classLoader);
        appCtx.refresh();

        if (logger.isDebugEnabled()) {
            logger.debug("\n\nstartUp() set spring classloader " +
                         "via axisService.getClassLoader() ... ");
        }
    }

可以看出这个方法可以retrieve（充当）Spring 类装载器，而且根据ApplicationContext.xml文件创建一个Application Context 作为参数。这个新的Application Context 接下来把Spring的类装载器作为自己的类装载器。至此，Spring Framework 已经准备妥当可以运行WeatherSpringService了。
用Apache Axis2和Tomcat 构建并部署
你的POJO 现在已经在Spring Framework下准备妥当。在build之前，必须确认axis2-spring-1.4.jar 和 spring.jar 两个文件在你工程的Axis2_HOME/lib文件夹下。
注意：如果你把上述两个jar文件复制到了服务文件夹，而导致启动异常，则Service服务将不会被部署。
现在可以用ant 开始build 源码并创建一个AAR文件。
结果会创建一个target/WeatherSpringService.aar文件，复制此文件到<tomcat-home>/webapps/axis2/WEB-INF/services，axis2才能正确部署此服务。
接下来，测试Web Service 看看Spring是否能正确的为你初始化Weather的数据。
用RPCServiceClient做测试
这次测试跟上面的测试基本相同，不同是需要键入：ant rpc.client
客户端的源码位于src/client/WeatherSpringRPCClient.java。很明显，这个客户端跟测试WeatherService的客户端作用是一样的。不同的是这个客户端忽略了“Setting the Weather”任务，因为Weather数据已经在启动的时候由Spring Framework 完成了设置。
输出部分如下：
run.client:
[javac] Compiling 1 source file to C:\axis2-1.4\samples\pojoguidespring\build\cl
asses
[java] Temperature : 89.9
[java] Forecast : Sunny
[java] Rain : false
[java] How much rain (in inches) : 0.2
你在ApplicationContext.xml文件中设置的值已经正确返回。
JSR 181 注释支持的POJO Web Service
使用JSR181注释式的POJO？很好，本章将会想你展示如何把这些东西打包到一个jar格式的文件中，借助axis2 POJO部署器做一个简洁pojo部署。
JSR181 POJO Web Service样本
让我们假设一个 JSR181注释类如下：

@WebService(name="JSR181TestService" targetNamespace="http://www.test.org/jsr181/Example")
@SOAPBinding(style=SOAPBinding.Style.RPC)
public class TestService {
    @WebMethod(operationName = "echoMethod")
    public String echoString(@WebParam(name="stringIn")String s){
        return s;
    }
}

用axis2的工具类来编译这个类。Add one additional like to the axis2.xml to deploy jar files on the pojo directory
Ex: <deployer extension=".jar" directory="pojo" class="org.apache.axis2.deployment.POJODeployer"/>
如果POJO的文件夹没有则在Axis2的位置创建一个，并且把JSR181注释相关jar复制到Axis2的lib下，启动Axis2. 你会发现服务已经被准备好，并且运行中。
总结
Apache Axis2是一个非常有效的方法让你来部署你的POJO Web Service。Spring也加入了更多对POJO精彩的支持，如初始化功能，还有其他许多良好的支持。
深入学习可以参考如下网站：
Apache Axis2-http://ws.apache.org/axis2/
Axis2 Architecture-http://ws.apache.org/axis2/1_0/Axis2ArchitectureGuide.html
Introduction to Apache Axis2-http://www.redhat.com/magazine/021jul06/features/apache_axis2/
Working With Apache Axis2-http://www.wso2.net/articles/axis2/java/2006/09/13/working-with-axis2
Apache Tomcat-http://tomcat.apache.org
Spring Framework-http://www.springframework.org/