Using the SOAP Monitor

Web service developers often have the need to see the SOAP messages being used to invoke Web services along with the results of those messages. The goal of the SOAP Monitor utility is to provide a way for these developers to monitor the SOAP messages being used without requiring any special configuration or restarting of the server.

In this utility, a handler has been written and added to the global handler chain. As SOAP requests and responses are received, the SOAP message information is forwarded to a SOAP monitor service where it can be displayed using a Web browser interface. The SOAP message information is accessed by a Web browser by going to http://localhost:8080/axis2/SOAPMonitor (where 8080 is the port number where the application server is running). The SOAP message information is displayed through a Web browser by using an applet that opens a socket connection to the SOAP monitor service. This applet requires a Java plug-in 1.3 or higher to be installed in your browser. If you do not have a correct plug-in, the browser should prompt you to install one. The port used by the SOAP monitor service to communicate with applets is configurable. Edit the web.xml file to change the port used by Axis2 Web application.

The SOAP Monitor module (soapmonitor.mar) is available in the axis2.war but it is not engaged by default. The SOAP Monitor is NOT enabled by default for security reasons.

The SOAP Monitor can be engaged by inserting the following in the axis2.xml file.

   <module ref="soapmonitor"/>

Then in the axis2.xml file define your phase orders for 'soapmonitorPhase' referenced in the module.xml of soapmonitor.mars. Below is an example which should NOT be copied exactly, since the default phases change occasionally. The important point here is that 'soapmonitorPhase' should be placed under the 'user can add his own phases to this area' comment in the 'inflow', 'outflow', 'INfaultflow', and 'Outfaultflow' sections.

    <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 or service author can add any phase he want-->
        <phase name="userphase1"/>
        <phase name="soapmonitorPhase"/>
    </phaseOrder>
    <phaseOrder type="outflow">
        <!--user can add his own phases to this area-->
        <phase name="userphase1"/>
        <phase name="soapmonitorPhase"/>
        <!--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"/>
        <phase name="soapmonitorPhase"/>
    </phaseOrder>
    <phaseOrder type="Outfaultflow">
        <!--user can add his own phases to this area-->
        <phase name="userphase1"/>
        <phase name="soapmonitorPhase"/>
        <phase name="PolicyDetermination"/>
        <phase name="MessageOut"/>
    </phaseOrder>

To configure the servlet to communicate with the applet, add the following to web.xml (the SOAPMonitorPort is configurable):

    <servlet>
       <servlet-name>SOAPMonitorService</servlet-name>
       <display-name>SOAPMonitorService</display-name>
       <servlet-class>
         org.apache.axis2.soapmonitor.servlet.SOAPMonitorService
       </servlet-class>
       <init-param>
          <param-name>SOAPMonitorPort</param-name>
          <param-value>5001</param-value>
       </init-param>
       <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>SOAPMonitorService</servlet-name>
        <url-pattern>/SOAPMonitor</url-pattern>
    </servlet-mapping>

Finally, compile the applet classes and place them at the root of the war - for example axis2/SOAPMonitorApplet*.class/WEB-INF :

javac -classpath axis2-soapmonitor.jar SOAPMonitorApplet.java

You can find the SOAPMonitorApplet.java in the source distribution.

Alternatively, you can get the compiled applet classes from the axis2-soapmonitor-*.jar from inside the expanded axis2.war under WEB-INF/lib . Simply execute 'jar -xf axis2-soapmonitor-*.jar' and place the applet classes as axis2/SOAPMonitorApplet*.class/WEB-INF.

Using a Web browser, go to http[s]://host[:port][/webapp]/SOAPMonitor (e.g.http://localhost:8080/axis2/SOAPMonitor) substituting the correct values for your Web application. This will show the SOAP Monitor applet for viewing service requests and responses. Any requests to services that have been configured and deployed correctly should show up in the applet.