Axis2中文手册.docx

中文原文/blog/100736英文原文/axis2/1_0/userguide.html概述这个说明文档涉及以下内容：如何使用axis2创建web service和客户端程序如何定制一个模块(Module)并在web service中使用它Samples discussionAdvanced Topics第一部分：简介Axis2是重新设计的一个架构，它没有基于Axis1.*的结构，这种新的架构much more flexible, efficient and configurable。Axis2的特性有：Speed：采用自己的对象模型，利用StAX解析Low memory foot print：Axis2在设计过程中一直遵循low memory cost的理念AXIOM：采用自己的轻量级的对象模型，使得消息处理过程可扩展、性能高，对开发者来说更加简单。Hot Deployment：Axis2装备了在系统运行时部署服务和处理器的能力。也就是说，新的服务新服务的添加不再需要重启服务器。将服务的发布包放在服务部属文件夹中，部署模型将自动部署该服务。Asynchronous Web Services：Axis2现在可以通过non-blocking clients and transports支持异步的服务和异步的服务调用。（？什么是异步的服务?）MEP Support：Axis2具备良好的伸缩性来支持MEPs，因为它内置了对WSDL2.0中MEPs的支持。Flexibility：Axis2的架构使得程序员能自由的对Axis添加扩展，这些扩展包括对自定义Header的处理，系统管理，甚至是任何一件你可以想象的到的事情Stability：Axis2定义了一套公共接口，这些接口相对于其他代码而言改动很小Component-oriented Deployment：你可以自定义一些在处理过程中常用的可重用的处理器，并可以将这些处理器发布出来供其它人使用Transport Framework：定义了一个干净、简单的抽象作品来集成任意的传输协议，引擎的核心部分的实现是与传输协议无关的Add-ons：一些web service相关的协议也合并了进来。如安全方面的WSS4J(Rampart),可靠消息传输的Sandesha，封装了WS-Coordination, WS-AtomicTransaction和WS-BusinessActivity的Kandula。Composition and Extensibility：模块和层支持可扩展性和可组合性（composability）。模块支持可组合性，对添加新的web service规范的支持的方式非常简单和干净。但是他们并不是热部署的，因为他们影响整个系统的功能。Tips:WSS4J: /wss4j/Apache WSS4J is an implementation of the OASIS Web Services Security (WS-Security) from OASIS Web Services Security TC. WSS4J is a primarily a Java library that can be used to sign and verify SOAP Messages with WS-Security information. WSS4J will use Apache Axis and Apache XML-Security projects and will be interoperable with JAX-RPC based server/clients and .NET server/clients.这个项目提供了在Axis上部署的帮助文档和例子Rampart这是Axis2的一个Module（现在Axis2有两个可选的Module，分别是Addressing和Security，Addressing包含在Standard版本中，但是Rampart需要单独下载），目前作用不详，猜测是与WSS4J合作完成WS-SecuritySendesha: /sandesha/Sandesha2 is an implementation of WS-ReliableMessaging specification published by IBM, Microsoft, BEA and TIBCO. Sandesha2 was built on top of Axis2. Therefore by using Sandesha2 you can add reliable messaging capability to the web services hosted using Axis2. Sandesha2 can also be used with Axis2 client to interact with already hosted web services in a reliable manner. Please see sandesha2 user guide for more information on using Sandesha2.Kandula: /kandula/2/index.htmlKandula will provide an open-source implementation of WS-Coordination, WS-AtomicTransaction and WS-BusinessActivity based on Axis. The initial implementation will be in Java using Axis/Java. In addition to providing an implementation, a major focus of this project would be to ensure interoperability with other implementations of above specifications, particularly those by Microsoft (.NET) and IBM.第二部分：使用Axis2开发web services首先你需要在Servlet容器中部署axis2.war可以通过两种方式来创建web services1.使用Axis2的API，实现业务代码2.从WSDL开始，生成代码框架，然后实现业务逻辑1）使用Axis2的API首先，计划生成一个服务MyService，它有两个方法：public void ping(OMElement element) /IN-ONLY operation, just accepts the OMElement and do some processing.public OMElement echo(OMElement element)/IN-OUT operation, accepts an OMElement and sends back the same again从例子里找到实现的代码：Axis2Home/samples/userguide/src中的userguide/example1创建一个服务分4个步骤a.编写实现代码b.用service.xml来解释这个服务c.创建一个*.aar的服务部署包d.发布服务Step 1:实现代码public class MyService public void ping(OMElement element) . public OMElement echo(OMElement element) . Step 2:通过service.xml来描述服务 This is a sample Web Service with two operations, echo and ping. userguide.example1.MyService urn:echo urn:ping说明：For the echo operation we have used a RawXMLINOutMessageReceiver since it is an IN-OUT operation. For IN-ONLY operation ping, we have used RawXMLINOnlyMessageReceiver as the message receiver.The actionMapping is required only if you want to enable WS-Addressing.还可以用这个文件来描述一组服务，这组服务之间可以共享ServiceGroupContext value 1Step 3:创建服务发布包这个服务发布包的结构如图所示。将这些文件按照图中的结构组织好，然后打包成jar或者rar，然后修改后缀名为aar即可。Step 4:部属服务将服务发布包放到/webapps/axis2/WEB-INF中的services文件夹下，然后在Axis2的首页(http:/localhost:8080/axis2/index.jsp)的services连接下察看服务发布情况2）用服务代码生成的方式创建服务首先要写好服务的wsdl然后利用WSDL2Java工具该工具的命令有：Usage WSDL2Code -uri : WSDL file location-o : output file location-a : Generate async style code only. Default is off-s : Generate sync style code only. Default is off. takes precedence over -a-p : set custom package name-l : 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. services.xml). Default is off. Valid with -ss-d : valid databinding(s) are adb, xmlbeans and jaxme. Default is adb-g Generates all the classes. valid only with the -ss-pn : name of port in the presence of multiple ports-sn : name of service in the presence of multiple services-u : unpacks the databinding classes-r : path of the repository against which code is generated在windows平台下可以用WSDL2Java -uri ./samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans -o ./samples -p org.apache.axis2.userguide在Linux平台下可以用WSDL2Java -uri ./samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans -o ./samples -p org.apache.axis2.userguide于是生成了服务的代码框架，在代码框架中填入代码第三部分：用Axis2创建服务客户端服务可以完成各种各样的功能，有的简单，时间消费比较低，有的复杂，时间消费比较高。我们不能采用一个统一的机制来调用这些时间消费区别很大的服务。例如：我们用HTTP协议来带调用一个IN-OUT类型的服务，而这个服务的执行时间很长，于是我们可能得到一个connection time out的结果。而且，在一个客户端同时发出两个服务调用请求的情况下，使用blocking的客户端API将降低客户端程序的性能。类似的，当我们使用One-Way传输的时候还可能有很多其他的后果产生。Blocking API:当服务调用请求发出后，客户端等待服务结果的返回，这期间不能再发出服务调用请求。Non-Blocking API:这是一个基于callback或者polling的API，让客户端发出服务调用请求的时候，客户端程序立刻得到控制权，服务的调用结果由callback对象来接收。这样，客户端就可以同时调用多个服务而不进行阻止。Axis将利用Non-Blocking API方式的异步叫做API Level Asynchrony前面提到的两个机制在Request和Response上使用了一个的传输连接，他们限制了服务调用在请求与结果返回使用两个传输连接的情况( either One-Way or Two-Way )。所以这两种机制都无法解决在长时间运行的事务中的寻址问题（传输连接可能在操作结束前就已经timeout了）。一种解决方案是在request和response中使用两个不同的传输连接。在这个级别上得到的异步属性，称为Transport Level Asynchrony将前面的2种异步结合起来，就有了四种不同的调用模式服务的调用代码：blocking invocationtry OMElement payload = ClientUtil.getEchoOMElement();Options options = new Options();options.setTo(targetEPR); / this sets the location of MyService serviceServiceClient serviceClient = new ServiceClient();serviceClient.setOptions(options);OMElement result = sender.sendReceive(payload);System.out.println(result); catch (AxisFault axisFault) axisFault.printStackTrace();IN-ONLYtry OMElement payload = ClientUtil.getPingOMElement();Options options = new Options();options.setTo(targetEPR);ServiceClient serviceClient = new ServiceClient();serviceClient.setOptions(options);serviceClient.fireAndForget(payload);/*We have to block this thread untill we send the request , the problemis if we go out of the*main thread , then request wont send ,so you have to wait some time :) */Thread.sleep(500); catch (AxisFault axisFault) axisFault.printStackTrace();You can test this client by running the target testPingClient of the ant build file at Axis2Home/samples/userguide.EchoBlockingClient将第一段代码的调用代码改为serviceClient.sendReceiveNonblocking(payload, callback);具体的例子在Axis2Home/samples/userguide/src/userguide/clients中Axis提供三个方法来接收callback对象public abstract void onComplete(AsyncResult result);public abstract void onError(Exception e);public boolean isComplete() 其中，前面两个是需要用户来实现的EchoNonBlockingDualClienttry OMElement payload = ClientUtil.getEchoOMElement();Options options = new Options();options.setTo(targetEPR);options.setTransportInProtocol(Constants.TRANSPORT_HTTP);options.setUseSeparateListener(true);options.setAction(urn:echo);/ this is the action mapping we put within the service.xml/Callback to handle the responseCallback callback = new Callback() public void onComplete(AsyncResult result) System.out.println(result.getResponseEnvelope();public void onError(Exception e) e.printStackTrace();/Non-Blocking Invocationsender = new ServiceClient();sender.engageModule(new QName(Constants.MODULE_ADDRESSING);sender.setOptions(options);sender.sendReceiveNonBlocking(payload, callback);/Wait till the callback receives the response.while (!callback.isComplete() Thread.sleep(1000);/Need to close the Client Side Listener. catch (AxisFault axisFault) axisFault.printStackTrace(); catch (Exception ex) ex.printStackTrace(); finally try sender.finalizeInvoke(); catch (AxisFault axisFault) /have to ignore this在Server端添加Addressing支持的方式是，在Addressing Module中，将Handlers的描述放在”pre-dispatch”语句中，那么它的加载则需要通过在/webapps/axis2/WEB-INF文件夹下的axis2.xml中增加一句话来完成：客户端支持Addressing的方式，一种是将addressing-.mar放在classpath中，另一种就是根据给定的库位置创建一个ConfigurationContext具体的做法是在sender = new ServiceClient();之前加上ConfigurationContext configContext = ConfigurationContextFactory.createConfigurationContextFromFileSystem(, null);然后将sender = new ServiceClient();改为sender = new ServiceClient(configContext, null);EchoBlockingDualClient示例代码可以在Axis2Home/samples/userguide/src/userguide/clients/中找到，它与EchoNonBlockingDualClient相似，在这种情况下不再需要callback来处理response。这个机制非常适用于处理IN-OUT类型的调用，而传输协议却是One-Way(SMTP)的情况。我们可以用Axis2Home/samples/userguide中的echoBlockingDualClient来测试第四部分：Module构造和部署Module分为以下几个步骤：a.创建Module的实现b.创建Handlersc.创建module.xmld.修改axis2.xml（如果你需要定制的语句）e.修改services.xml在Axis部署的时候使用这些Modulesf.在Axis2中部署这些Modules现在来创建一个简单的Logging Module，这个Module包含一个Hander，它的作用就是纪录通过它的消息。Axis通过*.mar来部署Modules，下图就是这个部署包的结构Step 1:创建LoggingModule ClassLogging Module是Axis2 Module的实现，它必须实现org.apache.axis2.modules.Module接口：Step 2:创建LogHandlerAxis的一个Module可以包含一个或者多个Handler。这些Handler将处理Soap头文件中的不同phases。一个Handler必须实现org.apache.axis2.engine.Handler接口，或者通过另一种简单方式，继承org.apache.axis2.handlers.AbstractHandler类public class LogHandler extends AbstractHandler implements Handler private Log log = LogFactory.getLog(getClass(); private QName name;public QName getName() return name; public void invoke(MessageContext msgContext) thr