axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nand...@apache.org
Subject svn commit: r688807 [10/17] - in /webservices/axis2/site/1_4_1: ./ adb/ adb/images/ images/ images/archi-guide/ images/userguide/ jibx/ src/
Date Mon, 25 Aug 2008 18:10:09 GMT
Added: webservices/axis2/site/1_4_1/migration.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4_1/migration.html?rev=688807&view=auto
==============================================================================
--- webservices/axis2/site/1_4_1/migration.html (added)
+++ webservices/axis2/site/1_4_1/migration.html Mon Aug 25 11:10:04 2008
@@ -0,0 +1,959 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>Apache Axis2 - </title>
+    <style type="text/css" media="all">
+      @import url("../css/maven-base.css");
+      @import url("../css/maven-theme.css");
+      @import url("../css/site.css");
+    </style>
+    <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+      </head>
+  <body class="composite">
+    <div id="banner">
+                  <a href="../" id="bannerLeft">
+    
+                                    <img src="http://www.apache.org/images/asf_logo_wide.png" alt="" />
+    
+            </a>
+                          <span id="bannerRight">
+    
+                                            <img src="../../images/axis.jpg" alt="" />
+    
+            </span>
+            <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="breadcrumbs">
+          
+  
+
+  
+    
+  
+  
+    
+            <div class="xleft">
+        Last Published: 2008-08-24
+                      </div>
+            <div class="xright">            <a href="../index.html">Axis2/Java</a>
+            |
+                <a href="../../c">Axis2/C</a>
+            |
+                <a href="../../..">Apache WS</a>
+            |
+                <a href="http://www.apache.org" class="externalLink">Apache</a>
+            
+  
+
+  
+    
+  
+  
+    
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="leftColumn">
+      <div id="navcolumn">
+           
+  
+
+  
+    
+  
+  
+    
+                   <h5>Axis2/Java</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../index.html">Home</a>
+          </li>
+          </ul>
+              <h5>Downloads</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../download.cgi">Releases</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../modules/index.html">Modules</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../tools/index.html">Tools</a>
+          </li>
+          </ul>
+              <h5>Documentation</h5>
+            <ul>
+              
+          
+              
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+            
+              
+            <li class="expanded">
+                    <a href="../1_4_1/contents.html">Version 1.4.1</a>
+                  <ul>
+                  
+    <li class="none">
+                    <a href="../1_4_1/toc.html">Table of Contents</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/installationguide.html">Installation Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/quickstartguide.html">QuickStart Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/userguide.html">User Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/jaxws-guide.html">JAXWS Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/pojoguide.html">POJO Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/spring.html">Spring Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/webadminguide.html">Web Administrator's Guide</a>
+          </li>
+                  
+    <li class="none">
+              <strong>Migration Guide (from Axis1)</strong>
+        </li>
+              </ul>
+        </li>
+              
+    <li class="none">
+                    <a href="../1_4/contents.html">Version 1.4</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_3/contents.html">Version 1.3</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_2/contents.html">Version 1.2</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_1_1/contents.html">Version 1.1.1</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_1/contents.html">Version 1.1</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_0/index.html">Version 1.0</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_95/index.html">Version 0.95</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_94/index.html">Version 0.94</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_93/index.html">Version 0.93</a>
+          </li>
+          </ul>
+              <h5>Resources</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../faq.html">FAQ</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../articles.html">Articles</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink">Wiki</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../refLib.html">Reference Library</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../../1_4_1/api/index.html">Online Java Docs</a>
+          </li>
+          </ul>
+              <h5>Get Involved</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../overview.html">Overview</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../svn.html">Checkout the Source</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../mail-lists.html">Mailing Lists</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../release-process.html">Release Process</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../guidelines.html">Developer Guidelines</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../siteHowTo.html">Build the Site</a>
+          </li>
+          </ul>
+              <h5>Project Information</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../team-list.html">Project Team</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../issue-tracking.html">Issue Tracking</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink">Source Code</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../thanks.html">Acknowledgements</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink">License</a>
+          </li>
+          </ul>
+                                           <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+            <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+          </a>
+                       
+  
+
+  
+    
+  
+  
+    
+        </div>
+    </div>
+    <div id="bodyColumn">
+      <div id="contentBox">
+        <html xmlns="http://www.w3.org/1999/xhtml"><head><meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org"><meta http-equiv="content-type" content="">Migrating from Axis 1.x<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></head><h1>Migrating from Apache Axis 1.x to Axis2</h1><p>This document is intended for helping Axis 1.x users migrate to
+the Axis2 series. We'll begin by listing the improvements in Axis2
+in comparison with Axis1. This will be followed by guidelines for
+migration to the new version.</p>
+<p><i>Send your feedback or questions to: <a class="externalLink" href="mailto:axis-user@ws.apache.org?subject=[Axis2]">axis-user@ws.apache.org</a></i>.
+(Subscription details are available on the <a class="externalLink" href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.)
+Kindly prefix subject with [Axis2].</p>
+<h2>Content</h2><ul><li><a href="#comp">Compatibility</a></li>
+<li><a href="#start">Getting Started</a></li>
+<li><a href="#custom_deployment">Custom Deployment of Services,
+Handlers and Modules</a></li>
+<li><a href="#transports">Transports for HTTP Connection</a></li>
+<li><a href="#data_binding">Data Binding Support</a></li>
+<li><a href="#best">Best Usage</a></li>
+</ul>
+<a name="comp"></a><h2>Compatibility</h2><p>Axis1.x and Axis2 have evolved from different architectures.</p>
+<p><strong>Speed</strong> - Axis2 is based on the StAX API, which
+gives greater speed than the SAX event based parsing used in
+Axis1.x.</p>
+<p><strong>Stability</strong> - Axis2 has fixed phases as well as
+user-defined phases for extensions. This allows far more stability
+as well as flexibility than Axis1.x.</p>
+<p><strong>Transport framework</strong> - Transports (i.e., senders
+and listeners for SOAP over various protocols such as HTTP, SMTP,
+etc.), have been abstracted away from the Axis2 engine. Having a
+transport-independent Axis engine allows far more flexibility in
+transport options.</p>
+<p><strong>WSDL 2.0 support</strong> - Axis2 supports both WSDL
+versions 1.1 and 2.0, which are used by Axis2's code generation
+tools to create web service skeletons and client stubs.</p>
+<p><strong>Component-oriented architecture</strong> - Axis2
+components consist of handlers and modules in .mar and .aar
+archives. These easily reusable components allow extended
+functionality such as pattern processing for your applications or
+distribution to partners. Axis2 emphasizes the &quot;Module&quot; concept
+over the &quot;Handler&quot; concept of Axis 1.x. Modules contain handlers
+that are ordered by phase rules. These are attached to specific
+service(s).</p>
+<a name="start"></a><h2>Getting Started</h2><p>Let's look at a simple example of echoing at client API.</p>
+<p><b>Axis 1.x</b></p>
+<pre>
+import org.apache.axis.client.Call;
+import org.apache.axis.client.Service;
+import javax.xml.namespace.QName;
+   
+public class TestClient {
+  public static void main(String [] args) {
+    try {
+      String endpoint =&quot;http://ws.apache.org:5049/axis/services/echo&quot;;
+      Service  service = new Service();
+      Call     call    = (Call) service.createCall();
+      call.setTargetEndpointAddress( new java.net.URL(endpoint) );
+      call.setOperationName(new QName(&quot;http://soapinterop.org/&quot;, &quot;echoString&quot;));
+      String ret = (String) call.invoke( new Object[] { &quot;Hello!&quot; } );
+      System.out.println(&quot;Sent 'Hello!', got '&quot; + ret + &quot;'&quot;);
+    } catch (Exception e) {
+       System.err.println(e.toString());
+    }
+  }
+}
+</pre><p><b>Axis 2</b></p>
+<pre>
+import org.apache.axiom.om.OMAbstractFactory;
+import org.apache.axiom.om.OMElement;
+import org.apache.axiom.om.OMFactory;
+import org.apache.axiom.om.OMNamespace;
+import org.apache.axis2.AxisFault;
+import org.apache.axis2.addressing.EndpointReference;
+import org.apache.axis2.client.Options;
+import org.apache.axis2.client.ServiceClient;
+
+
+public class EchoBlockingClient {
+        private static EndpointReference targetEPR = new EndpointReference(
+                        &quot;http://127.0.0.1:8080/axis2/services/MyService&quot;);
+        public static void main(String[] args) {
+                try {
+                        OMFactory fac = OMAbstractFactory.getOMFactory();
+                        OMNamespace ns = fac.createOMNamespace(&quot;http://soapinterop.org/&quot;, &quot;ns1&quot;);
+                        OMElement payload = fac.createOMElement(&quot;echoString&quot;, ns);
+                        payload.setText(&quot;Hello!&quot;);
+                        Options options = new Options();
+                        ServiceClient client = new ServiceClient();
+                        options.setTo(targetEPR);
+                        client.setOptions(options); 
+                        //Blocking invocation
+                        OMElement result = client.sendReceive(payload);
+                        System.out.println(&quot;Sent Hello, got : &quot; + result.toString());
+
+                } catch (AxisFault axisFault) {
+                        axisFault.printStackTrace();
+                }
+
+        }
+}
+</pre><p>The above code demonstrates that Axis2 service invocations deal
+with the SOAP body element itself. The simple shows a synchronous
+invocation, but Axis2 can handle asynchronous invocations as well.
+The &quot;payload&quot; variable above contains the SOAP body element which
+will go in the SOAP envelope.</p>
+<p>Once the service is called by the client stub in Axis2, the
+&quot;payload&quot; will be bound according to the data binding framework in
+use. So the extra work of parsing the &quot;payload&quot; will vanish.</p>
+<p>Axis2 supports asynchronous invocation through
+sendReceiveNonblocking(). Synchronous/Asynchronous invocations can
+handle both single and double HTTP connections.</p>
+<p>With this advanced architecture, Axis2 is capable of handling
+megabytes of requests and responses, well above the capabilities of
+Axis1.x.</p>
+<a name="custom_deployment"></a><h2>Custom Deployment of Services, Handlers, and Modules</h2><p>In Axis 1.x, the deployment of services was via the rather
+cumbersome WSDD. Service deployment in Axis2 is straightforward and
+dynamic using the web-based Axis2 Admin application. Deployment is
+just a matter of creating the service archive (.aar) file and
+deploying it. More details regarding this is given in the Axis2
+user guide.</p>
+<p>Axis2 has moved away from the &quot;Handler concept&quot; and is more into
+the &quot;Module concept&quot;. Abstractly speaking, the module concept is a
+collection of handlers with rules that govern which modules are
+created as .mar files. It uses a module.xml file to specify handler
+configuration and activation.</p>
+<p>When a service is called through a handler, it is just a matter
+of giving a reference to the module that includes the handler in
+the services.xml (using &lt;module ref=&quot;foo/&gt;&quot;).</p>
+<p>Services are hot deployable in Axis2, but modules are not. This
+is one feature which is unique to Axis2.</p>
+<p>Let's take a detailed look at what it takes to migrate the Axis
+1.x handlers to the Axis 2 modules via the &quot;SOAP Monitor&quot;. The SOAP
+monitor is really a combination of three components: An applet
+which displays responses/requests, a servlet which binds to a
+default port of 5001 and connects to the applet, and a handler
+chain used to intercept the SOAP messages. Here we'll focus on the
+handler.</p>
+<p><b>Axis 1.x required two WSDD's to use the SOAP Monitor. First,
+the SOAP Monitor Handler itself:</b></p>
+<pre>
+&lt;deployment xmlns=&quot;http://xml.apache.org/axis/wsdd/&quot;
+    xmlns:java=&quot;http://xml.apache.org/axis/wsdd/providers/java&quot;&gt;
+    
+  &lt;handler name=&quot;soapmonitor&quot; 
+      type=&quot;java:org.apache.axis.handlers.SOAPMonitorHandler&quot;&gt;
+    &lt;parameter name=&quot;wsdlURL&quot; 
+      value=&quot;/wzs/SOAPMonitorService-impl.wsdl&quot;/&gt;
+    &lt;parameter name=&quot;namespace&quot; 
+      value=&quot;http://tempuri.org/wsdl/2001/12/SOAPMonitorService-impl.wsdl&quot;/&gt;
+    &lt;parameter name=&quot;serviceName&quot; value=&quot;SOAPMonitorService&quot;/&gt;
+    &lt;parameter name=&quot;portName&quot; value=&quot;Demo&quot;/&gt;
+  &lt;/handler&gt;
+
+  &lt;service name=&quot;SOAPMonitorService&quot; provider=&quot;java:RPC&quot;&gt;
+    &lt;parameter name=&quot;allowedMethods&quot; value=&quot;publishMessage&quot;/&gt;
+    &lt;parameter name=&quot;className&quot; 
+      value=&quot;org.apache.axis.monitor.SOAPMonitorService&quot;/&gt;
+    &lt;parameter name=&quot;scope&quot; value=&quot;Application&quot;/&gt;
+  &lt;/service&gt;
+&lt;/deployment&gt;
+</pre><p><b>Axis 1.x requires a reference to the handler in the user's
+WSDD that defines their Web Service:</b></p>
+<pre>
+&lt;deployment name=&quot;example&quot; xmlns=&quot;http://xml.apache.org/axis/wsdd/&quot; 
+    xmlns:java=&quot;http://xml.apache.org/axis/wsdd/providers/java&quot;&gt;
+  
+  &lt;service name=&quot;urn:myService&quot; provider=&quot;java:RPC&quot;&gt;
+    &lt;parameter name=&quot;className&quot; value=&quot;org.MyService&quot;/&gt;
+    &lt;parameter name=&quot;allowedMethods&quot; value=&quot;*&quot;/&gt;
+
+    &lt;requestFlow&gt;
+      &lt;handler type=&quot;soapmonitor&quot;/&gt;
+    &lt;/requestFlow&gt;
+    &lt;responseFlow&gt;
+      &lt;handler type=&quot;soapmonitor&quot;/&gt;
+    &lt;/responseFlow&gt;
+
+  &lt;/service&gt;
+&lt;/deployment&gt;
+</pre><p><b>Axis 2 requires a module.xml, placed inside a jar with a .mar
+extension under WEB-INF/modules, to define a Handler:</b></p>
+<pre>
+&lt;module name=&quot;soapmonitor&quot; class=&quot;org.apache.axis2.handlers.soapmonitor.SOAPMonitorModule&quot;&gt;
+    &lt;inflow&gt;
+        &lt;handler name=&quot;InFlowSOAPMonitorHandler&quot; class=&quot;org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler&quot;&gt;
+            &lt;order phase=&quot;soapmonitorPhase&quot;/&gt;
+        &lt;/handler&gt;
+    &lt;/inflow&gt;
+
+    &lt;outflow&gt;
+        &lt;handler name=&quot;OutFlowSOAPMonitorHandler&quot; class=&quot;org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler&quot;&gt;
+            &lt;order phase=&quot;soapmonitorPhase&quot;/&gt;
+        &lt;/handler&gt;
+    &lt;/outflow&gt;
+
+    &lt;Outfaultflow&gt;
+        &lt;handler name=&quot;FaultOutFlowSOAPMonitorHandler&quot; class=&quot;org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler&quot;&gt;
+            &lt;order phase=&quot;soapmonitorPhase&quot;/&gt;
+        &lt;/handler&gt;
+    &lt;/Outfaultflow&gt;
+
+    &lt;INfaultflow&gt;
+        &lt;handler name=&quot;FaultInFlowSOAPMonitorHandler&quot; class=&quot;org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler&quot;&gt;
+            &lt;order phase=&quot;soapmonitorPhase&quot;/&gt;
+        &lt;/handler&gt;
+    &lt;/INfaultflow&gt;
+&lt;/module&gt;
+</pre><p>The SOAPMonitorModule referenced above simply implements the
+org.apache.axis2.modules.Module, and is used for any additional
+tasks needed to initialize the module and shutdown the module. In
+this situation, nothing is needed and the implemented interface
+methods have blank bodies. Furthermore, the 'soapmonitorPhase' will
+be used later (below) in the axis2.xml .</p>
+<p><b>Axis 1.x the SOAPMonitorHandler has the class signature
+as:</b></p>
+<pre>
+public class SOAPMonitorHandler extends BasicHandler
+</pre><p><b>Axis 2 the SOAPMonitorHandler has the class signature
+as:</b></p>
+<pre>
+public class SOAPMonitorHandler extends AbstractHandler 
+</pre><p><b>In Axis2, you need to reference the module that contains the
+handler chain that you want to use inside your
+services.xml:</b></p>
+<pre>
+&lt;service name=&quot;ExampleService&quot;&gt;
+    &lt;module ref=&quot;soapmonitor&quot;/&gt;
+    &lt;description&gt;
+       This service has the SOAP Monitor wired in 
+    &lt;/description&gt;
+    &lt;parameter name=&quot;ServiceClass&quot;&gt;org.ExampleService&lt;/parameter&gt;
+    &lt;operation name=&quot;myExecute&quot;&gt;
+        &lt;messageReceiver class=&quot;org.apache.axis2.receivers.RawXMLINOutMessageReceiver&quot;/&gt;
+    &lt;/operation&gt;
+&lt;/service&gt;
+</pre><p><b>Finally, Axis2 requires you to make some changes to
+axis2.xml. Start by adding a global module:</b></p>
+<pre>
+    &lt;module ref=&quot;soapmonitor&quot;/&gt;
+</pre><p><b>Then define your phase orders for the 'soapmonitorPhase'
+referenced in the module.xml :</b></p>
+<pre>
+    &lt;phaseOrder type=&quot;inflow&quot;&gt;
+        &lt;!--  Global Phases       --&gt;
+        &lt;phase name=&quot;TransportIn&quot;/&gt;
+        &lt;phase name=&quot;PreDispatch&quot;/&gt;
+        &lt;phase name=&quot;Dispatch&quot; class=&quot;org.apache.axis2.engine.DispatchPhase&quot;&gt;
+            &lt;handler name=&quot;AddressingBasedDispatcher&quot;
+                     class=&quot;org.apache.axis2.dispatchers.AddressingBasedDispatcher&quot;&gt;
+                &lt;order phase=&quot;Dispatch&quot;/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name=&quot;RequestURIBasedDispatcher&quot;
+                     class=&quot;org.apache.axis2.dispatchers.RequestURIBasedDispatcher&quot;&gt;
+                &lt;order phase=&quot;Dispatch&quot;/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name=&quot;SOAPActionBasedDispatcher&quot;
+                     class=&quot;org.apache.axis2.dispatchers.SOAPActionBasedDispatcher&quot;&gt;
+                &lt;order phase=&quot;Dispatch&quot;/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name=&quot;SOAPMessageBodyBasedDispatcher&quot;
+                     class=&quot;org.apache.axis2.dispatchers.SOAPMessageBodyBasedDispatcher&quot;&gt;
+                &lt;order phase=&quot;Dispatch&quot;/&gt;
+            &lt;/handler&gt;
+            &lt;handler name=&quot;InstanceDispatcher&quot;
+                     class=&quot;org.apache.axis2.engine.InstanceDispatcher&quot;&gt;
+                &lt;order phase=&quot;Dispatch&quot;/&gt;
+            &lt;/handler&gt;
+        &lt;/phase&gt;
+        &lt;!--    Global Phases     --&gt;
+        &lt;!--   After Dispatch phase module author or service author can add any phase he wants      --&gt;
+        &lt;phase name=&quot;userphase1&quot;/&gt;
+        &lt;phase name=&quot;soapmonitorPhase&quot;/&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type=&quot;outflow&quot;&gt;
+        &lt;!--   user can add his own phases to this area  --&gt;
+        &lt;!--   Global phases   --&gt;
+        &lt;!--   these phases will run irrespective of the service   --&gt;
+        &lt;phase name=&quot;MessageOut&quot;/&gt;
+        &lt;phase name=&quot;userphase1&quot;/&gt;
+        &lt;phase name=&quot;soapmonitorPhase&quot;/&gt;
+        &lt;phase name=&quot;PolicyDetermination&quot;/&gt;
+        &lt;!--   Global phases   --&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type=&quot;INfaultflow&quot;&gt;
+        &lt;phase name=&quot;userphase1&quot;/&gt;
+        &lt;phase name=&quot;soapmonitorPhase&quot;/&gt;
+        &lt;!--   user can add his own phases to this area  --&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type=&quot;Outfaultflow&quot;&gt;
+        &lt;!--   user can add his own phases to this area  --&gt;
+        &lt;!--   Global phases   --&gt;
+        &lt;phase name=&quot;MessageOut&quot;/&gt;
+        &lt;phase name=&quot;userphase1&quot;/&gt;
+        &lt;phase name=&quot;soapmonitorPhase&quot;/&gt;
+        &lt;phase name=&quot;PolicyDetermination&quot;/&gt;
+        &lt;!--   Global phases   --&gt;
+    &lt;/phaseOrder&gt;
+</pre><p>See the user guide for more information on Axis2 modules.</p>
+<a name="transports"></a><h2>Transports for HTTP Connection</h2><p>Axis2 comes with the CommonsHTTPTransportSender which is based
+on commons-httpclient.</p>
+<p>It should be noted that axis2.xml should be configured to call
+the commons transports in this manner:</p>
+<pre>
+...
+&lt;transportSender name=&quot;http&quot; class=&quot;org.apache.axis2.transport.http.CommonsHTTPTransportSender&quot;&gt; 
+   &lt;parameter name=&quot;PROTOCOL&quot;&gt;HTTP/1.1&lt;/parameter&gt;
+   &lt;parameter name=&quot;Transfer-Encoding&quot;&gt;chunked&lt;/parameter&gt;
+&lt;/transportSender&gt;
+...
+</pre><a name="data_binding"></a><h2>Data Binding Support</h2><p>ADB is used to provide data binding support. In Axis2, XML is
+manipulated via AXIOM, which is based on the StAX API. AXIOM
+provides full XML schema support. Thus, serialization and
+de-serialization of XML is handled in Axis2 via the xml-data
+binding framework.</p>
+<p>Below is an example of migrating a WSDL based Axis 1.x Web
+Service to Axis2.</p>
+<p>First, let's take a look at a simple document/literal style WSDL
+used in an Axis 1.x Web Service. This example assumes the name
+simple.wsdl for the WSDL below:</p>
+<pre>
+&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
+
+&lt;definitions name=&quot;SimpleService&quot; targetNamespace=&quot;http://simpleNS&quot; xmlns:tns=&quot;http://simpleNS&quot; 
+xmlns=&quot;http://schemas.xmlsoap.org/wsdl/&quot; xmlns:xsd=&quot;http://www.w3.org/2001/XMLSchema&quot; 
+xmlns:soap=&quot;http://schemas.xmlsoap.org/wsdl/soap/&quot; xmlns:ns2=&quot;http://simpleNS/types&quot;&gt;
+  &lt;types&gt;
+    &lt;schema targetNamespace=&quot;http://simpleNS/types&quot; xmlns:tns=&quot;http://simpleNS/types&quot; 
+xmlns:soap11-enc=&quot;http://schemas.xmlsoap.org/soap/encoding/&quot; 
+xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; xmlns:wsdl=&quot;http://schemas.xmlsoap.org/wsdl/&quot; 
+xmlns=&quot;http://www.w3.org/2001/XMLSchema&quot;&gt;
+      &lt;import namespace=&quot;http://schemas.xmlsoap.org/soap/encoding/&quot;/&gt;
+      &lt;element name=&quot;simpleLogin&quot;&gt;
+        &lt;complexType&gt;
+          &lt;sequence&gt;
+            &lt;element name=&quot;user_name&quot; type=&quot;xsd:string&quot;/&gt;
+            &lt;element name=&quot;user_password&quot; type=&quot;xsd:string&quot;/&gt;
+          &lt;/sequence&gt;
+        &lt;/complexType&gt;
+      &lt;/element&gt;
+      &lt;element name=&quot;simpleLoginResponse&quot;&gt;
+        &lt;complexType&gt;
+          &lt;sequence&gt;
+            &lt;element name=&quot;soap_session_id&quot; type=&quot;xsd:string&quot;/&gt;
+            &lt;element name=&quot;web_user_name&quot; type=&quot;xsd:string&quot;/&gt;
+          &lt;/sequence&gt;
+        &lt;/complexType&gt;
+      &lt;/element&gt;
+&lt;/schema&gt;&lt;/types&gt;
+  &lt;message name=&quot;SimpleEndpoint_simpleLogin&quot;&gt;
+     &lt;part name=&quot;parameters&quot; element=&quot;ns2:simpleLogin&quot;/&gt;
+  &lt;/message&gt;
+  &lt;message name=&quot;SimpleEndpoint_simpleLoginResponse&quot;&gt;
+    &lt;part name=&quot;result&quot; element=&quot;ns2:simpleLoginResponse&quot;/&gt;
+  &lt;/message&gt;
+  &lt;portType name=&quot;SimpleEndpoint&quot;&gt;
+    &lt;operation name=&quot;simpleLogin&quot;&gt;
+      &lt;input message=&quot;tns:SimpleEndpoint_simpleLogin&quot; name=&quot;SimpleEndpoint_simpleLogin&quot;/&gt;
+      &lt;output message=&quot;tns:SimpleEndpoint_simpleLoginResponse&quot; name=&quot;SimpleEndpoint_simpleLoginResponse&quot;/&gt;
+    &lt;/operation&gt;
+  &lt;/portType&gt;
+  &lt;binding name=&quot;SimpleEndpointBinding&quot; type=&quot;tns:SimpleEndpoint&quot;&gt;
+    &lt;soap:binding transport=&quot;http://schemas.xmlsoap.org/soap/http&quot; style=&quot;document&quot;/&gt;
+    &lt;operation name=&quot;simpleLogin&quot;&gt;
+      &lt;soap:operation soapAction=&quot;simpleLogin&quot;/&gt;
+      &lt;input name=&quot;SimpleEndpoint_simpleLogin&quot;&gt;
+        &lt;soap:body use=&quot;literal&quot;/&gt;
+      &lt;/input&gt;
+      &lt;output name=&quot;SimpleEndpoint_simpleLoginResponse&quot;&gt;
+        &lt;soap:body use=&quot;literal&quot;/&gt;
+      &lt;/output&gt;
+    &lt;/operation&gt;
+  &lt;/binding&gt;
+  &lt;service name=&quot;SimpleService&quot;&gt;
+    &lt;port name=&quot;SimpleEndpointPort&quot; binding=&quot;tns:SimpleEndpointBinding&quot;&gt;
+      &lt;soap:address location=&quot;http://localhost:8080/axis/services/SimpleEndpointPort&quot;/&gt;&lt;/port&gt;&lt;/service&gt;&lt;/definitions&gt;
+</pre><p>The next step is to run WSDL2Java on the wsdl. For axis 1.x,
+this example uses the following Ant task:</p>
+<pre>
+&lt;target name=&quot;wsdl2java&quot; description=&quot;axis 1.x&quot;&gt;
+       &lt;delete dir=&quot;output&quot; /&gt;
+       &lt;mkdir dir=&quot;output&quot; /&gt;
+       &lt;axis-wsdl2java
+         output=&quot;output&quot;
+         verbose=&quot;true&quot;
+         url=&quot;wsdl/simple.wsdl&quot;
+         serverside=&quot;true&quot;
+         skeletondeploy=&quot;true&quot;
+         nowrapped=&quot;true&quot;&gt;
+       &lt;/axis-wsdl2java&gt;
+   &lt;/target&gt;
+</pre><p>The Axis 1.x Ant task above takes the simple.wsdl under the
+directory 'wsdl' , and from that creates files under the directory
+'output'. The files created are shown below:</p>
+<pre>
+output/
+output/simpleNS
+output/simpleNS/types
+output/simpleNS/types/SimpleLoginResponse.java
+output/simpleNS/types/SimpleLogin.java
+output/simpleNS/SimpleEndpoint.java
+output/simpleNS/SimpleEndpointBindingStub.java
+output/simpleNS/SimpleEndpointBindingSkeleton.java
+output/simpleNS/SimpleEndpointBindingImpl.java
+output/simpleNS/SimpleService.java
+output/simpleNS/SimpleServiceLocator.java
+output/simpleNS/deploy.wsdd
+output/simpleNS/undeploy.wsdd
+</pre><p>Now let's run WSDL2Java with Axis2. In this example, the only
+change to simple.wsdl required for Axis2 is that 'soap:address
+location' be changed to:</p>
+<pre>
+&lt;soap:address location=&quot;http://localhost:8080/axis2/services/SimpleEndpoint&quot;/&gt;&lt;/port&gt;&lt;/service&gt;&lt;/definitions&gt;
+</pre><p>In Axis2, the default databinding uses ADB. However, XMLBeans,
+JiBX and JAXB-RI are also supported. This example uses XMLBeans. For
+Axis2, our example uses the following Ant task:</p>
+<pre>
+&lt;target name=&quot;wsdl2java&quot;&gt;
+      &lt;delete dir=&quot;output&quot; /&gt;
+      &lt;java classname=&quot;org.apache.axis2.wsdl.WSDL2Java&quot; fork=&quot;true&quot;&gt;
+          &lt;classpath refid=&quot;axis.classpath&quot;/&gt; 
+          &lt;arg value=&quot;-d&quot;/&gt;
+          &lt;arg value=&quot;xmlbeans&quot;/&gt;
+          &lt;arg value=&quot;-uri&quot;/&gt;
+          &lt;arg file=&quot;wsdl/simple.wsdl&quot;/&gt;
+          &lt;arg value=&quot;-ss&quot;/&gt;
+          &lt;arg value=&quot;-g&quot;/&gt;
+          &lt;arg value=&quot;-sd&quot;/&gt;
+          &lt;arg value=&quot;-o&quot;/&gt;
+          &lt;arg file=&quot;output&quot;/&gt;
+          &lt;arg value=&quot;-p&quot;/&gt;
+          &lt;arg value=&quot;org.simple.endpoint&quot;/&gt;
+      &lt;/java&gt;
+
+      &lt;!-- Move the schema folder to classpath--&gt;
+      &lt;move todir=&quot;${build.classes}&quot;&gt;
+          &lt;fileset dir=&quot;output/resources&quot;&gt;
+              &lt;include name=&quot;*schema*/**/*.class&quot;/&gt;
+              &lt;include name=&quot;*schema*/**/*.xsb&quot;/&gt;
+          &lt;/fileset&gt;
+      &lt;/move&gt;
+
+  &lt;/target&gt;
+</pre><p>For an explanation of the Axis2 WSDL2Java Ant task and its
+options, see the <a href="../tools/1_4_1/CodegenToolReference.html">CodegenToolReference
+Guide.</a></p>
+<p>A feature of XMLBeans is that there is one class file created
+with WSDL2java, and a series of .xsb files. They must be referenced
+when compiling, and as the example shows, these files are moved to
+a build directory.</p>
+<p>The Axis2 WSDL2Java example also takes the simple.wsdl, which is
+under the directory 'wsdl', and creates files under the directory
+'output'. The relevant non-xmlbean files created are shown
+below:</p>
+<pre>
+output/resources/services.xml
+output/src/org/simple
+output/src/org/simple/endpoint
+output/src/org/simple/endpoint/SimpleEndpointSkeleton.java
+output/src/org/simple/endpoint/SimpleEndpointMessageReceiverInOut.java
+output/src/org/simple/endpoint/SimpleEndpointCallbackHandler.java
+output/src/org/simple/endpoint/SimpleEndpointStub.java
+output/src/simplens
+output/src/simplens/types
+output/src/simplens/types/SimpleLoginDocument.java
+output/src/simplens/types/impl
+output/src/simplens/types/impl/SimpleLoginDocumentImpl.java
+output/src/simplens/types/impl/SimpleLoginResponseDocumentImpl.java
+output/src/simplens/types/SimpleLoginResponseDocument.java
+</pre><p>The first important distinction is that while the Axis 1.x
+example generated deploy.wsdd and undeploy.wsdd, the Axis2 example
+created a services.xml. The files deploy.wsdd and services.xml are
+a breed apart, coming from different architectures. There is no
+direct parallel between them. See the Axis2 user guide for an
+explanation about services.xml</p>
+<p>Now we're ready to code. We'll start with Axis 1.x on the
+service side. To implement the business logic, we'll change
+simpleNS/SimpleEndpointBindingImpl.java from:</p>
+<pre class="code">
+package simpleNS;
+
+public class SimpleEndpointBindingImpl implements simpleNS.SimpleEndpoint{
+    public simpleNS.types.SimpleLoginResponse simpleLogin(simpleNS.types.SimpleLogin parameters) 
+        throws java.rmi.RemoteException {
+        return null;
+    }
+
+}
+</pre><p>To:</p>
+<pre class="code">
+package simpleNS;
+
+public class SimpleEndpointBindingImpl implements simpleNS.SimpleEndpoint{
+    public simpleNS.types.SimpleLoginResponse simpleLogin(simpleNS.types.SimpleLogin parameters) 
+        throws java.rmi.RemoteException {
+
+        String userName = parameters.getUser_name();
+        String password = parameters.getUser_password();
+        // do something with those vars...
+        return new simpleNS.types.SimpleLoginResponse(&quot;mySessionID&quot;, &quot;username&quot;);
+    }
+
+}
+</pre><p>In Axis 1.x, the next step is to compile the classes and put
+them in the Axis.war, and then run the admin client with the
+generated deploy.wsdd. You then look at the happy axis page to
+verify that the service has been installed correctly.</p>
+<p>Now let's code Axis2. In Axis 1.x, while the Ant task shown in
+the example created a skeleton, a peek inside shows that the
+skeleton calls the binding implementation class. In Axis2, we work
+with the skeleton directly. To implement the business logic in the
+generated Axis2 classes, we'll change
+org/simple/endpoint/SimpleEndpointSkeleton.java from:</p>
+<pre class="code">
+package org.simple.endpoint;
+    /**
+     *  SimpleEndpointSkeleton java skeleton for the axisService
+     */
+    public class SimpleEndpointSkeleton {
+
+        /**
+         * Auto generated method signature
+          * @param param0
+         */
+        public  simplens.types.SimpleLoginResponseDocument simpleLogin
+                  (simplens.types.SimpleLoginDocument param0 ) throws Exception {
+                //Todo fill this with the necessary business logic
+                throw new  java.lang.UnsupportedOperationException();
+        }
+}
+</pre><p>To:</p>
+<pre class="code">
+package org.simple.endpoint;
+    
+    import simplens.types.*;
+    import simplens.types.SimpleLoginResponseDocument.*;
+    import simplens.types.SimpleLoginDocument.*;
+    /**
+     *  SimpleEndpointSkeleton java skeleton for the axisService
+     */
+    public class SimpleEndpointSkeleton {
+     
+        /**
+         * Modified 
+          * @param simpleLoginDocument
+         */
+        public SimpleLoginResponseDocument simpleLogin
+                  (simplens.types.SimpleLoginDocument simpleLoginDocument){
+  
+                SimpleLoginResponseDocument retDoc =
+                    SimpleLoginResponseDocument.Factory.newInstance();
+                 
+                SimpleLoginResponse retElement =
+                    SimpleLoginResponse.Factory.newInstance();
+  
+                // Get parameters passed in 
+                SimpleLogin simpleLogin = simpleLoginDocument.getSimpleLogin();
+                String userName = simpleLogin.getUserName();
+                String password = simpleLogin.getUserPassword();
+
+                // do something with those variables...
+
+                retElement.setWebUserName(userName);
+                retElement.setSoapSessionId(&quot;my random string&quot;);
+                retDoc.setSimpleLoginResponse(retElement);
+                return retDoc; 
+        }
+}
+</pre><p>In Axis2, the next step is to compile the classes, put them
+along with the generated services.xml in an AAR, and then hot
+deploy the AAR by placing it in the Axis2.war under
+WEB-INF/services. Point a browser to
+http://localhost:8080/axis2/listServices, and you should see the
+service 'SimpleService' ready for action. See the Axis2 user guide
+for more info.</p>
+<p>The last step is constructing the client. Our Axis 1.x client
+for this example is:</p>
+<pre>
+package org;
+
+import simpleNS.*;
+import simpleNS.types.*;
+
+public class Tester {
+  public static void main(String [] args) throws Exception {
+    // Make a service
+    SimpleService service = new SimpleServiceLocator();
+
+    // Now use the service to get a stub which implements the SDI.
+    SimpleEndpoint port =  service.getSimpleEndpointPort();
+
+    // set the params
+    SimpleLogin parameters = new SimpleLogin(&quot;username&quot;,&quot;password&quot;);
+    // Make the actual call
+    SimpleLoginResponse simpleLoginResponse = port.simpleLogin(parameters);
+    String session = simpleLoginResponse.getSoap_session_id();
+    String user = simpleLoginResponse.getWeb_user_name();
+    System.out.println(&quot;simpleLoginResponse, session: &quot; + session + &quot;, user: &quot; + user);
+  }
+}
+</pre><p>Finally, our Axis2 client for this example is:</p>
+<pre>
+package org;
+import simplens.types.*;
+import simplens.types.SimpleLoginDocument.*;
+import simplens.types.SimpleLoginResponseDocument.*;
+import simplens.types.impl.*;
+import org.simple.endpoint.*;
+
+public class Tester {
+  public static void main(String [] args) throws Exception {
+
+    // you may not need to pass in the url to the constructor - try the default no arg one
+    SimpleEndpointStub stub =
+         new SimpleEndpointStub(null, &quot;http://localhost:8080/axis2/services/SimpleService&quot;);
+
+    SimpleLogin simpleLogin = SimpleLogin.Factory.newInstance();
+    simpleLogin.setUserName(&quot;userName&quot;);
+    simpleLogin.setUserPassword(&quot;password&quot;);
+
+    SimpleLoginDocument simpleLoginDocument =
+        SimpleLoginDocument.Factory.newInstance();
+
+    simpleLoginDocument.setSimpleLogin(simpleLogin);
+
+    SimpleLoginResponseDocument simpleLoginResponseDocument
+        = stub.simpleLogin(simpleLoginDocument);
+
+    SimpleLoginResponse simpleLoginResponse =
+        simpleLoginResponseDocument.getSimpleLoginResponse();
+
+    String session = simpleLoginResponse.getSoapSessionId();
+    String user = simpleLoginResponse.getWebUserName();
+    System.out.println(&quot;simpleLoginResponse, session: &quot; + session + &quot;, user: &quot; + user);
+
+  }
+}
+</pre><p>Axis2 clients also have asynchronous options via a Callback and
+alternatively a 'Fire and forget'. See the user guide for more
+details.</p>
+<a name="best"></a><h2>Best Usage</h2><p>Axis1.x and Axis2 have different ways of seeing the SOAP stack.
+So the best way to migrate is to follow the <a href="userguide.html">User's Guide</a> and the <a href="Axis2ArchitectureGuide.html">Architecture Guide</a> of Axis2
+properly. We are confident you will find Axis2 very straightforward
+and more friendly to use than its predecessor.</p>
+</html>
+      </div>
+    </div>
+    <div class="clear">
+      <hr/>
+    </div>
+    <div id="footer">
+      <div class="xright">&#169;  
+          2004-2008
+    
+          Apache Software Foundation
+          
+  
+
+  
+    
+  
+  
+    
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+  </body>
+</html>

Added: webservices/axis2/site/1_4_1/modules.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4_1/modules.html?rev=688807&view=auto
==============================================================================
--- webservices/axis2/site/1_4_1/modules.html (added)
+++ webservices/axis2/site/1_4_1/modules.html Mon Aug 25 11:10:04 2008
@@ -0,0 +1,614 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>Apache Axis2 - </title>
+    <style type="text/css" media="all">
+      @import url("../css/maven-base.css");
+      @import url("../css/maven-theme.css");
+      @import url("../css/site.css");
+    </style>
+    <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+      </head>
+  <body class="composite">
+    <div id="banner">
+                  <a href="../" id="bannerLeft">
+    
+                                    <img src="http://www.apache.org/images/asf_logo_wide.png" alt="" />
+    
+            </a>
+                          <span id="bannerRight">
+    
+                                            <img src="../../images/axis.jpg" alt="" />
+    
+            </span>
+            <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="breadcrumbs">
+          
+  
+
+  
+    
+  
+  
+    
+            <div class="xleft">
+        Last Published: 2008-08-24
+                      </div>
+            <div class="xright">            <a href="../index.html">Axis2/Java</a>
+            |
+                <a href="../../c">Axis2/C</a>
+            |
+                <a href="../../..">Apache WS</a>
+            |
+                <a href="http://www.apache.org" class="externalLink">Apache</a>
+            
+  
+
+  
+    
+  
+  
+    
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+    <div id="leftColumn">
+      <div id="navcolumn">
+           
+  
+
+  
+    
+  
+  
+    
+                   <h5>Axis2/Java</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../index.html">Home</a>
+          </li>
+          </ul>
+              <h5>Downloads</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../download.cgi">Releases</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../modules/index.html">Modules</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../tools/index.html">Tools</a>
+          </li>
+          </ul>
+              <h5>Documentation</h5>
+            <ul>
+              
+          
+              
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+            
+      
+              
+        <li class="expanded">
+                    <a href="../1_4_1/contents.html">Version 1.4.1</a>
+                  <ul>
+                  
+    <li class="none">
+                    <a href="../1_4_1/toc.html">Table of Contents</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/installationguide.html">Installation Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/quickstartguide.html">QuickStart Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/userguide.html">User Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/jaxws-guide.html">JAXWS Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/pojoguide.html">POJO Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/spring.html">Spring Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/webadminguide.html">Web Administrator's Guide</a>
+          </li>
+                  
+    <li class="none">
+                    <a href="../1_4_1/migration.html">Migration Guide (from Axis1)</a>
+          </li>
+              </ul>
+        </li>
+              
+    <li class="none">
+                    <a href="../1_4/contents.html">Version 1.4</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_3/contents.html">Version 1.3</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_2/contents.html">Version 1.2</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_1_1/contents.html">Version 1.1.1</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_1/contents.html">Version 1.1</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../1_0/index.html">Version 1.0</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_95/index.html">Version 0.95</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_94/index.html">Version 0.94</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../0_93/index.html">Version 0.93</a>
+          </li>
+          </ul>
+              <h5>Resources</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../faq.html">FAQ</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../articles.html">Articles</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink">Wiki</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../refLib.html">Reference Library</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../../1_4_1/api/index.html">Online Java Docs</a>
+          </li>
+          </ul>
+              <h5>Get Involved</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../overview.html">Overview</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../svn.html">Checkout the Source</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../mail-lists.html">Mailing Lists</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../release-process.html">Release Process</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../guidelines.html">Developer Guidelines</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../siteHowTo.html">Build the Site</a>
+          </li>
+          </ul>
+              <h5>Project Information</h5>
+            <ul>
+              
+    <li class="none">
+                    <a href="../team-list.html">Project Team</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../issue-tracking.html">Issue Tracking</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink">Source Code</a>
+          </li>
+              
+    <li class="none">
+                    <a href="../thanks.html">Acknowledgements</a>
+          </li>
+              
+    <li class="none">
+                    <a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink">License</a>
+          </li>
+          </ul>
+                                           <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+            <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+          </a>
+                       
+  
+
+  
+    
+  
+  
+    
+        </div>
+    </div>
+    <div id="bodyColumn">
+      <div id="contentBox">
+        <html xmlns="http://www.w3.org/1999/xhtml"><head><meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org"><meta http-equiv="content-type" content="">Writing your Own Axis2 Module<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></head><a name="Modules"></a><h1>Writing Your Own Axis2 Module</h1><p>Axis2 provides extended support for modules (See the <a href="Axis2ArchitectureGuide.html">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 class="externalLink" href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a>.
+( Subscription details are available on the <a class="externalLink" 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_&quot;axis2_xml&quot;">Step4:
+Modify the &quot;axis2.xml&quot;</a></li>
+<li><a href="#Step5_:_Modify_the_&quot;services_xml&quot;">Step5 :
+Modify the &quot;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 type="1"><li>Create the Module Implementation</li>
+<li>Create the Handlers</li>
+<li>Create the module.xml</li>
+<li>Modify the &quot;axis2.xml&quot; (if you need
+custom phases)</li>
+<li>Modify the &quot;services.xml&quot; to engage
+modules at the deployment time.</li>
+<li>Package in a &quot;.mar&quot; (Module
+Archive)</li>
+<li>Deploy the module in Axis2</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>&quot;samples\userguide\src&quot;</b> directory of the binary
+distribution. This module contains one handler that just logs the
+message that is passed through it. Axis2 uses &quot;.mar&quot; (Module
+Archive) to deploy modules in Axis2. The following diagram shows
+the file structure inside which needs to be there in the &quot;.mar&quot;
+archive. Let's create all these and see how it works.</p>
+<p><img src="images/userguide/ModuleView.jpg" /></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 &quot;<a class="externalLink" href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/modules/Module.java?rev=396785&amp;view=log">org.apache.axis2.modules.Module</a>&quot;
+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">Architecture Guide</a> for more information on phases). To
+write a handler one should implement <a class="externalLink" href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/engine/Handler.java?rev=357187&amp;view=log">
+org.apache.axis2.engine.Handler</a>. But for convenience, <a class="externalLink" href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/handlers/AbstractHandler.java?rev=396788&amp;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. &quot;public void invoke(MessageContext ctx);&quot; is the
+method that is called by the Axis2 engine when the control is
+passed to the handler. &quot;public void revoke(MessageContext ctx);&quot; 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>&quot;module.xml&quot; 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 &quot;LoggingModule&quot;
+class and various handlers that will run in different phases). The
+&quot;module.xml&quot; for the logging module will be as follows:</p>
+<pre>
+&lt;module name=&quot;logging&quot; class=&quot;userguide.loggingmodule.LoggingModule&quot;&gt;
+   &lt;InFlow&gt;
+        &lt;handler name=&quot;InFlowLogHandler&quot; class=&quot;userguide.loggingmodule.LogHandler&quot;&gt;
+        &lt;order phase=&quot;loggingPhase&quot; /&gt;
+        &lt;/handler&gt;
+   &lt;/InFlow&gt;
+
+   &lt;OutFlow&gt;
+        &lt;handler name=&quot;OutFlowLogHandler&quot; class=&quot;userguide.loggingmodule.LogHandler&quot;&gt;
+        &lt;order phase=&quot;loggingPhase&quot;/&gt;
+        &lt;/handler&gt;
+   &lt;/OutFlow&gt;
+
+   &lt;OutFaultFlow&gt;
+        &lt;handler name=&quot;FaultOutFlowLogHandler&quot; class=&quot;userguide.loggingmodule.LogHandler&quot;&gt;
+        &lt;order phase=&quot;loggingPhase&quot;/&gt;
+        &lt;/handler&gt;
+   &lt;/OutFaultFlow&gt;
+
+   &lt;InFaultFlow&gt;
+        &lt;handler name=&quot;FaultInFlowLogHandler&quot; class=&quot;userguide.loggingmodule.LogHandler&quot;&gt;
+        &lt;order phase=&quot;loggingPhase&quot;/&gt;
+        &lt;/handler&gt;
+   &lt;/InFaultFlow&gt;
+&lt;/module&gt;
+</pre><p>As you can see, there are four flows defined in the
+&quot;module.xml&quot;</p>
+<ol type="1"><li>InFlow Represents the handler chain that will run when a
+message is coming in.</li>
+<li>OutFlow Represents the handler chain
+that will run when the message is going out.</li>
+<li>OutFaultFlow - Represents the handler
+chain that will run when there is a fault, and the fault is going
+out.</li>
+<li>InFaultFlow - Represents the handler chain that will run when
+there is a fault, and the fault is coming in.</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.
+&quot;InFlowLogHandler&quot; 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. &quot;&lt;order
+phase=&quot;loggingPhase&quot; /&gt;&quot; describes the phase in which this
+handler runs.</p>
+<pre>
+&lt;handler name=&quot;InFlowLogHandler&quot; class=&quot;userguide.loggingmodule.LogHandler&quot;&gt;
+&lt;order phase=&quot;loggingPhase&quot; /&gt;
+&lt;/handler&gt;
+</pre><p>To learn more about Phase rules, check out the article <a class="externalLink" href="http://www.developer.com/java/web/article.php/3529321">Axis2 Execution Framework</a></p>
+<a name="Step_4:_Modify_the_axis2_xml"></a><h4>Step 4: Modify the &quot;axis2.xml&quot;</h4>
+<p>In this handler, the &quot;loggingPhase&quot;, is defined by the module
+writer. It is not a pre-defined handler phase, hence the module
+writer should introduce it to the &quot;axis2.xml&quot; (NOT the
+services.xml) so that the Axis2 engine knows where to place the
+handler in different &quot;flows&quot; (inFlow, outFlow, etc.). The following
+XML lines show the respective changes made to the &quot;axis2.xml&quot; in
+order to deploy the logging module in the Axis2 engine. This is an
+extract of the phase section of &quot;axis2.xml&quot;.</p>
+<pre>
+&lt;!-- ================================================= --&gt;
+&lt;!-- Phases --&gt;
+&lt;!-- ================================================= --&gt;
+
+&lt;phaseOrder type=&quot;inflow&quot;&gt;
+        &lt;!--  System pre defined phases       --&gt;
+        &lt;phase name=&quot;TransportIn&quot;/&gt;
+        &lt;phase name=&quot;PreDispatch&quot;/&gt;
+        &lt;phase name=&quot;Dispatch&quot; class=&quot;org.apache.axis2.engine.DispatchPhase&quot;&gt;
+            &lt;handler name=&quot;AddressingBasedDispatcher&quot;
+                     class=&quot;org.apache.axis2.dispatchers.AddressingBasedDispatcher&quot;&gt;
+                &lt;order phase=&quot;Dispatch&quot;/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name=&quot;RequestURIBasedDispatcher&quot;
+                     class=&quot;org.apache.axis2.dispatchers.RequestURIBasedDispatcher&quot;&gt;
+                &lt;order phase=&quot;Dispatch&quot;/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name=&quot;SOAPActionBasedDispatcher&quot;
+                     class=&quot;org.apache.axis2.dispatchers.SOAPActionBasedDispatcher&quot;&gt;
+                &lt;order phase=&quot;Dispatch&quot;/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name=&quot;SOAPMessageBodyBasedDispatcher&quot;
+                     class=&quot;org.apache.axis2.dispatchers.SOAPMessageBodyBasedDispatcher&quot;&gt;
+                &lt;order phase=&quot;Dispatch&quot;/&gt;
+            &lt;/handler&gt;
+            &lt;handler name=&quot;InstanceDispatcher&quot;
+                     class=&quot;org.apache.axis2.engine.InstanceDispatcher&quot;&gt;
+                &lt;order phase=&quot;PostDispatch&quot;/&gt;
+            &lt;/handler&gt;
+        &lt;/phase&gt;
+        &lt;!--  System pre defined phases       --&gt;
+        &lt;!--   After Postdispatch phase module author or service author can add any phase he wants      --&gt;
+        &lt;phase name=&quot;OperationInPhase&quot;/&gt;
+                &lt;phase name=&quot;<span style="color: rgb(36, 193, 19);">loggingPhase</span>&quot;/&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type=&quot;outflow&quot;&gt;
+        &lt;!--      user can add his own phases to this area  --&gt;
+        &lt;phase name=&quot;OperationOutPhase&quot;/&gt;
+        &lt;phase name=&quot;<span style="color: rgb(36, 193, 19);">loggingPhase</span>&quot;/&gt;
+        &lt;!--system predefined phases--&gt;
+        &lt;!--these phases will run irrespective of the service--&gt;
+        &lt;phase name=&quot;PolicyDetermination&quot;/&gt;
+        &lt;phase name=&quot;MessageOut&quot;/&gt;
+    &lt;/phaseOrder/&gt;
+    &lt;phaseOrder type=&quot;INfaultflow&quot;&gt;
+        &lt;!--      user can add his own phases to this area  --&gt;
+        &lt;phase name=&quot;OperationInFaultPhase&quot;/&gt;
+        &lt;phase name=&quot;<span style="color: rgb(36, 193, 19);">loggingPhase</span>&quot;/&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type=&quot;Outfaultflow&quot;&gt;
+        &lt;!--      user can add his own phases to this area  --&gt;
+        &lt;phase name=&quot;OperationOutFaultPhase&quot;/&gt;
+        &lt;phase name=&quot;<span style="color: rgb(36, 193, 19);">loggingPhase</span>&quot;/&gt;
+        &lt;phase name=&quot;PolicyDetermination&quot;/&gt;
+        &lt;phase name=&quot;MessageOut&quot;/&gt;
+    &lt;/phaseOrder&gt;
+    
+</pre><p>The text in green, the custom phase &quot;loggingPhase&quot; 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 &quot;services.xml&quot;</h4>
+<p>Up to this point, we have created the required classes and
+configuration descriptions for the logging module, and by changing
+the &quot;axis2.xml&quot; we created the required phases for the logging
+module.</p>
+<p>Next step is to &quot;<b>engage</b>&quot; (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 &quot;services.xml&quot; 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
+&quot;<strong>Axis2_HOME/samples/userguide/src/userguide/example2</strong>&quot;
+directory. The simple changes that we have done to &quot;services.xml'
+are shown in green in the following lines of xml.</p>
+<pre>
+&lt;service name=&quot;<span style="color: rgb(36, 193, 19);">MyServiceWithModule</span>&quot;&gt;
+    &lt;description&gt;
+    This is a sample Web service with a logging module engaged.
+    &lt;/description&gt;
+    <span style="color: rgb(36, 193, 19);">&lt;module ref=&quot;logging&quot;/&gt;</span>
+    &lt;parameter name=&quot;ServiceClass&quot; locked=&quot;xsd:false&quot;&gt;userguide.example2.MyService&lt;/parameter&gt;
+    &lt;operation name=&quot;echo&quot;&gt;
+    &lt;messageReceiver class=&quot;org.apache.axis2.receivers.RawXMLINOutMessageReceiver&quot;/&gt;
+    &lt;/operation&gt;
+    &lt;operation name=&quot;ping&quot;&gt;
+    &lt;messageReceiver class=&quot;org.apache.axis2.receivers.RawXMLINOutMessageReceiver&quot;/&gt;
+    &lt;/operation&gt;
+&lt;/service&gt;
+</pre><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>&quot;&lt;module ref=&quot;logging&quot;/&gt;&quot;</b> to &quot;services.xml&quot;.
+This informs the Axis2 engine that the module &quot;logging&quot; should be
+engaged for this service. The handler inside the module will be
+executed in their respective phases as described by the
+&quot;module.xml&quot;.</p>
+<a name="Step6_:_Packaging"></a><h4>Step6 : Packaging</h4>
+<p>Before deploying the module, we need to create the &quot;.mar&quot; file
+for this module. This can be done, using the &quot;jar&quot; command and then
+renaming the created .jar file. Else, you can find the
+&quot;logging.mar&quot; that has already been created in the
+&quot;<strong>Axis2_HOME/samples/userguide</strong>&quot; 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 &quot;modules&quot; in the &quot;webapps/axis2/WEB-INF&quot;
+directory of their servlet container, and then copying the &quot;.mar&quot;
+file to that directory. So let's first create the &quot;modules&quot;
+directory and drop the &quot;logging.mar&quot; into this directory.</p>
+<p>Although the required changes to the &quot;services.xml&quot; 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 &quot;logging.mar&quot; file to the
+&quot;modules&quot; 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
+&quot;log4j.properties&quot; to log INFO. The property file is located in
+&quot;<strong>webapps/axis2/WEB-INF/classes</strong>&quot; of your servlet
+container. Change the line &quot;log4j.rootCategory= ERROR, LOGFILE&quot; to
+&quot;log4j.rootCategory=INFO, ERROR, LOGFILE&quot;.</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>&quot;samples\userguide\src&quot;</b> directory of the binary
+distribution.</p>
+</html>
+      </div>
+    </div>
+    <div class="clear">
+      <hr/>
+    </div>
+    <div id="footer">
+      <div class="xright">&#169;  
+          2004-2008
+    
+          Apache Software Foundation
+          
+  
+
+  
+    
+  
+  
+    
+  </div>
+      <div class="clear">
+        <hr/>
+      </div>
+    </div>
+  </body>
+</html>



Mime
View raw message