axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d...@apache.org
Subject svn commit: r556222 [7/22] - in /webservices/axis2/trunk/java/xdocs: ./ @axis2_version_dir@/ @axis2_version_dir@/adb/ @axis2_version_dir@/jibx/ @axis2_version_dir@/src/ download/0_9/ download/0_91/ download/0_92/ download/0_93/ download/0_94/ download/...
Date Sat, 14 Jul 2007 04:37:36 GMT
Copied: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/migration.xml (from r556217, webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/migration.html)
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/migration.xml?view=diff&rev=556222&p1=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/migration.html&r1=556217&p2=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/migration.xml&r2=556222
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/migration.html (original)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/migration.xml Fri Jul 13 21:37:26 2007
@@ -1,709 +1,716 @@
-<!--
-  ~ Licensed to the Apache Software Foundation (ASF) under one
-  ~ or more contributor license agreements. See the NOTICE file
-  ~ distributed with this work for additional information
-  ~ regarding copyright ownership. The ASF licenses this file
-  ~ to you under the Apache License, Version 2.0 (the
-  ~ "License"); you may not use this file except in compliance
-  ~ with the License. You may obtain a copy of the License at
-  ~
-  ~ http://www.apache.org/licenses/LICENSE-2.0
-  ~
-  ~ Unless required by applicable law or agreed to in writing,
-  ~ software distributed under the License is distributed on an
-  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-  ~ KIND, either express or implied. See the License for the
-  ~ specific language governing permissions and limitations
-  ~ under the License.
-  -->
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html>
-<head>
-  <meta http-equiv="content-type" content="">
-  <title>Migrating from Axis 1.x</title>
-  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
-  media="all">
-</head>
-
-<body lang="en">
-<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
-href="mailto:axis-user@ws.apache.org?subject=[Axis2]">axis-user@ws.apache.org</a></i>.
-(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</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 "Module" concept over the
-"Handler" 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 ="http://ws.apache.org:5049/axis/services/echo";
-      Service  service = new Service();
-      Call     call    = (Call) service.createCall();
-      call.setTargetEndpointAddress( new java.net.URL(endpoint) );
-      call.setOperationName(new QName("http://soapinterop.org/", "echoString"));
-      String ret = (String) call.invoke( new Object[] { "Hello!" } );
-      System.out.println("Sent 'Hello!', got '" + ret + "'");
-    } 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(
-			"http://127.0.0.1:8080/axis2/services/MyService");
-	public static void main(String[] args) {
-		try {
-			OMFactory fac = OMAbstractFactory.getOMFactory();
-			OMNamespace ns = fac.createOMNamespace("http://soapinterop.org/", "ns1");
-			OMElement payload = fac.createOMElement("echoString", ns);
-			payload.setText("Hello!");
-			Options options = new Options();
-			ServiceClient client = new ServiceClient();
-			options.setTo(targetEPR);
-			client.setOptions(options); 
-			//Blocking invocation
-			OMElement result = client.sendReceive(payload);
-      			System.out.println("Sent Hello, got : " + 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 "payload" 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 "payload" will
-be bound according to the data binding framework in use. So the extra
-work of parsing the "payload" 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 "Handler concept" and is more into the
-"Module concept". 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="foo/&gt;").</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 "SOAP Monitor". 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="http://xml.apache.org/axis/wsdd/"
-    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"&gt;
-    
-  &lt;handler name="soapmonitor" 
-      type="java:org.apache.axis.handlers.SOAPMonitorHandler"&gt;
-    &lt;parameter name="wsdlURL" 
-      value="/wzs/SOAPMonitorService-impl.wsdl"/&gt;
-    &lt;parameter name="namespace" 
-      value="http://tempuri.org/wsdl/2001/12/SOAPMonitorService-impl.wsdl"/&gt;
-    &lt;parameter name="serviceName" value="SOAPMonitorService"/&gt;
-    &lt;parameter name="portName" value="Demo"/&gt;
-  &lt;/handler&gt;
-
-  &lt;service name="SOAPMonitorService" provider="java:RPC"&gt;
-    &lt;parameter name="allowedMethods" value="publishMessage"/&gt;
-    &lt;parameter name="className" 
-      value="org.apache.axis.monitor.SOAPMonitorService"/&gt;
-    &lt;parameter name="scope" value="Application"/&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="example" xmlns="http://xml.apache.org/axis/wsdd/" 
-    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"&gt;
-  
-  &lt;service name="urn:myService" provider="java:RPC"&gt;
-    &lt;parameter name="className" value="org.MyService"/&gt;
-    &lt;parameter name="allowedMethods" value="*"/&gt;
-
-    &lt;requestFlow&gt;
-      &lt;handler type="soapmonitor"/&gt;
-    &lt;/requestFlow&gt;
-    &lt;responseFlow&gt;
-      &lt;handler type="soapmonitor"/&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="soapmonitor" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorModule"&gt;
-    &lt;inflow&gt;
-        &lt;handler name="InFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler"&gt;
-            &lt;order phase="soapmonitorPhase"/&gt;
-        &lt;/handler&gt;
-    &lt;/inflow&gt;
-
-    &lt;outflow&gt;
-        &lt;handler name="OutFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler"&gt;
-            &lt;order phase="soapmonitorPhase"/&gt;
-        &lt;/handler&gt;
-    &lt;/outflow&gt;
-
-    &lt;Outfaultflow&gt;
-        &lt;handler name="FaultOutFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler"&gt;
-            &lt;order phase="soapmonitorPhase"/&gt;
-        &lt;/handler&gt;
-    &lt;/Outfaultflow&gt;
-
-    &lt;INfaultflow&gt;
-        &lt;handler name="FaultInFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler"&gt;
-            &lt;order phase="soapmonitorPhase"/&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="ExampleService"&gt;
-    &lt;module ref="soapmonitor"/&gt;
-    &lt;description&gt;
-       This service has the SOAP Monitor wired in 
-    &lt;/description&gt;
-    &lt;parameter name="ServiceClass"&gt;org.ExampleService&lt;/parameter&gt;
-    &lt;operation name="myExecute"&gt;
-        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&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="soapmonitor"/&gt;</pre>
-
-<p><b>Then define your phase orders for the 'soapmonitorPhase' referenced in
-the module.xml :</b></p>
-<pre>    &lt;phaseOrder type="inflow"&gt;
-        &lt;!--  Global 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.dispatchers.AddressingBasedDispatcher"&gt;
-                &lt;order phase="Dispatch"/&gt;
-            &lt;/handler&gt;
-
-            &lt;handler name="RequestURIBasedDispatcher"
-                     class="org.apache.axis2.dispatchers.RequestURIBasedDispatcher"&gt;
-                &lt;order phase="Dispatch"/&gt;
-            &lt;/handler&gt;
-
-            &lt;handler name="SOAPActionBasedDispatcher"
-                     class="org.apache.axis2.dispatchers.SOAPActionBasedDispatcher"&gt;
-                &lt;order phase="Dispatch"/&gt;
-            &lt;/handler&gt;
-
-            &lt;handler name="SOAPMessageBodyBasedDispatcher"
-                     class="org.apache.axis2.dispatchers.SOAPMessageBodyBasedDispatcher"&gt;
-                &lt;order phase="Dispatch"/&gt;
-            &lt;/handler&gt;
-            &lt;handler name="InstanceDispatcher"
-                     class="org.apache.axis2.engine.InstanceDispatcher"&gt;
-                &lt;order phase="Dispatch"/&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="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;!--   Global phases   --&gt;
-        &lt;!--   these phases will run irrespective of the service   --&gt;
-        &lt;phase name="MessageOut"/&gt;
-        &lt;phase name="userphase1"/&gt;
-        &lt;phase name="soapmonitorPhase"/&gt;
-        &lt;phase name="PolicyDetermination"/&gt;
-        &lt;!--   Global phases   --&gt;
-    &lt;/phaseOrder&gt;
-    &lt;phaseOrder type="INfaultflow"&gt;
-        &lt;phase name="userphase1"/&gt;
-        &lt;phase name="soapmonitorPhase"/&gt;
-        &lt;!--   user can add his own phases to this area  --&gt;
-    &lt;/phaseOrder&gt;
-    &lt;phaseOrder type="Outfaultflow"&gt;
-        &lt;!--   user can add his own phases to this area  --&gt;
-        &lt;!--   Global phases   --&gt;
-        &lt;phase name="MessageOut"/&gt;
-        &lt;phase name="userphase1"/&gt;
-        &lt;phase name="soapmonitorPhase"/&gt;
-        &lt;phase name="PolicyDetermination"/&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="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"&gt; 
-   &lt;parameter name="PROTOCOL"&gt;HTTP/1.1&lt;/parameter&gt;
-   &lt;parameter name="Transfer-Encoding"&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="1.0" encoding="UTF-8"?&gt;
-
-&lt;definitions name="SimpleService" targetNamespace="http://simpleNS" xmlns:tns="http://simpleNS" 
-xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
-xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ns2="http://simpleNS/types"&gt;
-  &lt;types&gt;
-    &lt;schema targetNamespace="http://simpleNS/types" xmlns:tns="http://simpleNS/types" 
-xmlns:soap11-enc="http://schemas.xmlsoap.org/soap/encoding/" 
-xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
-xmlns="http://www.w3.org/2001/XMLSchema"&gt;
-      &lt;import namespace="http://schemas.xmlsoap.org/soap/encoding/"/&gt;
-      &lt;element name="simpleLogin"&gt;
-        &lt;complexType&gt;
-          &lt;sequence&gt;
-            &lt;element name="user_name" type="xsd:string"/&gt;
-            &lt;element name="user_password" type="xsd:string"/&gt;
-          &lt;/sequence&gt;
-        &lt;/complexType&gt;
-      &lt;/element&gt;
-      &lt;element name="simpleLoginResponse"&gt;
-        &lt;complexType&gt;
-          &lt;sequence&gt;
-            &lt;element name="soap_session_id" type="xsd:string"/&gt;
-            &lt;element name="web_user_name" type="xsd:string"/&gt;
-          &lt;/sequence&gt;
-        &lt;/complexType&gt;
-      &lt;/element&gt;
-&lt;/schema&gt;&lt;/types&gt;
-  &lt;message name="SimpleEndpoint_simpleLogin"&gt;
-     &lt;part name="parameters" element="ns2:simpleLogin"/&gt;
-  &lt;/message&gt;
-  &lt;message name="SimpleEndpoint_simpleLoginResponse"&gt;
-    &lt;part name="result" element="ns2:simpleLoginResponse"/&gt;
-  &lt;/message&gt;
-  &lt;portType name="SimpleEndpoint"&gt;
-    &lt;operation name="simpleLogin"&gt;
-      &lt;input message="tns:SimpleEndpoint_simpleLogin" name="SimpleEndpoint_simpleLogin"/&gt;
-      &lt;output message="tns:SimpleEndpoint_simpleLoginResponse" name="SimpleEndpoint_simpleLoginResponse"/&gt;
-    &lt;/operation&gt;
-  &lt;/portType&gt;
-  &lt;binding name="SimpleEndpointBinding" type="tns:SimpleEndpoint"&gt;
-    &lt;soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/&gt;
-    &lt;operation name="simpleLogin"&gt;
-      &lt;soap:operation soapAction="simpleLogin"/&gt;
-      &lt;input name="SimpleEndpoint_simpleLogin"&gt;
-        &lt;soap:body use="literal"/&gt;
-      &lt;/input&gt;
-      &lt;output name="SimpleEndpoint_simpleLoginResponse"&gt;
-        &lt;soap:body use="literal"/&gt;
-      &lt;/output&gt;
-    &lt;/operation&gt;
-  &lt;/binding&gt;
-  &lt;service name="SimpleService"&gt;
-    &lt;port name="SimpleEndpointPort" binding="tns:SimpleEndpointBinding"&gt;
-      &lt;soap:address location="http://localhost:8080/axis/services/SimpleEndpointPort"/&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="wsdl2java" description="axis 1.x"&gt;
-       &lt;delete dir="output" /&gt;
-       &lt;mkdir dir="output" /&gt;
-       &lt;axis-wsdl2java
-         output="output"
-         verbose="true"
-         url="wsdl/simple.wsdl"
-         serverside="true"
-         skeletondeploy="true"
-         nowrapped="true"&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="http://localhost:8080/axis2/services/SimpleEndpoint"/&gt;&lt;/port&gt;&lt;/service&gt;&lt;/definitions&gt;</pre>
-
-<p>In Axis2, the default databinding uses ADB. However, XMLBeans, JiBX and JaxMe
-are also supported. This example uses XMLBeans. For Axis2, our example uses
-the following Ant task:</p>
-<pre>&lt;target name="wsdl2java"&gt;
-      &lt;delete dir="output" /&gt;
-      &lt;java classname="org.apache.axis2.wsdl.WSDL2Java" fork="true"&gt;
-          &lt;classpath refid="axis.classpath"/&gt; 
-          &lt;arg value="-d"/&gt;
-          &lt;arg value="xmlbeans"/&gt;
-          &lt;arg value="-uri"/&gt;
-          &lt;arg file="wsdl/simple.wsdl"/&gt;
-          &lt;arg value="-ss"/&gt;
-          &lt;arg value="-g"/&gt;
-          &lt;arg value="-sd"/&gt;
-          &lt;arg value="-o"/&gt;
-          &lt;arg file="output"/&gt;
-          &lt;arg value="-p"/&gt;
-          &lt;arg value="org.simple.endpoint"/&gt;
-      &lt;/java&gt;
-
-      &lt;!-- Move the schema folder to classpath--&gt;
-      &lt;move todir="${build.classes}"&gt;
-          &lt;fileset dir="output/resources"&gt;
-              &lt;include name="*schema*/**/*.class"/&gt;
-              &lt;include name="*schema*/**/*.xsb"/&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/@axis2_version_dir@/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("mySessionID", "username");
-    }
-
-}</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("my random string");
-                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("username","password");
-    // Make the actual call
-    SimpleLoginResponse simpleLoginResponse = port.simpleLogin(parameters);
-    String session = simpleLoginResponse.getSoap_session_id();
-    String user = simpleLoginResponse.getWeb_user_name();
-    System.out.println("simpleLoginResponse, session: " + session + ", user: " + 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, "http://localhost:8080/axis2/services/SimpleService");
-
-    SimpleLogin simpleLogin = SimpleLogin.Factory.newInstance();
-    simpleLogin.setUserName("userName");
-    simpleLogin.setUserPassword("password");
-
-    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("simpleLoginResponse, session: " + session + ", user: " + 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>
-</body>
-</html>
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one
+  ~ or more contributor license agreements. See the NOTICE file
+  ~ distributed with this work for additional information
+  ~ regarding copyright ownership. The ASF licenses this file
+  ~ to you under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License. You may obtain a copy of the License at
+  ~
+  ~ http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied. See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+  -->
+<!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>
+<meta name="generator" content=
+"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" />
+<meta http-equiv="content-type" content="" />
+<title>Migrating from Axis 1.x</title>
+<link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+media="all" />
+</head>
+<body lang="en" xml:lang="en">
+<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 href=
+"mailto:axis-user@ws.apache.org?subject=[Axis2]">axis-user@ws.apache.org</a></i>.
+(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</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" id="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 "Module" concept
+over the "Handler" 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" id="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 ="http://ws.apache.org:5049/axis/services/echo";
+      Service  service = new Service();
+      Call     call    = (Call) service.createCall();
+      call.setTargetEndpointAddress( new java.net.URL(endpoint) );
+      call.setOperationName(new QName("http://soapinterop.org/", "echoString"));
+      String ret = (String) call.invoke( new Object[] { "Hello!" } );
+      System.out.println("Sent 'Hello!', got '" + ret + "'");
+    } 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(
+                        "http://127.0.0.1:8080/axis2/services/MyService");
+        public static void main(String[] args) {
+                try {
+                        OMFactory fac = OMAbstractFactory.getOMFactory();
+                        OMNamespace ns = fac.createOMNamespace("http://soapinterop.org/", "ns1");
+                        OMElement payload = fac.createOMElement("echoString", ns);
+                        payload.setText("Hello!");
+                        Options options = new Options();
+                        ServiceClient client = new ServiceClient();
+                        options.setTo(targetEPR);
+                        client.setOptions(options); 
+                        //Blocking invocation
+                        OMElement result = client.sendReceive(payload);
+                        System.out.println("Sent Hello, got : " + 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 "payload" 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
+"payload" will be bound according to the data binding framework in
+use. So the extra work of parsing the "payload" 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" id="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 "Handler concept" and is more into
+the "Module concept". 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="foo/&gt;").</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 "SOAP Monitor". 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="http://xml.apache.org/axis/wsdd/"
+    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"&gt;
+    
+  &lt;handler name="soapmonitor" 
+      type="java:org.apache.axis.handlers.SOAPMonitorHandler"&gt;
+    &lt;parameter name="wsdlURL" 
+      value="/wzs/SOAPMonitorService-impl.wsdl"/&gt;
+    &lt;parameter name="namespace" 
+      value="http://tempuri.org/wsdl/2001/12/SOAPMonitorService-impl.wsdl"/&gt;
+    &lt;parameter name="serviceName" value="SOAPMonitorService"/&gt;
+    &lt;parameter name="portName" value="Demo"/&gt;
+  &lt;/handler&gt;
+
+  &lt;service name="SOAPMonitorService" provider="java:RPC"&gt;
+    &lt;parameter name="allowedMethods" value="publishMessage"/&gt;
+    &lt;parameter name="className" 
+      value="org.apache.axis.monitor.SOAPMonitorService"/&gt;
+    &lt;parameter name="scope" value="Application"/&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="example" xmlns="http://xml.apache.org/axis/wsdd/" 
+    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"&gt;
+  
+  &lt;service name="urn:myService" provider="java:RPC"&gt;
+    &lt;parameter name="className" value="org.MyService"/&gt;
+    &lt;parameter name="allowedMethods" value="*"/&gt;
+
+    &lt;requestFlow&gt;
+      &lt;handler type="soapmonitor"/&gt;
+    &lt;/requestFlow&gt;
+    &lt;responseFlow&gt;
+      &lt;handler type="soapmonitor"/&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="soapmonitor" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorModule"&gt;
+    &lt;inflow&gt;
+        &lt;handler name="InFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler"&gt;
+            &lt;order phase="soapmonitorPhase"/&gt;
+        &lt;/handler&gt;
+    &lt;/inflow&gt;
+
+    &lt;outflow&gt;
+        &lt;handler name="OutFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler"&gt;
+            &lt;order phase="soapmonitorPhase"/&gt;
+        &lt;/handler&gt;
+    &lt;/outflow&gt;
+
+    &lt;Outfaultflow&gt;
+        &lt;handler name="FaultOutFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler"&gt;
+            &lt;order phase="soapmonitorPhase"/&gt;
+        &lt;/handler&gt;
+    &lt;/Outfaultflow&gt;
+
+    &lt;INfaultflow&gt;
+        &lt;handler name="FaultInFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler"&gt;
+            &lt;order phase="soapmonitorPhase"/&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="ExampleService"&gt;
+    &lt;module ref="soapmonitor"/&gt;
+    &lt;description&gt;
+       This service has the SOAP Monitor wired in 
+    &lt;/description&gt;
+    &lt;parameter name="ServiceClass"&gt;org.ExampleService&lt;/parameter&gt;
+    &lt;operation name="myExecute"&gt;
+        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&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="soapmonitor"/&gt;
+</pre>
+<p><b>Then define your phase orders for the 'soapmonitorPhase'
+referenced in the module.xml :</b></p>
+<pre>
+    &lt;phaseOrder type="inflow"&gt;
+        &lt;!--  Global 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.dispatchers.AddressingBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name="RequestURIBasedDispatcher"
+                     class="org.apache.axis2.dispatchers.RequestURIBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name="SOAPActionBasedDispatcher"
+                     class="org.apache.axis2.dispatchers.SOAPActionBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name="SOAPMessageBodyBasedDispatcher"
+                     class="org.apache.axis2.dispatchers.SOAPMessageBodyBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+            &lt;handler name="InstanceDispatcher"
+                     class="org.apache.axis2.engine.InstanceDispatcher"&gt;
+                &lt;order phase="Dispatch"/&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="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;!--   Global phases   --&gt;
+        &lt;!--   these phases will run irrespective of the service   --&gt;
+        &lt;phase name="MessageOut"/&gt;
+        &lt;phase name="userphase1"/&gt;
+        &lt;phase name="soapmonitorPhase"/&gt;
+        &lt;phase name="PolicyDetermination"/&gt;
+        &lt;!--   Global phases   --&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type="INfaultflow"&gt;
+        &lt;phase name="userphase1"/&gt;
+        &lt;phase name="soapmonitorPhase"/&gt;
+        &lt;!--   user can add his own phases to this area  --&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type="Outfaultflow"&gt;
+        &lt;!--   user can add his own phases to this area  --&gt;
+        &lt;!--   Global phases   --&gt;
+        &lt;phase name="MessageOut"/&gt;
+        &lt;phase name="userphase1"/&gt;
+        &lt;phase name="soapmonitorPhase"/&gt;
+        &lt;phase name="PolicyDetermination"/&gt;
+        &lt;!--   Global phases   --&gt;
+    &lt;/phaseOrder&gt;
+</pre>
+<p>See the user guide for more information on Axis2 modules.</p>
+<a name="transports" id="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="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"&gt; 
+   &lt;parameter name="PROTOCOL"&gt;HTTP/1.1&lt;/parameter&gt;
+   &lt;parameter name="Transfer-Encoding"&gt;chunked&lt;/parameter&gt;
+&lt;/transportSender&gt;
+...
+</pre>
+<a name="data_binding" id="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="1.0" encoding="UTF-8"?&gt;
+
+&lt;definitions name="SimpleService" targetNamespace="http://simpleNS" xmlns:tns="http://simpleNS" 
+xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
+xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ns2="http://simpleNS/types"&gt;
+  &lt;types&gt;
+    &lt;schema targetNamespace="http://simpleNS/types" xmlns:tns="http://simpleNS/types" 
+xmlns:soap11-enc="http://schemas.xmlsoap.org/soap/encoding/" 
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
+xmlns="http://www.w3.org/2001/XMLSchema"&gt;
+      &lt;import namespace="http://schemas.xmlsoap.org/soap/encoding/"/&gt;
+      &lt;element name="simpleLogin"&gt;
+        &lt;complexType&gt;
+          &lt;sequence&gt;
+            &lt;element name="user_name" type="xsd:string"/&gt;
+            &lt;element name="user_password" type="xsd:string"/&gt;
+          &lt;/sequence&gt;
+        &lt;/complexType&gt;
+      &lt;/element&gt;
+      &lt;element name="simpleLoginResponse"&gt;
+        &lt;complexType&gt;
+          &lt;sequence&gt;
+            &lt;element name="soap_session_id" type="xsd:string"/&gt;
+            &lt;element name="web_user_name" type="xsd:string"/&gt;
+          &lt;/sequence&gt;
+        &lt;/complexType&gt;
+      &lt;/element&gt;
+&lt;/schema&gt;&lt;/types&gt;
+  &lt;message name="SimpleEndpoint_simpleLogin"&gt;
+     &lt;part name="parameters" element="ns2:simpleLogin"/&gt;
+  &lt;/message&gt;
+  &lt;message name="SimpleEndpoint_simpleLoginResponse"&gt;
+    &lt;part name="result" element="ns2:simpleLoginResponse"/&gt;
+  &lt;/message&gt;
+  &lt;portType name="SimpleEndpoint"&gt;
+    &lt;operation name="simpleLogin"&gt;
+      &lt;input message="tns:SimpleEndpoint_simpleLogin" name="SimpleEndpoint_simpleLogin"/&gt;
+      &lt;output message="tns:SimpleEndpoint_simpleLoginResponse" name="SimpleEndpoint_simpleLoginResponse"/&gt;
+    &lt;/operation&gt;
+  &lt;/portType&gt;
+  &lt;binding name="SimpleEndpointBinding" type="tns:SimpleEndpoint"&gt;
+    &lt;soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/&gt;
+    &lt;operation name="simpleLogin"&gt;
+      &lt;soap:operation soapAction="simpleLogin"/&gt;
+      &lt;input name="SimpleEndpoint_simpleLogin"&gt;
+        &lt;soap:body use="literal"/&gt;
+      &lt;/input&gt;
+      &lt;output name="SimpleEndpoint_simpleLoginResponse"&gt;
+        &lt;soap:body use="literal"/&gt;
+      &lt;/output&gt;
+    &lt;/operation&gt;
+  &lt;/binding&gt;
+  &lt;service name="SimpleService"&gt;
+    &lt;port name="SimpleEndpointPort" binding="tns:SimpleEndpointBinding"&gt;
+      &lt;soap:address location="http://localhost:8080/axis/services/SimpleEndpointPort"/&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="wsdl2java" description="axis 1.x"&gt;
+       &lt;delete dir="output" /&gt;
+       &lt;mkdir dir="output" /&gt;
+       &lt;axis-wsdl2java
+         output="output"
+         verbose="true"
+         url="wsdl/simple.wsdl"
+         serverside="true"
+         skeletondeploy="true"
+         nowrapped="true"&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="http://localhost:8080/axis2/services/SimpleEndpoint"/&gt;&lt;/port&gt;&lt;/service&gt;&lt;/definitions&gt;
+</pre>
+<p>In Axis2, the default databinding uses ADB. However, XMLBeans,
+JiBX and JaxMe are also supported. This example uses XMLBeans. For
+Axis2, our example uses the following Ant task:</p>
+<pre>
+&lt;target name="wsdl2java"&gt;
+      &lt;delete dir="output" /&gt;
+      &lt;java classname="org.apache.axis2.wsdl.WSDL2Java" fork="true"&gt;
+          &lt;classpath refid="axis.classpath"/&gt; 
+          &lt;arg value="-d"/&gt;
+          &lt;arg value="xmlbeans"/&gt;
+          &lt;arg value="-uri"/&gt;
+          &lt;arg file="wsdl/simple.wsdl"/&gt;
+          &lt;arg value="-ss"/&gt;
+          &lt;arg value="-g"/&gt;
+          &lt;arg value="-sd"/&gt;
+          &lt;arg value="-o"/&gt;
+          &lt;arg file="output"/&gt;
+          &lt;arg value="-p"/&gt;
+          &lt;arg value="org.simple.endpoint"/&gt;
+      &lt;/java&gt;
+
+      &lt;!-- Move the schema folder to classpath--&gt;
+      &lt;move todir="${build.classes}"&gt;
+          &lt;fileset dir="output/resources"&gt;
+              &lt;include name="*schema*/**/*.class"/&gt;
+              &lt;include name="*schema*/**/*.xsb"/&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/@axis2_version_dir@/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("mySessionID", "username");
+    }
+
+}
+</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("my random string");
+                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("username","password");
+    // Make the actual call
+    SimpleLoginResponse simpleLoginResponse = port.simpleLogin(parameters);
+    String session = simpleLoginResponse.getSoap_session_id();
+    String user = simpleLoginResponse.getWeb_user_name();
+    System.out.println("simpleLoginResponse, session: " + session + ", user: " + 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, "http://localhost:8080/axis2/services/SimpleService");
+
+    SimpleLogin simpleLogin = SimpleLogin.Factory.newInstance();
+    simpleLogin.setUserName("userName");
+    simpleLogin.setUserPassword("password");
+
+    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("simpleLoginResponse, session: " + session + ", user: " + 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" id="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>
+</body>
+</html>



---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org


Mime
View raw message