WebService实现包--AXIS2

深度探索 Axis2：AXIOM：

http://www.ibm.com/developerworks/cn/webservices/ws-java2/index.html

 http://blog.csdn.net/tafu/article/details/524116

Axis2是全新设计的，在2004年的“Axis峰会”上，大家决定采用新的架构来让Axis更加的富有弹性，更有效率，并且更加的可配置。Axis2现在具有的一些feature:

　　Speed

　　Low memory foot print

　　AXIOM - AXis Object Model

　　Hot Deployment

　　Asynchronous Web Services

　　MEP Support - Message Exchange Patterns

　　Flexibility

　　Stability

　　Component-oriented deployment

　　Transport framework

　　WSDL support

　　有些feature现在看不懂，还是先动手做一下，感性认识一下吧

　　第一步：下载AXIS2。http://ws.apache.org/axis2/download.cgi 。很有趣，在apache的Web Service 的Project目录下面还看不到AXIS2。要下那个binary的版本，因为里面有例程。

　　第二步：Copy axis2.war到$TOMCAT_HOME/webapps目录下面。Tomcat好像只能用JDK1.4，我在JDK1.5 用不出来。

　　第三步：打开 http://localhost:8080/axis2 ，就可以看到axis2的Welcome页面了。点一下Validate 和Services，看是不是都没有错误。都没有错误的话，就表示deploy成功了。那个adminstration页面可以通过上传文件来hot deploy Web service，可以用来remote deploy。

　　第四步：研究例程。先从"samples/userguide/src"目录下的例程看起。看到写一个web service很简单嘛:

public class MyService {

　　public OMElement echo(OMElement element) throws XMLStreamException {

　　//Praparing the OMElement so that it can be attached to another OM Tree.

　　//First the OMElement should be completely build in case it is not fully built and still

　　//some of the xml is in the stream.

　　element.build();

　　//Secondly the OMElement should be detached from the current OMTree so that it can be attached

　　//some other OM Tree. Once detached the OmTree will remove its connections to this OMElement.

　　element.detach();

　　return element;

　　}

　　public void ping(OMElement element) throws XMLStreamException {

　　//Do some processing

　　}

　　public void pingF(OMElement element) throws AxisFault{

　　throw new AxisFault("Fault being thrown");

　　}

　　}

 

　看得出来，函数统一使用OMElement作为参数。在META-INF目录下面有个services.xml文件：

　<service name="MyService">

　　<description>

　　This is a sample Web Service with two operations,echo and ping.

　　</description>

　　<parameter name="ServiceClass" locked="false">userguide.example1.MyService</parameter>

　　<operation name="echo">

　　<messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>

　　</operation>

　　<operation name="ping">

　　<messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/>

　　</operation>

　　</service>

 

呵呵，也很简单嘛。有返回值的就用RawXMLINOutMessageReceiver，没返回值的就用RawXMLINOnlyMessageReceiver。把它们编译(要把axis2的jar写到classpath里去)打包压到 MyService.aar，包里文件目录如下：

　　./\META-INF/services.xml

　　./userguide/example1/MyService.class

　　把MyService.aar拷贝到$TOMCAT_HOME/webapps/axis2/WEB-INF/services，然后去点一下http://localhost:8080/axis2 页面上的Services，也就是http://localhost:8080/axis2/listServices.jsp ，就可以看到MyService已经被列出来了。

 

 

客户端的调用

　　Web services提供的服务多种多样，有的可以马上获得结果，有的要消耗很长的时间。所以，如果我们需要多种调用方式来对付不同的情况。

　　大多数的Web services都提供阻塞(Blocking)和非阻塞(Non-Blocking)两种APIs.

　　这两个概念以前应该学过，简单说一下。

　　Blocking API - 调用端要等被调用的函数运行完毕才继续往下走。

　　Non-Bloking API - 调用端运行完调用函数以后就直接往下走了，调用端和被调用端是异步执行的。返回值是用回调函数来实现的。

　　这种异步叫做API层异步（API Level Asynchrony）。他们只用到一个连接来发送和接收消息，而且，如果是那种需要运行很长时间的函数，还会碰到Time Out 错误，如果用两个连接分别处理发送和接收消息，调用的时间就可以缩短，也可以解决Time Out 问题。用两个连接来分别处理发送和接收消息，叫做传输层异步（Transport Level Asynchrony）。

　理论真无聊，还是来看实例吧。

　　打开 Eclipse, 创建一个新Project, 新建一个叫userguide.clients的包, 把"samples\userguide\src\userguide\clients" 下面的文件都copy到那个包下面, 把AXIS2的lib下面的jar都加到ilbrary里面去(应该不用全加,懒一点就全加了吧.) 发现了关于echo的调用的方式, 居然有五个:

　　EchoBlockingClient

　　EchoBlockingDualClient

　　EchoBlockingWsaBasedClient

　　EchoNonBlockingClient

　　EchoNonBlockingDualClient

　　一个一个看吧.

EchoBlockingClient.java

　　public class EchoBlockingClient {

　　private static EndpointReference targetEPR = new EndpointReference("http://localhost:8080/axis2/services/MyService");

　　public static void main(String[] args) {

　　try {

　　OMElement payload = ClientUtil.getEchoOMElement();

　　Call call = new Call();

　　call.setTo(targetEPR);

　　call.setTransportInfo(Constants.TRANSPORT_HTTP,

　　Constants.TRANSPORT_HTTP,

　　false);

　　//Blocking invocation

　　OMElement result = call.invokeBlocking("echo",

　　payload);

　　StringWriter writer = new StringWriter();

　　result.serializeWithCache(XMLOutputFactory.newInstance()

　　.createXMLStreamWriter(writer));

　　writer.flush();

　　System.out.println(writer.toString());

　　} catch (AxisFault axisFault) {

　　axisFault.printStackTrace();

　　} catch (XMLStreamException e) {

　　e.printStackTrace();

　　}

　　}

　　}

 

和一代几乎一样, 弄一个EndpointReference, 再弄一个call, 其他不一样,但是也很简单， 弄一个OMElement作为参数, 返回也是一个OMElement. 可惜运行居然有错.

 

　　再来看双通道的版本

EchoBlockingDualClient.java

　　public class EchoBlockingDualClient {

　　private static EndpointReference targetEPR = new EndpointReference("http://127.0.0.1:8080/axis2/services/MyService");

　　public static void main(String[] args) {

　　try {

　　OMElement payload = ClientUtil.getEchoOMElement();

　　Call call = new Call();

　　call.setTo(targetEPR);

　　call.engageModule(new QName(Constants.MODULE_ADDRESSING));

　　call.setTransportInfo(Constants.TRANSPORT_HTTP,

　　Constants.TRANSPORT_HTTP,

　　true);

　　//Blocking Invocation

　　OMElement result = call.invokeBlocking("echo",

　　payload);

　　StringWriter writer = new StringWriter();

　　result.serializeWithCache(XMLOutputFactory.newInstance()

　　.createXMLStreamWriter(writer));

　　writer.flush();

　　System.out.println(writer.toString());

　　//Need to close the Client Side Listener.

　　call.close();

　　} catch (AxisFault axisFault) {

　　axisFault.printStackTrace();

　　} catch (Exception ex) {

　　ex.printStackTrace();

　　}

　　}

　　}

 

　加了一句engageModule, 这句话好像没什么用，我删掉这句话也能运行的, 然后setTransportInfo最后一个参数改成了true. 关于setTransportInfo的三个参数, 第一个是发送的Transport, 第二个是接收的Transport, 第三个是"是否双通道", 支持的搭配形式如下:

　　http, http, true

　　http, http, false

　　http,smtp,true

　　smtp,http,true

　　smtp,smtp,true

　　看下一个吧，EchoNonBlockingClient，这个是单通道的非阻塞模式：

public class EchoNonBlockingClient {

　　private static EndpointReference targetEPR = new EndpointReference("http://127.0.0.1:8080/axis2/services/MyService");

　　public static void main(String[] args) {

　　try {

　　OMElement payload = ClientUtil.getEchoOMElement();

　　Call call = new Call();

　　call.setTo(targetEPR);

　　call.setTransportInfo(Constants.TRANSPORT_HTTP,

　　Constants.TRANSPORT_HTTP,

　　false);

　　//Callback to handle the response

　　Callback callback = new Callback() {

　　public void onComplete(AsyncResult result) {

　　try {

　　StringWriter writer = new StringWriter();

　　result.getResponseEnvelope().serializeWithCache(XMLOutputFactory.newInstance()

　　.createXMLStreamWriter(writer));

　　writer.flush();

　　System.out.println(writer.toString());

　　} catch (XMLStreamException e) {

　　reportError(e);

　　}

　　}

　　public void reportError(Exception e) {

　　e.printStackTrace();

　　}

　　};

　　//Non-Blocking Invocation

　　call.invokeNonBlocking("echo", payload, callback);

　　//Wait till the callback receives the response.

　　while (!callback.isComplete()) {

　　Thread.sleep(1000);

　　}

　　} catch (AxisFault axisFault) {

　　axisFault.printStackTrace();

　　} catch (Exception ex) {

　　ex.printStackTrace();

　　}

　　}

　　}

 

不同的地方，只是调用的方法从invokeBlocking变成了invokeNonBlocking，然后写了一个简单的匿名Callback类作为回调函数。关于这个Callback类，它是一个抽象类，其中有两个方法：onComplete和reportError，都是client端必须实现的，他还有一个Field，就是complete，可以用来设置和查询调用是否完成。可惜也不能运行，和上面的错误一样，是在createSOAPMessage的时候报null错误。

　　看下一个EchoNonBlockingDualClient，非阻塞的双通道：

public class EchoNonBlockingDualClient {

　　private static EndpointReference targetEPR = new EndpointReference("http://127.0.0.1:8080/axis2/services/MyService");

　　public static void main(String[] args) {

　　try {

　　OMElement payload = ClientUtil.getEchoOMElement();

　　Call call = new Call();

　　call.setTo(targetEPR);

　　//The boolean flag informs the axis2 engine to use two separate transport connection

　　//to retrieve the response.

　　call.engageModule(new QName(Constants.MODULE_ADDRESSING));

　　call.setTransportInfo(Constants.TRANSPORT_HTTP,

　　Constants.TRANSPORT_HTTP,

　　true);

　　//Callback to handle the response

　　Callback callback = new Callback() {

　　public void onComplete(AsyncResult result) {

　　try {

　　StringWriter writer = new StringWriter();

　　result.getResponseEnvelope().serializeWithCache(XMLOutputFactory.newInstance()

　　.createXMLStreamWriter(writer));

　　writer.flush();

　　System.out.println(writer.toString());

　　} catch (XMLStreamException e) {

　　reportError(e);

　　}

　　}

　　public void reportError(Exception e) {

　　e.printStackTrace();

　　}

　　};

　　//Non-Blocking Invocation

　　call.invokeNonBlocking("echo", payload, callback);

　　//Wait till the callback receives the response.

　　while (!callback.isComplete()) {

　　Thread.sleep(1000);

　　}

　　//Need to close the Client Side Listener.

　　call.close();

　　} catch (AxisFault axisFault) {

　　axisFault.printStackTrace();

　　} catch (Exception ex) {

　　ex.printStackTrace();

　　}

　　}

　　}

 双通道和单通道基本没什么不同，只是双通道的时候，它总是要设定engageModule，然后多了一个call.close();，自己关闭监听器（close the Client Side Listener）。以上这些都是需要返回值的调用，如果不需要返回值呢，看看PingClient

 

public class PingClient {
    private static EndpointReference targetEPR = new EndpointReference("http://localhost:8080/axis2/services/MyService");

    public static void main(String[] args) {
        try {
            OMElement payload = ClientUtil.getPingOMElement();

            MessageSender msgSender = new MessageSender();
            msgSender.setTo(targetEPR);
            msgSender.setSenderTransport(Constants.TRANSPORT_HTTP);

            msgSender.send("ping", payload);

        } catch (AxisFault axisFault) {
            axisFault.printStackTrace();
        }
    }

}

 呵呵，这也忒简单了一点，就一个msgSender.send就搞定了。

Client端的调用组合基本看完了，但是还有一个EchoBlockingWsaBasedClient，这是什么东啊? 还有那个engageModule是用来做啥的？先不管它们吧。

看 看那个我认为最有用的工具：WSDL2Java，在bin目录下面有WSDL2Java.bat和WSDL2Java.sh，这个工具是用来干啥的呢，和 一代一样，是用来生成stub的，就是说别人发布了Web Service以后，就会有一个wsdl文件，这个工具可以根据wsdl生成几个class，把底层的调用都wrap起来了，然后你用的时候就像普通函数 调用一样。
演练一下吧，从命令行走到samples/wsdl目录下面，看到Axis2SampleDocLit.wsdl，执行../.. /bin/WSDL2Java.bat -uri Axis2SampleDocLit.wsdl，目录下面一下子多了两个目录，不管schemaorg_apache_xmlbeans，把 codegen目录copy到Eclipse的一个Project里面去，哇，好多class啊，不看别的，就看 Axis2SampleDocLitPortTypeStub，里面有三个函数是Web Service提供的：echoStringArray，echoStruct和echoString，哈哈，什么Call类 了，MessageContext了，都在里面了，使用起来嘛，就像这样：

try {
     Axis2SampleDocLitPortTypeStub stub= new Axis2SampleDocLitPortTypeStub(null,                                "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
     //Create the request document to be sent.
     EchoStringParamDocument  reqDoc= EchoStringParamDocument.Factory.newInstance();
     reqDoc.setEchoStringParam("Axis2 Echo");
     //invokes the web service.
     EchoStringReturnDocument resDoc=stub.echoString(reqDoc);
     System.out.println(resDoc.getEchoStringReturn());

    } catch (Exception e) {
        e.printStackTrace();
    }

 就是创一个stub，再创一个参数类(EchoStringParamDocument)，然后调用函数传参数，和普通的函数调用没有区别。如果你在命令行输入WSDL2Java.bat，会看到它的帮助提示如下：
Usage WSDL2Code -uri <Location of WSDL> :WSDL file location
-o <output Location> : output file location
-a : Generate async style code only. Default if off
-s : Generate sync style code only. Default if off. takes precedence over -a
-p <package name> : set custom package name
-l <language> : valid languages are java and csharp. Default is java
-t : Generate TestCase to test the generated code
-ss : Generate server side code (i.e. skeletons).Default is off
-sd : Generate service descriptor (i.e. axis2.xml).Default is off.Valid with -ss