Axis2配置指南（翻译）

Axis2配置指南（翻译）
关键字: Axis2
In Axis2, there are three kinds of configuration files to configure the system. The first one is to configure the whole system (global configuration), the second one is to configure a service (service configuration), and the third one is to configure a module (module configuration). This document explains the above configurations in detail.

在Aixs2中，有三个文件可以用来配置系统。第一个配置整个系统（全局配置），第二个配置一个服务（服务配置），第三个配置一个模块（模块配置）。本文档详细介绍上面的配置。

内容
全局配置 (axis2.xml)
服务配置(services.xml)
模块配置 (module.xml)
全局配置

书写axis2.xml

所有在启动axis2时需要的配置信息都从axis2.xml中取得。指明它们的方法非常简单和容易。此部分都是关于如何在axis2中以合适的方式指定配置信息的，在配置文件中可以看到六个顶级元素，如下：

Parameter
Transport Receiver
Transport Sender
Phase Order
Module References
Listeners (Observers)
Parameter：在Axis2中，parameter（参数）就是一个名－值对，axis2.xml中的每个顶级parameter元素将都被转换成AxisConfiguration中的属性，因此，配置文档中的顶级参数都可以在运行时环境中通过AxisConfiguration得到。下面是定义参数的正确的方法：

<parameter name="name of the parameter" >parameter value parameter>  


TransportReceiver:依赖于Axis2可能需要运行于其上的传输协议（Depending on the underlying transport on which Axis2 is going to run,），你需要不同的传输接收端。在系统中加入它们的方式如下：






<transportReceiver name="http" class="org.apache.axis2.transport.http.SimpleHTTPServer">  
        <parameter name="port" >6060parameter>  
transportReceiver>   



上面的元素说明了如何在axis2.xml中定义传输接收端，这里，transportReceiver标签中的name属性标识指明传输接收端的类型，它可以是http,tcp,smtp,CommonsHTTP等。当系统启动或者你在客户端设置传输器（transport）的时候，你可以使用这些传输名字（transport names）装载合适的传输器。class属性是为了指明为该传输器实现需要的接口的实际的java类。任何的传输都可以有0个或多个参数，任何给定的参数可以通过相应的传输接收端访问。

Transport Sender：正如传输接收者，你可以在系统中注册传输发送者，也可以在运行时进行。发送者可以用来发送消息。例如，假设Axis2运行于Apache Tomcat中。那么Axis2可以使用TCP传输发送器来发送消息，而不是http。指明传输发送者的方法如下：

xml 代码
<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">  
        <parameter name="PROTOCOL" locked="xsd:false">HTTP/1.0parameter>  
transportSender>   

name：传输的名字，可以是http或者http1。

class：相应传输的实现类。

和传输接收者一样，传输发送者可以有0个或多个参数（例如例子中有一个parameter），如果存在，它们可以通过相应的传输发送者得到。

Phase Order：指明执行链中阶段的顺序必须使用phase order元素。如下：

xml 代码
<phaseOrder type="InFlow">  
         <phase name="TransportIn"/>  
         .   
         .   
phaseOrder>     

最有趣的是你也可以在这里添加handler。如果你想要添加一个handler到一个阶段中，你可以直接通过在它里面添加一个handler元素来实现。除此之外，Axis2中没有其他的进行handler链硬编码的地方。因此，所有的那些配置也在phase order元素中完成。完整的代码如下：



xml 代码
<phaseOrder type="InFlow">  
          
         <phase name="Transport">  
            <handler name="RequestURIBasedDispatcher"  
                     class="org.apache.axis2.dispatchers.RequestURIBasedDispatcher">  
                <order phase="Transport"/>  
            handler>  
  
            <handler name="SOAPActionBasedDispatcher"  
                     class="org.apache.axis2.dispatchers.SOAPActionBasedDispatcher">  
                <order phase="Transport"/>  
            handler>  
        phase>  
        <phase name="Security"/>  
        <phase name="PreDispatch"/>  
        <phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase">  
            <handler name="AddressingBasedDispatcher"  
                     class="org.apache.axis2.dispatchers.AddressingBasedDispatcher">  
                <order phase="Dispatch"/>  
            handler>  
  
            <handler name="SOAPMessageBodyBasedDispatcher"  
                     class="org.apache.axis2.dispatchers.SOAPMessageBodyBasedDispatcher">  
                <order phase="Dispatch"/>  
            handler>  
  
            <handler name="InstanceDispatcher"  
                     class="org.apache.axis2.engine.InstanceDispatcher">  
                <order phase="Dispatch"/>  
            handler>  
        phase>  
          
          
        <phase name="OperationInPhase"/>  
    phaseOrder>  
    <phaseOrder type="OutFlow">  
          
        <phase name="OperationOutPhase"/>  
          
          
        <phase name="MessageOut"/>  
        <phase name="PolicyDetermination"/>  
    phaseOrder>  
    <phaseOrder type="InFaultFlow">  
        <phase name="PreDispatch"/>  
        <phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase">  
            <handler name="RequestURIBasedDispatcher"  
                     class="org.apache.axis2.dispatchers.RequestURIBasedDispatcher">  
                <order phase="Dispatch"/>  
            handler>  
  
            <handler name="SOAPActionBasedDispatcher"  
                     class="org.apache.axis2.dispatchers.SOAPActionBasedDispatcher">  
                <order phase="Dispatch"/>  
            handler>  
  
            <handler name="AddressingBasedDispatcher"  
                     class="org.apache.axis2.dispatchers.AddressingBasedDispatcher">  
                <order phase="Dispatch"/>  
            handler>  
  
            <handler name="SOAPMessageBodyBasedDispatcher"  
                     class="org.apache.axis2.dispatchers.SOAPMessageBodyBasedDispatcher">  
                <order phase="Dispatch"/>  
            handler>  
            <handler name="InstanceDispatcher"  
                     class="org.apache.axis2.engine.InstanceDispatcher">  
                <order phase="Dispatch"/>  
            handler>  
        phase>  
          
        <phase name="OperationInFaultPhase"/>  
    phaseOrder>  
    <phaseOrder type="OutFaultFlow">  
          
        <phase name="OperationOutFaultPhase"/>  
        <phase name="PolicyDetermination"/>  
        <phase name="MessageOut"/>  
    phaseOrder>  

type：代表流的类型的属性，只能是以下几种：

InFlow
OutFlow
InFaultFlow
OutFaultFlow
除此之外，允许在phaseOrder内出现的元素是phase元素。phase元素代表了执行链中可用的phases。在phaseOrder中指明phase的方法如下：

xml 代码
<phase name="Transport"/>  

name：phase的名字。

改变phaseOrder的时候，必须牢记一些事情：

如果phaseOrder的类型是InFlow和InFaultFlow

1.  所有在"Dispatch"阶段（phase）上的阶段，包括它本身，都是全局阶段（Global Phase）。你可以在这里添加任意数量的新阶段，这些阶段都可以被认为是全局的。

2.在这两个phaseOrder类型中，添加在Dispatch之后的阶段，被认为是操作阶段（Operation Phase）。

如果phaseOrder类型是OutFlow和OutFaultFlow

1.所有在"MessageOut"阶段（phase）下的阶段，包括它本身，都是全局阶段（Global Phase）。你可以根据需求添加任意新的阶段。

2.添加在MessageOut阶段之前的阶段被认为是操作阶段。

注意：如果你认真观者默认的axis2.xml，你讲可以明确得发现这些。

Module References

如果你想要在系统范围内启用一个模块，你可以通过在axis2.xml文件中增加一个顶级模块元素来实现，例如：

xml 代码
<module ref="addressing" />  

ref：将要被启用的模块的名字，系统范围。

Listeners（Observers）：在Axis2中，AxisConfiguration是可被监听的，因此你可以把监听器注册进去。当AxisConfiguration发生改变时，监听器会自动得被通知到。就现在的实现而言，监听器会被通知到下述事件：

Deploying a service

Removing a service

Activate/Inactivate Service

Module deploy

Module Remove

注册监听器对附加的功能非常有用，例如RSS种子的生成，它将向订阅者提供服务信息。下面是注册监听器的正确方法：

xml 代码
<listener class="org.apache.axis2.ObserverIMPL">  
    <parameter name="RSS_URL" >http://127.0.0.1/rssparameter>  
listener>  

class：代表监听器的实现类，需要注意该实现类必须实现AxisObserver接口，并且必须在classpath中。

服务配置（Service Configuration）

书写services.xml：服务的描述使用services.xml指明。每个服务.aar文件都需要一个services.xml文件以便成为有效的服务，并且这个文件应该放置在META-INF目录下。一个非常简单的services.xml如下：

xml 代码
<service name="name of the service" scope="name of the scope" class="full qualifide name the service lifecycle class"   targetNamespace="target namespase for the service">  
    <description> The description of the service  description>     
  
    <transports>    
       <transport>HTTPtransport>  
    transports>  
       
    <schema schemaNamespace="schema namespace"/>    
        
    <messageReceivers>  
            <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"  
                             class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>  
    messageReceivers>  
        
     <parameter name="ServiceClass" locked="xsd:false">org.apache.axis2.sample.echo.EchoImplparameter>  
       
    <operation name="echoString" mep="operation MEP">    
        <actionMapping>Mapping to actionactionMapping>  
        <module ref=" a module name "/>  
        <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>  
    operation>  
  service>  

name：服务的名字将会是.aar文件的名字，如果该文件中只包含一个服务。或者，将是此name属性指定的名字。

scope：（可选属性）说明部署的服务的运行时信息在什么时间段是有效的。该范围有几种类型，"Application"，"SOAPSession"，"TransportSession"，"Request"，默认值是"Request"。

class：（可选属性）服务生命周期实现类的全名。服务生命周期类可以在系统启动和关闭是做一些任务。

targetNameSpace：（可选属性）服务的命名空间。这个值将在生成WSDL时用到。如果不指定，这个值将会根据服务实现类的包名生成。

description：（可选）如果你想通过Axis2 web-admin模块显示关于service的描述，可以使用该标签。

transports：（可选）服务将被发布成什么传输方式。如果transport标签没有出现，那么服务将会以系统中支持的所有传输协议发布。transport子元素指明传输前缀（也就是axis2.xml指定的传输的名字）。

parameters：services.xml可以包含任意数量的顶级parameters，所有的指定的parameters将会转换成相应的AxisService中的服务属性。services.xml中有一个强制性参数叫做ServiceClass指定java类，该java类执行上面的转换，这个类由MessageReceiver装载。
operations：如果服务实现类是java，该服务中所有的公用方法都会被公开。如果用户想覆盖它，就需要使用"operations"标签。在一个非java环境或者没有服务类的情况下，用户想发布的所有方法都必须在services.xml中指定。例如：

xml 代码
<operation name="echoString">  
    <module ref=" a module name "/>  
    <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>  
operation>  

name是唯一必须的属性，它代表将被发布的操作的名字。操作可以包含模块指针也可以包括任何数量的参数。最有趣的是你可以为每个操作注册客户消息接收器。从而，注册的消息接收器将成为相应的操作的消息接收器。如果你不指定消息接收器，那么默认的消息接收器将执行操作。

模块配置（Module Configuration）

书写module.xml

模块的描述使用module.xml描述。每个mar文件需要module.xml文件以便成为有效的模块，并且，这个文件需要放在模块的META-INF文件夹下。下面是一个非常简单的module.xml文件。

xml 代码
<module class="org.apache.module.Module1Impl">  
    <InFlow>  
        .   
        .   
    InFlow>  
    <OutFlow>  
        .   
        .   
    OutFlow>  
  
    <OutFaultFlow>  
        .      
        .   
    OutFaultFlow>  
  
    <InFaultFlow>  
        .            
        .   
    InFaultFlow>  
  
    <operation name="creatSeq" mep="MEP_URI_IN_OUT">  
        <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>  
        <parameter name="para1" locked="xsd:true">10parameter>  
    operation>  
module>  

class：（可选参数）说明模块的实现类，一个模块可以包含实现类，也可以不包含实现类，这是因为模块也可以是handler的集合。如果一个模块包含了实现了org.apache.axis2.modules.Module接口的实现类，那么在部署时，它的init()方法将会被调用。

parameter：一个模块可以包含任意数量的参数，所有在module.xml中列出来的参数将被转换成这个module的相应的AxisModule。

flow：在模块中定义handlers必须定义在flows当中。总共有4种flows的类型。

你可以在一个flow当中添加任意数量的handlers。当启动时，那些handlers将会在相应的链中。

(原文：You can add any number of handlers into a flow, and those handlers will be available in the corresponding chains at runtime, when they are engaged.)

InFlow

OutFlow

InFaultFlow

OutFaultFlow

operations：如果一个模块想在它在某个服务中启动时增加一个操作的话，可以通过在module.xml中增加一个operation标签。这里声明操作的方法与在services.xml中声明操作的方法相同。

handler：handler元素由必须的和可选的属性组成。定义一个handler的方法如下：

xml 代码
<handler name="handler1" class="handlerClass ">  
            <order phase="userphase1" />  
handler>  

必须的属性：

name：handler的名字。

class：handler的实现类。

phase：handler在执行链中应该所处的阶段的名字。

可选的属性：

phaseLast：说明handler是phase中的最后一个。

phaseFirst：说明handler是phase中的第一个。

before：说明当前handler应该在被before标识的handler之前被触发。

after：说明当前handler应该在被after标识的handler之后被触发。