Using the SOAP Monitor

Using the SOAP Monitor

Web service developers often want to see the SOAP messages that are being used to invoke the Web services, along with the results of those messages. The goal of the SOAP Monitor utility is to provide a way for the developers to monitor these SOAP messages without requiring any special configuration or restarting 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 will 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 the 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"/>

In the axis2.xml file, define your phase orders for the '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="Dispatch" clas
    
    
    
    

     
             <phase name="PreDispatch"/>
    
    
    
    

     
     

      
      hase">
     
     
     
     

      
                  <handler name="Addressi
     
     
    
    
    
    

     
     s="org.apache.axis2.engine.Dispatch
    
    
    
    

     
     PngBasedDispatcher"
    
    
    
    

     
     

      
       class="org.apache.axis2.dispatchers.AddressingBasedDispatcher">
     
     
     
     

      
                      <or
     
     
    
    
    
    
                   
    
    
    
    

     
      der phase="Dispatch"/>
    
    
    
    

     
                 </handler>
    
    
    
    

     
     me="RequestURIBasedDispatcher"

    
    
    
    

     
                 <handler n
    
    
    
    

     
     a
    
    
    
    

     
     

      
      <order phase="Dispatch"/>
     
     
            </handler>

     
     

      
      me="SOAPActi
     
     
            <handler n
a
    
    
    
    

     
                          class="org.apache.axis2.dispatchers.RequestURIBasedDispatcher">
    
    
    
    
               
    
    
    
    

     
      onBasedDispatcher"
    
    
    
    

     
                          class="org.apache.axis2.dispatchers.SOAPActionBasedDispatcher">
    
    
    
    

     
                     <order phase="Dispatch"/>
    
    
            </handler>

    
    

     
     

      
      r phase="Dispatch"/>
     
     
     
     

      
                  </handler>
     
     
     
     

      
                  <h
     
     
    
    
            <handler name="SOAPMessageBodyBasedDispatcher"
                     class="org.apache.axis2.dispatchers.SOAPMessageBodyBasedDispatcher">
                <ord
eandler name="InstanceDispatcher"
                     class="org.apache.axis2.engine.InstanceDispatcher">
                <order phase="PostDispatch"/>
            </handler>
        </phase>

    
    

     
     

      
      ame="soapmonitorPhase"/>
     
     
     
     

      
          </phaseOrde
     
     
    
    
        <!--System pre defined phases-->
        <!--After Postdispatch phase module author or or service author can add any phase he want-->
        <phase name="userphase1"/>
        <phase 
nr>
    <phaseOrder type="outflow">
        <!--user can add his own phases to this area-->
        <phase name="userphase1"/>
        <phase name="soapmonitorPhase"/>
        <!--system predefined phase-->

    
    

     
     

      
      --user can add his own phases to this area-->
     
     
     
     

      
              <phase na
     
     
    
    
        <!--these phase will run irrespective of the service-->
        <phase name="PolicyDetermination"/>
        <phase name="MessageOut"/>
    </phaseOrder>
    <phaseOrder type="INfaultflow">
        <
!me="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 code to the web.xml (The SOAPMonitorPort is configurable.):

    
    

     
         <servlet>
    
    
    
    

     
            <servlet-name>SOAPMonitorService</servlet-name>
    
    
    
    

     
            <display-name>SOAPMonitorService</display-name>
    
    
    
    

     
     nitor.servlet.SOAPMoni
    
    
    
    

     
            <servlet-class>
    
    
    
    

     
              org.apache.axis2.soapm
    
    
    
    

     
     otorService
    
    
    
    

     
            </servlet-class>
    
    
    
    

     
            <init-param>
    
    
    
    

     
     

      
           <param-value>5001</param-value>
     
     
     
     

      
             </init
     
     
    
    
    
    

     
               <param-name>SOAPMonitorPort</param-name>
    
    
    
    
    
    
    
    
    

     
      -param>
    
    
    
    

     
            <load-on-startup>1</load-on-startup>
    
    
    </servlet>

    <servlet-mapping>

    
    

     
     

      
      url-pattern>
     
     
     
     

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

    
    

     
     /
    
    

Finally, the applet classes must be placed into the Web application so that they can be loaded by the Web browser. You can get the compiled applet classes from the WEB-INF/lib/axis2-soapmonitor-servlet-1.6.1.jar which is inside the extracted axis2.war. To extract the content of the file, simply execute the command, jar -xf axis2-soapmonitor-servlet-1.6.1.jar. The applet code is in the org.apache.axis2.soapmonitor.applet package and therefore the 'org' directory created by the unpacking of JAR file should be placed in <CATALINA_HOME>/webapps/axis2/.

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 used to view the service requests and responses. Any requests to services that have been configured and deployed correctly should show up in the applet.

The SOAPMonitor with attachments currently serializes themselves as base64 characters. It is therefore recommended to use the TCPMon tool to correctly capture MTOM and SWA messages as an multipart mime where the binary data is an attachment.

http://axis.apache.org/axis2/java/core/docs/soapmonitor-module.html