<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta http-equiv="content-type" content="">
  <title>Axis2 Configuration Documents</title>
</head>

<body>
<p>In Axis2 there are three kinds of configuration files to configure the
system. First one configuration file is to configure whole system, second one
is to configure a service and the third one is to configure a module.</p>
<ul>
  <li><a href="#Global_Configuration">Global Configuration
  (axis2.xml)</a></li>
  <li><a href="#Service_Configuration">Service Configuration
    (services.xml)</a></li>
  <li><a href="#Module_Configuration">Module Configuration
  (module.xml)</a></li>
</ul>

<h2><a name="Global_Configuration">Global Configuration</a></h2>
<ul>
  <li>Writing axis2.xml</li>
</ul>

<p>All the configuration that requires starting axis2 is obtained from
axis2.xml. The way of specifying them is very simple and easy. The document
is all about the proper way of specifying the configurations in axis2.xml.
There are six top level elements that can be seen in the configuration file
and those can be listed as follows;</p>
<ul>
  <li>Parameter</li>
  <li>Transport Receiver</li>
  <li>Transport Sender</li>
  <li>Phase Order</li>
  <li>Module References</li>
  <li>Listeners (Observers)</li>
</ul>

<p><b>Parameter </b> <br>
In axis2 a parameter is nothing but name value pair, each and every top level
parameter available in the axis2.xml (direct sub elements of root element)
will be transformed into properties in AxisConfiguration. Therefore the top
level parameters in configuration document can be accessed via
AxisConfiguration in the running system. The correct way of defining a
parameter looks like what is shown below;</p>
<source><pre> 
  &lt;parameter name="name of the parameter" &gt;parameter value &lt;/parameter&gt;</pre>
</source>
<p><b>Transport Receiver</b><br>
Depending on the underline transport that axis going to be run , need to have
different transport receivers so the way of adding them to the system can be
done as follows;</p>
<pre> 
&lt;transportReceiver name="http" class="org.apache.axis2.transport.http.SimpleHTTPServer"&gt;
        &lt;parameter name="port" &gt;6060&lt;/parameter&gt;
 &lt;/transportReceiver&gt; 
 </pre>
</source>The above elements shows the way of defining transport receivers in
axis2.xml , here name attribute of the 'transportReceiver' element is the
name of transport it can be http, tcp , smtp , commonshttp stc , and when the
system starts up or when setting transport at the client side one can use
these transport names to load the appropriate transport. Class attribute is
to specify actual java class which implements required interfaces for the
transport. Any transport can have zero or more parameters, and if there are
any, then those parameters can be accessed via the corresponding transport
receiver.

<p><b>Transport Senders</b><br>
As same as transport receivers it is possible to register transport senders
in the system, and latter at the run time those senders can be used to send
the messages. As an example consider Axis2 running under tomcat, then axis
can use TCP transport senders to send message rather than HTTP. The way of
specifying transport senders is as follows:</p>

<p><source></p>
<pre> 
&lt;transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"&gt;
        &lt;parameter name="PROTOCOL" locked="xsd:false"&gt;HTTP/1.0&lt;/parameter&gt;
 &lt;/transportSender&gt; 
 </pre>
</source>name: Name of the transport (it is possible to have http and http1
as transport name) Class: Implementation class of the corresponding
transport. As same as transport receivers, transport senders can have zero or
more parameters, and if there is any then it can be accessed via
corresponding transport sender.

<p><b>Phase Order</b><br>
The specifying order of phases in execution chain has to be done using phase
order element and it will be look like below;</p>

<p><source></p>
<pre>&lt;phaseOrder type="inflow"&gt;
         &lt;phase name="TransportIn"/&gt;
         .
         .
&lt;/phaseOrder&gt;   </pre>
</source>The most interesting thing is that you can add handlers here as well
, if you want to add a handler which should go in to that phase you can
directly do that by adding a handler element into it . In addition to that
there is no any hard coding stuffs for handler  chain in anywhere in Axis2
(at any Axis*) , so all those configuration are also done here in phase order
element. The complete configuration will look like as follows; <source>
<pre>&lt;phaseOrder type="inflow""&gt;
        &lt;!--  System pre defined phases       --"&gt;
        &lt;phase name="TransportIn"/"&gt;
        &lt;phase name="PreDispatch"/"&gt;
        &lt;phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase"&gt;
            &lt;handler name="AddressingBasedDispatcher"
                     class="org.apache.axis2.engine.AddressingBasedDispatcher""&gt;
                &lt;order phase="Dispatch"/"&gt;
            &lt;/handler"&gt;
             &lt;handler name="RequestURIBasedDispatcher"
                     class="org.apache.axis2.engine.RequestURIBasedDispatcher""&gt;
                &lt;order phase="Dispatch"/"&gt;
            &lt;/handler"&gt;
             &lt;handler name="SOAPActionBasedDispatcher"
                     class="org.apache.axis2.engine.SOAPActionBasedDispatcher""&gt;
                &lt;order phase="Dispatch"/"&gt;
            &lt;/handler"&gt;
             &lt;handler name="SOAPMessageBodyBasedDispatcher"
                     class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher""&gt;
                &lt;order phase="Dispatch"/"&gt;
            &lt;/handler"&gt;
            &lt;handler name="InstanceDispatcher"
                     class="org.apache.axis2.engine.InstanceDispatcher""&gt;
                &lt;order phase="Dispatch"/"&gt;
            &lt;/handler"&gt;
        &lt;/phase"&gt;
        &lt;!--  Sysem pre defined phases       --"&gt;
        &lt;!--   After Postdispatch phase module author or or service author can add any phase he want      --"&gt;
        &lt;phase name="OperationInPhase"/"&gt;
    &lt;/phaseOrder"&gt;
    &lt;phaseOrder type="outflow""&gt;
        &lt;!--      user can add his own phases to this area  --"&gt;
        &lt;phase name="OperationOutPhase"/"&gt;
        &lt;!--system predefined phase--"&gt;
        &lt;!--these phase will run irrespective of the service--"&gt;
        &lt;phase name="PolicyDetermination"/"&gt;
        &lt;phase name="MessageOut"/"&gt;
    &lt;/phaseOrder"&gt;
    &lt;phaseOrder type="INfaultflow""&gt;
        &lt;!--      user can add his own phases to this area  --"&gt;
        &lt;phase name="OperationInFaultPhase"/"&gt;
    &lt;/phaseOrder"&gt;
    &lt;phaseOrder type="Outfaultflow""&gt;
        &lt;!--      user can add his own phases to this area  --"&gt;
        &lt;phase name="OperationOutFaultPhase"/"&gt;
        &lt;phase name="PolicyDetermination"/"&gt;
        &lt;phase name="MessageOut"/"&gt;
    &lt;/phaseOrder"&gt;</pre>
</source>type: the attribute represent type of the flow and which can only be
one of the following
<ul>
  <li>inflow</li>
  <li>outflow</li>
  <li>INfaultflow</li>
  <li>Outfaultflow</li>
</ul>

<p>In addition to that only child element allowed inside pahseOrder is phase
element, which represents available phases in the execution chain. The way of
specifying phase inside phaseOrder has to be done as follows;</p>

<p><source></p>
<pre> &lt;phase name="TransportIn"/&gt;</pre>
</source>name: Name of the phase. <br>
There are number of things that one has to keep in mind when changing
pahseOrder,
<ul>
</ul>
<ol>
  there are phases called system pre-defined phases in all four flows;</ol>
<ol>
  You are not allowed change those  , and you can add new phase after system
  pre-defined phase</ol>
<ol>
  If you closely look at the default axis2.xml can clearly identify that.</ol>

<p><b>Module References</b><br>
If you want to engage a module system wide you can do it by adding top level
module element in axis2.xml.  It should be look like following:</p>

<p><source></p>
<pre>&lt;module ref="addressing"/&gt;  </pre>
</source>ref: the module name which is going to be engage, system wide.

<p><strong>Listeners (Observers)</strong></p>

<p>In Axis2 AxisConfiguration is observable so that one can register
observers into that, and they will be automatically informed whenever a
change occurs in AxisConfiuration. In the current implementation the
observers are informed of the following events</p>
<ul>
  <li>Deploying a Service</li>
  <li>Removing a service</li>
  <li>Activate/Inactivate Service</li>
  <li>Module deploy</li>
  <li>Module remove</li>
</ul>
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 be like below; <source>
<pre>&lt;listener class="org.apache.axis2.ObserverIMPL"&gt;
    &lt;parameter name="RSS_URL" &gt;http://127.0.0.1/rss&lt;/parameter&gt;
  &lt;/listener&gt;</pre>
</source>class: Represent an Implementation class of observer, and it should
be note that the implementation class should implement AxisObserver
interface, and the class has to be available in the classpath. <a
name="Service_Configuration"></a>

<h2><font>Service Configuration</font></h2>
<ul>
  <li><font>Writing services.xml</font></li>
</ul>

<p><font>The description of service is specified using services.xml, each
service archive file need to have services.xml in order to be a valid
service. And which has to be available in META-INF directory of the archive
file. <br>
A very simple services.xml is shown below:</font></p>
<source><pre><font>&lt;service name="name of the service" scope="name of the scope" targetNamespace="target namespase for the service"&gt;
    &lt;description&gt; The description of the service  &lt;/description&gt;  

    &lt;transports&gt; 
       &lt;transport&gt;HTTP&lt;/transport&gt;
    &lt;/transports&gt;
    
    &lt;schema schemaNamespace="schema namespace"/&gt; 
     
    &lt;messageReceivers&gt;
            &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"
                             class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/&gt;
    &lt;/messageReceivers&gt;
     
     &lt;parameter name="ServiceClass"     locked="xsd:false"&gt;org.apache.axis2.sample.echo.EchoImpl&lt;/parameter&gt;
    
    &lt;operation name="echoString" mep="operation MEP"&gt; 
        &lt;actionMapping&gt;Mapping to action&lt;/actionMapping&gt;
        &lt;module ref=" a module name "/&gt;
        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
    &lt;/operation&gt;
  &lt;/service&gt;</font></pre>
</source><font><em><strong>name</strong></em>: the service name will be the
name of the archive file if the .aar file contains only one service else name
of the service will be the name given by the name attribute</font>

<p><em><strong>scope</strong></em> : Scope that the service need to be
deployed and scope can be one of
"Application","SOAPSession","TransportSession","Request";</p>

<p><em><strong>targetNamespace</strong></em> : Targtet name space of the
service , and this value will be used when generation wsdl</p>

<p></p>

<p><font><strong>description</strong>: This is an optional element if you
want to display any description about the service via Axis2 web-admin module
then the description can be specified here.</font></p>

<p><strong>transports</strong> : The transports that the service is going to
be exposed , this is an optional element . If the transports element is not
present then the service will be exposed in every transports available in the
system. The transport child element is to specify the transport prefix (the
name of the transport specified in axis2.xml)</p>

<p><b>Parameter:</b><br>
services.xml can have any number of top level parameters and all the
specified parameters will be transformed into service properties in
corresponding AxisService. There is a compulsory parameter in a services.xml
called ServiceClass which specify the java class which really does the job
and the class will be loaded by MessageReceiver.</p>

<p><b>Operations</b><br>
If the service impl class is java then all the public methods in that service
will be exposed and if user wnats to override then he has to add operation
tag and override that . In the case of Non-Java case or if you does no thave
service class then all the operations user wants to expose by the service has
to be indicated in the services.xml and the correct way of specifying that
should be as follows:</p>
<pre>    &lt;operation name="echoString"&gt;
        &lt;module ref=" a module name "/&gt;
        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
    &lt;/operation&gt;</pre>
</source>Only compulsory attribute here is name, which represent the
operation name that is going to be exposed. Any operation can contains module
references, any number of parameters. The most interesting is that one can
register custom message receiver per operation, then the registered message
receiver will be the message receiver for the corresponding operation. If one
does not specify the message receiver then the default message receiver will
do the job. <br>
<a name="Module_Configuration"></a>

<h2>Module Configuration</h2>
<ul>
  <li>Writing module.xml</li>
</ul>

<p>The description of module is specified using module.xml, each module
archive file need to have module.xml in order to be a valid module. And which
has to be available in META-INF directory of the archive file. <br>
A very simple module.xml is shown below:</p>

<p><source></p>
<pre>&lt;module class="org.apache.module.Module1Impl"&gt;
    &lt;inflow&gt;
        .
        .
    &lt;/inflow&gt;
    &lt;outflow&gt;
        .
        .
    &lt;/outflow&gt;

    &lt;Outfaultflow&gt;
        .   
        .
    &lt;/Outfaultflow&gt;

    &lt;INfaultflow&gt;
        .         
        .
    &lt;/INfaultflow&gt;

    &lt;operation name="creatSeq" mep="MEP_URI_IN_OUT"&gt;
        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
        &lt;parameter name="para1" locked="xsd:true"&gt;10&lt;/parameter&gt;
    &lt;/operation&gt;
&lt;/module&gt;
</pre>
</source>class: This is an optional attribute which indicate module
implementation class, a module may or may not contain module implementation
class since the module can also be a collection of handlers. If a module
contains an implementation class which implements the
org.apache.axis2.modules.Module inteface where at the deployment time its
init(); method will be called.

<p><b>parameter:</b> Module can contains any number of parameters and all the
listed parameters in the module.xml will be transformed into corresponding
AxisModule of the module.</p>

<p><b>Flow :</b></p>

<p>Defining of handlers in a module has to done inside Flows , and there are
four types of flows as listed below.</p>

<p> It is possible to add any number of handlers into a flow and those
handlers will be available in corresponding chains at the runtime when they
engaged .</p>
<ul>
  <li>Inflow</li>
  <li>outflow</li>
  <li>INfaultflow</li>
  <li>Outfaultflow</li>
</ul>

<p><b>operations</b> If a module wants to add an operation when it is engaged
into a service it can be done by adding operation tag in module.xml and the
way of specifying the operation is same as operation in services.xml.</p>

<p><b>Handler</b><br>
Handler element consists of compulsory and optional attribute and the way of
defining a handler will be look like follows;</p>

<p><source></p>
<pre>&lt;handler name="handler1" class="handlerClass "&gt;
            &lt;order phase="userphase1" /&gt;
 &lt;/handler&gt;</pre>
</source>
<p><b><i>Compulsory attributes</i></b> <br>
name: name of the handler<br>
nlass: handler implementation class<br>
phase: name of the phase that the handler should stay in the execution chain
<br>
<br>
<i><b>Optional attributes :</b></i><br>
phaseLast: to indicate the handler is last handler of the phase<br>
phaseFirst: to indicate the handler is first handler of the phase.<br>
before : the handler should be invoked before the handler specified by before
handler<br>
after:  the handler should be invoked after the handler specified by after
handler<br>
</p>

<p><br>
</p>
</body>
</html>