You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by de...@apache.org on 2007/04/27 14:39:46 UTC
svn commit: r533081 [7/23] - in /webservices/axis2/site: ./ 1_2/ 1_2/adb/
1_2/adb/images/ 1_2/images/ 1_2/images/archi-guide/ 1_2/images/userguide/
1_2/jibx/ 1_2/resources/ 1_2/resources/schemas/ 1_2/src/ css/ download/0_9/
download/0_91/ download/0_92...
Added: webservices/axis2/site/1_2/migration.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_2/migration.html?view=auto&rev=533081
==============================================================================
--- webservices/axis2/site/1_2/migration.html (added)
+++ webservices/axis2/site/1_2/migration.html Fri Apr 27 05:39:33 2007
@@ -0,0 +1,646 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/Java - Migrating from Axis 1.x</title><style type="text/css" media="all">
+ @import url("../style/maven-base.css");
+
+ @import url("../style/maven-theme.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Apache Axis2" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 27 April 2007
+ | Doc for 1.2</div><div class="xright">
+
+ <a href="../index.html">Axis2/Java</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org/axis2/c" class="externalLink" title="External Link">Axis2/C</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org" class="externalLink" title="External Link">Apache WS</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://www.apache.org" class="externalLink" title="External Link">Apache </a>
+ </div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_Java"><h5>Axis2/Java</h5><ul><li class="none"><a href="../index.html">Home</a></li></ul></div><div id="menuDownloads"><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></div><div id="menuDocumentation"><h5>Documentation</h5><ul><li class="expanded"><a href="../1_2/contents.html">Version 1.2</a><ul><li class="none"><a href="../1_2/toc.html">Table of Contents</a></li><li class="none"><a href="../1_2/installationguide.html">Installation Guide</a></li><li class="none"><a href="../1_2/quickstartguide.html">QuickStart Guide</a></li><li class="none"><a href="../1_2/userguide.html">User Guide</a></li><li class="none"><a href="../1_2/pojoguide.html">POJO Guide</a></li><li class="none"><a href="../1_2/spring.html">
Spring Guide</a></li><li class="none"><a href="../1_2/webadminguide.html">Web Administrator's Guide</a></li><li class="none"><a href="../1_2/migration.html">Migration Guide (from Axis1)</a></li></ul></li><li class="none"><a href="../1_1_1/index.html">Version 1.0</a></li><li class="none"><a href="../1_1/index.html">Version 1.0</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></div><div id="menuResources"><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" title="External Link">Wiki</a></li><li class="none"><a href="../refLib.html">Reference Library</a></li><li class="none"><a href
="http://ws.apache.org/axis2/1_2/api/index.html" class="externalLink" title="External Link">Online Java Docs</a></li></ul></div><div id="menuGet_Involved"><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="../guidelines.html">Developer Guidelines</a></li><li class="none"><a href="../siteHowTo.html">Build the Site</a></li></ul></div><div id="menuProject_Information"><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" title="External Link">Source Code</a></li><li class="none"><a href="../thanks.html">Acknowledgements</a></li><li class="none"><a hr
ef="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="External Link">License</a></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Migrating_from_Apache_Axis_1_x_to_Axis2"></a><h2>Migrating from Apache Axis 1.x to Axis2</h2><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" class="externalLink" title="External Link">Axis2 site</a>.) Kindly
+prefix subject with [Axis2]. </p><div class="subsection"><a name="Content"></a><h3>Content</h3><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><p><a name="comp"></a></p></div><div class="subsection"><a name="Compatibility"></a><h3>Compatibility</h3><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><p><a name="start"></a></p></div><div class="subsection"><a name="Getting_Started"></a><h3>Getting Started</h3><p>Let's look at a simple example of echoing at client API.</p><p><b>Axis 1.x</b></p>
+ <div class="source"><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 class="source"><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></div>
+ <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><p><a name="custom_deployment"></a></p></div><div class="subsection"><a name="Custom_Deployment_of_Services__Handlers__and_Modules"></a><h3>Custom Deployment of Services, Handlers, and Modules</h3><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>
+ <div class="source"><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 class="source"><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 class="source"><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 class="source"><pre>public class SOAPMonitorHandler extends BasicHandler
+
+</pre></div>
+ <p><b>Axis 2 the SOAPMonitorHandler has the class signature as:</b></p>
+ <div class="source"><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 class="source"><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></div>
+ <p><b>Finally, Axis2 requires you to make some changes to axis2.xml. Start by
+adding a global module:</b></p>
+ <div class="source"><pre> <module ref="soapmonitor"/>
+
+</pre></div>
+ <p><b>Then define your phase orders for the 'soapmonitorPhase' referenced in
+the module.xml :</b></p>
+ <div class="source"><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></div>
+ <p>See the user guide for more information on Axis2 modules.</p><p><a name="transports"></a></p></div><div class="subsection"><a name="Transports_for_HTTP_Connection"></a><h3>Transports for HTTP Connection</h3><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>
+ <div class="source"><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></div>
+ <p><a name="data_binding"></a></p></div><div class="subsection"><a name="Data_Binding_Support"></a><h3>Data Binding Support</h3><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>
+ <div class="source"><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 class="source"><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 class="source"><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 class="source"><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 and JaxMe
+are also supported. This example uses XMLBeans. For Axis2, our example uses
+the following Ant task:</p>
+ <div class="source"><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/1_2/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 class="source"><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 class="source"><pre>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 class="source"><pre>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 class="source"><pre>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 class="source"><pre>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></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 the client. Our Axis 1.x client for this example is:</p>
+ <div class="source"><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 class="source"><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><p><a name="best"></a></p></div><div class="subsection"><a name="Best_Usage"></a><h3>Best Usage</h3><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></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/axis2/site/1_2/modules.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_2/modules.html?view=auto&rev=533081
==============================================================================
--- webservices/axis2/site/1_2/modules.html (added)
+++ webservices/axis2/site/1_2/modules.html Fri Apr 27 05:39:33 2007
@@ -0,0 +1,293 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/Java - Writing your Own Axis2 Module</title><style type="text/css" media="all">
+ @import url("../style/maven-base.css");
+
+ @import url("../style/maven-theme.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Apache Axis2" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 27 April 2007
+ | Doc for 1.2</div><div class="xright">
+
+ <a href="../index.html">Axis2/Java</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org/axis2/c" class="externalLink" title="External Link">Axis2/C</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org" class="externalLink" title="External Link">Apache WS</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://www.apache.org" class="externalLink" title="External Link">Apache </a>
+ </div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_Java"><h5>Axis2/Java</h5><ul><li class="none"><a href="../index.html">Home</a></li></ul></div><div id="menuDownloads"><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></div><div id="menuDocumentation"><h5>Documentation</h5><ul><li class="expanded"><a href="../1_2/contents.html">Version 1.2</a><ul><li class="none"><a href="../1_2/toc.html">Table of Contents</a></li><li class="none"><a href="../1_2/installationguide.html">Installation Guide</a></li><li class="none"><a href="../1_2/quickstartguide.html">QuickStart Guide</a></li><li class="none"><a href="../1_2/userguide.html">User Guide</a></li><li class="none"><a href="../1_2/pojoguide.html">POJO Guide</a></li><li class="none"><a href="../1_2/spring.html">
Spring Guide</a></li><li class="none"><a href="../1_2/webadminguide.html">Web Administrator's Guide</a></li><li class="none"><a href="../1_2/migration.html">Migration Guide (from Axis1)</a></li></ul></li><li class="none"><a href="../1_1_1/index.html">Version 1.0</a></li><li class="none"><a href="../1_1/index.html">Version 1.0</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></div><div id="menuResources"><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" title="External Link">Wiki</a></li><li class="none"><a href="../refLib.html">Reference Library</a></li><li class="none"><a href
="http://ws.apache.org/axis2/1_2/api/index.html" class="externalLink" title="External Link">Online Java Docs</a></li></ul></div><div id="menuGet_Involved"><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="../guidelines.html">Developer Guidelines</a></li><li class="none"><a href="../siteHowTo.html">Build the Site</a></li></ul></div><div id="menuProject_Information"><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" title="External Link">Source Code</a></li><li class="none"><a href="../thanks.html">Acknowledgements</a></li><li class="none"><a hr
ef="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="External Link">License</a></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><p><a name="Modules"></a></p></div><div class="section"><a name="Writing_Your_Own_Axis2_Module"></a><h2>Writing Your Own Axis2 Module</h2><p>Axis2 provides extended support for modules (See the <a href="Axis2ArchitectureGuide.html" class="newWindow" title="New Window" target="_blank">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 href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a>.
+( Subscription details are available on the <a href="http://ws.apache.org/axis2/mail-lists.html" class="externalLink" title="External Link">Axis2 site</a>.) Kindly
+prefix subject with [Axis2].</p><div class="subsection"><a name="Content_List"></a><h3>Content List</h3><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>
+ <li><p style="margin-bottom: 0in">Create the Module Implementation</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Create the Handlers</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Create the module.xml</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Modify the "axis2.xml" (if you need
+ custom phases)</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Modify the "services.xml" to engage
+ modules at the deployment time.</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Package in a ".mar" (Module Archive)</p>
+ </li>
+ <li><p>Deploy the module in Axis2</p>
+ </li>
+</ol><p><a name="MyService_with_a_Logging_Module"></a></p></div><div class="subsection"><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" name="Graphic5" align="bottom" border="0" alt=""></img></p><p><a name="Step1_:_LoggingModule_Class"></a></p></div><div class="subsection"><a name="Step1_:_LoggingModule_Class"></a><h3>Step1 : LoggingModule Class</h3><p>LoggingModule is the implementation class of the Axis2 module. Axis2
+modules should implement the "<a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/modules/Module.java?rev=396785&view=log" class="externalLink" title="External Link">org.apache.axis2.modules.Module</a>"
+interface with the following methods.</p>
+ <div class="source"><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></div>
+ <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><p><a name="Step2_:_LogHandler"></a></p></div><div class="subsection"><a name="Step2_:_LogHandler"></a><h3>Step2 : LogHandler</h3><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" class="newWindow" title="New Window" target="_blank"> Architecture
+Guide</a> for more information on phases). To write a handler one should
+implement <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/engine/Handler.java?rev=357187&view=log" class="externalLink" title="External Link">org.apache.axis2.engine.Handler</a>.
+But for convenience, <a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/handlers/AbstractHandler.java?rev=396788&view=log" class="externalLink" title="External Link">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>
+ <div class="source"><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></div>
+ <p><a name="Step3_:_module_xml"></a></p></div><div class="subsection"><a name="Step3_:_module_xml"></a><h3>Step3 : module.xml</h3><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>
+ <div class="source"><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></div>
+ <p>As you can see, there are four flows defined in the "module.xml"</p><ol>
+ <li>inflow - Represents the handler chain that will run when a message is
+ coming in. </li>
+ <li><p style="margin-bottom: 0in">outflow - Represents the handler chain
+ that will run when the message is going out. </p>
+ </li>
+ <li><p style="margin-bottom: 0in">Outfaultflow - Represents the handler
+ chain that will run when there is a fault, and the fault is going out.</p>
+ </li>
+ <li><p>INfaultflow - Represents the handler chain that will run when there
+ is a fault, and the fault is coming in. </p>
+ </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>
+ <div class="source"><pre><handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+<order phase="loggingPhase" />
+</handler>
+
+</pre></div>
+ <p>To learn more about Phase rules, check out the article <a href="http://www.developer.com/java/web/article.php/3529321" class="newWindow" title="New Window" target="_blank">Axis2 Execution Framework</a></p><p><a name="Step_4:_Modify_the_"axis2_xml""></a></p></div><div class="subsection"><a name="Step_4:_Modify_the_"axis2_xml""></a><h3>Step 4: Modify the "axis2.xml"</h3><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><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.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="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><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><p><a name="Step5_:_Modify_the_"services_xml""></a></p></div><div class="subsection"><a name="Step5_:_Modify_the_"services_xml""></a><h3>Step5 : Modify the "services.xml"</h3><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><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><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><p><a name="Step6_:_Packaging"></a></p></div><div class="subsection"><a name="Step6_:_Packaging"></a><h3>Step6 : Packaging</h3><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><p><a name="Step7_:_Deploy_the_Module_in_Axis2"></a></p></div><div class="subsection"><a name="Step7_:_Deploy_the_Module_in_Axis2"></a><h3>Step7 : Deploy the Module in Axis2</h3><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></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org