Axis2中文手册范本

1、中文原文tenn.javaeye./blog/100736英文原文/axis2/1_0/userguide.html概述这个说明文档涉及以下容：如何使用axis2创建webservice和客户端程序如何定制一个模块(Module)并在webservice中使用它SamplesdiscussionAdvancedTopics第一部分：简介Axis2是重新设计的一个架构，它没有基于Axis1.*的结构，这种新的架构muchmoreflexible,efficientandconfigurable。Axis2的特性有：Speed:采用自己的对象模型，利用StAX解析Lowm

2、emoryfootprint:Axis2在设计过程中一直遵循lowmemorycost的理念AXIOM采用自己的轻量级的对象模型，使得消息处理过程可扩展、性能高，对开发者来说更加简单。HotDeployment:Axis2装备了在系统运行时部署服务和处理器的能力。也就是说，新的服务新服务的添加不再需要重启服务器。将服务的发布包放在服务部属文件夹中，部署模型将自动部署该服务。AsynchronousWebServices:Axis2现在可以通过non-blockingclientsandtransports支持异步的服务和异步的服务调用。(？什么是异步的服务？)MEPSupport:Axis2具

3、备良好的伸缩性来支持MEPs,因为它置了对WSDL2.0中MEPs的支持。Flexibility:Axis2的架构使得程序员能自由的对Axis添加扩展，这些扩展包括对自定义Header的处理，系统管理，甚至是任何一件你可以想象的到的事情Stability:Axis2定义了一套公共接口，这些接口相对于其他代码而言改动很小Component-orientedDeployment:你可以自定义一些在处理过程中常用的可重用的处理器，并可以将这些处理器发布出来供其它人使用TransportFramework:定义了一个干净、简单的抽象作品来集成任意的传输协议，引擎的核心部分的实现是与传输协议无关的Add

4、-ons：一些webservice相关的协议也合并了进来。如安全方面的WSS4J(Rampart),可靠消息传输的Sandesha,封装了WS-Coordination,WS-AtomicTransaction和WS-BusinessActivity的Kandula。CompositionandExtensibility:模块和层支持可扩展性和可组合性(composability)。模块支持可组合性，对添加新的webservice规的支持的方式非常简单和干净。但是他们并不是热部署的，因为他们影响整个系统的功能。Tips:WSS4J:/wss4j/ApacheWSS4J

5、sanimplementationoftheOASISWebServicesSecurity(WS-Security)fromOASISWebServicesSecurityTC.WSS4JisaprimarilyaJavalibrarythatcanbeusedtosignandverifySOAPMessageswithWS-Securityinformation.WSS4JwilluseApacheAxisandApacheXML-SecurityprojectsandwillbeinteroperablewithJAX-RPCbasedserver/clientsand.NETserv

6、er/clients.这个项目提供了在Axis上部署的帮助文档和例子Rampart这是Axis2的一个Module(现在Axis2有两个可选的Module,分别是Addressing和Security,Addressing包含在Standard版本中，但是Rampart需要单独下载)，目前作用不详，猜测是与WSS4J合作完成WS-SecuritySendesha:/sandesha/Sandesha2isanimplementationofWS-ReliableMessagingspecificationpublishedbyIBM,Microsoft,BEAandT

7、IBCO.Sandesha2wasbuiltontopofAxis2.ThereforebyusingSandesha2youcanaddreliablemessagingcapabilitytothewebserviceshostedusingAxis2.Sandesha2canalsobeusedwithAxis2clienttointeractwithalreadyhostedwebservicesinareliablemanner.Pleaseseesandesha2userguideformoreinformationonusingSandesha2.Kandula:ws.apach

8、/kandula/2/index.htmlKandulawillprovideanopen-sourceimplementationofWS-Coordination,WS-AtomicTransactionandWS-BusinessActivitybasedonAxis.TheinitialimplementationwillbeinJavausingAxis/Java.Inadditiontoprovidinganimplementation,amajorfocusofthisprojectwouldbetoensureinteroperabilitywithotherimpl

9、ementationsofabovespecifications,particularlythosebyMicrosoft(.NET)andIBM.首先你需要在Servlet容器中部署axis2.war可以通过两种方式来创建webservices1. 使用Axis2的API,实现业务代码2. 从WSDL开始，生成代码框架，然后实现业务逻辑1 )使用Axis2的API首先，计划生成一个服务MyService,它有两个方法：publicvoidping(OMElementelement)。/IN-ONLYoperation,justacceptstheOMElementanddosomeproce

10、ssing.publicOMElementecho(OMElementelement)/IN-OUToperation,acceptsanOMElementandsendsbackthesameagain从例子里找到实现的代码："Axis2Home/samples/userguide/src"中的"userguide/example1"创建一个服务分4个步骤a. 编写实现代码b. 用service.xml来解释这个服务c. 创建一个*.aar的服务部署包d. 发布服务Step1:实现代码publicclassMyServicepublicvoidping

11、(OMElementelement)publicOMElementecho(OMElementelement)ThisisasampleWebServicewithtwooperations,echoandping.userguide.examplel.MyServiceurn:echourn:ping说明：Forthe"echo"operationwehaveusedaRawXMLINOutMessageReceiversinceitisanIN-OUToperation.ForIN-ONLYoperation"ping",wehaveusedRawX

12、MLINOnlyMessageReceiverasthemessagereceiver.TheactionMappingisrequiredonlyifyouwanttoenableWS-Addressing.ServiceGroupContext还可以用这个文件来描述一组服务，这组服务之间可以共享<!-detailsforService1-><!-detailsforService2->value1Step3:创建服务发布包这个服务发布包的结构如图所示。将这些文件按照图中的结构组织好，然后打包成jar或者rar,然后修改后缀名为aar即可。WMIIIMWIIMlI-M

13、ETA-INF共5已FviB.xnnl®MyServiceStep4:部属服务将服务发布包放到"/webapps/axis2/WEB-INF"中的"services”文件夹下，然后在Axis2的首页(localhost:8080/axis2/index.jsp)的'services'连接下察看上 9 L Serwicm Mazilla 4 ire#cm服务发布情况ApacheSoftwareFoundationhttp:/www.apactie.crg/AvailableservicesmEPRi*1：fIccilhMt和时川咬Sv.ic

14、eS*nic«DotcnplieknTNiatATHpieWtbS«rvicawithoppatio*echo*pirgversionEm同Mlp"a浦3*1i0S0<'iMts2-s*r.ic0i-.«iiiiQn&ervice.吞cmpLi口riThiswrwice%IogettherunnimgA.mk»verssoliTbtAkIw的*w»FwndMiQfi2 ）用服务代码生成的方式创建服务首先要写好服务的wsdl然后利用WSDL2Java工具该工具的命令有：UsageWSDL2Code-uri:WSDL

15、filelocation- o:outputfilelocation- a:Generateasyncstylecodeonly.Defaultisoff- s:Generatesyncstylecodeonly.Defaultisoff.takesprecedenceover-a- p:setcustompackagename- l:validlanguagesarejavaandcsharp.Defaultisjava- t:GenerateTestCasetotestthegeneratedcode- ss:Generateserversidecode(i.e.skeletons).De

16、faultisoff- sd:Generateservicedescriptor(i.e.services.xml).Defaultisoff.Validwith-ss- d:validdatabinding(s)areadb,xmlbeansandjaxme.Defaultisadb- gGeneratesalltheclasses.validonlywiththe-ss- pn:nameofportinthepresenceofmultipleports- sn:nameofserviceinthepresenceofmultipleservices- u:unpacksthedatabi

17、ndingclasses- r:pathoftherepositoryagainstwhichcodeisgenerated在windows平台下可以用WSDL2Java-uri./samples/wsdl/Axis2SampleDocLit.wsdl-ss-sd-dxmlbeans- o./samples-porg.apache.axis2.userguide在Linux平台下可以用WSDL2Java-uri./samples/wsdl/Axis2SampleDocLit.wsdl-ss-sd-dxmlbeans- o./samples-porg.apache.axis2.userguide

18、于是生成了服务的代码框架，在代码框架中填入代码第三部分：用Axis2创建服务客户端服务可以完成各种各样的功能，有的简单，时间消费比较低，有的复杂，时间消费比较高。我们不能采用一个统一的机制来调用这些时间消费区别很大的服务。例如：我们用HTTP协议来带调用一个IN-OUT类型的服务，而这个服务的执行时间很长，于是我们可能得到一个connectiontimeout的结果。而且，在一个客户端同时发出两个服务调用请求的情况下，使用blocking'的客户端API将降低客户端程序的性能。类似的，当我们使用One-Way传输的时候还可能有很多其他的后果产生。BlockingAPI:当服务调用请求发

19、出后，客户端等待服务结果的返回，这期间不能再发出服务调用请求。Non-BlockingAPI:这是一个基于callback或者polling的API,让客户端发出服务调用请求的时候，客户端程序立刻得到控制权，服务的调用结果由callback对象来接收。这样，客户端就可以同时调用多个服务而不进行阻止。Axis将利用Non-BlockingAPI方式的异步叫做APILevelAsynchrony前面提到的两个机制在Request和Response上使用了一个的传输连接，他们限制了服务调用在请求与结果返回使用两个传输连接的情况(eitherOne-WayorTwo-Way)。所以这两种机制都无法解决

20、在长时间运行的事务中的寻址问题(传输连接可能在操作结束前就已经timeout了)。一种解决方案是在request和response中使用两个不同的传输连接。在这个级别上得到的异步属性，称为TransportLevelAsynchrony将前面的2种异步结合起来，就有了四种不同的调用模式服务的调用代码：blockinginvocationtryOMElementpayload=ClientUtil.getEchoOMElement();Optionsoptions=newOptions。；options.setTo(targetEPR);thissetsthelocationofMyServic

21、eserviceServiceClientserviceClient=newServiceClient();serviceClient.setOptions(options);OMElementresult=sender.sendReceive(payload);System.out.println(result);catch(AxisFaultaxisFault)axisFault.printStackTrace();IN-ONLYtryOMElementpayload=ClientUtil.getPingOMElement();Optionsoptions=newOptions。；opti

22、ons.setTo(targetEPR);ServiceClientserviceClient=newServiceClient();serviceClient.setOptions(options);serviceClient.fireAndForget(payload);/*Wehavetoblockthisthreaduntillwesendtherequest,theproblemisifwegooutofthe*mainthread,thenrequestwontsend,soyouhavetowaitsometime:)*/Thread.sleep(500);catch(AxisF

23、aultaxisFault)axisFault.printStackTrace();Youcantestthisclientbyrunningthetarget"testPingClient"oftheantbuildfileat"Axis2Home/samples/userguide".EchoBlockingClient将第一段代码的调用代码改为serviceClient.sendReceiveNonblocking(payload,callback);具体的例子在"Axis2Home/samples/userguide/src/userg

24、uide/clients"中Axis提供三个方法来接收callback对象publicabstractvoidonComplete(AsyncResultresult);publicabstractvoidonError(Exceptione);publicbooleanisComplete()其中，前面两个是需要用户来实现的EchoNonBlockingDualClienttryOMElementpayload=ClientUtil.getEchoOMElement();Optionsoptions=newOptions。；options.setTo(targetEPR);opti

25、ons.setTransportInProtocol(Constants.TRANSPORT_HTTP);options.setUseSeparateListener(true);options.setAction("urn:echo"); this is the action mapping we put within theservice.xml/CallbacktohandletheresponseCallbackcallback=newCallback。publicvoidonComplete(AsyncResultresult)System.out.println

26、(result.getResponseEnvelope();publicvoidonError(Exceptione)e.printStackTrace();/Non-BlockingInvocationsender=newServiceClient();sender.engageModule(newQName(Constants.MODULE_ADDRESSING);sender.setOptions(options);sender.sendReceiveNonBlocking(payload,callback);/Waittillthecallbackreceivestheresponse

27、.while(!callback.isComplete()Thread.sleep(1000);/NeedtoclosetheClientSideListener.catch(AxisFaultaxisFault)axisFault.printStackTrace();catch(Exceptionex)ex.printStackTrace();finallytrysender.finalizeInvoke();catch(AxisFaultaxisFault)/havetoignorethis在Server端添加Addressing支持的方式是，在AddressingModule中，将Han

28、dlers的描述放在"pre-dispatch”语句中，那么它的加载则需要通过在"/webapps/axis2/WEB-INF"文件夹下的axis2.xml中增加一句话来完成：客户端支持Addressing的方式，种是将addressing-.mar放在classpath中，另一种就是根据给定的库位置创建一个ConfigurationContext具体的做法是在sender=newServiceClient();之前加上ConfigurationContextconfigContext=ConfigurationContextFactory.createConfi

29、gurationContextFromFileSystem(<Axis2RepositoryLocation>,null);然后将"sender=newServiceClient();"改为"sender=newServiceClient(configContext,null);"EchoBlockingDualClient示例代码可以在"Axis2Home/samples/userguide/src/userguide/clients/"中找到，它与EchoNonBlockingDualClient相似，在这种情况下不再

30、需要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中部

31、署这些Modules现在来创建一个简单的LoggingModule,这个Module包含一个Hander,它的作用就是纪录通过它的消息。Axis通过*.mar来部署Modules,下图就是这个部署包的结构亩.ioggingmodiile;工，rrria!,miliMETA-INF5岫MIFE3RMFx|modiJlB.xmll-uLogingModuleG由LogHandlarStep1:创建LoggingModuleClassLoggingModule是Axis2Module的实现，它必须实现org.apache.axis2.modules.Module接口：Step2:创建LogHandl

32、er将处Axis的一个Module可以包含一个或者多个Handler。这些Handler理Soap头文件中的不同phases。一个Handler必须实现org.apache.axis2.engine.Handler接口，或者通过另一种简单方式，继承org.apache.axis2.handlers.AbstractHandler类publicclassLogHandlerextendsAbstractHandlerimplementsHandlerprivateLoglog=LogFactory.getLog(getClass();privateQNamename;publicQNamegetName()returnname;publicvoidinvoke(MessageContextmsgContext)thr