| <!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> |
| <parameter name="name of the parameter" >parameter value </parameter></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> |
| <transportReceiver name="http" class="org.apache.axis2.transport.http.SimpleHTTPServer"> |
| <parameter name="port" >6060</parameter> |
| </transportReceiver> |
| </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> |
| <transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"> |
| <parameter name="PROTOCOL" locked="xsd:false">HTTP/1.0</parameter> |
| </transportSender> |
| </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><phaseOrder type="inflow"> |
| <phase name="TransportIn"/> |
| . |
| . |
| </phaseOrder> </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><phaseOrder type="inflow""> |
| <!-- System pre defined phases --"> |
| <phase name="TransportIn"/"> |
| <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="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="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"> |
| <!-- Sysem pre defined phases --"> |
| <!-- After Postdispatch phase module author or or service author can add any phase he want --"> |
| <phase name="OperationInPhase"/"> |
| </phaseOrder"> |
| <phaseOrder type="outflow""> |
| <!-- user can add his own phases to this area --"> |
| <phase name="OperationOutPhase"/"> |
| <!--system predefined phase--"> |
| <!--these phase will run irrespective of the service--"> |
| <phase name="PolicyDetermination"/"> |
| <phase name="MessageOut"/"> |
| </phaseOrder"> |
| <phaseOrder type="INfaultflow""> |
| <!-- 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"></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> <phase name="TransportIn"/></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><module ref="addressing"/> </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><listener class="org.apache.axis2.ObserverIMPL"> |
| <parameter name="RSS_URL" >http://127.0.0.1/rss</parameter> |
| </listener></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><service name="name of the service" scope="name of the scope" 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></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> <operation name="echoString"> |
| <module ref=" a module name "/> |
| <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/> |
| </operation></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><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> |
| </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><handler name="handler1" class="handlerClass "> |
| <order phase="userphase1" /> |
| </handler></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> |