<!--
  ~ 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>
</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:java-user@axis.apache.org?subject=[Axis2]">java-user@axis.apache.org</a></i>.
(Subscription details are available on the <a href="../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 HTTPClient4TransportSender which is based
on Apache Httpcomponents.</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.impl.httpclient4.HTTPClient4TransportSender"&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 JAXB-RI 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/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>