You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by di...@apache.org on 2008/05/01 23:20:38 UTC
svn commit: r652665 [10/45] - in /webservices/axis2/site: ./ 1_4/ 1_4/adb/
1_4/adb/images/ 1_4/images/ 1_4/images/archi-guide/ 1_4/images/userguide/
1_4/jibx/ 1_4/src/ css/ download/0_9/ download/0_91/ download/0_92/
download/0_93/ download/0_94/ downl...
Added: webservices/axis2/site/1_4/migration.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4/migration.html?rev=652665&view=auto
==============================================================================
--- webservices/axis2/site/1_4/migration.html (added)
+++ webservices/axis2/site/1_4/migration.html Thu May 1 14:20:27 2008
@@ -0,0 +1,983 @@
+<!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>
+ <title>Maven - </title>
+ <style type="text/css" media="all">
+ @import url("../css/maven-base.css");
+ @import url("../css/maven-theme.css");
+ @import url("../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="../" id="bannerLeft">
+
+ <img src="http://www.apache.org/images/asf_logo_wide.png" alt="" />
+
+ </a>
+ <span id="bannerRight">
+
+ <img src="../../images/axis.jpg" alt="" />
+
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+
+
+
+
+
+
+ <div class="xleft">
+ Last Published: 2008-05-01
+ </div>
+ <div class="xright"> <a href="../index.html">Axis2/Java</a>
+ |
+ <a href="../../c">Axis2/C</a>
+ |
+ <a href="../../..">Apache WS</a>
+ |
+ <a href="http://www.apache.org" class="externalLink">Apache</a>
+
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+
+
+
+
+
+
+ <h5>Axis2/Java</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../index.html">Home</a>
+ </li>
+ </ul>
+ <h5>Downloads</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../download.cgi">Releases</a>
+ </li>
+
+ <li class="none">
+ <a href="../modules/index.html">Modules</a>
+ </li>
+
+ <li class="none">
+ <a href="../tools/index.html">Tools</a>
+ </li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="../1_4/contents.html">Version 1.4</a>
+ <ul>
+
+ <li class="none">
+ <a href="../1_4/toc.html">Table of Contents</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/installationguide.html">Installation Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/quickstartguide.html">QuickStart Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/userguide.html">User Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/jaxws-guide.html">JAXWS Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/pojoguide.html">POJO Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/spring.html">Spring Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/webadminguide.html">Web Administrator's Guide</a>
+ </li>
+
+ <li class="none">
+ <strong>Migration Guide (from Axis1)</strong>
+ </li>
+ </ul>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/contents.html">Version 1.3</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_2/contents.html">Version 1.2</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_1_1/contents.html">Version 1.1.1</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_1/contents.html">Version 1.1</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_0/index.html">Version 1.0</a>
+ </li>
+
+ <li class="none">
+ <a href="../0_95/index.html">Version 0.95</a>
+ </li>
+
+ <li class="none">
+ <a href="../0_94/index.html">Version 0.94</a>
+ </li>
+
+ <li class="none">
+ <a href="../0_93/index.html">Version 0.93</a>
+ </li>
+ </ul>
+ <h5>Resources</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../faq.html">FAQ</a>
+ </li>
+
+ <li class="none">
+ <a href="../articles.html">Articles</a>
+ </li>
+
+ <li class="none">
+ <a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink">Wiki</a>
+ </li>
+
+ <li class="none">
+ <a href="../refLib.html">Reference Library</a>
+ </li>
+
+ <li class="none">
+ <a href="../../1_4/api/index.html">Online Java Docs</a>
+ </li>
+ </ul>
+ <h5>Get Involved</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../overview.html">Overview</a>
+ </li>
+
+ <li class="none">
+ <a href="../svn.html">Checkout the Source</a>
+ </li>
+
+ <li class="none">
+ <a href="../mail-lists.html">Mailing Lists</a>
+ </li>
+
+ <li class="none">
+ <a href="../release-process.html">Release Process</a>
+ </li>
+
+ <li class="none">
+ <a href="../guidelines.html">Developer Guidelines</a>
+ </li>
+
+ <li class="none">
+ <a href="../siteHowTo.html">Build the Site</a>
+ </li>
+ </ul>
+ <h5>Project Information</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../team-list.html">Project Team</a>
+ </li>
+
+ <li class="none">
+ <a href="../issue-tracking.html">Issue Tracking</a>
+ </li>
+
+ <li class="none">
+ <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink">Source Code</a>
+ </li>
+
+ <li class="none">
+ <a href="../thanks.html">Acknowledgements</a>
+ </li>
+
+ <li class="none">
+ <a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink">License</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+ </a>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <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="">Migrating from Axis 1.x<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></head><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:axis-user@ws.apache.org?subject=[Axis2]">axis-user@ws.apache.org</a>
+</i>
+.
+(Subscription details are available on the <a class="externalLink" 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 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"></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"></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"></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 in this manner:</p>
+<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><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. 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/1_4/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"></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>
+</html>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">©
+ 2004-2008
+
+ Apache Software Foundation
+
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Added: webservices/axis2/site/1_4/modules.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_4/modules.html?rev=652665&view=auto
==============================================================================
--- webservices/axis2/site/1_4/modules.html (added)
+++ webservices/axis2/site/1_4/modules.html Thu May 1 14:20:27 2008
@@ -0,0 +1,642 @@
+<!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>
+ <title>Maven - </title>
+ <style type="text/css" media="all">
+ @import url("../css/maven-base.css");
+ @import url("../css/maven-theme.css");
+ @import url("../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="../" id="bannerLeft">
+
+ <img src="http://www.apache.org/images/asf_logo_wide.png" alt="" />
+
+ </a>
+ <span id="bannerRight">
+
+ <img src="../../images/axis.jpg" alt="" />
+
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+
+
+
+
+
+
+ <div class="xleft">
+ Last Published: 2008-05-01
+ </div>
+ <div class="xright"> <a href="../index.html">Axis2/Java</a>
+ |
+ <a href="../../c">Axis2/C</a>
+ |
+ <a href="../../..">Apache WS</a>
+ |
+ <a href="http://www.apache.org" class="externalLink">Apache</a>
+
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+
+
+
+
+
+
+ <h5>Axis2/Java</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../index.html">Home</a>
+ </li>
+ </ul>
+ <h5>Downloads</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../download.cgi">Releases</a>
+ </li>
+
+ <li class="none">
+ <a href="../modules/index.html">Modules</a>
+ </li>
+
+ <li class="none">
+ <a href="../tools/index.html">Tools</a>
+ </li>
+ </ul>
+ <h5>Documentation</h5>
+ <ul>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="../1_4/contents.html">Version 1.4</a>
+ <ul>
+
+ <li class="none">
+ <a href="../1_4/toc.html">Table of Contents</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/installationguide.html">Installation Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/quickstartguide.html">QuickStart Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/userguide.html">User Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/jaxws-guide.html">JAXWS Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/pojoguide.html">POJO Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/spring.html">Spring Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/webadminguide.html">Web Administrator's Guide</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_4/migration.html">Migration Guide (from Axis1)</a>
+ </li>
+ </ul>
+ </li>
+
+ <li class="none">
+ <a href="../1_3/contents.html">Version 1.3</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_2/contents.html">Version 1.2</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_1_1/contents.html">Version 1.1.1</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_1/contents.html">Version 1.1</a>
+ </li>
+
+ <li class="none">
+ <a href="../1_0/index.html">Version 1.0</a>
+ </li>
+
+ <li class="none">
+ <a href="../0_95/index.html">Version 0.95</a>
+ </li>
+
+ <li class="none">
+ <a href="../0_94/index.html">Version 0.94</a>
+ </li>
+
+ <li class="none">
+ <a href="../0_93/index.html">Version 0.93</a>
+ </li>
+ </ul>
+ <h5>Resources</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../faq.html">FAQ</a>
+ </li>
+
+ <li class="none">
+ <a href="../articles.html">Articles</a>
+ </li>
+
+ <li class="none">
+ <a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink">Wiki</a>
+ </li>
+
+ <li class="none">
+ <a href="../refLib.html">Reference Library</a>
+ </li>
+
+ <li class="none">
+ <a href="../../1_4/api/index.html">Online Java Docs</a>
+ </li>
+ </ul>
+ <h5>Get Involved</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../overview.html">Overview</a>
+ </li>
+
+ <li class="none">
+ <a href="../svn.html">Checkout the Source</a>
+ </li>
+
+ <li class="none">
+ <a href="../mail-lists.html">Mailing Lists</a>
+ </li>
+
+ <li class="none">
+ <a href="../release-process.html">Release Process</a>
+ </li>
+
+ <li class="none">
+ <a href="../guidelines.html">Developer Guidelines</a>
+ </li>
+
+ <li class="none">
+ <a href="../siteHowTo.html">Build the Site</a>
+ </li>
+ </ul>
+ <h5>Project Information</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../team-list.html">Project Team</a>
+ </li>
+
+ <li class="none">
+ <a href="../issue-tracking.html">Issue Tracking</a>
+ </li>
+
+ <li class="none">
+ <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink">Source Code</a>
+ </li>
+
+ <li class="none">
+ <a href="../thanks.html">Acknowledgements</a>
+ </li>
+
+ <li class="none">
+ <a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink">License</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+ </a>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <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="">Writing your Own Axis2 Module<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all"></head><a name="Modules"></a>
+<h1>Writing Your Own Axis2 Module</h1><p>Axis2 provides extended support for modules (See the <a href="Axis2ArchitectureGuide.html">Architecture
+Guide</a>
+ for more details about modules in Axis2). Let's create a
+custom module and deploy it to MyService, which we created
+earlier.</p>
+<p>Send your feedback or questions to: <a class="externalLink" href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a>
+.
+( Subscription details are available on the <a class="externalLink" href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>
+.)
+Kindly prefix subject with [Axis2].</p>
+<h2>Content List</h2><ul><li><a href="#MyService_with_a_Logging_Module">MyService with a
+Logging Module</a>
+<ul><li><a href="#Step1_:_LoggingModule_Class">Step1 : LoggingModule
+Class</a>
+</li>
+<li><a href="#Step2_:_LogHandler">Step2 : LogHandler</a>
+</li>
+<li><a href="#Step3_:_module_xml">Step3 : module.xml</a>
+</li>
+<li><a href="#Step_4:_Modify_the_"axis2_xml"">Step4:
+Modify the "axis2.xml"</a>
+</li>
+<li><a href="#Step5_:_Modify_the_"services_xml"">Step5 :
+Modify the "services.xml</a>
+</li>
+<li><a href="#Step6_:_Packaging">Step6 : Packaging</a>
+</li>
+<li><a href="#Step7_:_Deploy_the_Module_in_Axis2">Step7 : Deploy
+the Module in Axis2</a>
+</li>
+</ul>
+</li>
+</ul>
+<p>The following steps show the actions that need to be performed
+to deploy a custom module for a given Web service:</p>
+<ol type="1"><li>Create the Module Implementation</li>
+<li>Create the Handlers</li>
+<li>Create the module.xml</li>
+<li>Modify the "axis2.xml" (if you need
+custom phases)</li>
+<li>Modify the "services.xml" to engage
+modules at the deployment time.</li>
+<li>Package in a ".mar" (Module
+Archive)</li>
+<li>Deploy the module in Axis2</li>
+</ol>
+<a name="MyService_with_a_Logging_Module"></a>
+<h3>MyService with a Logging Module</h3><p>Let's write a simple logging module for our sample located at
+the <b>"samples\userguide\src"</b>
+ directory of the binary
+distribution. This module contains one handler that just logs the
+message that is passed through it. Axis2 uses ".mar" (Module
+Archive) to deploy modules in Axis2. The following diagram shows
+the file structure inside which needs to be there in the ".mar"
+archive. Let's create all these and see how it works.</p>
+<p><img src="images/userguide/ModuleView.jpg" /></p>
+<a name="Step1_:_LoggingModule_Class"></a>
+<h4>Step1 : LoggingModule Class</h4>
+<p>LoggingModule is the implementation class of the Axis2 module.
+Axis2 modules should implement the "<a class="externalLink" href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/modules/Module.java?rev=396785&view=log">org.apache.axis2.modules.Module</a>
+"
+interface with the following methods.</p>
+<pre>
+public void init(ConfigurationContext configContext, AxisModule module) throws AxisFault;//Initialize the module
+public void shutdown(ConfigurationContext configurationContext) throws AxisFault;//End of module processing
+public void engageNotify(AxisDescription axisDescription) throws AxisFault;
+public String[] getPolicyNamespaces() throws AxisFault;
+public void applyPolicy(Policy policy, AxisDescription axisDescription) throws AxisFault ;
+public boolean canSupportAssertion(Assertion assertion) ;
+</pre><p>The first three methods can be used to control the module
+initialization and the termination, and the next three methods are
+used to perform policy related operations. With the input parameter
+AxisConfiguration, the user is provided with the complete
+configuration hierarchy. This can be used to fine-tune the module
+behavior by the module writers. For a simple logging service, we
+can keep these methods blank in our implementation class.</p>
+<a name="Step2_:_LogHandler"></a>
+<h4>Step2 : LogHandler</h4>
+<p>A module in Axis2 can contain, one or more handlers that perform
+various SOAP header processing at different phases. (See the
+<a href="Axis2ArchitectureGuide.html#incomingsoap">Architecture Guide</a>
+ for more information on phases). To
+write a handler one should implement <a class="externalLink" href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/engine/Handler.java?rev=357187&view=log">
+org.apache.axis2.engine.Handler</a>
+. But for convenience, <a class="externalLink" href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/handlers/AbstractHandler.java?rev=396788&view=log">
+org.apache.axis2.handlers.AbstractHandler</a>
+ provides an abstract
+implementation of the Handler interface.</p>
+<p>For the logging module, we will write a handler with the
+following methods. "public void invoke(MessageContext ctx);" is the
+method that is called by the Axis2 engine when the control is
+passed to the handler. "public void revoke(MessageContext ctx);" is
+called when the handlers are revoked by the Axis2 engine.</p>
+<pre>
+public class LogHandler extends AbstractHandler implements Handler {
+ private static final Log log = LogFactory.getLog(LogHandler.class);
+ private String name;
+
+ public String getName() {
+ return name;
+ }
+
+ public InvocationResponse invoke(MessageContext msgContext) throws AxisFault {
+ log.info(msgContext.getEnvelope().toString());
+ return InvocationResponse.CONTINUE;
+ }
+
+ public void revoke(MessageContext msgContext) {
+ log.info(msgContext.getEnvelope().toString());
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+}
+</pre><a name="Step3_:_module_xml"></a>
+<h4>Step3 : module.xml</h4>
+<p>"module.xml" contains the deployment configurations for a
+particular module. It contains details such as the Implementation
+class of the module (in this example it is the "LoggingModule"
+class and various handlers that will run in different phases). The
+"module.xml" for the logging module will be as follows:</p>
+<pre>
+<module name="logging" class="userguide.loggingmodule.LoggingModule">
+ <InFlow>
+ <handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase" />
+ </handler>
+ </InFlow>
+
+ <OutFlow>
+ <handler name="OutFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
+ </OutFlow>
+
+ <OutFaultFlow>
+ <handler name="FaultOutFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
+ </OutFaultFlow>
+
+ <InFaultFlow>
+ <handler name="FaultInFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
+ </InFaultFlow>
+</module>
+</pre><p>As you can see, there are four flows defined in the
+"module.xml"</p>
+<ol type="1"><li>InFlow Represents the handler chain that will run when a
+message is coming in.</li>
+<li>OutFlow Represents the handler chain
+that will run when the message is going out.</li>
+<li>OutFaultFlow - Represents the handler
+chain that will run when there is a fault, and the fault is going
+out.</li>
+<li>InFaultFlow - Represents the handler chain that will run when
+there is a fault, and the fault is coming in.</li>
+</ol>
+<p>The following set of tags describe the name of the handler,
+handler class, and the phase in which this handler is going to run.
+"InFlowLogHandler" is the name given for the particular instance of
+this handler class. The value of the class attribute is the actual
+implementation class for this handler. Since we are writing a
+logging handler, we can reuse the same handler in all these phases.
+However, this may not be the same for all the modules. "<order
+phase="loggingPhase" />" describes the phase in which this
+handler runs.</p>
+<pre>
+<handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+<order phase="loggingPhase" />
+</handler>
+</pre><p>To learn more about Phase rules, check out the article <a class="externalLink" href="http://www.developer.com/java/web/article.php/3529321">Axis2 Execution Framework</a>
+</p>
+<a name="Step_4:_Modify_the_axis2_xml"></a>
+<h4>Step 4: Modify the "axis2.xml"</h4>
+<p>In this handler, the "loggingPhase", is defined by the module
+writer. It is not a pre-defined handler phase, hence the module
+writer should introduce it to the "axis2.xml" (NOT the
+services.xml) so that the Axis2 engine knows where to place the
+handler in different "flows" (inFlow, outFlow, etc.). The following
+XML lines show the respective changes made to the "axis2.xml" in
+order to deploy the logging module in the Axis2 engine. This is an
+extract of the phase section of "axis2.xml".</p>
+<pre>
+<!-- ================================================= -->
+<!-- Phases -->
+<!-- ================================================= -->
+
+<phaseOrder type="inflow">
+ <!-- System pre defined 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="PostDispatch"/>
+ </handler>
+ </phase>
+ <!-- System pre defined phases -->
+ <!-- After Postdispatch phase module author or service author can add any phase he wants -->
+ <phase name="OperationInPhase"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
+ </phaseOrder>
+ <phaseOrder type="outflow">
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationOutPhase"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
+ <!--system predefined phases-->
+ <!--these phases will run irrespective of the service-->
+ <phase name="PolicyDetermination"/>
+ <phase name="MessageOut"/>
+ </phaseOrder/>
+ <phaseOrder type="INfaultflow">
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationInFaultPhase"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
+ </phaseOrder>
+ <phaseOrder type="Outfaultflow">
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationOutFaultPhase"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
+ <phase name="PolicyDetermination"/>
+ <phase name="MessageOut"/>
+ </phaseOrder>
+
+</pre><p>The text in green, the custom phase "loggingPhase" is placed in
+all the flows, hence that phase will be called in all the message
+flows in the engine. Since our module is associated with this
+phase, the LogHandler inside the module will now be executed in
+this phase.</p>
+<a name="Step5_:_Modify_the_services_xml"></a>
+<h4>Step5 : Modify the "services.xml"</h4>
+<p>Up to this point, we have created the required classes and
+configuration descriptions for the logging module, and by changing
+the "axis2.xml" we created the required phases for the logging
+module.</p>
+<p>Next step is to "<b>engage</b>
+" (use) this module in one of our
+services. For this, let's use the same Web service that we have
+used throughout the user's guide- MyService. However, since we need
+to modify the "services.xml" of MyService in order to engage this
+module, we use a separate Web service, but with similar
+operations.</p>
+<p>The code for this service can be found in the
+"<strong>Axis2_HOME/samples/userguide/src/userguide/example2</strong>"
+directory. The simple changes that we have done to "services.xml'
+are shown in green in the following lines of xml.</p>
+<pre>
+<service name="<span style="color: rgb(36, 193, 19);">MyServiceWithModule</span>">
+ <description>
+ This is a sample Web service with a logging module engaged.
+ </description>
+ <span style="color: rgb(36, 193, 19);"><module ref="logging"/></span>
+ <parameter name="ServiceClass" locked="xsd:false">userguide.example2.MyService</parameter>
+ <operation name="echo">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+ <operation name="ping">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+</service>
+</pre><p>In this example, we have changed the service name (the
+implementation class is very similar to what we have used earlier,
+although it is in a different package). In addition we have added
+the line <b>"<module ref="logging"/>"</b>
+ to "services.xml".
+This informs the Axis2 engine that the module "logging" should be
+engaged for this service. The handler inside the module will be
+executed in their respective phases as described by the
+"module.xml".</p>
+<a name="Step6_:_Packaging"></a>
+<h4>Step6 : Packaging</h4>
+<p>Before deploying the module, we need to create the ".mar" file
+for this module. This can be done, using the "jar" command and then
+renaming the created .jar file. Else, you can find the
+"logging.mar" that has already been created in the
+"<strong>Axis2_HOME/samples/userguide</strong>" directory.</p>
+<a name="Step7_:_Deploy_the_Module_in_Axis2"></a>
+<h4>Step7 : Deploy the Module in Axis2</h4>
+<p>Deploying a module in Axis2 requires the user to create a
+directory with the name "modules" in the "webapps/axis2/WEB-INF"
+directory of their servlet container, and then copying the ".mar"
+file to that directory. So let's first create the "modules"
+directory and drop the "logging.mar" into this directory.</p>
+<p>Although the required changes to the "services.xml" is very
+little, we have created a separate service archive
+(MyServiceWithModule.aar) for users to deploy the service..</p>
+<p>Deploy this service using the same steps used in the <a href="adv-userguide.html#Step5_Deploy_web_service">'Step 4: Deploy Web
+Service'</a>
+ sub section in '<a href="userguide.html#ws_codegen">Writing a New Service using
+Codegeneration</a>
+', and copy the "logging.mar" file to the
+"modules" directory.</p>
+<p>Then run 'ant run.client.servicewithmodule' from
+<strong>axis2home/samples/userguide directory</strong></p>
+<p>Note: To see the logs, the user needs to modify the
+"log4j.properties" to log INFO. The property file is located in
+"<strong>webapps/axis2/WEB-INF/classes</strong>" of your servlet
+container. Change the line "log4j.rootCategory= ERROR, LOGFILE" to
+"log4j.rootCategory=INFO, ERROR, LOGFILE".</p>
+<p><font size="2"><b>Note (on samples):</b>
+</font> All the samples
+mentioned in the user's guide are located at the
+<b>"samples\userguide\src"</b>
+ directory of the binary
+distribution.</p>
+</html>
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">©
+ 2004-2008
+
+ Apache Software Foundation
+
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org