<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
  <meta http-equiv="content-type" content="">
  <title>The SOAP Monitor Module</title>
  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
</head>
<body>

<h1>Using the SOAP Monitor</h1>

<p>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.</p>

<p>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.</p>

<p>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.</p>

<p>The SOAP Monitor can be engaged by inserting the following in the
axis2.xml file.</p>
<source><pre>   &lt;module ref="soapmonitor"/&gt;</pre>
</source>
<p>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.</p>
<pre>    &lt;phaseOrder type="inflow"&gt;
        &lt;!--System pre defined phases--&gt;
        &lt;phase name="TransportIn"/&gt;
        &lt;phase name="PreDispatch"/&gt;
        &lt;phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase"&gt;
            &lt;handler name="AddressingBasedDispatcher"
                     class="org.apache.axis2.engine.AddressingBasedDispatcher"&gt;
                &lt;order phase="Dispatch"/&gt;
            &lt;/handler&gt;
            &lt;handler name="RequestURIBasedDispatcher"
                     class="org.apache.axis2.engine.RequestURIBasedDispatcher"&gt;
                &lt;order phase="Dispatch"/&gt;
            &lt;/handler&gt;
            &lt;handler name="SOAPActionBasedDispatcher"
                     class="org.apache.axis2.engine.SOAPActionBasedDispatcher"&gt;
                &lt;order phase="Dispatch"/&gt;
            &lt;/handler&gt;
            &lt;handler name="SOAPMessageBodyBasedDispatcher"
                     class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher"&gt;
                &lt;order phase="Dispatch"/&gt;
            &lt;/handler&gt;
            &lt;handler name="InstanceDispatcher"
                     class="org.apache.axis2.engine.InstanceDispatcher"&gt;
                &lt;order phase="PostDispatch"/&gt;
            &lt;/handler&gt;
        &lt;/phase&gt;
        &lt;!--System pre defined phases--&gt;
        &lt;!--After Postdispatch phase module author or or service author can add any phase he want--&gt;
        &lt;phase name="userphase1"/&gt;
        &lt;phase name="soapmonitorPhase"/&gt;
    &lt;/phaseOrder&gt;
    &lt;phaseOrder type="outflow"&gt;
        &lt;!--user can add his own phases to this area--&gt;
        &lt;phase name="userphase1"/&gt;
        &lt;phase name="soapmonitorPhase"/&gt;
        &lt;!--system predefined phase--&gt;
        &lt;!--these phase will run irrespective of the service--&gt;
        &lt;phase name="PolicyDetermination"/&gt;
        &lt;phase name="MessageOut"/&gt;
    &lt;/phaseOrder&gt;
    &lt;phaseOrder type="INfaultflow"&gt;
        &lt;!--user can add his own phases to this area--&gt;
        &lt;phase name="userphase1"/&gt;
        &lt;phase name="soapmonitorPhase"/&gt;
    &lt;/phaseOrder&gt;
    &lt;phaseOrder type="Outfaultflow"&gt;
        &lt;!--user can add his own phases to this area--&gt;
        &lt;phase name="userphase1"/&gt;
        &lt;phase name="soapmonitorPhase"/&gt;
        &lt;phase name="PolicyDetermination"/&gt;
        &lt;phase name="MessageOut"/&gt;
    &lt;/phaseOrder&gt;</pre>

<p>To configure the servlet to communicate with the applet, add the following
to web.xml (the SOAPMonitorPort is configurable): </p>
<pre>    &lt;servlet&gt;
       &lt;servlet-name&gt;SOAPMonitorService&lt;/servlet-name&gt;
       &lt;display-name&gt;SOAPMonitorService&lt;/display-name&gt;
       &lt;servlet-class&gt;
         org.apache.axis2.soapmonitor.servlet.SOAPMonitorService
       &lt;/servlet-class&gt;
       &lt;init-param&gt;
          &lt;param-name&gt;SOAPMonitorPort&lt;/param-name&gt;
          &lt;param-value&gt;5001&lt;/param-value&gt;
       &lt;/init-param&gt;
       &lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
    &lt;/servlet&gt;

    &lt;servlet-mapping&gt;
        &lt;servlet-name&gt;SOAPMonitorService&lt;/servlet-name&gt;
        &lt;url-pattern&gt;/SOAPMonitor&lt;/url-pattern&gt;
    &lt;/servlet-mapping&gt;</pre>

<p>Finally, compile the applet classes and place them at the root of the war
- for example axis2/SOAPMonitorApplet*.class/WEB-INF :</p>
<pre>javac -classpath axis2-soapmonitor.jar SOAPMonitorApplet.java</pre>

<p>You can find the SOAPMonitorApplet.java in the source distribution. </p>

<p>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.  </p>

<p>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.</p>

</body>
</html>