In Axis2 there are three kinds of configuration files to configure the system. First one is to configure whole system (global configuration), second one is to configure a service (service configuration) and the third one is to configure a module (module configuration). This document will explain in detail the above configurations.
All the configurations that require starting Axis2 are obtained from the axis2.xml. The way of specifying them is extremely 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 can be listed as follows:
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 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>
Depending on the underlying transport that Axis2 is going to run on, you need to have different transport receivers. The way of adding 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 the way of defining transport receivers in axis2.xml. Here the name attribute of the 'transportReceiver' element is the name of transport receiver. It can be http, tcp, smtp, commonshttp etc, and when the system starts up or when you set the transport at the client side, one can use these transport names to load the appropriate transport. Class attribute is to specify actual java classes 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.
As same as transport receivers, it is possible to register transport senders in the system, and later at the run time, those senders can be used to send the messages. As an example, consider Axis2 running under Apache Tomcat. Then Axis2 can use TCP transport senders to send messages rather than HTTP. The way of specifying transport senders is as follows:
<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
<parameter name="PROTOCOL" locked="xsd:false">HTTP/1.0</parameter>
</transportSender>
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 are any then it can be accessed via corresponding transport sender.
The specifying order of phases in execution chain has to be done using phase order element and it will look like below:
<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 which 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.engine.RequestURIBasedDispatcher">
<order phase="Transport"/>
</handler>
<handler name="SOAPActionBasedDispatcher"
class="org.apache.axis2.engine.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.engine.AddressingBasedDispatcher">
<order phase="Dispatch"/>
</handler>
<handler name="SOAPMessageBodyBasedDispatcher"
class="org.apache.axis2.engine.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.engine.RequestURIBasedDispatcher">
<order phase="Dispatch"/>
</handler>
<handler name="SOAPActionBasedDispatcher"
class="org.apache.axis2.engine.SOAPActionBasedDispatcher">
<order phase="Dispatch"/>
</handler>
<handler name="AddressingBasedDispatcher"
class="org.apache.axis2.engine.AddressingBasedDispatcher">
<order phase="Dispatch"/>
</handler>
<handler name="SOAPMessageBodyBasedDispatcher"
class="org.apache.axis2.engine.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 and can only be one of the following:
In addition to that, the only child element that is allowed inside "phaseOrder" is "phase" element which represents available phases in the execution chain. The way 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"
For the phaseOrder types "OutFlow" and "OutFaultFlow"
Note : If you closely look at the default axis2.xml you will be able to clearly identify that.
If you want to engage a module, system wide, you can do it by adding top level module element in axis2.xml. It should look like following:
<module ref="addressing"/>
ref: the module name which is going to be engage, system wide.
In Axis2, AxisConfiguration is observable so that one can register observers into that, and they will be automatically informed whenever a change occurs in AxisConfiguration. In the current implementation, the observers are informed of the following events:
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:
<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.
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. A very simple services.xml is shown below:
<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>HTTP</transport>
</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.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 in which runtime information of deployed services will be available. Scope is of several types- "Application", "SOAPSession", "TransportSession", "Request". The default value (if you dont put any value) will be "Request"
class: (Optional attribute) To specify the full qualified name of the service lifecycle implementation class. ServiceLifeCycle class is usefull when you want to do some tasks when the system start and when it shutdowns.
targetNamespace: (Optional Attribute) Target name space of the service, and this value will be used when generating the wsdl , if you do not specify this value , then the value will be calculated from the package name of the service impl class
description: 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.
transports : The transports that the service is going to be exposed to. This is an optional element. 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 is there to specify 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 a services.xml called ServiceClass which specifies the java class which really does the job and the class will be loaded by the MessageReceiver.
operations : If the service impl class is java, then all the public methods in that service will be exposed and if the user wants to override it then he has to add the "operation" tag and override it. In the case of non-Java 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 and the correct way of specifying is 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 one can register custom message receivers 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.
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.
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: This is an optional attribute which 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 which implements the
org.apache.axis2.modules.Module interface where at the deployment time 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 corresponding AxisModule of the module.
flow: Defining of handlers in a module has to be done inside flows, and there are four types of flows as listed below.
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 are engaged .
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 and the way of specifying the operation is the same as operation in services.xml.
handler: The Handler element consists of compulsory and optional attributes and the way 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 stay in the execution
chain
Optional Attributes :
phaseLast: to indicate the handler is last handler of the phase
phaseFirst: to indicate the handler is first handler of the phase.
before : the handler should be invoked before the handler specified by
the before handler
after: the handler should be invoked after the handler specified by
the after handler