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 ch...@apache.org on 2007/05/25 10:09:37 UTC
svn commit: r541579 [6/18] - in /webservices/axis2/trunk/java/xdocs: ./
@axis2_version_dir@/ @axis2_version_dir@/adb/
@axis2_version_dir@/adb/images/ @axis2_version_dir@/images/
@axis2_version_dir@/images/archi-guide/ @axis2_version_dir@/images/usergui...
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/mail-transport.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/mail-transport.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/mail-transport.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/mail-transport.html Fri May 25 01:09:03 2007
@@ -0,0 +1,221 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Invoking a service using mail</title>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
+</head>
+
+<body>
+<h1>Invoking a Service Using a Mail Transport</h1>
+
+<p>This document explains how to invoke a service through Mail transports.</p>
+
+<p><i>Send your feedback or questions to: <a
+href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a></i>.
+(Subscription details are available on the <a
+href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.) Kindly
+prefix subject with [Axis2].</p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#prologue">Prologue</a></li>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#axis2">Using Simple Mail Server Included in Axis2</a></li>
+ <li><a href="#generic">Using a Generic Mail Server</a></li>
+ <!--li><a href="#mailet">Calling Axis Through a James Mailet</a></li-->
+</ul>
+<a name="prologue"></a>
+
+<h2>Prologue</h2>
+
+<p>Most of the Web services that we interact with are synchronous and
+request-response in nature. However, we see that the synchronous
+request-response type of interaction is only a part of the messaging
+scenarios we encounter in real life. Asynchronous messaging is very important
+in constructing loosely coupled systems. Take for instance a chain of stores.
+At the end of the day, all the stores can send a mail to the central system
+telling it about that day's business activities, and when the store opens in
+the morning, there will be a reply to that mail with new instructions and
+updates. It is a lot like the way old businesses worked, but with a modern
+touch. Similarly, the Axis2 mail transport can be used to implement
+asynchronous messaging through mail.</p>
+<a name="intro"></a>
+
+<h2>Introduction</h2>
+
+<p>First, you need to go through the <a href="mail-configuration.html"
+target="_blank">Mail Transport Configuration</a> document. It provides first
+hand experience in setting up the mail transports to operate with Axis2.</p>
+
+<p>Broadly speaking, there are three ways of calling a service through
+mail.</p>
+
+<blockquote>
+ 1. Using the simple mail server included in Axis2 (not recommended in
+ production).<br>
+ 2. Using a generic mail server.<br>
+ 3. Using mailets.<br>
+</blockquote>
+
+<p>Options 1 and 2 are fairly simple and easy to implement, whereas option 3
+is somewhat harder. The mailet scenario however does provide a more robust
+and useful solution in a production environment.</p>
+
+<p>It is very easy to start learning the workings of mail transports with the
+aid of the Simple Mail Server that is provided with Axis2. Once you get the
+hang of Axis2 related issues, then you can move on to tackle the mail beast.
+Please do note that the Simple Mail Server provided with Axis2 is not graded
+for production use.</p>
+<a name="axis2"></a>
+
+<h2>1. Using the Simple Mail Server Included in Axis2</h2>
+
+<p>The SMTP/POP server that we have included has the ability to function as a
+standalone SMTP/POP server and also has the ability to work as a mailet. All
+this is done through a small filter that keeps watch for certain
+pre-configured email addresses. These pre-configured email addresses can be
+changed by doing a simple edit of the filter class
+org.apache.axis2.transport.mail.server.Sorter.</p>
+
+<p>Now that we have the environment set up, we can use the code below to get
+the mail functionality started. First we'll have a look at it from the mail
+server side. <br>
+</p>
+<source><pre> // Start the mail server using the default configurations.
+ ConfigurationContext configContext = UtilsMailServer.start();
+
+ // Start the default mail listener. It will starting polling for mail
+ // using the configuration from the XML file.
+ SimpleMailListener ml = new SimpleMailListener();
+ ml.init(configContext,
+ configContext.getAxisConfiguration().getTransportIn(
+ new QName(Constants.TRANSPORT_MAIL)));
+ ml.start();
+
+ private QName serviceName = new QName("EchoXMLService");
+ private QName operationName = new QName("echoOMElement");
+
+ // Setup a service that will echo what we send to the server.
+ AxisService service = Utils.createSimpleService(serviceName, Echo.class
+ .getName(), operationName);
+ serverConfigContext.getAxisConfiguration().addService(service);</pre>
+</source>
+<p>This code sets up your Axis2 server which uses a single service to work
+through the mail. If you want to have a look under the hood, check out the
+MailServer and UtilsMailServer classes.</p>
+
+<p>Moving onto the client side, have a look at the code listing below. It
+will call the axisService that was setup in the previous code listing.</p>
+<source><pre> ConfigurationContext configContext = UtilsMailServer
+ .createClientConfigurationContext();
+ AxisService service = new AxisService(serviceName.getLocalPart());
+ AxisOperation axisOperation = new OutInAxisOperation();
+ axisOperation.setName(operationName);
+ axisOperation.setMessageReceiver(new MessageReceiver() {
+ public void receive(MessageContext messageCtx) {
+ envelope = messageCtx.getEnvelope();
+ }
+ });
+ service.addOperation(axisOperation);
+ configContext.getAxisConfiguration().addService(service);
+ ServiceContext serviceContext = new ServiceGroupContext(configContext,
+ (AxisServiceGroup) service.getParent()).getServiceContext(service);
+
+ Options options = new Options();
+ options.setTo(targetEPR);
+ options.setAction(operationName.getLocalPart());
+ options.setTransportInProtocol(Constants.TRANSPORT_MAIL);
+ options.setUseSeparateListener(true);
+
+ Callback callback = new Callback() {
+ public void onComplete(AsyncResult result) {
+ try {
+ result.getResponseEnvelope().serializeAndConsume(
+ XMLOutputFactory.newInstance()
+ .createXMLStreamWriter(System.out));
+ } catch (XMLStreamException e) {
+ onError(e);
+ } finally {
+ finish = true;
+ }
+ }
+
+ public void onError(Exception e) {
+ log.info(e.getMessage());
+ finish = true;
+ }
+ };
+
+ ServiceClient sender = new ServiceClient(configContext, service);
+ sender.setOptions(options);
+ //options.setTo(targetEPR);
+ sender.sendReceiveNonBlocking(operationName, createEnvelope(), callback);
+
+ int index = 0;
+ while (!finish) {
+ Thread.sleep(1000);
+ index++;
+ if (index > 10) {
+ throw new AxisFault(
+ "Server was shutdown as the async response is taking too long to complete.");
+ }
+ }
+
+ }</pre>
+</source>
+<p>This will call the service that was setup on the server, and will poll the
+mail server until the response is received. Please note that the serviceName
+and operationName need to be QNames.</p>
+<a name="generic"></a>
+
+<h2>2. Using a Generic Mail Server</h2>
+
+<p>First you will need two email accounts that work with POP/SMTP. One will act as
+a server and the other will act as the client. For the time being, we will
+use server@somewhere.org and client@somewhere.org as the server and the
+client email addresses. Now that we have the email addresses, you will have
+to set up the client and the server using the Mail Transport <a
+href="mail-configuration.html" target="_blank">configuration document</a>.</p>
+
+<p>When you call the generic mail server, the client side code will remain
+the same and there will be some modification to the server-side code.</p>
+
+<p></p>
+<source><pre> // Create a configuration context. This will also load the details about the mail
+ // address to listen to from the configuration file.
+ File file = new File(MAIL_TRANSPORT_SERVER_ENABLED_REPO_PATH);
+ ConfigurationContextFactory builder = new ConfigurationContextFactory();
+ ConfigurationContext configContext = configContextbuilder
+ .buildConfigurationContext(file.getAbsolutePath());
+
+ // Start the default mail listener. It will starting poling for mail
+ // using the configuration from the XML file.
+ SimpleMailListener ml = new SimpleMailListener();
+ ml.init(configContext,
+ configContext.getAxisConfiguration().getTransportIn(
+ new QName(Constants.TRANSPORT_MAIL)));
+ ml.start();
+
+ private QName serviceName = new QName("EchoXMLService");
+ private QName operationName = new QName("echoOMElement");
+
+ // Setup a service that will echo what we send to the server.
+ AxisService service = Utils.createSimpleService(serviceName, Echo.class
+ .getName(), operationName);
+ serverConfigContext.getAxisConfiguration().addService(service);</pre>
+</source>
+<p>Note that a separate ConfigurationContext needs to be created and used.</p>
+
+<h2>Resources</h2>
+
+<p>For more information on Mail client invocation, see
+AXIS2_HOME\samples\userguide\src\userguide\clients\MailClient.java</p>
+<!--a name="mailet"></a>
+
+<h3>3. Calling Axis2 Through a Mailet</h3-->
+
+<p></p>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/migration.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/migration.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/migration.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/migration.html Fri May 25 01:09:03 2007
@@ -0,0 +1,690 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Migrating from Axis 1.x</title>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
+</head>
+
+<body lang="en">
+<h1>Migrating from Apache Axis 1.x to Axis2</h1>
+
+<p>For all those users who are familiar with Axis 1.x series will be assisted
+through this document to switch to Axis2 series. We begin by listing the
+improvements in Axis2 in comparison with Axis1. This is followed by
+guidelines for the migration.</p>
+
+<p><i>Send your feedback or questions to: <a
+href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a></i>.
+(Subscription details are available on the <a
+href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.) Kindly
+prefix subject with [Axis2]. </p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#comp">Compatibility</a></li>
+ <li><a href="#start">Getting Started</a></li>
+ <li><a href="#custom_deployment">Custom Deployment of Services, Handlers
+ and Modules</a></li>
+ <li><a href="#transports">Transports for HTTP Connection</a></li>
+ <li><a href="#data_binding">Data Binding Support</a></li>
+ <li><a href="#best">Best Usage</a></li>
+</ul>
+<a name="comp"></a>
+
+<h2>Compatibility</h2>
+
+<p>Axis1.x and Axis2 have evolved from different architectures.</p>
+
+<p><strong>Speed</strong> - Axis2 is based on StAX API, which gives greater
+speed than SAX event based parsing that has been used in Axis1.x.</p>
+
+<p><strong>Stability</strong> - Axis2 has fixed phases as well as
+user-defined phases for extensions. This allows far more stability as well as
+flexibility than Axis1.x.</p>
+
+<p><strong>Transport framework</strong> - Simple abstraction in the designing
+of transports (i.e., senders and listeners for SOAP over various protocols
+such as SMTP, etc), allows far more flexibility and the core of the engine is
+completely transport-independent.</p>
+
+<p><strong>WSDL support</strong> - Axis2 supports versions 1.1 and 2.0, which
+allow you to create stubs and skeletons to manipulate the web services
+arena.</p>
+
+<p><strong>Component - oriented architecture</strong> - The components are
+.mar and .aar archives . Easily reusable components such as handlers and
+modules allow pattern processing for your applications or distribution to
+partners. Axis2 is more concerned on the "Module" concept rather the
+"Handler" concept. Modules contain handlers that have been ordered through
+the phase rules. These are ordered to specific service(s).</p>
+<a name="start"></a>
+
+<h2>Getting Started</h2>
+
+<p>Let's look at a simple example of echoing at client API.</p>
+
+<p><b>Axis 1.x</b></p>
+<pre>
+import org.apache.axis.client.Call;
+import org.apache.axis.client.Service;
+import javax.xml.namespace.QName;
+
+public class TestClient {
+ public static void main(String [] args) {
+ try {
+ String endpoint ="http://ws.apache.org:5049/axis/services/echo";
+ Service service = new Service();
+ Call call = (Call) service.createCall();
+ call.setTargetEndpointAddress( new java.net.URL(endpoint) );
+ call.setOperationName(new QName("http://soapinterop.org/", echoString"));
+ String ret = (String) call.invoke( new Object[] { "Hello!" } );
+ System.out.println("Sent 'Hello!', got '" + ret + "'");
+ } catch (Exception e) {
+ System.err.println(e.toString());
+ }
+ }
+}
+</pre>
+
+<p><b>Axis 2</b></p>
+<pre>
+import org.apache.axiom.om.OMAbstractFactory;
+import org.apache.axiom.om.OMElement;
+import org.apache.axiom.om.OMFactory;
+import org.apache.axiom.om.OMNamespace;
+import org.apache.axis2.AxisFault;
+import org.apache.axis2.addressing.EndpointReference;
+import org.apache.axis2.client.Options;
+import org.apache.axis2.client.ServiceClient;
+
+
+public class EchoBlockingClient {
+ private static EndpointReference targetEPR = new EndpointReference(
+ "http://127.0.0.1:8080/axis2/services/MyService");
+ public static void main(String[] args) {
+ try {
+ OMFactory fac = OMAbstractFactory.getOMFactory();
+ OMNamespace ns = fac.createOMNamespace("http://soapinterop.org/", "ns1");
+ OMElement payload = fac.createOMElement("echoString", ns);
+ payload.setText("Hello!");
+ Options options = new Options();
+ ServiceClient client = new ServiceClient();
+ options.setTo(targetEPR);
+ //Blocking invocation
+ OMElement result = client.sendReceive(payload);
+
+ } catch (AxisFault axisFault) {
+ axisFault.printStackTrace();
+ }
+
+ }
+}
+</pre>
+
+<p>It has been clearly depicted that the invocation in Axis2 is dealt with
+the SOAP body element itself. Here the invocation is synchronous, but Axis2
+can handle asynchronous invocations as well. The "payload" variable above
+contains the SOAP body element which should go in the SOAP envelope.</p>
+
+<p>Once the service is called through the stub in Axis2, the "payload" will
+be according to the data binding framework that will be used. So the extra
+work of "payload" will vanish.</p>
+
+<p>Apart from synchronous invocation, Axis2 also supports asynchronous
+invocation through sendReceiveNonblocking(). Synchronous/Asynchronous
+invocations can handle both single and double HTTP connections.</p>
+
+<p>With this advanced architecture, Axis2 is capable of handling megabytes of
+requests and responses, which is far from the capabilities of Axis1.x.</p>
+<a name="custom_deployment"></a>
+
+<h2>Custom Deployment of Services, Handlers, and Modules</h2>
+
+<p>In Axis 1.x, the deployment of services was via WSDD, which in my opinion
+was highly cumbersome. Service deployment in Axis2 is straight forward and
+dynamic. Dynamic behavior is from the "Administrator" facility given by the
+development in the server side. It's just a matter of creating the .aar file
+and deploying it. More details regarding this is given in the Axis2 user
+guide.</p>
+
+<p>Axis2 has moved away from the "Handler concept" and is more into the
+"Module concept". Abstractly speaking, the module concept is a collection of
+handlers with rules that govern which modules are created as .mar files. It
+has module.xml, which is the brain behind manipulating the handlers.</p>
+
+<p>When a service is called through a handler, it is just a matter of giving
+a reference to the module that includes the handler in the services.xml
+(using <module ref="foo/>").</p>
+
+<p>Services are hot deployable in Axis2, but modules are not. This is one
+feature which is unique to Axis2.</p>
+
+<p>Let's take a detailed look at what it takes to migrate the Axis 1.x
+handlers to the Axis 2 modules via the "SOAP Monitor". The SOAP monitor is
+really a combination of three components: An applet which displays
+responses/requests, a servlet which binds to a default port of 5001 and
+connects to the applet, and a handler chain used to intercept the SOAP
+messages. Here we'll focus on the handler.</p>
+
+<p><b>Axis 1.x required two WSDD's to use the SOAP Monitor. First, the SOAP
+Monitor Handler itself:</b></p>
+<pre><deployment xmlns="http://xml.apache.org/axis/wsdd/"
+ xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
+
+ <handler name="soapmonitor"
+ type="java:org.apache.axis.handlers.SOAPMonitorHandler">
+ <parameter name="wsdlURL"
+ value="/wzs/SOAPMonitorService-impl.wsdl"/>
+ <parameter name="namespace"
+ value="http://tempuri.org/wsdl/2001/12/SOAPMonitorService-impl.wsdl"/>
+ <parameter name="serviceName" value="SOAPMonitorService"/>
+ <parameter name="portName" value="Demo"/>
+ </handler>
+
+ <service name="SOAPMonitorService" provider="java:RPC">
+ <parameter name="allowedMethods" value="publishMessage"/>
+ <parameter name="className"
+ value="org.apache.axis.monitor.SOAPMonitorService"/>
+ <parameter name="scope" value="Application"/>
+ </service>
+</deployment></pre>
+
+<p><b>Axis 1.x requires a reference to the handler in the user's WSDD that
+defines their Web Service:</b></p>
+<pre><deployment name="example" xmlns="http://xml.apache.org/axis/wsdd/"
+ xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
+
+ <service name="urn:myService" provider="java:RPC">
+ <parameter name="className" value="org.MyService"/>
+ <parameter name="allowedMethods" value="*"/>
+
+ <requestFlow>
+ <handler type="soapmonitor"/>
+ </requestFlow>
+ <responseFlow>
+ <handler type="soapmonitor"/>
+ </responseFlow>
+
+ </service>
+</deployment></pre>
+
+<p><b>Axis 2 requires a module.xml, placed inside a jar with a .mar extension
+under WEB-INF/modules, to define a Handler:</b></p>
+<pre><module name="soapmonitor" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorModule">
+ <inflow>
+ <handler name="InFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler">
+ <order phase="soapmonitorPhase"/>
+ </handler>
+ </inflow>
+
+ <outflow>
+ <handler name="OutFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler">
+ <order phase="soapmonitorPhase"/>
+ </handler>
+ </outflow>
+
+ <Outfaultflow>
+ <handler name="FaultOutFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler">
+ <order phase="soapmonitorPhase"/>
+ </handler>
+ </Outfaultflow>
+
+ <INfaultflow>
+ <handler name="FaultInFlowSOAPMonitorHandler" class="org.apache.axis2.handlers.soapmonitor.SOAPMonitorHandler">
+ <order phase="soapmonitorPhase"/>
+ </handler>
+ </INfaultflow>
+</module></pre>
+
+<p>The SOAPMonitorModule referenced above simply implements the
+org.apache.axis2.modules.Module, and is used for any additional tasks needed
+to initialize the module and shutdown the module. In this situation, nothing
+is needed and the implemented interface methods have blank bodies.
+Furthermore, the 'soapmonitorPhase' will be used later (below) in the
+axis2.xml .</p>
+
+<p><b>Axis 1.x the SOAPMonitorHandler has the class signature as:</b></p>
+<pre>public class SOAPMonitorHandler extends BasicHandler</pre>
+
+<p><b>Axis 2 the SOAPMonitorHandler has the class signature as:</b></p>
+<pre>public class SOAPMonitorHandler extends AbstractHandler </pre>
+
+<p><b>In Axis2, you need to reference the module that contains the handler
+chain that you want to use inside your services.xml:</b></p>
+<pre><service name="ExampleService">
+ <module ref="soapmonitor"/>
+ <description>
+ This service has the SOAP Monitor wired in
+ </description>
+ <parameter name="ServiceClass" locked="false">org.ExampleService</parameter>
+ <operation name="myExecute">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+</service></pre>
+
+<p><b>Finally, Axis2 requires you to make some changes to axis2.xml. Start by
+adding a global module:</b></p>
+<pre> <module ref="soapmonitor"/></pre>
+
+<p><b>Then define your phase orders for the 'soapmonitorPhase' referenced in
+the module.xml :</b></p>
+<pre> <phaseOrder type="inflow">
+ <!-- Global Phases -->
+ <phase name="TransportIn"/>
+ <phase name="PreDispatch"/>
+ <phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase">
+ <handler name="AddressingBasedDispatcher"
+ class="org.apache.axis2.engine.AddressingBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="RequestURIBasedDispatcher"
+ class="org.apache.axis2.engine.RequestURIBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="SOAPActionBasedDispatcher"
+ class="org.apache.axis2.engine.SOAPActionBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="SOAPMessageBodyBasedDispatcher"
+ class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+ <handler name="InstanceDispatcher"
+ class="org.apache.axis2.engine.InstanceDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+ </phase>
+ <!-- Global Phases -->
+ <!-- After Dispatch phase module author or service author can add any phase he wants -->
+ <phase name="userphase1"/>
+ <phase name="soapmonitorPhase"/>
+ </phaseOrder>
+ <phaseOrder type="outflow">
+ <!-- user can add his own phases to this area -->
+ <!-- Global phases -->
+ <!-- these phases will run irrespective of the service -->
+ <phase name="MessageOut"/>
+ <phase name="userphase1"/>
+ <phase name="soapmonitorPhase"/>
+ <phase name="PolicyDetermination"/>
+ <!-- Global phases -->
+ </phaseOrder>
+ <phaseOrder type="INfaultflow">
+ <phase name="userphase1"/>
+ <phase name="soapmonitorPhase"/>
+ <!-- user can add his own phases to this area -->
+ </phaseOrder>
+ <phaseOrder type="Outfaultflow">
+ <!-- user can add his own phases to this area -->
+ <!-- Global phases -->
+ <phase name="MessageOut"/>
+ <phase name="userphase1"/>
+ <phase name="soapmonitorPhase"/>
+ <phase name="PolicyDetermination"/>
+ <!-- Global phases -->
+ </phaseOrder></pre>
+
+<p>See the user guide for more information on Axis2 modules.</p>
+<a name="transports"></a>
+
+<h2>Transports for HTTP Connection</h2>
+
+<p>Axis2 comes with the CommonsHTTPTransportSender which is based on
+commons-httpclient.</p>
+
+<p>It should be noted that axis2.xml should be configured to call the commons
+transports with the statement,</p>
+<pre>...
+<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
+ <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
+ <parameter name="Transfer-Encoding" locked="false">chunked</parameter>
+</transportSender>
+...</pre>
+<a name="data_binding"></a>
+
+<h2>Data Binding Support</h2>
+
+<p>ADB is used to provide data binding support. In Axis2, XML is manipulated
+via AXIOM, which is based on the StAX API. XML gives full schema support.
+Thus, serialization and de-serialization of XML is handled in Axis2 via the
+xml-data binding framework.</p>
+
+<p>Below is an example of migrating an WSDL based Axis 1.x Web Service to
+Axis2.</p>
+
+<p>First, let's take a look at a simple document/literal style WSDL used in
+an Axis 1.x Web Service. This example assumes the name simple.wsdl for the
+WSDL below:</p>
+<pre><?xml version="1.0" encoding="UTF-8"?>
+
+<definitions name="SimpleService" targetNamespace="http://simpleNS" xmlns:tns="http://simpleNS"
+xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:ns2="http://simpleNS/types">
+ <types>
+ <schema targetNamespace="http://simpleNS/types" xmlns:tns="http://simpleNS/types"
+xmlns:soap11-enc="http://schemas.xmlsoap.org/soap/encoding/"
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
+xmlns="http://www.w3.org/2001/XMLSchema">
+ <import namespace="http://schemas.xmlsoap.org/soap/encoding/"/>
+ <element name="simpleLogin">
+ <complexType>
+ <sequence>
+ <element name="user_name" type="xsd:string"/>
+ <element name="user_password" type="xsd:string"/>
+ </sequence>
+ </complexType>
+ </element>
+ <element name="simpleLoginResponse">
+ <complexType>
+ <sequence>
+ <element name="soap_session_id" type="xsd:string"/>
+ <element name="web_user_name" type="xsd:string"/>
+ </sequence>
+ </complexType>
+ </element>
+</schema></types>
+ <message name="SimpleEndpoint_simpleLogin">
+ <part name="parameters" element="ns2:simpleLogin"/>
+ </message>
+ <message name="SimpleEndpoint_simpleLoginResponse">
+ <part name="result" element="ns2:simpleLoginResponse"/>
+ </message>
+ <portType name="SimpleEndpoint">
+ <operation name="simpleLogin">
+ <input message="tns:SimpleEndpoint_simpleLogin" name="SimpleEndpoint_simpleLogin"/>
+ <output message="tns:SimpleEndpoint_simpleLoginResponse" name="SimpleEndpoint_simpleLoginResponse"/>
+ </operation>
+ </portType>
+ <binding name="SimpleEndpointBinding" type="tns:SimpleEndpoint">
+ <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
+ <operation name="simpleLogin">
+ <soap:operation soapAction="simpleLogin"/>
+ <input name="SimpleEndpoint_simpleLogin">
+ <soap:body use="literal"/>
+ </input>
+ <output name="SimpleEndpoint_simpleLoginResponse">
+ <soap:body use="literal"/>
+ </output>
+ </operation>
+ </binding>
+ <service name="SimpleService">
+ <port name="SimpleEndpointPort" binding="tns:SimpleEndpointBinding">
+ <soap:address location="http://localhost:8080/axis/services/SimpleEndpointPort"/></port></service></definitions></pre>
+
+<p>The next step is to run WSDL2Java on the wsdl. For axis 1.x, this example
+uses the following Ant task:</p>
+<pre><target name="wsdl2java" description="axis 1.x">
+ <delete dir="output" />
+ <mkdir dir="output" />
+ <axis-wsdl2java
+ output="output"
+ verbose="true"
+ url="wsdl/simple.wsdl"
+ serverside="true"
+ skeletondeploy="true"
+ nowrapped="true">
+ </axis-wsdl2java>
+ </target></pre>
+
+<p>The Axis 1.x Ant task above takes the simple.wsdl under the directory
+'wsdl' , and from that creates files under the directory 'output'. The files
+created are shown below:</p>
+<pre>output/
+output/simpleNS
+output/simpleNS/types
+output/simpleNS/types/SimpleLoginResponse.java
+output/simpleNS/types/SimpleLogin.java
+output/simpleNS/SimpleEndpoint.java
+output/simpleNS/SimpleEndpointBindingStub.java
+output/simpleNS/SimpleEndpointBindingSkeleton.java
+output/simpleNS/SimpleEndpointBindingImpl.java
+output/simpleNS/SimpleService.java
+output/simpleNS/SimpleServiceLocator.java
+output/simpleNS/deploy.wsdd
+output/simpleNS/undeploy.wsdd</pre>
+
+<p>Now let's run WSDL2Java with Axis2. In this example, the only change to
+simple.wsdl required for Axis2 is that 'soap:address location' be changed
+to:</p>
+<pre><soap:address location="http://localhost:8080/axis2/services/SimpleEndpoint"/></port></service></definitions></pre>
+
+<p>In Axis2, the default databinding uses ADB. However, XMLBeans and JaxMe
+are also supported. This example uses XMLBeans. For Axis2, our example uses
+the following Ant task:</p>
+<pre><target name="wsdl2java">
+ <delete dir="output" />
+ <java classname="org.apache.axis2.wsdl.WSDL2Java" fork="true">
+ <classpath refid="axis.classpath"/>
+ <arg value="-d"/>
+ <arg value="xmlbeans"/>
+ <arg value="-uri"/>
+ <arg file="wsdl/simple.wsdl"/>
+ <arg value="-ss"/>
+ <arg value="-g"/>
+ <arg value="-sd"/>
+ <arg value="-o"/>
+ <arg file="output"/>
+ <arg value="-p"/>
+ <arg value="org.simple.endpoint"/>
+ </java>
+
+ <!-- Move the schema folder to classpath-->
+ <move todir="${build.classes}">
+ <fileset dir="output/resources">
+ <include name="*schema*/**/*.class"/>
+ <include name="*schema*/**/*.xsb"/>
+ </fileset>
+ </move>
+
+ </target></pre>
+
+<p>For an explanation of the Axis2 WSDL2Java Ant task and its options, see
+the <a href="../tools/@axis2_version_dir@/CodegenToolReference.html">CodegenToolReference
+Guide.</a></p>
+
+<p>A feature of XMLBeans is that there is one class file created with
+WSDL2java, and a series of .xsb files. They must be referenced when
+compiling, and as the example shows, these files are moved to a build
+directory.</p>
+
+<p>The Axis2 WSDL2Java example also takes the simple.wsdl, which is under the
+directory 'wsdl', and creates files under the directory 'output'. The
+relevant non-xmlbean files created are shown below:</p>
+<pre>output/resources/services.xml
+output/src/org/simple
+output/src/org/simple/endpoint
+output/src/org/simple/endpoint/SimpleEndpointSkeleton.java
+output/src/org/simple/endpoint/SimpleEndpointMessageReceiverInOut.java
+output/src/org/simple/endpoint/SimpleEndpointCallbackHandler.java
+output/src/org/simple/endpoint/SimpleEndpointStub.java
+output/src/simplens
+output/src/simplens/types
+output/src/simplens/types/SimpleLoginDocument.java
+output/src/simplens/types/impl
+output/src/simplens/types/impl/SimpleLoginDocumentImpl.java
+output/src/simplens/types/impl/SimpleLoginResponseDocumentImpl.java
+output/src/simplens/types/SimpleLoginResponseDocument.java</pre>
+
+<p>The first important distinction is that while the Axis 1.x example
+generated deploy.wsdd and undeploy.wsdd, the Axis2 example created a
+services.xml. The files deploy.wsdd and services.xml are a breed apart,
+coming from different architectures. There is no direct parallel between
+them. See the Axis2 user guide for an explanation about services.xml</p>
+
+<p>Now we're ready to code. We'll start with Axis 1.x on the service side. To
+implement the business logic, we'll change
+simpleNS/SimpleEndpointBindingImpl.java from:</p>
+<pre class="code">package simpleNS;
+
+public class SimpleEndpointBindingImpl implements simpleNS.SimpleEndpoint{
+ public simpleNS.types.SimpleLoginResponse simpleLogin(simpleNS.types.SimpleLogin parameters)
+ throws java.rmi.RemoteException {
+ return null;
+ }
+
+}</pre>
+
+<p>To:</p>
+<pre class="code">package simpleNS;
+
+public class SimpleEndpointBindingImpl implements simpleNS.SimpleEndpoint{
+ public simpleNS.types.SimpleLoginResponse simpleLogin(simpleNS.types.SimpleLogin parameters)
+ throws java.rmi.RemoteException {
+
+ String userName = parameters.getUser_name();
+ String password = parameters.getUser_password();
+ // do something with those vars...
+ return new simpleNS.types.SimpleLoginResponse("mySessionID", "username");
+ }
+
+}</pre>
+
+<p>In Axis 1.x, the next step is to compile the classes and put them in the
+Axis.war, and then run the admin client with the generated deploy.wsdd. You
+then look at the happy axis page to verify that the service has been
+installed correctly.</p>
+
+<p>Now let's code Axis2. In Axis 1.x, while the Ant task shown in the example
+created a skeleton, a peek inside shows that the skeleton calls the binding
+implementation class. In Axis2, we work with the skeleton directly. To
+implement the business logic in the generated Axis2 classes, we'll change
+org/simple/endpoint/SimpleEndpointSkeleton.java from:</p>
+<pre class="code">package org.simple.endpoint;
+ /**
+ * SimpleEndpointSkeleton java skeleton for the axisService
+ */
+ public class SimpleEndpointSkeleton {
+
+ /**
+ * Auto generated method signature
+ * @param param0
+ */
+ public simplens.types.SimpleLoginResponseDocument simpleLogin
+ (simplens.types.SimpleLoginDocument param0 ) throws Exception {
+ //Todo fill this with the necessary business logic
+ throw new java.lang.UnsupportedOperationException();
+ }
+}</pre>
+
+<p>To:</p>
+<pre class="code">package org.simple.endpoint;
+
+ import simplens.types.*;
+ import simplens.types.SimpleLoginResponseDocument.*;
+ import simplens.types.SimpleLoginDocument.*;
+ /**
+ * SimpleEndpointSkeleton java skeleton for the axisService
+ */
+ public class SimpleEndpointSkeleton {
+
+ /**
+ * Modified
+ * @param simpleLoginDocument
+ */
+ public SimpleLoginResponseDocument simpleLogin
+ (simplens.types.SimpleLoginDocument simpleLoginDocument){
+ //Todo fill this with the necessary business logic
+
+ SimpleLoginResponseDocument retDoc =
+ SimpleLoginResponseDocument.Factory.newInstance();
+
+ SimpleLoginResponse retElement =
+ SimpleLoginResponse.Factory.newInstance();
+ // Get parameters passed in
+ SimpleLogin simpleLogin = simpleLoginDocument.getSimpleLogin();
+ String userName = simpleLogin.getUserName();
+ String password = simpleLogin.getUserPassword();
+ // do something with those variables...
+
+ retElement.setWebUserName(userName);
+ retElement.setSoapSessionId("my random string");
+ retDoc.setSimpleLoginResponse(retElement);
+ return retDoc;
+ }
+}</pre>
+
+<p>In Axis2, the next step is to compile the classes, put them along with the
+generated services.xml in an AAR, and then hot deploy the AAR by placing it
+in the Axis2.war under WEB-INF/services. Point a browser to
+http://localhost:8080/axis2/listServices, and you should see the service
+'SimpleService' ready for action. See the Axis2 user guide for more info.</p>
+
+<p>The last step is the client. Our Axis 1.x client for this example is:</p>
+<pre>package org;
+
+import simpleNS.*;
+import simpleNS.types.*;
+
+public class Tester {
+ public static void main(String [] args) throws Exception {
+ // Make a service
+ SimpleService service = new SimpleServiceLocator();
+
+ // Now use the service to get a stub which implements the SDI.
+ SimpleEndpoint port = service.getSimpleEndpointPort();
+
+ // set the params
+ SimpleLogin parameters = new SimpleLogin("username","password");
+ // Make the actual call
+ SimpleLoginResponse simpleLoginResponse = port.simpleLogin(parameters);
+ String session = simpleLoginResponse.getSoap_session_id();
+ String user = simpleLoginResponse.getWeb_user_name();
+ System.out.println("simpleLoginResponse, session: " + session + ", user: " + user);
+ }
+}</pre>
+
+<p>Finally, our Axis2 client for this example is:</p>
+<pre>package org;
+import simplens.types.*;
+import simplens.types.SimpleLoginDocument.*;
+import simplens.types.SimpleLoginResponseDocument.*;
+import simplens.types.impl.*;
+import org.simple.endpoint.*;
+
+public class Tester {
+ public static void main(String [] args) throws Exception {
+
+ // you may not need to pass in the url to the constructor - try the default no arg one
+ SimpleEndpointStub stub =
+ new SimpleEndpointStub(null, "http://localhost:8080/axis2/services/SimpleService");
+
+ SimpleLogin simpleLogin = SimpleLogin.Factory.newInstance();
+ simpleLogin.setUserName("userName");
+ simpleLogin.setUserPassword("password");
+
+ SimpleLoginDocument simpleLoginDocument =
+ SimpleLoginDocument.Factory.newInstance();
+
+ simpleLoginDocument.setSimpleLogin(simpleLogin);
+
+ SimpleLoginResponseDocument simpleLoginResponseDocument
+ = stub.simpleLogin(simpleLoginDocument);
+
+ SimpleLoginResponse simpleLoginResponse =
+ simpleLoginResponseDocument.getSimpleLoginResponse();
+
+ String session = simpleLoginResponse.getSoapSessionId();
+ String user = simpleLoginResponse.getWebUserName();
+ System.out.println("simpleLoginResponse, session: " + session + ", user: " + user);
+
+ }
+}</pre>
+
+<p>Axis2 clients also have asynchronous options via a Callback and
+alternatively a 'Fire and forget'. See the user guide for more details.</p>
+<a name="best"></a>
+
+<h2>Best Usage</h2>
+
+<p>Axis1.x and Axis2 have different ways of seeing the SOAP stack. So the
+best way to migrate is to follow the <a href="userguide.html">User's
+Guide</a> and the <a href="Axis2ArchitectureGuide.html">Architecture
+Guide</a> of Axis2 properly. Axis2 is very straight forward and friendly to
+use than its predecessor.</p>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/modules.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/modules.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/modules.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/modules.html Fri May 25 01:09:03 2007
@@ -0,0 +1,362 @@
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Writing your Own Axis2 Module</title>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
+</head>
+
+<body dir="ltr" lang="en-US">
+<a name="Modules"></a>
+
+<h1>Writing Your Own Axis2 Module</h1>
+
+<p>Axis2 provides extended support for modules (See the <a
+href="Axis2ArchitectureGuide.html" 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">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>
+ <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>
+<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"></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
+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" 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">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">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>
+ <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>
+<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
+href="http://www.developer.com/java/web/article.php/3529321"
+target="_blank">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>
+
+<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>
+<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>
+
+<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>
+<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>
+</body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org