| <!-- | |
| ~ 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 <module ref="foo/>").</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> | |
| <deployment xmlns="http://xml.apache.org/axis/wsdd/" | |
| xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"> | |
| <handler name="soapmonitor" | |
| type="java:org.apache.axis.handlers.SOAPMonitorHandler"> | |
| <parameter name="wsdlURL" | |
| value="/wzs/SOAPMonitorService-impl.wsdl"/> | |
| <parameter name="namespace" | |
| value="http://tempuri.org/wsdl/2001/12/SOAPMonitorService-impl.wsdl"/> | |
| <parameter name="serviceName" value="SOAPMonitorService"/> | |
| <parameter name="portName" value="Demo"/> | |
| </handler> | |
| <service name="SOAPMonitorService" provider="java:RPC"> | |
| <parameter name="allowedMethods" value="publishMessage"/> | |
| <parameter name="className" | |
| value="org.apache.axis.monitor.SOAPMonitorService"/> | |
| <parameter name="scope" value="Application"/> | |
| </service> | |
| </deployment> | |
| </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> | |
| <deployment name="example" xmlns="http://xml.apache.org/axis/wsdd/" | |
| xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"> | |
| <service name="urn:myService" provider="java:RPC"> | |
| <parameter name="className" value="org.MyService"/> | |
| <parameter name="allowedMethods" value="*"/> | |
| <requestFlow> | |
| <handler type="soapmonitor"/> | |
| </requestFlow> | |
| <responseFlow> | |
| <handler type="soapmonitor"/> | |
| </responseFlow> | |
| </service> | |
| </deployment> | |
| </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> | |
| <module name="soapmonitor" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorModule"> | |
| <inflow> | |
| <handler name="InFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler"> | |
| <order phase="soapmonitorPhase"/> | |
| </handler> | |
| </inflow> | |
| <outflow> | |
| <handler name="OutFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler"> | |
| <order phase="soapmonitorPhase"/> | |
| </handler> | |
| </outflow> | |
| <Outfaultflow> | |
| <handler name="FaultOutFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler"> | |
| <order phase="soapmonitorPhase"/> | |
| </handler> | |
| </Outfaultflow> | |
| <INfaultflow> | |
| <handler name="FaultInFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler"> | |
| <order phase="soapmonitorPhase"/> | |
| </handler> | |
| </INfaultflow> | |
| </module> | |
| </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> | |
| <service name="ExampleService"> | |
| <module ref="soapmonitor"/> | |
| <description> | |
| This service has the SOAP Monitor wired in | |
| </description> | |
| <parameter name="ServiceClass">org.ExampleService</parameter> | |
| <operation name="myExecute"> | |
| <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/> | |
| </operation> | |
| </service> | |
| </pre> | |
| <p><b>Finally, Axis2 requires you to make some changes to | |
| axis2.xml. Start by adding a global module:</b></p> | |
| <pre> | |
| <module ref="soapmonitor"/> | |
| </pre> | |
| <p><b>Then define your phase orders for the 'soapmonitorPhase' | |
| referenced in the module.xml :</b></p> | |
| <pre> | |
| <phaseOrder type="inflow"> | |
| <!-- Global Phases --> | |
| <phase name="TransportIn"/> | |
| <phase name="PreDispatch"/> | |
| <phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase"> | |
| <handler name="AddressingBasedDispatcher" | |
| class="org.apache.axis2.dispatchers.AddressingBasedDispatcher"> | |
| <order phase="Dispatch"/> | |
| </handler> | |
| <handler name="RequestURIBasedDispatcher" | |
| class="org.apache.axis2.dispatchers.RequestURIBasedDispatcher"> | |
| <order phase="Dispatch"/> | |
| </handler> | |
| <handler name="SOAPActionBasedDispatcher" | |
| class="org.apache.axis2.dispatchers.SOAPActionBasedDispatcher"> | |
| <order phase="Dispatch"/> | |
| </handler> | |
| <handler name="SOAPMessageBodyBasedDispatcher" | |
| class="org.apache.axis2.dispatchers.SOAPMessageBodyBasedDispatcher"> | |
| <order phase="Dispatch"/> | |
| </handler> | |
| <handler name="InstanceDispatcher" | |
| class="org.apache.axis2.engine.InstanceDispatcher"> | |
| <order phase="Dispatch"/> | |
| </handler> | |
| </phase> | |
| <!-- Global Phases --> | |
| <!-- After Dispatch phase module author or service author can add any phase he wants --> | |
| <phase name="userphase1"/> | |
| <phase name="soapmonitorPhase"/> | |
| </phaseOrder> | |
| <phaseOrder type="outflow"> | |
| <!-- user can add his own phases to this area --> | |
| <!-- Global phases --> | |
| <!-- these phases will run irrespective of the service --> | |
| <phase name="MessageOut"/> | |
| <phase name="userphase1"/> | |
| <phase name="soapmonitorPhase"/> | |
| <phase name="PolicyDetermination"/> | |
| <!-- Global phases --> | |
| </phaseOrder> | |
| <phaseOrder type="INfaultflow"> | |
| <phase name="userphase1"/> | |
| <phase name="soapmonitorPhase"/> | |
| <!-- user can add his own phases to this area --> | |
| </phaseOrder> | |
| <phaseOrder type="Outfaultflow"> | |
| <!-- user can add his own phases to this area --> | |
| <!-- Global phases --> | |
| <phase name="MessageOut"/> | |
| <phase name="userphase1"/> | |
| <phase name="soapmonitorPhase"/> | |
| <phase name="PolicyDetermination"/> | |
| <!-- Global phases --> | |
| </phaseOrder> | |
| </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> | |
| ... | |
| <transportSender name="http" class="org.apache.axis2.transport.http.impl.httpclient4.HTTPClient4TransportSender"> | |
| <parameter name="PROTOCOL">HTTP/1.1</parameter> | |
| <parameter name="Transfer-Encoding">chunked</parameter> | |
| </transportSender> | |
| ... | |
| </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> | |
| <?xml version="1.0" encoding="UTF-8"?> | |
| <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"> | |
| <types> | |
| <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"> | |
| <import namespace="http://schemas.xmlsoap.org/soap/encoding/"/> | |
| <element name="simpleLogin"> | |
| <complexType> | |
| <sequence> | |
| <element name="user_name" type="xsd:string"/> | |
| <element name="user_password" type="xsd:string"/> | |
| </sequence> | |
| </complexType> | |
| </element> | |
| <element name="simpleLoginResponse"> | |
| <complexType> | |
| <sequence> | |
| <element name="soap_session_id" type="xsd:string"/> | |
| <element name="web_user_name" type="xsd:string"/> | |
| </sequence> | |
| </complexType> | |
| </element> | |
| </schema></types> | |
| <message name="SimpleEndpoint_simpleLogin"> | |
| <part name="parameters" element="ns2:simpleLogin"/> | |
| </message> | |
| <message name="SimpleEndpoint_simpleLoginResponse"> | |
| <part name="result" element="ns2:simpleLoginResponse"/> | |
| </message> | |
| <portType name="SimpleEndpoint"> | |
| <operation name="simpleLogin"> | |
| <input message="tns:SimpleEndpoint_simpleLogin" name="SimpleEndpoint_simpleLogin"/> | |
| <output message="tns:SimpleEndpoint_simpleLoginResponse" name="SimpleEndpoint_simpleLoginResponse"/> | |
| </operation> | |
| </portType> | |
| <binding name="SimpleEndpointBinding" type="tns:SimpleEndpoint"> | |
| <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/> | |
| <operation name="simpleLogin"> | |
| <soap:operation soapAction="simpleLogin"/> | |
| <input name="SimpleEndpoint_simpleLogin"> | |
| <soap:body use="literal"/> | |
| </input> | |
| <output name="SimpleEndpoint_simpleLoginResponse"> | |
| <soap:body use="literal"/> | |
| </output> | |
| </operation> | |
| </binding> | |
| <service name="SimpleService"> | |
| <port name="SimpleEndpointPort" binding="tns:SimpleEndpointBinding"> | |
| <soap:address location="http://localhost:8080/axis/services/SimpleEndpointPort"/></port></service></definitions> | |
| </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> | |
| <target name="wsdl2java" description="axis 1.x"> | |
| <delete dir="output" /> | |
| <mkdir dir="output" /> | |
| <axis-wsdl2java | |
| output="output" | |
| verbose="true" | |
| url="wsdl/simple.wsdl" | |
| serverside="true" | |
| skeletondeploy="true" | |
| nowrapped="true"> | |
| </axis-wsdl2java> | |
| </target> | |
| </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> | |
| <soap:address location="http://localhost:8080/axis2/services/SimpleEndpoint"/></port></service></definitions> | |
| </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> | |
| <target name="wsdl2java"> | |
| <delete dir="output" /> | |
| <java classname="org.apache.axis2.wsdl.WSDL2Java" fork="true"> | |
| <classpath refid="axis.classpath"/> | |
| <arg value="-d"/> | |
| <arg value="xmlbeans"/> | |
| <arg value="-uri"/> | |
| <arg file="wsdl/simple.wsdl"/> | |
| <arg value="-ss"/> | |
| <arg value="-g"/> | |
| <arg value="-sd"/> | |
| <arg value="-o"/> | |
| <arg file="output"/> | |
| <arg value="-p"/> | |
| <arg value="org.simple.endpoint"/> | |
| </java> | |
| <!-- Move the schema folder to classpath--> | |
| <move todir="${build.classes}"> | |
| <fileset dir="output/resources"> | |
| <include name="*schema*/**/*.class"/> | |
| <include name="*schema*/**/*.xsb"/> | |
| </fileset> | |
| </move> | |
| </target> | |
| </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> |