Axis2 Configuration Guide

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.

Content

Global Configuration (axis2.xml)

All the configurations that require starting Axis2 are obtained from axis2.xml. The way to specify them is extremely simple and easy. The document is all about the proper way of specifying the configurations in axis2.xml, which is located at AXIS2_HOME/conf. There are six top level elements that can be seen in the configuration file inside the root element, <axisconfig name="AxisJava2.0"> and can be listed as follows:

Parameter

In Axis2, a parameter is nothing but a name-value pair. Each and every top level parameter available in the axis2.xml (direct sub elements of the root element) will be transformed into properties in AxisConfiguration. Therefore, the top level parameters in the configuration document can be accessed via AxisConfiguration in the running system. The correct way of defining a parameter is shown below:

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

Transport Receiver

Depending on the underlying transport on which Axis2 is going to run, you need to have different transport receivers. The way you add them to the system is as follows:

<transportReceiver name="http" class="org.apache.axis2.transport.http.SimpleHTTPServer">
    <parameter name="port" >6060</parameter>
</transportReceiver>
The above elements show how to define transport receivers in axis2.xml. Here the "name" attribute of the <transportReceiver/> element identifies the type of the transport receiver. It can be HTTP, TCP, SMTP, etc. When the system starts up or when you set the transport at the client side, you can use these transport names to load the appropriate transport. The "class" attribute is for specifying the actual java class that will implement the required interfaces for the transport. Any transport can have zero or more parameters, and any parameters given can be accessed via the corresponding transport receiver.

Transport Sender

Just like the transport receivers, you can register transport senders in the system, and later at run time, the senders can be used to send the messages. For example, consider Axis2 running under Apache Tomcat. Then Axis2 can use TCP transport senders to send messages rather than HTTP. The method of specifying transport senders is as follows:

 
<transportSender name="http" class="org.apache.axis2.transport.http.impl.httpclient4.HTTPClient4TransportSender">
        <parameter name="PROTOCOL" locked="xsd:false">HTTP/1.0</parameter>
 </transportSender>
name: Name of the transport (you can have HTTP and HTTP1 as the transport name)

class: Implementation class of the corresponding transport.

Just like the transport receivers, transport senders can have zero or more parameters, and if there are any, they can be accessed via the corresponding transport sender.

Phase Order

Specifying the order of phases in the execution chain has to be done using the phase order element. It will look as follows:

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

The most interesting thing is that you can add handlers here as well. If you want to add a handler that should go into that phase, you can directly do that by adding a handler element into it. In addition to that, there is no hard coding work for the handler chain anywhere in Axis2 (at any Axis*). So all those configurations are also done in the phase order element. The complete configurations will look as follows: 

<phaseOrder type="InFlow">
        <!--   Global phases    -->
         <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>
        <!--   Global phases   -->
        <!--   After the Dispatch phase module author or service author can add any phase he wants    -->
        <phase name="OperationInPhase"/>
    </phaseOrder>
    <phaseOrder type="OutFlow">
        <!--   user can add his own phases to this area  -->
        <phase name="OperationOutPhase"/>
        <!--  Global phases  -->
        <!--  these phases will run irrespective of the service  -->
        <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>
        <!--      user can add his own phases to this area  -->
        <phase name="OperationInFaultPhase"/>
    </phaseOrder>
    <phaseOrder type="OutFaultFlow">
        <!--      user can add his own phases to this area  -->
        <phase name="OperationOutFaultPhase"/>
        <phase name="PolicyDetermination"/>
        <phase name="MessageOut"/>
    </phaseOrder>

type: the attribute represents the type of the flow. It can only be one of the following:

  • InFlow
  • OutFlow
  • InFaultFlow
  • OutFaultFlow

In addition to that, the only child element that is allowed inside "phaseOrder" is the "phase" element which represents the available phases in the execution chain. The method of specifying phases inside "phaseOrder" is as follows:

<phase name="Transport"/>

name: Name of the phase.

There are a number of things that one has to keep in mind when changing a phaseOrder:

For the phaseOrder types "InFlow" and "InFaultFlow"

  • All the phases that are above the "Dispatch" phase, including the "Dispatch" phase, are known as "Global phases" . You can add any number of new phases here and they will be considered global.
  • In these two phaseOrder types, the phases added after the "Dispatch" phase are known as "Operation phases".

For the phaseOrder types "OutFlow" and "OutFaultFlow"

  • All the phases that are below the "MessageOut" phase, including the "MessageOut" phase, are known as "Global phases". You can add new phases according to your requirement.
  • The phases added before the "MessageOut" phase are known as "Operation phases".

    • Note : If you look closely at the default axis2.xml, you will be able to clearly identify it.

Module References

If you want to engage a module, system wide, you can do it by adding a top level module element in axis2.xml. It should look as follows:

<module ref="addressing"/>

ref: the module name which is going to be engaged, system wide.

Listeners (Observers)

In Axis2, AxisConfiguration is observable so that you can register observers into that. They will be automatically informed whenever a change occurs in AxisConfiguration. In the current implementation, the observers are informed of the following events:

  • Deploying a Service
  • Removing a service
  • Activate/Inactivate Service
  • Module deploy
  • Module remove

Registering Observers is very useful for additional features such as RSS feed generation, which will provide service information to subscribers. The correct way of registering observers should as follows:

<listener class="org.apache.axis2.ObserverIMPL">
    <parameter name="RSS_URL" >http://127.0.0.1/rss</parameter>
</listener>

class: Represents an Implementation class of observer, and it should be noted that the Implementation class should implement AxisObserver interface, and the class has to be available in the classpath.

Service Configuration (services.xml)

The description of services are specified using services.xml. Each service archive file needs to have a services.xml in order to be a valid service and it should be available in the META-INF directory of the archive file(aar) which should be located in AXIS2_HOME/repository/services in standalone use. In war distribution this will be axis2/WEB-INF/services inside the servlet container. A very simple services.xml is shown below:

<service name="name of the service" scope="name of the scope" 
    class="fully qualified name the service lifecycle class"   
    targetNamespace="target namespace for the service">
    
    <description> The description of the service  </description>  

    <transports> 
        <transport>HTTP</transport>
    </transports>
    
    <schema schemaNamespace="schema namespace"/> 
     
    <messageReceivers>
            <messageReceiver mep="http://www.w3.org/ns/wsdl/in-out"
                             class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
    </messageReceivers>
     
    <parameter name="ServiceClass" locked="xsd:false">org.apache.axis2.sample.echo.EchoImpl</parameter>
    
    <operation name="echoString" mep="operation MEP"> 
        <actionMapping>Mapping to action</actionMapping>
        <module ref=" a module name "/>
        <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
    </operation>
</service>

name: The service name will be the name of the archive file if the .aar file contains only one service, or else the name of the service will be the name given by the name attribute.

scope: (Optional Attribute) The time period during which runtime information of the deployed services will be available. Scope is of several types- "application", "soapsession", "transportsession", "request". The default value (if you don't enter any value) will be "request"

class: (Optional attribute) The full qualified name of the service lifecycle implementation class. ServiceLifeCycle class is useful when you want to do some tasks when the system starts and when it shuts down.

targetNamespace: (Optional Attribute) Target name space of the service. This value will be used when generating the WSDL. If you do not specify this value, the value will be calculated from the package name of the service impl class.

Description: (Optional) If you want to display any description about the service via Axis2 web-admin module, then the description can be specified here.

transports : (Optional) The transports to which the service is going to be exposed. If the transport element is not present, then the service will be exposed in all the transports available in the system. The transport child element specifies the transport prefix (the name of the transport specified in axis2.xml).

parameters: A services.xml can have any number of top level parameters and all the specified parameters will be transformed into service properties in the corresponding AxisService. There is a compulsory parameter in services.xml called ServiceClass that specifies the Java class, which performs the above transformation. This class is loaded by the MessageReceiver.

operations : If the service impl class is Java, then all the public methods in that service will be exposed. If the user wants to override it, he has to add the "operation" tag and override it. In a non-Java scenario or if you do not have a service class, then all the operations the user wants to expose by the service has to be indicated in the services.xml. It is specified as follows:

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

The only compulsory attribute here is "name", which represents the operation name that is going to be exposed. Any operation can contain module references as well as any number of parameters. The most interesting thing is that you can register custom message receivers per operation. Then the registered message receiver will be the message receiver for the corresponding operation. If you do not specify the message receiver, then the default message receiver will perform the operation.

Module Configuration (module.xml)

The description of the module is specified using the module.xml. Each module archive file needs to have a module.xml in order to be a valid module, and it should be available in the META-INF directory of the archive file(mar) which should be located in AXIS2_HOME/repository/modules in standalone use. In war distribution this will be axis2/WEB-INF/modules inside the servlet container.

A very simple module.xml is shown below:

<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">10</parameter>
    </operation>
</module>

class: (Optional attribute) Indicates the module implementation class. A module may or may not contain a module implementation class since the module can also be a collection of handlers. If a module contains an implementation class that implements the org.apache.axis2.modules.Module interface at deployment, its init(); method will be called.

parameter: A module can contain any number of parameters and all the listed parameters in the module.xml will be transformed into the corresponding AxisModule of the module.

flow: Defining of handlers in a module has to be done inside flows. There are four types of flows as listed below.

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: If a module wants to add an operation when it is engaged into a service, it can be done by adding an operation tag in module.xml. The method of specifying the operation is the same as operation in services.xml.

handler: The Handler element consists of compulsory and optional attributes. The method of defining a handler will look as follows:

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

Compulsory Attributes
name: Name of the handler.
class: Handler implementation class.
phase: Name of the phase that the handler should remain, in the execution chain.

Optional Attributes :
phaseLast: Indicates that the handler is the last handler of the phase.
phaseFirst: Indicate that the handler is the first handler of the phase.
before : Indicates that the current handler should be invoked before the handler specified by the before handler
after: Indicates that the current handler should be invoked after the handler specified by the after handler