| <html> |
| <head> |
| <meta http-equiv="content-type" content=""> |
| <title>Writing your Own Axis2 Module</title> |
| <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" |
| media="all"> |
| </head> |
| |
| <body dir="ltr" lang="en-US"> |
| <a name="Modules"></a> |
| |
| <h1>Writing Your Own Axis2 Module</h1> |
| |
| <p>Axis2 provides extended support for modules (See the <a |
| href="Axis2ArchitectureGuide.html" target="_blank">Architecture Guide</a> for |
| more details about modules in Axis2). Let's create a custom module and deploy |
| it to MyService, which we created earlier.</p> |
| |
| <p>Send your feedback or questions to: <a |
| href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a>. |
| ( Subscription details are available on the <a |
| href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.) Kindly |
| prefix subject with [Axis2].</p> |
| |
| <h2>Content List</h2> |
| <ul> |
| <li><a href="#MyService_with_a_Logging_Module">MyService with a Logging |
| Module</a> |
| <ul> |
| <li><a href="#Step1_:_LoggingModule_Class">Step1 : LoggingModule |
| Class</a></li> |
| <li><a href="#Step2_:_LogHandler">Step2 : LogHandler</a></li> |
| <li><a href="#Step3_:_module_xml">Step3 : module.xml</a></li> |
| <li><a href="#Step_4:_Modify_the_"axis2_xml"">Step4: Modify |
| the "axis2.xml"</a></li> |
| <li><a href="#Step5_:_Modify_the_"services_xml"">Step5 : |
| Modify the "services.xml</a></li> |
| <li><a href="#Step6_:_Packaging">Step6 : Packaging</a></li> |
| <li><a href="#Step7_:_Deploy_the_Module_in_Axis2">Step7 : Deploy the |
| Module in Axis2</a></li> |
| </ul> |
| </li> |
| </ul> |
| |
| <p>The following steps show the actions that need to be performed to deploy a |
| custom module for a given Web service:</p> |
| <ol> |
| <li><p style="margin-bottom: 0in">Create the Module Implementation</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Create the Handlers</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Create the module.xml</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Modify the "axis2.xml" (if you need |
| custom phases)</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Modify the "services.xml" to engage |
| modules at the deployment time.</p> |
| </li> |
| <li><p style="margin-bottom: 0in">Package in a ".mar" (Module Archive)</p> |
| </li> |
| <li><p>Deploy the module in Axis2</p> |
| </li> |
| </ol> |
| <a name="MyService_with_a_Logging_Module"></a> |
| |
| <h3>MyService with a Logging Module</h3> |
| |
| <p>Let's write a simple logging module for our sample located at the |
| <b>"samples\userguide\src"</b> directory of the binary distribution. This |
| module contains one handler that just logs the message that is passed through |
| it. Axis2 uses ".mar" (Module Archive) to deploy modules in Axis2. The |
| following diagram shows the file structure inside which needs to be there in |
| the ".mar" archive. Let's create all these and see how it works.</p> |
| |
| <p><img src="images/userguide/ModuleView.jpg" name="Graphic5" align="bottom" |
| border="0"></p> |
| <a name="Step1_:_LoggingModule_Class"></a> |
| |
| <h4>Step1 : LoggingModule Class</h4> |
| |
| <p>LoggingModule is the implementation class of the Axis2 module. Axis2 |
| modules should implement the "<a |
| href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/modules/Module.java?rev=396785&view=log">org.apache.axis2.modules.Module</a>" |
| interface with the following methods.</p> |
| <pre>public void init(ConfigurationContext configContext, AxisModule module) throws AxisFault;//Initialize the module |
| public void shutdown(ConfigurationContext configurationContext) throws AxisFault;//End of module processing |
| public void engageNotify(AxisDescription axisDescription) throws AxisFault; |
| public String[] getPolicyNamespaces() throws AxisFault; |
| public void applyPolicy(Policy policy, AxisDescription axisDescription) throws AxisFault ; |
| public boolean canSupportAssertion(Assertion assertion) ;</pre> |
| |
| <p>The first three methods can be used to control the module initialization |
| and the termination, and the next three methods are used to perform policy |
| related operations. With the input parameter AxisConfiguration, the user is |
| provided with the complete configuration hierarchy. This can be used to |
| fine-tune the module behavior by the module writers. For a simple logging |
| service, we can keep these methods blank in our implementation class.</p> |
| <a name="Step2_:_LogHandler"></a> |
| |
| <h4>Step2 : LogHandler</h4> |
| |
| <p>A module in Axis2 can contain, one or more handlers that perform various |
| SOAP header processing at different phases. (See the<a |
| href="Axis2ArchitectureGuide.html#incomingsoap" target="_blank"> Architecture |
| Guide</a> for more information on phases). To write a handler one should |
| implement <a |
| href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/engine/Handler.java?rev=357187&view=log">org.apache.axis2.engine.Handler</a>. |
| But for convenience, <a |
| href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/handlers/AbstractHandler.java?rev=396788&view=log">org.apache.axis2.handlers.AbstractHandler</a> |
| provides an abstract implementation of the Handler interface.</p> |
| |
| <p>For the logging module, we will write a handler with the following |
| methods. "public void invoke(MessageContext ctx);" is the method that is |
| called by the Axis2 engine when the control is passed to the handler. "public |
| void revoke(MessageContext ctx);" is called when the handlers are revoked by |
| the Axis2 engine.</p> |
| <pre>public class LogHandler extends AbstractHandler implements Handler { |
| private static final Log log = LogFactory.getLog(LogHandler.class); |
| private String name; |
| |
| public String getName() { |
| return name; |
| } |
| |
| public InvocationResponse invoke(MessageContext msgContext) throws AxisFault { |
| log.info(msgContext.getEnvelope().toString()); |
| return InvocationResponse.CONTINUE; |
| } |
| |
| public void revoke(MessageContext msgContext) { |
| log.info(msgContext.getEnvelope().toString()); |
| } |
| |
| public void setName(String name) { |
| this.name = name; |
| } |
| }</pre> |
| <a name="Step3_:_module_xml"></a> |
| |
| <h4>Step3 : module.xml</h4> |
| |
| <p>"module.xml" contains the deployment configurations for a particular |
| module. It contains details such as the Implementation class of the module |
| (in this example it is the "LoggingModule" class and various handlers that |
| will run in different phases). The "module.xml" for the logging module will |
| be as follows:</p> |
| <pre><module name="logging" class="userguide.loggingmodule.LoggingModule "> |
| <inflow> |
| <handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler"> |
| <order phase="loggingPhase" /> |
| </handler> |
| </inflow> |
| |
| <outflow> |
| <handler name="OutFlowLogHandler" class="userguide.loggingmodule.LogHandler"> |
| <order phase="loggingPhase"/> |
| </handler> |
| </outflow> |
| |
| <Outfaultflow> |
| <handler name="FaultOutFlowLogHandler" class="userguide.loggingmodule.LogHandler"> |
| <order phase="loggingPhase"/> |
| </handler> |
| </Outfaultflow> |
| |
| <INfaultflow> |
| <handler name="FaultInFlowLogHandler" class="userguide.loggingmodule.LogHandler"> |
| <order phase="loggingPhase"/> |
| </handler> |
| </INfaultflow> |
| </module></pre> |
| |
| <p>As you can see, there are four flows defined in the "module.xml"</p> |
| <ol> |
| <li>inflow - Represents the handler chain that will run when a message is |
| coming in. </li> |
| <li><p style="margin-bottom: 0in">outflow - Represents the handler chain |
| that will run when the message is going out. </p> |
| </li> |
| <li><p style="margin-bottom: 0in">Outfaultflow - Represents the handler |
| chain that will run when there is a fault, and the fault is going out.</p> |
| </li> |
| <li><p>INfaultflow - Represents the handler chain that will run when there |
| is a fault, and the fault is coming in. </p> |
| </li> |
| </ol> |
| |
| <p>The following set of tags describe the name of the handler, handler class, |
| and the phase in which this handler is going to run. "InFlowLogHandler" is |
| the name given for the particular instance of this handler class. The value |
| of the class attribute is the actual implementation class for this handler. |
| Since we are writing a logging handler, we can reuse the same handler in all |
| these phases. However, this may not be the same for all the modules. |
| "<order phase="loggingPhase" />" describes the phase in which this |
| handler runs.</p> |
| <pre><handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler"> |
| <order phase="loggingPhase" /> |
| </handler></pre> |
| |
| <p>To learn more about Phase rules, check out the article <a |
| href="http://www.developer.com/java/web/article.php/3529321" |
| target="_blank">Axis2 Execution Framework</a></p> |
| <a name="Step_4:_Modify_the_"axis2_xml""></a> |
| |
| <h4>Step 4: Modify the "axis2.xml"</h4> |
| |
| <p>In this handler, the "loggingPhase", is defined by the module writer. It |
| is not a pre-defined handler phase, hence the module writer should introduce |
| it to the "axis2.xml" (NOT the services.xml) so that the Axis2 engine knows |
| where to place the handler in different "flows" (inFlow, outFlow, etc.). The |
| following XML lines show the respective changes made to the "axis2.xml" in |
| order to deploy the logging module in the Axis2 engine. This is an extract of |
| the phase section of "axis2.xml".</p> |
| |
| <p><pre><!-- ================================================= --> |
| <!-- Phases --> |
| <!-- ================================================= --> |
| |
| <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="PostDispatch"/> |
| </handler> |
| </phase> |
| <!-- System pre defined phases --> |
| <!-- After Postdispatch phase module author or service author can add any phase he wants --> |
| <phase name="OperationInPhase"/> |
| <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/> |
| </phaseOrder> |
| <phaseOrder type="outflow"> |
| <!-- user can add his own phases to this area --> |
| <phase name="OperationOutPhase"/> |
| <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/> |
| <!--system predefined phases--> |
| <!--these phases 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"/> |
| <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/> |
| </phaseOrder> |
| <phaseOrder type="Outfaultflow"> |
| <!-- user can add his own phases to this area --> |
| <phase name="OperationOutFaultPhase"/> |
| <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/> |
| <phase name="PolicyDetermination"/> |
| <phase name="MessageOut"/> |
| </phaseOrder> |
| </pre></p> |
| |
| <p>The text in green, the custom phase "loggingPhase" is placed in all the |
| flows, hence that phase will be called in all the message flows in the |
| engine. Since our module is associated with this phase, the LogHandler inside |
| the module will now be executed in this phase.</p> |
| <a name="Step5_:_Modify_the_"services_xml""></a> |
| |
| <h4>Step5 : Modify the "services.xml"</h4> |
| |
| <p>Up to this point, we have created the required classes and configuration |
| descriptions for the logging module, and by changing the "axis2.xml" we |
| created the required phases for the logging module.</p> |
| |
| <p>Next step is to "<b>engage</b>" (use) this module in one of our services. |
| For this, let's use the same Web service that we have used throughout the |
| user's guide- MyService. However, since we need to modify the "services.xml" |
| of MyService in order to engage this module, we use a separate Web service, |
| but with similar operations.</p> |
| |
| <p>The code for this service can be found in the |
| "<strong>Axis2_HOME/samples/userguide/src/userguide/example2</strong>" |
| directory. The simple changes that we have done to "services.xml' are shown |
| in green in the following lines of xml.</p> |
| |
| <p><pre><service name="<span style="color: rgb(36, 193, 19);">MyServiceWithModule</span>"> |
| <description> |
| This is a sample Web service with a logging module engaged. |
| </description> |
| <span style="color: rgb(36, 193, 19);"><module ref="logging"/></span> |
| <parameter name="ServiceClass" locked="xsd:false">userguide.example2.MyService</parameter> |
| <operation name="echo"> |
| <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/> |
| </operation> |
| <operation name="ping"> |
| <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/> |
| </operation> |
| </service></pre></p> |
| |
| <p>In this example, we have changed the service name (the implementation |
| class is very similar to what we have used earlier, although it is in a |
| different package). In addition we have added the line <b>"<module |
| ref="logging"/>"</b> to "services.xml". This informs the Axis2 engine that |
| the module "logging" should be engaged for this service. The handler inside |
| the module will be executed in their respective phases as described by the |
| "module.xml".</p> |
| <a name="Step6_:_Packaging"></a> |
| |
| <h4>Step6 : Packaging</h4> |
| |
| <p>Before deploying the module, we need to create the ".mar" file for this |
| module. This can be done, using the "jar" command and then renaming the |
| created .jar file. Else, you can find the "logging.mar" that has already been |
| created in the "<strong>Axis2_HOME/samples/userguide</strong>" directory.</p> |
| <a name="Step7_:_Deploy_the_Module_in_Axis2"></a> |
| |
| <h4>Step7 : Deploy the Module in Axis2</h4> |
| |
| <p>Deploying a module in Axis2 requires the user to create a directory with |
| the name "modules" in the "webapps/axis2/WEB-INF" directory of their servlet |
| container, and then copying the ".mar" file to that directory. So let's first |
| create the "modules" directory and drop the "logging.mar" into this |
| directory.</p> |
| |
| <p>Although the required changes to the "services.xml" is very little, we |
| have created a separate service archive (MyServiceWithModule.aar) for users |
| to deploy the service..</p> |
| |
| <p>Deploy this service using the same steps used in the <a |
| href="adv-userguide.html#Step5_Deploy_web_service">'Step 4: Deploy Web |
| Service'</a> sub section in '<a href="userguide.html#ws_codegen">Writing a |
| New Service using Codegeneration</a>', and copy the "logging.mar" file to the |
| "modules" directory.</p> |
| |
| <p>Then run 'ant run.client.servicewithmodule' from |
| <strong>axis2home/samples/userguide directory</strong></p> |
| |
| <p>Note: To see the logs, the user needs to modify the "log4j.properties" to |
| log INFO. The property file is located in |
| "<strong>webapps/axis2/WEB-INF/classes</strong>" of your servlet container. |
| Change the line "log4j.rootCategory= ERROR, LOGFILE" to |
| "log4j.rootCategory=INFO, ERROR, LOGFILE".</p> |
| |
| <p><font size="2"><b>Note (on samples):</b></font> All the samples mentioned |
| in the user's guide are located at the <b> |
| "samples\userguide\src"</b> directory of the binary distribution.</p> |
| </body> |
| </html> |
