| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia at 2016-02-20 |
| | Rendered using Apache Maven Fluido Skin 1.4 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <meta name="Date-Revision-yyyymmdd" content="20160220" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <title>Apache Axis2 – Migrating from Axis 1.x</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.4.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| |
| |
| <script type="text/javascript" src="../js/apache-maven-fluido-1.4.min.js"></script> |
| |
| |
| <meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" /><meta http-equiv="content-type" content="" /> </head> |
| <body class="topBarDisabled"> |
| |
| |
| |
| <div class="container-fluid"> |
| <div id="banner"> |
| <div class="pull-left"> |
| <a href="http://www.apache.org/" id="bannerLeft"> |
| <img src="http://www.apache.org/images/asf_logo_wide.png" alt="Apache Axis2"/> |
| </a> |
| </div> |
| <div class="pull-right"> <a href=".././" id="bannerRight"> |
| <img src="../images/axis.jpg" /> |
| </a> |
| </div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| |
| |
| <li id="publishDate">Last Published: 2016-02-20 |
| <span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 1.7.1 |
| <span class="divider">|</span> |
| </li> |
| <li class=""> |
| <a href="http://www.apache.org" class="externalLink" title="Apache"> |
| Apache</a> |
| <span class="divider">/</span> |
| </li> |
| <li class=""> |
| <a href="../index.html" title="Axis2/Java"> |
| Axis2/Java</a> |
| <span class="divider">/</span> |
| </li> |
| <li class="active ">Migrating from Axis 1.x</li> |
| |
| |
| |
| |
| </ul> |
| </div> |
| |
| |
| <div class="row-fluid"> |
| <div id="leftColumn" class="span2"> |
| <div class="well sidebar-nav"> |
| |
| |
| <ul class="nav nav-list"> |
| <li class="nav-header">Axis2/Java</li> |
| |
| <li> |
| |
| <a href="../index.html" title="Home"> |
| <span class="none"></span> |
| Home</a> |
| </li> |
| |
| <li> |
| |
| <a href="../download.html" title="Downloads"> |
| <span class="none"></span> |
| Downloads</a> |
| </li> |
| |
| <li> |
| |
| <a href="javascript:void(0)" title="Release Notes"> |
| <span class="icon-chevron-down"></span> |
| Release Notes</a> |
| <ul class="nav nav-list"> |
| |
| <li> |
| |
| <a href="../release-notes/1.6.1.html" title="1.6.1"> |
| <span class="none"></span> |
| 1.6.1</a> |
| </li> |
| |
| <li> |
| |
| <a href="../release-notes/1.6.2.html" title="1.6.2"> |
| <span class="none"></span> |
| 1.6.2</a> |
| </li> |
| |
| <li> |
| |
| <a href="../release-notes/1.6.3.html" title="1.6.3"> |
| <span class="none"></span> |
| 1.6.3</a> |
| </li> |
| |
| <li> |
| |
| <a href="../release-notes/1.6.4.html" title="1.6.4"> |
| <span class="none"></span> |
| 1.6.4</a> |
| </li> |
| |
| <li> |
| |
| <a href="../release-notes/1.7.0.html" title="1.7.0"> |
| <span class="none"></span> |
| 1.7.0</a> |
| </li> |
| |
| <li> |
| |
| <a href="../release-notes/1.7.1.html" title="1.7.1"> |
| <span class="none"></span> |
| 1.7.1</a> |
| </li> |
| </ul> |
| </li> |
| |
| <li> |
| |
| <a href="../modules/index.html" title="Modules"> |
| <span class="none"></span> |
| Modules</a> |
| </li> |
| |
| <li> |
| |
| <a href="../tools/index.html" title="Tools"> |
| <span class="none"></span> |
| Tools</a> |
| </li> |
| <li class="nav-header">Documentation</li> |
| |
| <li> |
| |
| <a href="../docs/toc.html" title="Table of Contents"> |
| <span class="none"></span> |
| Table of Contents</a> |
| </li> |
| |
| <li> |
| |
| <a href="../docs/installationguide.html" title="Installation Guide"> |
| <span class="none"></span> |
| Installation Guide</a> |
| </li> |
| |
| <li> |
| |
| <a href="../docs/quickstartguide.html" title="QuickStart Guide"> |
| <span class="none"></span> |
| QuickStart Guide</a> |
| </li> |
| |
| <li> |
| |
| <a href="../docs/userguide.html" title="User Guide"> |
| <span class="none"></span> |
| User Guide</a> |
| </li> |
| |
| <li> |
| |
| <a href="../docs/jaxws-guide.html" title="JAXWS Guide"> |
| <span class="none"></span> |
| JAXWS Guide</a> |
| </li> |
| |
| <li> |
| |
| <a href="../docs/pojoguide.html" title="POJO Guide"> |
| <span class="none"></span> |
| POJO Guide</a> |
| </li> |
| |
| <li> |
| |
| <a href="../docs/spring.html" title="Spring Guide"> |
| <span class="none"></span> |
| Spring Guide</a> |
| </li> |
| |
| <li> |
| |
| <a href="../docs/webadminguide.html" title="Web Administrator's Guide"> |
| <span class="none"></span> |
| Web Administrator's Guide</a> |
| </li> |
| |
| <li class="active"> |
| |
| <a href="#"><span class="none"></span>Migration Guide (from Axis1)</a> |
| </li> |
| <li class="nav-header">Resources</li> |
| |
| <li> |
| |
| <a href="../faq.html" title="FAQ"> |
| <span class="none"></span> |
| FAQ</a> |
| </li> |
| |
| <li> |
| |
| <a href="../articles.html" title="Articles"> |
| <span class="none"></span> |
| Articles</a> |
| </li> |
| |
| <li> |
| |
| <a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="Wiki"> |
| <span class="none"></span> |
| Wiki</a> |
| </li> |
| |
| <li> |
| |
| <a href="../refLib.html" title="Reference Library"> |
| <span class="none"></span> |
| Reference Library</a> |
| </li> |
| |
| <li> |
| |
| <a href="../apidocs/index.html" title="Online Java Docs"> |
| <span class="none"></span> |
| Online Java Docs</a> |
| </li> |
| <li class="nav-header">Get Involved</li> |
| |
| <li> |
| |
| <a href="../overview.html" title="Overview"> |
| <span class="none"></span> |
| Overview</a> |
| </li> |
| |
| <li> |
| |
| <a href="../svn.html" title="Checkout the Source"> |
| <span class="none"></span> |
| Checkout the Source</a> |
| </li> |
| |
| <li> |
| |
| <a href="../mail-lists.html" title="Mailing Lists"> |
| <span class="none"></span> |
| Mailing Lists</a> |
| </li> |
| |
| <li> |
| |
| <a href="../release-process.html" title="Release Process"> |
| <span class="none"></span> |
| Release Process</a> |
| </li> |
| |
| <li> |
| |
| <a href="../guidelines.html" title="Developer Guidelines"> |
| <span class="none"></span> |
| Developer Guidelines</a> |
| </li> |
| |
| <li> |
| |
| <a href="../siteHowTo.html" title="Build the Site"> |
| <span class="none"></span> |
| Build the Site</a> |
| </li> |
| <li class="nav-header">Project Information</li> |
| |
| <li> |
| |
| <a href="../team-list.html" title="Project Team"> |
| <span class="none"></span> |
| Project Team</a> |
| </li> |
| |
| <li> |
| |
| <a href="../issue-tracking.html" title="Issue Tracking"> |
| <span class="none"></span> |
| Issue Tracking</a> |
| </li> |
| |
| <li> |
| |
| <a href="http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/" class="externalLink" title="Source Code"> |
| <span class="none"></span> |
| Source Code</a> |
| </li> |
| |
| <li> |
| |
| <a href="../thanks.html" title="Acknowledgements"> |
| <span class="none"></span> |
| Acknowledgements</a> |
| </li> |
| <li class="nav-header">Apache</li> |
| |
| <li> |
| |
| <a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="License"> |
| <span class="none"></span> |
| License</a> |
| </li> |
| |
| <li> |
| |
| <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"> |
| <span class="none"></span> |
| Sponsorship</a> |
| </li> |
| |
| <li> |
| |
| <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"> |
| <span class="none"></span> |
| Thanks</a> |
| </li> |
| |
| <li> |
| |
| <a href="http://www.apache.org/security/" class="externalLink" title="Security"> |
| <span class="none"></span> |
| Security</a> |
| </li> |
| </ul> |
| |
| |
| |
| <hr /> |
| |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /> |
| </a> |
| </div> |
| </div> |
| </div> |
| |
| |
| <div id="bodyColumn" class="span10" > |
| |
| <!-- ~ 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. --><html xmlns="http://www.w3.org/1999/xhtml"> |
| |
| |
| <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 class="externalLink" 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> |
| |
| <div class="section"> |
| <h2><a name="Content"></a>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> |
| |
| <div class="section"> |
| <h2><a name="Compatibility"></a>Compatibility</h2> |
| |
| <p>Axis1.x and Axis2 have evolved from different architectures.</p> |
| |
| <p><b>Speed</b> - Axis2 is based on the StAX API, which |
| gives greater speed than the SAX event based parsing used in |
| Axis1.x.</p> |
| |
| <p><b>Stability</b> - 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><b>Transport framework</b> - 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><b>WSDL 2.0 support</b> - 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><b>Component-oriented architecture</b> - 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> |
| |
| <div class="section"> |
| <h2><a name="Getting_Started"></a>Getting Started</h2> |
| |
| <p>Let's look at a simple example of echoing at client API.</p> |
| |
| <p><b>Axis 1.x</b></p> |
| |
| <div> |
| <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></div> |
| |
| <p><b>Axis 2</b></p> |
| |
| <div> |
| <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></div> |
| |
| <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> |
| |
| <div class="section"> |
| <h2><a name="Custom_Deployment_of_Services_Handlers_and_Modules"></a>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> |
| |
| <div> |
| <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></div> |
| |
| <p><b>Axis 1.x requires a reference to the handler in the user's |
| WSDD that defines their Web Service:</b></p> |
| |
| <div> |
| <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></div> |
| |
| <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> |
| |
| <div> |
| <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></div> |
| |
| <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> |
| |
| <div> |
| <pre> |
| public class SOAPMonitorHandler extends BasicHandler |
| </pre></div> |
| |
| <p><b>Axis 2 the SOAPMonitorHandler has the class signature |
| as:</b></p> |
| |
| <div> |
| <pre> |
| public class SOAPMonitorHandler extends AbstractHandler |
| </pre></div> |
| |
| <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> |
| |
| <div> |
| <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></div> |
| |
| <p><b>Finally, Axis2 requires you to make some changes to |
| axis2.xml. Start by adding a global module:</b></p> |
| |
| <div> |
| <pre> |
| <module ref="soapmonitor"/> |
| </pre></div> |
| |
| <p><b>Then define your phase orders for the 'soapmonitorPhase' |
| referenced in the module.xml :</b></p> |
| |
| <div> |
| <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></div> |
| |
| <p>See the user guide for more information on Axis2 modules.</p> |
| <a name="transports" id="transports"></a> |
| |
| <div class="section"> |
| <h2><a name="Transports_for_HTTP_Connection"></a>Transports for HTTP Connection</h2> |
| |
| <p>Axis2 comes with the CommonsHTTPTransportSender which is based |
| on commons-httpclient.</p> |
| |
| <p>It should be noted that axis2.xml should be configured to call |
| the commons transports in this manner:</p> |
| |
| <div> |
| <pre> |
| ... |
| <transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"> |
| <parameter name="PROTOCOL">HTTP/1.1</parameter> |
| <parameter name="Transfer-Encoding">chunked</parameter> |
| </transportSender> |
| ... |
| </pre></div> |
| <a name="data_binding" id="data_binding"></a> |
| |
| <div class="section"> |
| <h2><a name="Data_Binding_Support"></a>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> |
| |
| <div> |
| <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></div> |
| |
| <p>The next step is to run WSDL2Java on the wsdl. For axis 1.x, |
| this example uses the following Ant task:</p> |
| |
| <div> |
| <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></div> |
| |
| <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> |
| |
| <div> |
| <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></div> |
| |
| <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> |
| |
| <div> |
| <pre> |
| <soap:address location="http://localhost:8080/axis2/services/SimpleEndpoint"/></port></service></definitions> |
| </pre></div> |
| |
| <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> |
| |
| <div> |
| <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></div> |
| |
| <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> |
| |
| <div> |
| <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></div> |
| |
| <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> |
| |
| <div> |
| <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></div> |
| |
| <p>To:</p> |
| |
| <div> |
| <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></div> |
| |
| <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> |
| |
| <div> |
| <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></div> |
| |
| <p>To:</p> |
| |
| <div> |
| <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></div> |
| |
| <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> |
| |
| <div> |
| <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></div> |
| |
| <p>Finally, our Axis2 client for this example is:</p> |
| |
| <div> |
| <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></div> |
| |
| <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> |
| |
| <div class="section"> |
| <h2><a name="Best_Usage"></a>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> |
| |
| </html> |
| </div> |
| </div> |
| </div> |
| |
| <hr/> |
| |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p >Copyright © 2004–2016 |
| <a href="http://www.apache.org/">The Apache Software Foundation</a>. |
| All rights reserved. |
| |
| </p> |
| </div> |
| |
| |
| </div> |
| </footer> |
| </body> |
| </html> |