| <!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> |
| |
| <a name="Global_Configuration"/> |
| <h2>Global Configuration</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><source> |
| <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><source> |
| <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><source> |
| <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="userphase1"/"> |
| </phaseOrder"> |
| <phaseOrder type="outflow""> |
| <!-- user can add his own phases to this area --"> |
| <phase name="userphase1"/"> |
| <!--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="userphase1"/"> |
| </phaseOrder"> |
| <phaseOrder type="Outfaultflow""> |
| <!-- user can add his own phases to this area --"> |
| <phase name="userphase1"/"> |
| <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><source> |
| <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><source> |
| <pre><module ref="addressing"/> </pre> |
| </source>ref: the module name which is going to be engage, system wide. |
| Listeners (Observers) 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 |
| <ul> |
| <li>Deploying a Service</li> |
| <li>Removing a service</li> |
| <li>Changing a service</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"/> |
| <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 > |
| <description> The description of the service </description> |
| |
| <parameter name="ServiceClass" locked="xsd:false">org.apache.axis2.sample.echo.EchoImpl</parameter> |
| |
| <operation name="echoString"> |
| <module ref=" a module name "/> |
| <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/> |
| </operation> |
| </service> |
| </font></pre></source> |
| |
| <font>service name: the service name will be the name of the archive file. |
| <br/> |
| 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.</font> |
| |
| <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 ServiceDescrption. 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>Handler</b><br/> |
| Handler element consists of compulsory and optional attribute and the way of |
| defining a handler will be look like follows; <p><source> |
| <pre><handler name="handler1" class="handlerClass "> |
| <order phase="userphase1" /> |
| </handler> |
| </pre></source> |
| <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><b>Operations</b><br/> |
| All the operations you are going to exposeby the service has to be indicated |
| in the services.xml and the correct way of specifying that should be as |
| follows: <p><source> |
| <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"/> |
| <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><source> |
| <pre><module name="module1" 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> |
| name: This is a compulsory attribute and which indicates the name of the |
| module <br/> |
| 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 |
| ModuleDescription of the module.</p> |
| |
| <p><b>Flow :</b><br/> |
| It is possible to add handlers into a flow directly form services.xml rather |
| than engaging a modules and the way of doing that is through flow elements. |
| It is possible to add any number of handlers into a flow and those handlers |
| will be available in corresponding operations flows in the service (inflow |
| consist of two parts, one part is up to post dispatch phase and other part is |
| consisting of operation handlers) <br/> |
| There are four types of valid flows that can be available in services.xml, |
| and the adding the handles into them can be done by following the above |
| procedure. <br/> |
| Valid flows:</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> |
| <br/> |
| </body> |
| </html> |