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:[EMAIL PROTECTED]">[EMAIL PROTECTED]</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 [EMAIL PROTECTED] and [EMAIL PROTECTED] 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:[EMAIL PROTECTED]">[EMAIL PROTECTED]</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:[EMAIL PROTECTED]">[EMAIL PROTECTED]</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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]