| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="content-type" content=""> |
| <title>Migrating from Axis 1.x</title> |
| <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" |
| media="all"> |
| </head> |
| |
| <body lang="en"> |
| <h1>Migrating from Apache Axis 1.x to Axis2</h1> |
| |
| <p>For all those users who are familiar with Axis 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?subject=[Axis2]">axis-dev@ws.apache.org</a></i>. |
| (Subscription details are available on the <a |
| href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.) Kindly |
| prefix subject with [Axis2]. </p> |
| |
| <h2>Content</h2> |
| <ul> |
| <li><a href="#comp">Compatibility</a></li> |
| <li><a href="#start">Getting Started</a></li> |
| <li><a href="#custom_deployment">Custom Deployment of Services, Handlers |
| and Modules</a></li> |
| <li><a href="#transports">Transports for HTTP Connection</a></li> |
| <li><a href="#data_binding">Data Binding Support</a></li> |
| <li><a href="#best">Best Usage</a></li> |
| </ul> |
| <a name="comp"></a> |
| |
| <h2>Compatibility</h2> |
| |
| <p>Axis1.x and Axis2 have evolved from different architectures.</p> |
| |
| <p><strong>Speed</strong> - Axis2 is based on 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 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> - 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 versions 1.1 and 2.0, which |
| allow you to create stubs and skeletons to manipulate the web services |
| arena.</p> |
| |
| <p><strong>Component - oriented architecture</strong> - The components are |
| .mar and .aar archives . Easily reusable components such as handlers and |
| modules allow pattern processing for your applications or 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>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); |
| //Blocking invocation |
| OMElement result = client.sendReceive(payload); |
| |
| } catch (AxisFault axisFault) { |
| axisFault.printStackTrace(); |
| } |
| |
| } |
| } |
| </pre> |
| |
| <p>It has been clearly depicted that the invocation in Axis2 is dealt with |
| the 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, the "payload" will |
| be according to the data binding framework that will be used. So the extra |
| work of "payload" will vanish.</p> |
| |
| <p>Apart from synchronous invocation, Axis2 also 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, which is far from the capabilities of Axis1.x.</p> |
| <a name="custom_deployment"></a> |
| |
| <h2>Custom Deployment of Services, Handlers, and Modules</h2> |
| |
| <p>In Axis 1.x, the deployment of services was via 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 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 |
| 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 <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" locked="false">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.engine.AddressingBasedDispatcher"> |
| <order phase="Dispatch"/> |
| </handler> |
| |
| <handler name="RequestURIBasedDispatcher" |
| class="org.apache.axis2.engine.RequestURIBasedDispatcher"> |
| <order phase="Dispatch"/> |
| </handler> |
| |
| <handler name="SOAPActionBasedDispatcher" |
| class="org.apache.axis2.engine.SOAPActionBasedDispatcher"> |
| <order phase="Dispatch"/> |
| </handler> |
| |
| <handler name="SOAPMessageBodyBasedDispatcher" |
| class="org.apache.axis2.engine.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"></a> |
| |
| <h2>Transports for HTTP Connection</h2> |
| |
| <p>Axis2 comes with the CommonsHTTPTransportSender which is based on |
| commons-httpclient.</p> |
| |
| <p>It should be noted that axis2.xml should be configured to call the commons |
| transports with the statement,</p> |
| <pre>... |
| <transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"> |
| <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter> |
| <parameter name="Transfer-Encoding" locked="false">chunked</parameter> |
| </transportSender> |
| ...</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, 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 and JaxMe |
| 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/@axis2_version_dir@/CodegenToolReference.html">CodegenToolReference |
| Guide.</a></p> |
| |
| <p>A feature of XMLBeans is that there is one class file created with |
| WSDL2java, and a series of .xsb files. They must be referenced when |
| compiling, and as the example shows, these files are moved to a build |
| directory.</p> |
| |
| <p>The Axis2 WSDL2Java example also takes the simple.wsdl, which is under the |
| directory 'wsdl', and creates files under the directory 'output'. The |
| relevant non-xmlbean files created are shown below:</p> |
| <pre>output/resources/services.xml |
| output/src/org/simple |
| output/src/org/simple/endpoint |
| output/src/org/simple/endpoint/SimpleEndpointSkeleton.java |
| output/src/org/simple/endpoint/SimpleEndpointMessageReceiverInOut.java |
| output/src/org/simple/endpoint/SimpleEndpointCallbackHandler.java |
| output/src/org/simple/endpoint/SimpleEndpointStub.java |
| output/src/simplens |
| output/src/simplens/types |
| output/src/simplens/types/SimpleLoginDocument.java |
| output/src/simplens/types/impl |
| output/src/simplens/types/impl/SimpleLoginDocumentImpl.java |
| output/src/simplens/types/impl/SimpleLoginResponseDocumentImpl.java |
| output/src/simplens/types/SimpleLoginResponseDocument.java</pre> |
| |
| <p>The first important distinction is that while the Axis 1.x example |
| generated deploy.wsdd and undeploy.wsdd, the Axis2 example created a |
| services.xml. The files deploy.wsdd and services.xml are a breed apart, |
| coming from different architectures. There is no direct parallel between |
| them. See the Axis2 user guide for an explanation about services.xml</p> |
| |
| <p>Now we're ready to code. We'll start with Axis 1.x on the service side. To |
| implement the business logic, we'll change |
| simpleNS/SimpleEndpointBindingImpl.java from:</p> |
| <pre class="code">package simpleNS; |
| |
| public class SimpleEndpointBindingImpl implements simpleNS.SimpleEndpoint{ |
| public simpleNS.types.SimpleLoginResponse simpleLogin(simpleNS.types.SimpleLogin parameters) |
| throws java.rmi.RemoteException { |
| return null; |
| } |
| |
| }</pre> |
| |
| <p>To:</p> |
| <pre class="code">package simpleNS; |
| |
| public class SimpleEndpointBindingImpl implements simpleNS.SimpleEndpoint{ |
| public simpleNS.types.SimpleLoginResponse simpleLogin(simpleNS.types.SimpleLogin parameters) |
| throws java.rmi.RemoteException { |
| |
| String userName = parameters.getUser_name(); |
| String password = parameters.getUser_password(); |
| // do something with those vars... |
| return new simpleNS.types.SimpleLoginResponse("mySessionID", "username"); |
| } |
| |
| }</pre> |
| |
| <p>In Axis 1.x, the next step is to compile the classes and put them in the |
| Axis.war, and then run the admin client with the generated deploy.wsdd. You |
| then look at the happy axis page to verify that the service has been |
| installed correctly.</p> |
| |
| <p>Now let's code Axis2. In Axis 1.x, while the Ant task shown in the example |
| created a skeleton, a peek inside shows that the skeleton calls the binding |
| implementation class. In Axis2, we work with the skeleton directly. To |
| implement the business logic in the generated Axis2 classes, we'll change |
| org/simple/endpoint/SimpleEndpointSkeleton.java from:</p> |
| <pre class="code">package org.simple.endpoint; |
| /** |
| * SimpleEndpointSkeleton java skeleton for the axisService |
| */ |
| public class SimpleEndpointSkeleton { |
| |
| /** |
| * Auto generated method signature |
| * @param param0 |
| */ |
| public simplens.types.SimpleLoginResponseDocument simpleLogin |
| (simplens.types.SimpleLoginDocument param0 ) throws Exception { |
| //Todo fill this with the necessary business logic |
| throw new java.lang.UnsupportedOperationException(); |
| } |
| }</pre> |
| |
| <p>To:</p> |
| <pre class="code">package org.simple.endpoint; |
| |
| import simplens.types.*; |
| import simplens.types.SimpleLoginResponseDocument.*; |
| import simplens.types.SimpleLoginDocument.*; |
| /** |
| * SimpleEndpointSkeleton java skeleton for the axisService |
| */ |
| public class SimpleEndpointSkeleton { |
| |
| /** |
| * Modified |
| * @param simpleLoginDocument |
| */ |
| public SimpleLoginResponseDocument simpleLogin |
| (simplens.types.SimpleLoginDocument simpleLoginDocument){ |
| //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 a 'Fire and forget'. See the user guide for more details.</p> |
| <a name="best"></a> |
| |
| <h2>Best Usage</h2> |
| |
| <p>Axis1.x and Axis2 have different ways of seeing the SOAP stack. So the |
| best way to migrate is to follow the <a href="userguide.html">User's |
| Guide</a> and the <a href="Axis2ArchitectureGuide.html">Architecture |
| Guide</a> of Axis2 properly. Axis2 is very straight forward and friendly to |
| use than its predecessor.</p> |
| </body> |
| </html> |
