clustering/xdocs/1_1/migration.html - axis-axis2-java-core - Git at Google


            
            <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

            
            <html>

            
            <head>

            
              <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 Axis 2</h1>


            <p>For all those users who are familiar with Axis2 1.x series will be

            
            assisted through this document to switch to Axis2 series. We begin by listing

            
            the improvements in Axis2 in comparison with Axis1. This is followed by

            
            guidelines for the migration.</p>


            <p><i>Send your feedback or questions to: <a

            
            href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix

            
            subject with [Axis2]. To subscribe to the mailing list see <a

            
            href="http://ws.apache.org/axis2/mail-lists.html">here.</a></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 been evolved from different architectures.</p>


            <p><strong>Speed</strong> - Axis2 is based on StAX API, which gives greater

            
            speed than SAX event based parsing that has been used in Axis1.x.</p>


            <p><strong>Stability</strong> - Axis2 has fixed phases and for extensions an

            
            area of user defined phases. This allows far more stability and flexibility

            
            than Axis1.x.</p>


            <p><strong>Transport framework</strong> - Simple abstraction in the designing

            
            of transports (i.e., senders and listeners for SOAP over various protocols

            
            such as SMTP, etc), allows far more flexibility and the core of the engine is

            
            completely transport-independent.</p>


            <p><strong>WSDL support</strong> - Axis2 supports version 1.1 and 2.0, which

            
            allows creating stubs and skeletons, to manipulate the web services arena.</p>


            <p><strong>Component - oriented architecture</strong> - This is merely

            
            through archives (.mar and .aar) . Easily reusable components such as

            
            handlers, modules allow patterns processing for your applications, or to

            
            distribution to partners. Axis2 is more concerned on the "Module" concept

            
            rather the "Handler" concept. Modules contain handlers that have been ordered

            
            through the phase rules. These are ordered to specific service(s).</p>

            
            <a name="start"></a>


            <h2>Getting Started</h2>


            <p>Lets look at a simple example of echoing at client API.</p>


            <p><b>Axis 1.x</b></p>

            
            <pre>import ...

            
            public class TestClient {

            
                    public static void main(String [] args) {

            
                            try {

            
                                    String endpoint = ... ;

            
                                    Service axisService = new Service();

            
                                    Call call = (Call) axisService.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 ...

            
            public class EchoBlockingClient {

            
                    private static EndpointReference targetEPR = new EndpointReference(

            
                    AddressingConstants.WSA_TO,

            
                                            "http://127.0.0.1:8080/axis2/services/MyService");

            
                    public static void main(String[] args) {

            
                            try {

            
                                    OMElement payload = ClientUtil.getEchoOMElement();

            
                                    Options options = new Options();

            
                                    ServiceClient client = new ServiceClient();

            
                                    options.setTo(targetEPR);

            
                                    //Blocking invocation

            
                                    OMElement result = client.sendReceive(payload);

            
                                    ...

            
                            } catch (AxisFault axisFault) {

            
                                    axisFault.printStackTrace();

            
                            } catch (XMLStreamException e) {

            
                                    e.printStackTrace();

            
                            }

            
                    }

            
            }</pre>


            <p>It has been clearly depicted that the invocation in Axis2 is dealt with

            
            SOAP body element itself. Here the invocation is synchronous but Axis2 can

            
            handle asynchronous invocations as well. The "payload" variable above

            
            contains the SOAP body element which should go in the soap envelope.</p>


            <p>Once the service is called through the stub in Axis2, "payload" is

            
            according to the data binding framework that will be used. So the extra work

            
            of "payload" will be vanished.</p>


            <p>Apart from synchronous invocation, Axis2 supports asynchronous invocation

            
            through sendReceiveNonblocking(). Synchronous/Asynchronous invocations can

            
            handle both single/double HTTP connections.</p>


            <p>With this advanced architecture, Axis2 is capable of handling megabytes of

            
            requests and responses, which is far from what Axis1.x was capable of.</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 WSDD, which in my opinion

            
            was highly cumbersome. Service deployment in Axis2 is straight forward and

            
            dynamic. Dynamic behavior is from the "Administrator" facility given by the

            
            development in the server side. It's just a matter of creating the .aar file,

            
            and deploying it. More details regarding this is given in the Axis2 user

            
            guide.</p>


            <p>Axis2 is far from the "Handler concept" and is more into the "Module

            
            concept". Abstractly speaking, the module concept is a collection of handlers

            
            with rules of governing which modules are created as .mar files. It has

            
            module.xml, which is the brain behind manipulating the handlers.</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>Lets 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

            
            org.apache.axis2.modules.Module and is used for any additional tasks needed

            
            to initialize the module and shutdown the module. In this case 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" locked="false"&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 '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.engine.AddressingBasedDispatcher"&gt;

            
                            &lt;order phase="Dispatch"/&gt;

            
                        &lt;/handler&gt;


                        &lt;handler name="RequestURIBasedDispatcher"

            
                                 class="org.apache.axis2.engine.RequestURIBasedDispatcher"&gt;

            
                            &lt;order phase="Dispatch"/&gt;

            
                        &lt;/handler&gt;


                        &lt;handler name="SOAPActionBasedDispatcher"

            
                                 class="org.apache.axis2.engine.SOAPActionBasedDispatcher"&gt;

            
                            &lt;order phase="Dispatch"/&gt;

            
                        &lt;/handler&gt;


                        &lt;handler name="SOAPMessageBodyBasedDispatcher"

            
                                 class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher"&gt;

            
                            &lt;order phase="Dispatch"/&gt;

            
                        &lt;/handler&gt;

            
                        &lt;handler name="InstanceDispatcher"

            
                                 class="org.apache.axis2.engine.InstanceDispatcher"&gt;

            
                            &lt;order phase="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 info on axis2 modules.</p>

            
            <a name="transports"></a>


            <h2>Transports for HTTP Connection</h2>


            <p>Axis2 comes with two  CommonsHTTPTransportSender which is based on

            
            commons-httpclient.</p>


            <p>It should be noted that axis2.xml should be configured to call the commons

            
            transports, with the statement,</p>

            
            <pre>...

            
            &lt;transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"&gt;

            
               &lt;parameter name="PROTOCOL" locked="false"&gt;HTTP/1.1&lt;/parameter&gt;

            
               &lt;parameter name="Transfer-Encoding" locked="false"&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. XML gives full 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 an WSDL based Axis 1.x Web Service to

            
            Axis2.</p>


            <p>First, lets 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 lets 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 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/1_1/CodegenToolReference.html">CodegenToolReference

            
            Guide.</a></p>


            <p>A feature of xmlbeans is that there is one class file created with

            
            WSDL2java, and a series of xsb files. These 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 from that 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'll then look at the happy axis page to verify the service is installed

            
            correctly.</p>


            <p>Now lets 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 Axis2 generated 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){

            
                            //Todo fill this with the necessary business logic


                            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 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 '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. Axis2 is very much straight forward and friendly to use than

            
            it's predecessor.</p>

            
            </body>

            
            </html>