You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ws.apache.org by ch...@apache.org on 2006/01/05 10:25:50 UTC
svn commit: r366133 [7/10] - in /webservices/site/trunk/targets/axis2: ./
0_93/ 0_94/ 0_94/adb/ 0_94/adb/images/ 0_94/images/
0_94/images/archi-guide/ 0_94/images/faq/ 0_94/images/logos/
0_94/images/tools/ 0_94/images/tools/service/ 0_94/images/tools/w...
Added: webservices/site/trunk/targets/axis2/0_94/userguide.html
URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_94/userguide.html?rev=366133&view=auto
==============================================================================
--- webservices/site/trunk/targets/axis2/0_94/userguide.html (added)
+++ webservices/site/trunk/targets/axis2/0_94/userguide.html Thu Jan 5 01:17:47 2006
@@ -0,0 +1,1180 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis 2.0 - Axis2 User's Guide</title><style type="text/css" media="all">
+ @import url("./style/maven-base.css");
+
+ @import url("./style/maven-theme.css");</style><link rel="stylesheet" href="./style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Apache Axis 2.0" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 05 January 2006
+ | Doc for 0.94</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis_2_0"><h5>Axis 2.0</h5><ul><li class="none"><a href="index.html">Home</a></li><li class="expanded"><a href="">Download Axis2</a><ul><li class="none"><a href="download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink" title="External Link">Source Code</a></li></ul></li><li class="expanded"><a href="">Documentation</a><ul><li class="none"><a href="0_93/index.html">Version 0.93</a></li><li class="none"><a href="0_94/index.html">Version 0.94</a></li></ul></li><li class="expanded"><a href="overview.html">Get Involved</a><ul><li class="none"><a href="svn.html">Checkout the Source</a></li><li class="none"><a href="siteHowTo.html">Build the Site</a></li><li class="none"><a href="guidelines.html">Developer Guidelines</a></li><li cl
ass="none"><a href="refLib.html">Reference Library</a></li><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><li class="none"><a href="faq.html">FAQ</a></li></ul></li><li class="none"><a href="thanks.html">Ackknowledgements</a></li><li class="expanded"><a href="">Project Information</a><ul><li class="none"><a href="team-list.html">Project Team</a></li><li class="none"><a href="issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="./images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Axis2_User_s_Guide"></a><h2>Axis2 User's Guide</h2><p><i>Version 0.94</i></p><i>User Feedback: <a href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a></i><div class="subsection"><a name="Contents"></a><h3>Contents</h3><ul>
+ <li><p><a href="#Introduction">Introduction</a></p>
+ <ul>
+ <li><a href="#Attention">Attention</a></li>
+ <li><a href="#What_is_Axis_2_0__">What is Axis2?</a></li>
+ <li><a href="#Featurelist">Axis2 Complete Features List</a>
+ <ul>
+ <li><a href="#experimental">Experimental Features List</a></li>
+ <li><a href="#majorchanges">Major Changes Since Last
+ Release</a></li>
+ </ul>
+ </li>
+ <li><a href="#toolsinrelease">Tools included in this Release</a></li>
+ <li><a href="#WhatsStillToDo">What's still to do?</a></li>
+ </ul>
+ </li>
+ <li><p><a href="#samples">Samples</a></p>
+ </li>
+ <li><p><a href="#WS">Web Services Using Axis2</a></p>
+ <ul>
+ <li><a href="#WSapi">Writing Web Services using Axis2 APIs</a>
+ <ul>
+ <li><a href="#CreateWS">Creating Web Service (MyService)</a></li>
+ <li><a href="#WriteWS">How to write the Web Service?</a>
+ <ul>
+ <li><a href="#step1">Step1 :Write the Implementation
+ Class</a></li>
+ <li><a href="#step2">Step2 :Write the services.xml file</a></li>
+ <li><a href="#step3">Step3 :Create the Web Service
+ Archive</a></li>
+ <li><a href="#step4">Step4 :Deploy the Web Service</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><p><a href="#generateskl">Writing Web Services by Code Generating
+ Skeleton</a></p>
+ <ul>
+ <li><a href="#WSDL2JavaTool">WSDL2Java Tool</a></li>
+ <li><a href="#businesslogic">Implement the Business Logic</a></li>
+ <li><a href="#echostring">echoString</a></li>
+ <li><a href="#echostringarray">echoStringArray</a></li>
+ <li><a href="#echostruct">echoStruct</a></li>
+ <li><a href="#servicesxml">services.xml</a></li>
+ <li><a href="#packaging">Packaging</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+</ul><ul>
+ <li><p><a href="#Web_Service_Clients_Using_Axis2">Web Service Clients Using
+ Axis2</a></p>
+ <ul>
+ <li><a href="#primaryAPIs">Writing Web Service Clients using Axis2's
+ Primary APIs</a>
+ <ul>
+ <li><a href="#echoblocking">EchoBlockingClient</a></li>
+ <li><a href="#ping">PingClient</a></li>
+ <li><a href="#echononblocking">EchoNonBlockingClient</a></li>
+ <li><a href="#echononblockingdual">EchoNonBlockingDualClient</a></li>
+ <li><a href="#echoblockingdual">EchoBlockingDualClient</a></li>
+ </ul>
+ </li>
+ <li><p><a href="#databinding">Writing Web Service Clients using Code
+ Generation</a></p>
+ <ul>
+ <li><a href="#echovoid">Client for echoVoid Operation</a></li>
+ <li><a href="#clientechostring">Client for echoString
+ Operation</a></li>
+ <li><a href="#clientechostringarray">Cient for
+ echoStringArray</a></li>
+ <li><a href="#clientechostruct">Client for echoStruct
+ Operation</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><p><a href="#Modules">Modules</a></p>
+ <ul>
+ <li><a href="#logging">MyService with a Logging Module</a>
+ <ul>
+ <li><a href="#step1loggingmodule">Step1 : LoggingModule
+ Class</a></li>
+ <li><a href="#step2loggingmodule">Step2 : LogHandler</a></li>
+ <li><a href="#step3loggingmodule">Step3 : module.xml</a></li>
+ <li><a href="#step4loggingmodule">Step 4: Modify the
+ "axis2.xml"</a></li>
+ <li><a href="#step5loggingmodule">Step5 : Modify the
+ "services.xml"</a></li>
+ <li><a href="#step6loggingmodule">Step6 : Packaging</a></li>
+ <li><a href="#step7loggingmodule">Step7 : Deploy the Module in
+ Axis2</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><p><a href="#Other_Samples">Other Samples</a></p>
+ <ul>
+ <li><a href="#googlespell">Google Spell Checker Sample</a></li>
+ <li><a href="#googlesearch">Google Search Sample</a></li>
+ <li><a href="#amazonqueuing">Amazon Queuing Service</a></li>
+ </ul>
+ </li>
+ <li><p><a href="#Advanced_Topics">Advanced Topics</a></p>
+ <ul>
+ <li><a href="rest-ws.html">RESTful Web Services</a></li>
+ <li><a href="tcp-transport.html">TCP transport</a></li>
+ <li><a href="mail-transport.html">Mail Transport</a></li>
+ <li><a href="http-transport.html">HTTP Transports</a></li>
+ <li><a href="mtom-guide.html">MTOM with Axis2</a></li>
+ <li><a href="security-module.html">Securing SOAP Messages with
+ WSS4J</a></li>
+ </ul>
+ </li>
+</ul></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><p>Welcome to Axis2, the next generation of Apache Axis!!! This User's Guide
+will help you to understand what Axis2 has to offer and how to get started
+with it. We hope you will benefit from the power of Axis2.</p></div><div class="subsection"><a name="Attention"></a><h3>Attention</h3><ul>
+ <li><p style="margin-bottom: 0in">This User's Guide is written based on
+ <em>Axis2 binary distribution</em>. (The binary distribution can also be
+ created from the source distribution using the maven goal <code>$maven
+ dist-bin)</code></p>
+ </li>
+ <li><p>If you are new to Axis, it's highly recommended that you read <a href="http://ws.apache.org/axis/java/user-guide.html" class="newWindow" title="New Window" target="_blank">Axis 1.x User's Guide</a> before you go any further in
+ this guide.</p>
+ </li>
+</ul></div><div class="subsection"><a name="What_is_Axis2_"></a><h3>What is Axis2?</h3><p>Axis2 is the next generation of Apache Axis. In late August 2004, during
+the Axis2 Summit held in Colombo, Sri Lanka, a new architecture for Axis was
+introduced which was much more flexible, efficient and configurable. Although
+the architecture is new, some of the well established concepts from Axis 1.x
+like handlers are preserved in Axis2. Axis2 comes with many new features,
+enhancements and industry specification implementations.</p><p>After months of continued discussion and coding in this direction, Axis2
+now delivers the following key features:</p><ul>
+ <li><p style="margin-bottom: 0in"><strong>Speed</strong>- Axis2 uses its
+ own object model and StAX (Streaming API for XML) parsing to achieve
+ significantly greater speed than earlier versions of Apache Axis.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>Low memory foot print</strong>-
+ Axis2 was designed ground-up keeping low memory foot print in mind.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>AXIOM</strong>- Axis2 comes with
+ its own light-weight object model, AXIOM, for message processing which is
+ extensible, high performance and developer convenient</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong><a name="hotdeployment">Hot
+ Deployment</a>-</strong> Axis2 is equipped with the capability of
+ deploying web service & handlers while system is up and running. In
+ other words, new services can be added to the system without having to
+ shut down server.Drop the required Web service archive into the services
+ directory in the repository and deployment model will automatically
+ deploy the service and make it available for use.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>Asynchronous Web
+ Services</strong>- Axis2 now supports asynchronous web services &
+ asynchronous web services invocation using non-blocking clients and
+ transports .</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>MEP Support-</strong> Axis2 now
+ comes handy with the flexibility to support Message Exchange Patterns
+ (MEPs) with in-built support for basic MEPs defined in WSDL 2.0.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>Flexibility</strong>- The Axis2
+ architecture gives the developer complete freedom to insert extensions
+ into the engine for custom header processing, system management, or
+ <em>anything else you can imagine</em>.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>Stability</strong>- Axis2 defines
+ a set of published interfaces which change relatively slowly compared to
+ the rest of Axis.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>Component-oriented
+ Deployment</strong>- You can easily define reusable networks of Handlers
+ to implement common patterns of processing for your applications, or to
+ distribute to partners.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>Transport Framework</strong>- We
+ have a clean and simple abstraction for integrating and using Transports
+ (i.e., senders and listeners for SOAP over various protocols such as
+ SMTP, FTP, message-oriented middleware, etc), and the core of the engine
+ is completely transport-independent.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>WSDL support-</strong> Axis2
+ supports the <a href="http://www.w3.org/TR/wsdl" class="newWindow" title="New Window" target="_blank">Web
+ Service Description Language</a>, version 1.1 and 2.0, which allows you
+ to easily build stubs to access remote services, and also to
+ automatically export machine-readable descriptions of your deployed
+ services from Axis2.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>Add-ons ?</strong> Several web
+ services have been incorporated including <a href="http://ws.apache.org/wss4j/" class="newWindow" title="New Window" target="_blank">WSS4J</a> for
+ security, <a href="http://ws.apache.org/sandesha/" class="newWindow" title="New Window" target="_blank">Sandesha</a> for reliable messaging, <a href="http://ws.apache.org/kandula/" class="newWindow" title="New Window" target="_blank">Kandula</a> which is
+ an encapsulation of WS- coordination, Atomic Transaction and Business
+ Activity.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>Composition and Extensibility
+ -</strong> modules and phases improve support for composability and
+ extensibility. Modules supports composability and is able to add support
+ for new WS-* specifications in a simple and clean manner. They are
+ however not <a href="#hotdeployment">hot deployable</a> as they change
+ the overall behavior of the system.</p>
+ </li>
+</ul><p>We hope you enjoy using Axis2. Please note that this is an open-source
+effort. If you feel the code could use some new features or fixes, please get
+involved and lend a hand! The Axis developer community welcomes your
+participation.</p><p>Let us know what you think!</p><p>Please send your feedback on Axis2 to "<a href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a>" and make
+sure to prefix the subject of the mail with [Axis2].</p></div><div class="subsection"><a name="Axis2_Complete_Features_List"></a><h3>Axis2 Complete Features List</h3><p>
+This release includes the following features:
+<ul>
+ <li>AXIOM, an XML object model working on StAX
+ (Streaming API for XML) parsing optimized for SOAP 1.1/1.2 Messages. This
+ has complete XML infoset support.</li>
+ <li><p style="margin-bottom: 0in">Support for One-Way Messaging (In-Only)
+ and Request Response Messaging (In-Out)</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Module Architecture, mechanism to extend
+ the SOAP Processing Model</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Content hierarchy</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Archive based deployment Model</p>
+ </li>
+ <li><p style="margin-bottom: 0in">WSDL Code Generation Tool for Stub and
+ skeletons</p>
+ </li>
+ <li><p style="margin-bottom: 0in">WS-Addressing, both the submission
+ (2004/08) and final (2005/08) versions</p>
+ </li>
+ <li><p style="margin-bottom: 0in">WSS4J module for security</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Improved and user friendly Client API</p>
+ </li>
+ <li><p style="margin-bottom: 0in">WSDL2Java and Java2WSDL</p>
+ </li>
+ <li><p style="margin-bottom: 0in">REST Web Service Support</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Transports supports: HTTP, SMTP, TCP,
+ JMS</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Raw XML providers</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Support for MTOM/ MIME/ SwA</p>
+ </li>
+ <li><p style="margin-bottom: 0in">SAAJ implementation</p>
+ </li>
+ <li><p style="margin-bottom: 0in">DOOM <sup><span style="color: #FF0000; background-color: #FFFFFF">new</span></sup></p>
+ </li>
+ <li><p style="margin-bottom: 0in">Wrap/Unwrap capability for the generated
+ code <sup><span style="color: #FF0000; background-color: #FFFFFF">new</span></sup></p>
+ </li>
+</ul></p></div><div class="subsection"><a name="Experimental_Features_List"></a><h3>Experimental Features List</h3><ul>
+ <li>Sessions scoping for Application, SOAP,
+ Transport and Request levels</li>
+ <li><p style="margin-bottom: 0in">Web Service Policy Support</p>
+ </li>
+</ul></div><div class="subsection"><a name="Major_Changes_Since_Last_Release"></a><h3>Major Changes Since Last Release</h3><ul>
+ <li>Fixing of memory leaks</li>
+</ul></div><div class="subsection"><a name="Tools_included_in_this_Release"></a><h3>Tools included in this Release</h3><ol>
+ <li>Axis2 Web Appplication (Web App)</li>
+ <li>WSDL2WS, eclipse Plugin/Command line
+ version</li>
+ <li>Service Archive Wizard, eclipse Plugin</li>
+ <li>Module Archive Wizard, eclipse Plugin</li>
+
+ <p>Axis2 is shipped with two standard tools. Both the tools are Eclipse
+ plug-ins, the Codegen tool even has the accompanying Ant task and the
+ command line tool.Documentation for the code generator tool is available
+ for the <a href="CodegenToolReference.html" class="newWindow" title="New Window" target="_blank">Codegen
+ wizard</a> and the <a href="ServiceArchiveToolReference.html" class="newWindow" title="New Window" target="_blank">Service Archiver</a>.</p>
+</ol></div><div class="subsection"><a name="What_s_still_to_do_"></a><h3>What's still to do?</h3><p>Please see a list of what we think needs doing - and please consider
+helping out if you're interested & able!</p><ul>
+ <li><p style="margin-bottom: 0in">JAX-RPC 1.1 and/or JAX-WS compliance</p>
+ </li>
+ <li><p style="margin-bottom: 0in">SOAP Encoding</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Binary serialization and de-serialization
+ support</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Management Interface for Axis2</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Implementation of other Transports.</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Resource framework implementation (WS-RF)
+ and Enterprise web services such as JSR 109 support</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Interop tests</p>
+ </li>
+</ul></div><div class="subsection"><a name="Samples"></a><h3>Samples</h3><p>In the following sections of the user's guide we will look at how to write
+and deploy Web Services and how to write Web Service Clients using Axis2. All
+the user's guide samples are located at the <b><font color="#000000">"samples/userguide/src"</font></b> directory of the binary
+distribution. So... let's explore the samples.</p></div><div class="subsection"><a name="Web_Services_Using_Axis2"></a><h3>Web Services Using Axis2</h3><p>Before starting, please check whether you have deployed the "axis2.war" in
+your servlet container and it is working properly. (See <a href="installationguide.html" class="newWindow" title="New Window" target="_blank">Installation Guide</a>). User
+can select any of the following two ways of writing web services using
+Axis2. </p><ol>
+ <li><a href="#WSapi">Use Axis2's primary
+ interfaces (APIs) and implement the business logic.</a></li>
+ <li><p><a href="#generateskl">Start from the WSDL ->Code generate the
+ Skeleton ->Implement the Business Logic.</a></p>
+ </li>
+</ol></div><div class="subsection"><a name="Writing_Web_Services_Using_Axis2_s_Primary_APIs"></a><h3>Writing Web Services Using Axis2's Primary APIs</h3></div><div class="subsection"><a name="Creating_Web_Service__MyService_"></a><h3>Creating Web Service (MyService)</h3><p>First let's see how we can write a simple Web Service (MyService) using
+Axis2's primary interfaces and deploy it. For this purpose we will create a
+Web Service with two operations as follows.</p>
+ <div class="source"><pre>public void ping(OMElement element){} //IN-ONLY operation, just accepts the OMElement and do some processing.
+public OMElement echo(OMElement element){}//IN-OUT operation, accepts an OMElement and
+ //responds with another OMElement after processing.
+
+</pre></div>
+ <p>Complete code for this example Web Service (MyService) can be found in the
+"Axis2Home/samples/userguide/src" directory under "userguide/example1"
+package. As you can see, the two operations are very simple and need no
+explanations on what they do. Now let's see how we can write the deployment
+descriptors for the service and deploy it.</p></div><div class="subsection"><a name="How_to_write_the_Web_Service_"></a><h3>How to write the Web Service?</h3><p>
+Writing a new Web Service with Axis2 involve four steps:
+<ol>
+ <li><p style="margin-bottom: 0in">Write the Implementation Class</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Write a services.xml file to explain the
+ Web Service</p>
+ </li>
+ <li><p style="margin-bottom: 0in">create a *.aar archive (Axis Archive) for
+ the Web Service</p>
+ </li>
+ <li><p>Deploy the Web Service</p>
+ </li>
+</ol></p></div><div class="subsection"><a name="Step1_:Write_the_Implementation_Class"></a><h3>Step1 :Write the Implementation Class</h3><p>Provides a implementation class that provide the business logic for the
+Web Service, it should have methods that match the operations in the Web
+Service. Unless you have data binding the signature of the methods can have
+one parameter of type OMElement.</p>
+ <div class="source"><pre>public class MyService{
+ public void ping(OMElement element){
+ ......
+ }
+ public OMElement echo(OMElement element){
+ ......
+ }
+}
+
+</pre></div>
+ </div><div class="subsection"><a name="Step2_:Write_the_services_xml_file"></a><h3>Step2 :Write the services.xml file</h3><p>Axis2 uses "services.xml" to keep configurations for a Web Service. Each
+Web Service deployed in Axis2 needs a "services.xml" containing the
+configurations. "services.xml" for MyService will be as follows.</p>
+ <div class="source"><pre><service name="MyService">
+ <description>
+ This is a sample Web Service with two operations, echo and ping.
+ </description>
+ <parameter name="ServiceClass" locked="false">userguide.example1.MyService</parameter>
+ <operation name="echo">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+ <operation name="ping">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/>
+ </operation>
+ </service>
+
+</pre></div>
+ <p><em>The above XML tags can be explained as follows:</em></p><p>As it can be seen, first line of the "services.xml" gives the name of the
+Web Service. This is used in the URL to the service as the service name.</p><p>Next comes the description and the service class.</p><p>The next two xml tags describe the operations that are available in this
+service with respective message receivers. For the "echo" operation we have
+used a <strong>RawXMLINOutMessageReceiver</strong> since it is an IN-OUT
+operation. For IN-ONLY operation "ping", we have used
+<strong>RawXMLINOnlyMessageReceiver</strong> as the message receiver.</p><p>MessageReceivers will be the destination point that Axis2 engine will hand over the message, depending on the operation the message is destined to. The message receiver must work according to the rules defined in the operation to process the message and it will hand over the message to the service implementation class.</p><p>You can write a services.xml file to include a group of services instead
+of a single service. This makes management and deployment of a set of related
+services very easy. At runtime you can share information between these
+services within a single interaction using the ServiceGroupContext. If you
+hope to use this functionality, the services.xml file should have following
+format.</p>
+ <div class="source"><pre><serviceGroup>
+ <service name="Service1">
+ <!-- details for Service1 -->
+ </service>
+ <service name="Service2">
+ <!-- details for Service2 -->
+ </service>
+ <module ref="ModuleName" />
+ <parameter name="serviceGroupParam1" locked="false">value 1</parameter>
+</serviceGroup>
+
+</pre></div>
+ </div><div class="subsection"><a name="Step3_:Create_the_Web_Service_Archive"></a><h3>Step3 :Create the Web Service Archive</h3><p>Axis2 use ".aar" (Axis Archive) file as the deployment package for Web
+Services. Therefore, for MyService we will use "MyService.aar" with the
+"services.xml" packaged in the META-INF as shown in the following picture.</p><p><img src="images/userguide/ServiceItems.jpg" name="Graphic1" align="bottom" width="176" height="91" border="0" alt=""></img></p><p>To create "MyService.aar" user can first create a jar file containing all
+the files necessary for the service and then rename the "jar" to "aar" so
+that Axis2 understands it as a service archive. This has already been created
+in the "Axis2Home/samples/userguide" directory. Now let's use it...</p></div><div class="subsection"><a name="Step4_:Deploy_the_Web_Service"></a><h3>Step4 :Deploy the Web Service</h3><p>Deploying the service is just a matter of dropping the ".aar" in to
+"services" directory that can be found in the "\webapps\axis2\WEB-INF" of
+your servlet container, hence copy the "MyService.aar" into the
+"<b>services</b>" directory. Once these steps are completed, start the
+servlet container (if you have not already started) and check the link
+"Services" on the <a href="http://localhost:8080/axis2/index.jsp" class="newWindow" title="New Window" target="_blank">Home Page of Axis2 Web Application</a>
+(http://localhost:8080/axis2/index.jsp) and see whether the MyService is
+deployed properly. If you can see the following output then you have
+successfully deployed MyService on Axis2.</p><p align="center"><img src="images/userguide/MyServiceDeployed.jpg" name="Graphic2" align="bottom" width="734" height="766" border="0" alt=""></img></p><p>Note: Axis2 provides an easy way to deploy Web Services using the "Upload
+Service" tool on Axis2 Web Application's Administration module. (See the <a href="webadminguide.html" class="newWindow" title="New Window" target="_blank">Web Administration Guide</a> for
+more information on this)</p></div><div class="subsection"><a name="Writing_Web_Services_by_Code_Generating_Skeleton"></a><h3>Writing Web Services by Code Generating Skeleton</h3><p>This is the second method of writing Web Services using Axis2. Let's see
+how we can generate the skeleton from a given WSDL and implement the business
+logic using Axis2. For this we use Axis2SampleDocLit.wsdl that can be found
+in the <b>wsdl</b> directory under samples.</p></div><div class="subsection"><a name="WSDL2Java_Tool"></a><h3>WSDL2Java Tool</h3><p>To generate the skeleton and the required classes you can use the
+WSDL2Java tool provided in Axis2. This tool is located in the bin directory
+of the distribution and can be executed using the provided scripts (.bat or
+.sh). The tool's parameter list is as follows and user can specify these
+values depending on their requirements.</p>
+ <div class="source"><pre>Usage WSDL2Code -uri :WSDL file location
+-o : output file location
+-a : Generate async style code only. Default if off
+-s : Generate sync style code only. Default if off. takes precedence over -a
+-p : set custom package name
+-l : valid languages are java and csharp. Default is java
+-t : Generate TestCase to test the generated code
+-ss : Generate server side code (i.e. skeletons).Default is off
+-sd : Generate service descriptor (i.e. axis2.xml).Default is off.Valid with -ss
+
+</pre></div>
+ <p>We will use the tool with the following parameters and generate the
+skeleton and the other required classes.</p><p>Windows users can use the following command in the console:</p>
+ <div class="source"><pre>WSDL2Java -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -ss -sd -o ..\samples\src -p org.apache.axis2.userguide
+
+</pre></div>
+ <p>Linux users should switch the file separator:</p>
+ <div class="source"><pre>WSDL2Java -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd -o ../samples/src -p org.apache.axis2.userguide
+
+</pre></div>
+ <p>This will generate the required classes in the <b>src</b> directory inside
+samples, and the schema classes in <strong>schema</strong> directory also
+inside samples. Note that these are not source files and should be availed in
+the class path in order to compile the generated classes</p></div><div class="subsection"><a name="Implement_the_Business_Logic"></a><h3>Implement the Business Logic</h3><p>Locate the skeleton class that can be found under src/userguide directory
+with the name "Axis2SampleDocLitPortTypeSkeleton.java". This is the skeleton
+for our web service and we can now easily implement the business logic. The
+WSDL we have used has three operations:
+</p><ul>
+ <li><p style="margin-bottom: 0in">echoString - Operation that echoes a
+ String value </p>
+ </li>
+ <li><p style="margin-bottom: 0in">echoStringArray - Operation that accept
+ string array as the input and echoes them back</p>
+ </li>
+ <li><p>echoStruct - Operation that accept a Struct as the input and echoes
+ them back.</p>
+ </li>
+</ul><p>
+
+</p></div><div class="subsection"><a name="echoString"></a><h3>echoString</h3><p>Locate the following code segment in the
+"Axis2SampleDocLitPortTypeSkeleton.java" and fill the business logic as
+shown below.</p>
+ <div class="source"><pre> public org.soapinterop.xsd.EchoStringArrayReturnDocument
+ echoStringArray(org.soapinterop.xsd.EchoStringArrayParamDocument param2){
+ //To do fill this with the necessary business logic
+ return null;
+ }
+
+</pre></div>
+ <p>Once filled with the business logic it will be as follows. The code is
+simple and the explanations are given as comments.</p>
+ <div class="source"><pre>public org.soapinterop.xsd.EchoStringReturnDocument
+ echoString(org.soapinterop.xsd.EchoStringParamDocument param6) {
+ //Use the factory to create the output document.
+ EchoStringReturnDocument retDoc = EchoStringReturnDocument.Factory.newInstance();
+ //send the string back.
+ retDoc.setEchoStringReturn(param6.getEchoStringParam());
+ return retDoc;
+}
+
+</pre></div>
+ <p>Similarly following code fragments shows how you can fill the business
+logic for our first web service.</p></div><div class="subsection"><a name="echoStringArray"></a><h3>echoStringArray</h3>
+ <div class="source"><pre>public org.soapinterop.xsd.EchoStringArrayReturnDocument
+ echoStringArray(org.soapinterop.xsd.EchoStringArrayParamDocument param2) {
+
+ //Use the factory to create the output document.
+ EchoStringArrayReturnDocument retDoc = EchoStringArrayReturnDocument.Factory.newInstance();
+
+ //Get the String array from the input parameters.
+ String[] inParams = param2.getEchoStringArrayParam().getStringArray();
+ ArrayOfstringLiteral retParams = ArrayOfstringLiteral.Factory.newInstance();
+ //Set the input parameters to the output parameters for echoing.
+ for (int i = 0; i < inParams.length; i++) {
+ retParams.addString(inParams[i]);
+ }
+
+ //return the output document.
+ retDoc.setEchoStringArrayReturn(retParams);
+ return retDoc;
+}
+
+</pre></div>
+ </div><div class="subsection"><a name="echoStruct"></a><h3>echoStruct</h3>
+ <div class="source"><pre>public org.soapinterop.xsd.EchoStructReturnDocument
+ echoStruct(org.soapinterop.xsd.EchoStructParamDocument param4) {
+
+ //Use the factory to create the output document.
+ EchoStructReturnDocument retDoc = EchoStructReturnDocument.Factory.newInstance();
+
+ //Get the SOAPStrcut from the incoming parameters
+ SOAPStruct inStruct = param4.getEchoStructParam();
+
+ //Struct for the sending back
+ SOAPStruct outStruct = SOAPStruct.Factory.newInstance();
+
+ //Fill the outgoing struct
+ outStruct.setVarFloat(inStruct.getVarFloat());
+ outStruct.setVarInt(inStruct.getVarInt());
+ outStruct.setVarString(inStruct.getVarString());
+ //Set the outgoing document.
+ retDoc.setEchoStructReturn(outStruct);
+
+ return retDoc;
+}
+
+</pre></div>
+ </div><div class="subsection"><a name="services_xml"></a><h3>services.xml</h3><p> Axis2 uses "services.xml" to hold the configurations for a particular web
+service deployed in the Axis2 engine. When we generate the skeleton using the
+WSDL2Java tool, it will also generate the required services.xml for this web
+service as well. This can be found in the same directory as the skeleton. The
+generated services.xml is as follows.</p>
+ <div class="source"><pre><!--Auto generated Axis Service XML-->
+<service name="Axis2SampleDocLitPortTypeSkeletonTest">
+ <parameter locked="xsd:false" name="ServiceClass">userguide.Axis2SampleDocLitPortTypeSkeleton</parameter>
+ <!--Mounting the method echoStringArray-->
+ <operation name="echoStringArray">
+ <messageReceiver class="userguide.Axis2SampleDocLitPortTypeMessageReceiver"/>
+ </operation>
+ <!--Mounting the method echoStruct-->
+ <operation name="echoStruct">
+ <messageReceiver class="userguide.Axis2SampleDocLitPortTypeMessageReceiver"/>
+ </operation>
+ <!--Mounting the method echoString-->
+ <operation name="echoString">
+ <messageReceiver class="userguide.Axis2SampleDocLitPortTypeMessageReceiver"/>
+ </operation>
+</service>
+
+</pre></div>
+ <p>First line of the "services.xml" gives the name of the Web Service. This
+is used in the URL to the service as the service name. Next comes the
+description and the service class. The next xml tags describe the operations
+that are available in this service with respective message receivers.</p></div><div class="subsection"><a name="Packaging"></a><h3>Packaging</h3><p>Next step in the process is to package the classes in a .aar (axis2
+archive) and deploy it in Axis2. When the WSDL2Java tool generate the
+skeleton it will also generate the required data binding classes. These
+schema related classes are located in the <b>schema </b>directory of the
+generated code. Copy this to your class path, compile the skeleton and the
+supporting classes. In order to create the .aar file, let's create the
+following directory structure with the required files and then simply use jar
+command to package it.</p><p><img src="images/userguide/DirectoryStructure.JPG" align="bottom" width="164" height="142" border="0" alt=""></img></p><p>Go to the top level directory where you can find the class files for the
+above service (i.e. one level up on the directory structure shown above),
+then type the following command in a command line.</p>
+ <div class="source"><pre>jar -cf Axis2SampleDocLitPortType.aar .
+
+</pre></div>
+ <p>Deploying the service is just a matter of dropping the ".aar" in to
+"services" directory that can be found in the "\webapps\axis2\WEB-INF" of
+your servlet container, hence copy the "echo.aar" into the "<b>services</b>"
+directory. Once these steps are completed, please start the servlet container
+(if you have not already started) and check the link "Services" on the <a href="http://localhost:8080/axis2/index.jsp" class="newWindow" title="New Window" target="_blank">Home Page of
+Axis2 Web Application</a> (http://localhost:8080/axis2/index.jsp) and see
+whether the Axis2SampleDocLitPortType is deployed properly. If you can see
+the following output then you have successfully deployed
+Axis2SampleDocLitPortType on Axis2.</p><p align="center"><img src="images/userguide/ServiceDeployed.JPG" name="Graphic4" align="bottom" width="734" height="764" border="0" alt=""></img></p><p>Note: Axis2 provides an easy way to deploy Web Services using the "Upload
+Service" tool on Axis2 Web Application's Administration module. (See the <a href="webadminguide.html" class="newWindow" title="New Window" target="_blank">Web Administration Guide</a> for
+more information on this)</p></div><div class="subsection"><a name="Web_Service_Clients_Using_Axis2"></a><h3>Web Service Clients Using Axis2</h3><p>Now let's see how we can write a Web Service Client to use this Web
+Service.</p><p>Web services can be used to provide wide range of functionality to the
+users ranging from simple, less time consuming operations such as
+"getStockQuote" to time consuming business services. When we utilize (invoke
+using client applications) these Web Service we cannot use some simple
+generic invocation paradigm that suites all the timing complexities involved
+in the service operations. For example, if we use a single transport channel
+(such as HTTP) to invoke a Web Service with and IN-OUT operation that take
+long time to complete, then most of the time we may end up with "connection
+time outs". On the other hand, if there are simultaneous service invocations
+that we need to perform from a single client application, then the use of a
+"blocking" client API will degrade the performance of the client application.
+Similarly there are various other consequences such as One-Way transports
+that come in to play when we need them. Let's try to analyze some common
+service invocation paradigms.</p><p>Many web service engines provide the users with a Blocking and
+Non-Blocking client APIs.</p><ul>
+ <li><p style="margin-bottom: 0in"><b>Blocking API</b> -Once the service
+ invocation is called, the client application hangs and only gets control
+ back when the operation completes, after which client receives a response
+ or a fault. This is the simplest way of invoking Web Services and it also
+ suites many business situations.</p>
+ </li>
+ <li><p><b>Non-Blocking API </b>- This is a callback or polling based API,
+ hence once a service invocation is called, the client application
+ immediately gets the control back and the response is retrieved using the
+ callback object provided. This approach provides the flexibility to the
+ client application to invoke several Web Services simultaneously without
+ blocking the operation already invoked.</p>
+ </li>
+</ul><p>Both these mechanisms work in the API level. Let's name the asynchronous
+behavior that we can get using the <strong>Non-Blocking API</strong> as
+<b>API Level Asynchrony.</b></p><p>Both these mechanisms use single transport connection to send the request
+and to receive the response. They severely lags the capability of using two
+transport connections for the request and the response (either One-Way of
+Two-Way). So both these mechanisms fail to address the problem of long
+running transactions (the transport connection may time-out before the
+operation completes). A possible solution would be to use <strong>two
+separate transport connections for request and response</strong>. The
+asynchronous behavior that we gain using this solution can be called
+<b>Transport Level Asynchrony</b>.</p><p>By combining API Level Asynchrony & Transport Level Asynchrony we can
+obtain four different invocation patterns for web services as shown in the
+following table.</p><p><a name="table1"></a><table class="bodyTable"><tbody>
+ <tr class="b"><td width="33%" height="19"><p><strong>API
+ (Blocking/Non-Blocking)</strong></p>
+ </td><td width="33%"><p><strong> Dual Transports (Yes/No)</strong></p>
+ </td><td width="33%"><p><strong>Description</strong></p>
+ </td></tr>
+ <tr class="a"><td width="33%" height="19"><p>Blocking</p>
+ </td><td width="33%"><p>No</p>
+ </td><td width="33%"><p>Simplest and the familiar invocation pattern</p>
+ </td></tr>
+ <tr class="b"><td width="33%" height="19"><p>Non-Blocking</p>
+ </td><td width="33%"><p>No</p>
+ </td><td width="33%"><p>Using callbacks or polling</p>
+ </td></tr>
+ <tr class="a"><td width="33%" height="19"><p>Blocking</p>
+ </td><td width="33%"><p>Yes</p>
+ </td><td width="33%"><p>This is useful when the service operation is IN-OUT
+ in nature but the transport used is One-Way (e.g. SMTP)</p>
+ </td></tr>
+ <tr class="b"><td width="33%" height="19"><p>Non-Blocking</p>
+ </td><td width="33%"><p>Yes</p>
+ </td><td width="33%"><p>This is can be used to gain the maximum asynchronous
+ behavior. No blocking in the API level and also in the transport
+ level</p>
+ </td></tr>
+ </tbody></table></p><p>Axis2 provides the user with all these possibilities to invoke Web
+Services.</p><p>Below we describe how to write Web Services Clients using Axis2. This can
+be done in two methods:</p><ol>
+ <li><a href="#primaryAPIs">Using the Axis2's primary APIs</a></li>
+ <li><p><a href="#databinding">Using stubs generated with data binding
+ support</a>, making the life easy for developers writing Web Service
+ client applications</p>
+ </li>
+</ol></div><div class="subsection"><a name="Writing_Web_Service_Clients_Using_Axis2_s_Primary_APIs"></a><h3>Writing Web Service Clients Using Axis2's Primary APIs</h3></div><div class="subsection"><a name="EchoBlockingClient"></a><h3>EchoBlockingClient</h3><p>Axis2 provides the user with several invocation patterns for Web Services,
+ranging from pure blocking single channel invocations to a non-blocking dual
+channel invocations. Let's first see how we can write a client to invoke
+"echo" operation of "MyService" using the simplest blocking invocation. The
+client code you need to write is as follows.</p>
+ <div class="source"><pre> try {
+ OMElement payload = ClientUtil.getEchoOMElement();
+
+
+
+
+ StringWriter writer = new StringWriter();
+ result.serializeWithCache(new OMOutput(XMLOutputFactory.newInstance().createXMLStreamWriter(writer)));
+ writer.flush();
+
+ System.out.println(writer.toString());
+
+ } catch (AxisFault axisFault) {
+ axisFault.printStackTrace();
+ } catch (XMLStreamException e) {
+ e.printStackTrace();
+ }
+}
+
+</pre></div>
+ <p>The green lines shows the set of operations that you need to perform
+inorder to invoke a web service. The rest is used to create the OMElement
+that needs to be sent and display the response OMElement. To test this
+client, use the provided ant build file that can be found in the
+"Axis2Home/samples" directory. Run the "testEchoBlockingClient" target . If
+you can see the response OMElement printed in your command line, then you
+have successfully tested the client. </p></div><div class="subsection"><a name="PingClient"></a><h3>PingClient</h3><p>In the Web Service "MyService" we had a IN-ONLY operation with the name
+"ping" (see <a href="#WS">Web Services Using Axis2</a>). Let's write a client
+to invoke this operation. The client code is as follows:</p>
+ <div class="source"><pre> try {
+ OMElement payload = ClientUtil.getPingOMElement();
+
+ MessageSender msgSender = new MessageSender();
+
+ Options options = new Options(); msgSender.setClientOptions(options); options.setTo(targetEPR);
+
+ msgSender.send("ping", payload);
+
+ }
+catch (AxisFault axisFault) {
+ axisFault.printStackTrace();
+ }
+
+</pre></div>
+ <p>Since we are accessing a IN-ONLY operation we can directly use the
+"MessageSender" to invoke this operation. MessageSender will not block the
+invocation, hence it will return the control immediately back to the client.
+You can test this client by running the target "testPingClient" of the ant
+build file at "Axis2Home/samples".</p><p>We have invoked the two operations in our service. Are we done? No! There
+are lot more to explore. Let's see some other ways to invoke the same
+operations...</p></div><div class="subsection"><a name="EchoNonBlockingClient"></a><h3>EchoNonBlockingClient</h3><p>In the EchoBlockingClient once the "call.invokeBlocking("echo", payload);"
+is called, the client is blocked till the operation is completed. This
+behavior is not desirable when there are many Web Service invocations to be
+done in a single client application. A solution would be to use a
+Non-Blocking API to invoke web services. Axis2 provides a callback based
+non-blocking API for users.</p><p>A sample client for this can be found under
+"Axis2Home/samples/userguide/src/userguide/clients" with the name
+EchoNonBlockingClient. If we consider the changes that user may have to do
+with respect to the "EchoBlockingClient" that we have already seen, it will
+be as follows:</p>
+ <div class="source"><pre>call.invokeNonBlocking("echo", payload, callback);
+
+</pre></div>
+ <p>The invocation accepts a callback object as a parameter. Axis2 client API
+provides an abstract Callback with the following methods:</p>
+ <div class="source"><pre>public abstract void onComplete(AsyncResult result);
+public abstract void reportError(Exception e);
+public boolean isComplete() {}
+
+</pre></div>
+ <p>The user is expected to implement the "onComplete " and "reportError "
+methods of their extended call back class. Axis2 engine calls the onComplete
+method once the Web Service response is received by the Axis2 Client API
+(Call). This will eliminate the blocking nature of the Web Service
+invocations and provides the user with the flexibility to use Non Blocking
+API for Web Service Clients.</p><p>To run the sample client ( EchoNonBlockingClient) you can simply use the
+"testEchoNonBlockingClient" target of the ant file found at the
+"Axis2Home/samples" directory.</p></div><div class="subsection"><a name="EchoNonBlockingDualClient"></a><h3>EchoNonBlockingDualClient</h3><p>The solution provided by the Non-Blocking API has one limitation when it
+comes to Web Service invocations which takes long time to complete. The
+limitation is due to the use of single transport connection to invoke the Web
+Service and to retrieve the response. In other words, client API provides a
+non blocking invocation mechanism for the users, but the request and the
+response comes in a single transport (Two-Way transport) connection (like
+HTTP). Long running Web Service invocations or Web Service invocations using
+One-Way transports (like SMTP) cannot be utilized by simply using a non
+blocking invocation. </p><p>The trivial solution is to use separate transport connections (either
+One-Way or Two-Way) for the request and response. The next problem that needs
+to be solved is the correlation (correlating the request and the response).
+<a href="http://www.w3.org/Submission/ws-addressing/" class="newWindow" title="New Window" target="_blank">WS-Addressing</a> provides a neat solution to this using
+<wsa:MessageID> and <wsa:RelatesTo> headers. Axis2 provides
+support for addressing based correlation mechanism and a complying Client
+API to invoke Web Services with two transport connections. (Core of Axis2
+does not depend on WS-Addressing, but contains a set of parameters like in
+addressing that can be populated in any means. WS-Addressing is one of the
+users that may populate them. Even the transports can populate these. Hence
+Axis2 has the flexibility to use different versions of addressing)</p><p>Users can select between Blocking or Non-Blocking APIs for the Web Service
+clients with two transport connections. By simply using a boolean flag, the
+same API can be used to invoke web services (IN-OUT operations) using two
+separate transport connections. Let's see how it's done using an example.
+Following code fragment shows how to invoke the same "echo" operation using
+Non-Blocking API with two transport connections<strong>. The ultimate
+asynchrony!!</strong></p>
+ <div class="source"><pre> try {
+ OMElement payload = ClientUtil.getEchoOMElement();
+ Options options = new Options(); options.setTo(targetEPR); options.setListenerTransportProtocol(Constants.TRANSPORT_HTTP);
+
+ //The boolean flag informs the axis2 engine to use two separate transport connection
+ //to retrieve the response. options.setUseSeparateListener(true);
+
+ Call call = new Call(); call.setClientOptions(options);
+
+ //Callback to handle the response
+ Callback callback = new Callback() {
+ public void onComplete(AsyncResult result) {
+ try {
+ StringWriter writer = new StringWriter();
+ result.serializeWithCache(new OMOutput(XMLOutputFactory.newInstance()
+ .createXMLStreamWriter(writer)));
+ writer.flush();
+
+ System.out.println(writer.toString());
+
+ } catch (XMLStreamException e) {
+ reportError(e);
+ }
+ }
+
+ public void reportError(Exception e) {
+ e.printStackTrace();
+ }
+ };
+
+ //Non-Blocking Invocation
+ call.invokeNonBlocking("echo", payload, callback);
+
+ //Wait till the callback receives the response.
+ while (!callback.isComplete()) {
+ Thread.sleep(1000);
+ }
+
+
+ } catch (AxisFault axisFault) {
+ axisFault.printStackTrace();
+ } catch (Exception ex) {
+ ex.printStackTrace();
+ }
+
+</pre></div>
+ <p><font color="#0000ff"><font color="#000000">The boolean flag (value true)
+in the "<b>call.setUseSeparateListener(...)</b>" method informs the Axis2
+engine to use separate transport connections for request and response.
+Finally "<b>call.close()</b>" informs the Axis2 engine to stop the client
+side listener started to retrieve the response.</font></font></p><p>Before we run the sample client we have one more step to perform. As
+mentioned earlier Axis2 uses addressing based correlation mechanism, hence we
+need to "engage" addressing module in the server side as well. According to
+the Axis2 architecture, addressing module is deployed in the
+"<strong>pre-dispatch</strong>" phase (See <a href="Axis2ArchitectureGuide.html" class="newWindow" title="New Window" target="_blank">Architecture Guide</a> for
+more details about phases) and hence "engaging" means simply adding module
+reference in the "axis2.xml" (NOT the "services.xml"). Now add the following
+line to the "axis2.xml" that you can find in the "/webapps/axis2/WEB-INF"
+directory in the servlet container. </p>
+ <div class="source"><pre> <module ref="addressing"/>
+
+</pre></div>
+ <p>Note: <font color="#000000">Once you change the "axis2.xml" you need to
+restart the servlet container.</font></p><p>This will enable the addressing in the server side. Now you can test the
+"TestEchoNonBlockingDualClient" using the "testEchoNonBlockingDualClient"
+target of the ant file found at "Axis2Home/samples" directory. If you see the
+response OMElement printed in the client side, then you have successfully
+tested the Non Blocking API with two transport channels at the client
+side.</p></div><div class="subsection"><a name="EchoBlockingDualClient"></a><h3>EchoBlockingDualClient</h3><p>This is again a Two-Way transport request/response client, but this time,
+we use a Blocking API in the client code. Sample code for this can be found
+in the "Axis2Home/samples/userguide/src/userguide/clients/" directory and the
+explanation is similar to the <a href="#echononblockingdual">EchoNonBlockingDualClient</a>, except that here
+we do not use a callback object to handle response. This is a very useful
+mechanism when the service invocation is IN-OUT in nature and the transports
+are One-Way (e.g. SMTP). For the sample client we use two HTTP connections
+for request and response. User can test this client using the
+"echoBlockingDualClient" target of the ant build file found in the
+"Axis2Home/samples" directory.</p><p>See <a href="http-transport.html" class="newWindow" title="New Window" target="_blank">Configuring
+Transports</a> for use different transports.</p></div><div class="subsection"><a name="Writing_Web_Service_Clients_using_Code_Generation_with_Data_Binding_Support"></a><h3>Writing Web Service Clients using Code Generation with Data Binding Support</h3><p>Axis2 provides the data binding support for Web Service client as well.
+The user can generate the required stubs from a given WSDL with the other
+supporting classes. Let's generate stubs for the WSDL used earlier to
+generate the skeleton for the "Axis2SampleDocLitPortType". Simply run the
+WSDL2Java tool that can be found in the bin directory of the Axis2
+distribution using the following command:</p>
+ <div class="source"><pre>WSDL2Java -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -o ..\samples\src -p org.apache.axis2.userguide
+
+</pre></div>
+ <p>This will generate the required stub "Axis2SampleDocLitPortTypeStub.java"
+that can be used to invoke the Web Service Axis2SampleDocLitPortType. Let's
+see how we can use this stub to write Web Service clients to utilize the Web
+Service Axis2SampleDocLitPortType (the service that we have already
+deployed).</p></div><div class="subsection"><a name="Client_for_echoVoid_Operation"></a><h3>Client for echoVoid Operation</h3><p>Following code fragment shows the necessary code for utilizing the
+echoVoid operation of the Axis2SampleDocLitPortType that we have already
+deployed. In this operation, a blank SOAP body element is sent to the Web
+Service and the same SOAP envelope is echoed back.</p>
+ <div class="source"><pre> try {
+ //Create the stub by passing the AXIS_HOME and target EPR.
+ //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
+ Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+ stub.echoVoid();
+
+} catch (Exception e) {
+ e.printStackTrace();
+}
+
+</pre></div>
+ </div><div class="subsection"><a name="Client_for_echoString_Operation"></a><h3>Client for echoString Operation</h3><p>Following code fragment shows the necessary code for utilizing the
+echoString operation of the Axis2SampleDocLitPortType that we have already
+deployed. The code is very simple to understand and the explanations are in
+the form of comments.</p>
+ <div class="source"><pre>try {
+ //Create the stub by passing the AXIS_HOME and target EPR.
+ //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
+ Axis2SampleDocLitPortTypeStub stub= new Axis2SampleDocLitPortTypeStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+ //Create the request document to be sent.
+ EchoStringParamDocument reqDoc= EchoStringParamDocument.Factory.newInstance();
+ reqDoc.setEchoStringParam("Axis2 Echo");
+ //invokes the web service.
+ EchoStringReturnDocument resDoc=stub.echoString(reqDoc);
+ System.out.println(resDoc.getEchoStringReturn());
+
+ } catch (Exception e) {
+ e.printStackTrace();
+ }
+
+</pre></div>
+ <p>Similarly following code fragments show client side code for
+echoStringArray operation and echoStruct operation respectively.</p></div><div class="subsection"><a name="Client_for_echoStringArray_Operation"></a><h3>Client for echoStringArray Operation</h3>
+ <div class="source"><pre>try {
+ //Create the stub by passing the AXIS_HOME and target EPR.
+ //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
+ Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+
+ //Create the request document to be sent.
+ EchoStringArrayParamDocument reqDoc = EchoStringArrayParamDocument.Factory.newInstance();
+ ArrayOfstringLiteral paramArray = ArrayOfstringLiteral.Factory.newInstance();
+
+ paramArray.addString("Axis2");
+ paramArray.addString("Echo");
+
+ reqDoc.setEchoStringArrayParam(paramArray);
+ EchoStringArrayReturnDocument resDoc = stub.echoStringArray(reqDoc);
+
+ //Get the response params
+ String[] resParams = resDoc.getEchoStringArrayReturn().getStringArray();
+
+ for (int i = 0; i < resParams.length; i++) {
+ System.out.println(resParams[i]);
+ }
+ } catch (Exception e) {
+ e.printStackTrace();
+ }
+
+</pre></div>
+ </div><div class="subsection"><a name="Client_for_echoStruct_Operation"></a><h3>Client for echoStruct Operation</h3>
+ <div class="source"><pre>try {
+ //Create the stub by passing the AXIS_HOME and target EPR.
+ //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
+ Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+ //Create the request Document
+ EchoStructParamDocument reqDoc = EchoStructParamDocument.Factory.newInstance();
+
+ //Create the complex type
+ SOAPStruct reqStruct = SOAPStruct.Factory.newInstance();
+
+ reqStruct.setVarFloat(100.50F);
+ reqStruct.setVarInt(10);
+ reqStruct.setVarString("High");
+
+ reqDoc.setEchoStructParam(reqStruct);
+
+ //Service invocation
+ EchoStructReturnDocument resDoc = stub.echoStruct(reqDoc);
+ SOAPStruct resStruct = resDoc.getEchoStructReturn();
+
+ System.out.println("floot Value :" + resStruct.getVarFloat());
+ System.out.println("int Value :" + resStruct.getVarInt());
+ System.out.println("String Value :" + resStruct.getVarString());
+
+} catch (Exception e) {
+ e.printStackTrace();
+}
+
+</pre></div>
+ </div><div class="subsection"><a name="Modules"></a><h3>Modules</h3><p>Axis2 provides an extended support for modules (See <a href="Axis2ArchitectureGuide.html">Architecture Guide</a> for more details
+about modules in Axis2). Let's create a custom module and deploy it to the
+MyService which we created earlier. Following steps shows 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></div><div class="subsection"><a name="MyService_with_a_Logging_Module"></a><h3>MyService with a Logging Module</h3><p>Let's write a simple logging module for our sample. 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. Following diagram shows
+the file structure inside that 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" width="185" height="120" border="0" alt=""></img></p></div><div class="subsection"><a name="Step1_:_LoggingModule_Class"></a><h3>Step1 : LoggingModule Class</h3><p>LoggingModule is the implementation class of the Axis2 module. Axis2
+modules should implement the "org.apache.axis2.modules.Module" interface with
+the following methods.</p>
+ <div class="source"><pre>public void init(AxisConfiguration axisSystem) throws AxisFault;//Initialize the module
+public void shutdown(AxisConfiguration axisSystem) throws AxisFault;//End of module processing
+
+</pre></div>
+ <p>These methods can be used to control the module initialization and the
+termination. With the input parameter AxisConfiguration user is provided with
+the complete configuration hierarchy. This can be used to fine-tune the
+module behavior using the module writers. For the simple logging service we
+can keep these methods blank in our implementation class.</p></div><div class="subsection"><a name="Step2_:_LogHandler"></a><h3>Step2 : LogHandler</h3><p>A module in Axis2 can contain, one or more handlers that perform various
+SOAP header processing at different phases. (See<a href="Axis2ArchitectureGuide.html" class="newWindow" title="New Window" target="_blank"> Architecture Guide</a>
+for more information about phases). For the logging module we will write a
+handle with the following methods. "public void invoke(MessageContext ctx);"
+is the method that is called by Axis2 engine when the control is passed to
+the handler. "public void revoke(MessageContext ctx);" is called when the
+handlers are revoked by the Axis2 engine.</p>
+ <div class="source"><pre>public class LogHandler extends AbstractHandler implements Handler {
+ private Log log = LogFactory.getLog(getClass());
+ private QName name;
+
+ public QName getName() {
+ return name;
+ }
+
+ public void invoke(MessageContext msgContext) throws AxisFault {
+ log.info(msgContext.getEnvelope().toString());
+ }
+
+ public void revoke(MessageContext msgContext) {
+ log.info(msgContext.getEnvelope().toString());
+ }
+
+ public void setName(QName name) {
+ this.name = name;
+ }
+}
+
+</pre></div>
+ </div><div class="subsection"><a name="Step3_:_module_xml"></a><h3>Step3 : module.xml</h3><p>"module.xml" contains the deployment configurations for a particular
+module. It contains details such as Implementation class of the module (in
+this example it is the "LoggingModule" class and various handlers that will
+run in different phases). "module.xml" for the logging module will be as
+follows:</p>
+ <div class="source"><pre><module name="logging" class="userguide.loggingmodule.LoggingModule ">
+ <inflow>
+ <handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase" />
+ </handler>
+ </inflow>
+
+ <outflow>
+ <handler name="OutFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
+ </outflow>
+
+ <Outfaultflow>
+ <handler name="FaultOutFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
+ </Outfaultflow>
+
+ <INfaultflow>
+ <handler name="FaultInFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+ <order phase="loggingPhase"/>
+ </handler>
+ </INfaultflow>
+</module>
+
+</pre></div>
+ <p>As it can be seen there are four phases defined in this "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>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. The value of class
+attribute is the actual implementation class for this handler. Since we are
+writing logging handler, we can reuse the same handler in all these phases.
+However this may not be the same for all the modules. "<order
+phase="loggingPhase" />" describes the phase in which this handler
+runs.</p>
+ <div class="source"><pre><handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler">
+<order phase="loggingPhase" />
+</handler>
+
+</pre></div>
+ </div><div class="subsection"><a name="Step_4:_Modify_the_"axis2_xml""></a><h3>Step 4: Modify the "axis2.xml"</h3><p>In this handler the phase "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 Axis2 engine
+knows where to place the handler in different "flows" ( InFlow, OutFlow,
+etc.). Following xml lines show the respective changes made to the
+"axis2.xml" in order to deploy this logging module in Axis2 engine. This is
+an extract of the phase section of the "axis2.xml".</p>
+ <div class="source"><pre><!-- ================================================= -->
+<!-- Phases -->
+<!-- ================================================= -->
+<phaseOrder type="inflow">
+<!-- System pre defined phases -->
+ <phase name="TransportIn"/>
+ <phase name="PreDispatch"/>
+ <phase name="Dispatch"/>
+ <phase name="PostDispatch"/>
+<!-- System pre defined phases -->
+
+<!-- After Postdispatch phase module author or or service author can add any phase he want -->
+ <phase name=""/>
+</phaseOrder>
+
+<phaseOrder type="outflow">
+<!-- user can add his own phases to this area -->
+ <phase name=""/>
+</phaseOrder>
+
+<phaseOrder type="INfaultflow">
+<!-- user can add his own phases to this area -->
+ <phase name=""/>
+</phaseOrder>
+
+<phaseOrder type="Outfaultflow">
+<!-- user can add his own phases to this area -->
+ <phase name=""/>
+</phaseOrder>
+
+</pre></div>
+ <p>Shown 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 now will be executed in this phase.</p></div><div class="subsection"><a name="Step5_:_Modify_the_"services_xml""></a><h3>Step5 : Modify the "services.xml"</h3><p>Up to this point we have created the required classes and configuration
+descriptions for the logging module and by changing the "axis2.xml" we have
+created the required phases for the logging module. 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 the
+similar operations. The code for this service can be found in the
+"Axis2Home/samples/userguide/src/userguide/example2" directory. The simple
+changes that we have done to "services.xml' are shown in green in the
+following lines of xml.</p>
+ <div class="source"><pre><service name="">
+ <description>
+ This is a sample Web Service with a logging module engaged.
+ </description>
+
+ <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></div>
+ <p>In this example we have changed the service name (the implementation class
+is very similar to what we have used earlier although it is in a different
+package). In addition we have added the line <b>"<module
+ref="logging"/>"</b> to "services.xml". This informs the Axis2 engine that
+the module "logging" should be engaged for this service. The handler inside
+the module will be executed in their respective phases as described by the
+"module.xml".</p><p><b><a name="step6loggingmodule">Step6 : Packaging</a></b></p><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. Or you can find the "Logging.mar" that is already created
+for you in the "Axis2Home/samples/userguide" directory.</p></div><div class="subsection"><a name="Step7_:_Deploy_the_Module_in_Axis2"></a><h3>Step7 : Deploy the Module in Axis2</h3><p>Deploying a module in Axis2 require 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 "LoggingModule.mar" in to 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 and see. Deploy this service using the <a href="#step4">same steps
+that you used to deploy "MyService"</a> and copy the "LoggingModule.mar" file
+to the "modules" directory. Then run using the
+"TestWebServiceWithModuleClient.bat" or "TestWebServiceWithModuleClient.sh"
+in the "Axis2Home/samples/userguide/src/userguide/clients/bin" directory.</p><p>Note: To see the logs, the user needs to modify the "log4j.properties" to
+log INFO. The property file is located in "webapps\axis2\WEB-INF\classes" of
+your servlet container. Change the line "log4j.rootCategory= ERROR, LOGFILE"
+to "log4j.rootCategory=INFO, ERROR, LOGFILE".</p></div><div class="subsection"><a name="Other_Samples"></a><h3>Other Samples</h3><p>To show the power of usage of Axis2, three standard samples are shipped
+with the binary distribution. These are meant to interact with outside web
+services and prove the capabilities of the Axis2 system.</p><p>The included samples are</p><ul>
+ <li>Google spell checker sample</li>
+ <li><p style="margin-bottom: 0in">Google search sample</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Amazon queuing sample</p>
+ </li>
+</ul><p>A simple introduction to each of the above samples are given below. Each
+sample contains it's own help document that speaks about the usage and the
+advanced operations of that particular sample.</p><p>The most obvious place to look for the samples are the binary
+distribution. All these samples are included in the samples directory in the
+binary distribution. The shell scripts and the batch files are in fact
+written to use the binary distribution's root directory as the home in order
+to find the libraries.</p><p>The alternate method is to build the samples from source. Moving to the
+modules/samples and running maven will create the samples in the
+target/samples directory. However if the samples need to be started using the
+shell scripts (or the batch files) then the AXIS_HOME environment need to be
+set.( the "guessed" AXIS_HOME would not be correct in this case)</p></div><div class="subsection"><a name="Google_Spell_Checker_Sample"></a><h3>Google Spell Checker Sample</h3><p>This includes a spell checker program that uses the Google spell checking
+service. It demonstrates the blocking and non-blocking modes of calling the
+service. This sample can be found at the samples\googleSpellcheck directory
+and can be easily started using either the batch file or the shell script.</p></div><div class="subsection"><a name="Google_Search_Sample"></a><h3>Google Search Sample</h3><p>This includes a search program that uses the familiar Google search over
+the SOAP API. It utilizes the non-blocking mode of the client API. This
+sample can be found at the samples\googleSearch directory and can be easily
+started using either the batch file or the shell script.</p></div><div class="subsection"><a name="Amazon_Queuing_Service"></a><h3>Amazon Queuing Service</h3><p>Amazon queuing service sample shows how to use the Amazon queuing service.
+It has two user interfaces , one to enqueue and the other dequeue. This
+sample is included in the samples\amazonQS directory and also contains the
+batch/shell scripts required to run sample.</p></div><div class="subsection"><a name="Advanced_Topics"></a><h3>Advanced Topics</h3><ul>
+ <li><a href="rest-ws.html" class="newWindow" title="New Window" target="_blank">RESTful Web Services</a></li>
+ <li><p style="margin-bottom: 0in"><a href="tcp-transport.html" class="newWindow" title="New Window" target="_blank">TCP transport</a></p>
+ </li>
+ <li><p style="margin-bottom: 0in"><a href="mail-transport.html" class="newWindow" title="New Window" target="_blank">Mail Transport</a></p>
+ </li>
+ <li><p style="margin-bottom: 0in"><a href="http-transport.html" class="newWindow" title="New Window" target="_blank">HTTP Transports</a></p>
+ </li>
+ <li><p><a href="mtom-guide.html" class="newWindow" title="New Window" target="_blank">MTOM with Axis2</a></p>
+ </li>
+ <li><a href="security-module.html" class="newWindow" title="New Window" target="_blank">Securing SOAP Messages
+ with WSS4J</a></li>
+</ul></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2006, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/site/trunk/targets/axis2/0_94/webadminguide.html
URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_94/webadminguide.html?rev=366133&view=auto
==============================================================================
--- webservices/site/trunk/targets/axis2/0_94/webadminguide.html (added)
+++ webservices/site/trunk/targets/axis2/0_94/webadminguide.html Thu Jan 5 01:17:47 2006
@@ -0,0 +1,135 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis 2.0 - Axis2 administartion guide</title><style type="text/css" media="all">
+ @import url("./style/maven-base.css");
+
+ @import url("./style/maven-theme.css");</style><link rel="stylesheet" href="./style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Apache Axis 2.0" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 05 January 2006
+ | Doc for 0.94</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis_2_0"><h5>Axis 2.0</h5><ul><li class="none"><a href="index.html">Home</a></li><li class="expanded"><a href="">Download Axis2</a><ul><li class="none"><a href="download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink" title="External Link">Source Code</a></li></ul></li><li class="expanded"><a href="">Documentation</a><ul><li class="none"><a href="0_93/index.html">Version 0.93</a></li><li class="none"><a href="0_94/index.html">Version 0.94</a></li></ul></li><li class="expanded"><a href="overview.html">Get Involved</a><ul><li class="none"><a href="svn.html">Checkout the Source</a></li><li class="none"><a href="siteHowTo.html">Build the Site</a></li><li class="none"><a href="guidelines.html">Developer Guidelines</a></li><li cl
ass="none"><a href="refLib.html">Reference Library</a></li><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><li class="none"><a href="faq.html">FAQ</a></li></ul></li><li class="none"><a href="thanks.html">Ackknowledgements</a></li><li class="expanded"><a href="">Project Information</a><ul><li class="none"><a href="team-list.html">Project Team</a></li><li class="none"><a href="issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="./images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Axis2_Web_Administration_Guide"></a><h2>Axis2 Web Administration Guide</h2><p><i>Version 0.94</i></p><i>Feedback: <a href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i><div class="subsection"><a name="Contents"></a><h3>Contents</h3><ul>
+ <li><a href="#Intro">Introduction</a>
+ <ul>
+ <li><p><a href="#login">Login into Administration Site</a></p>
+ </li>
+ </ul>
+ </li>
+ <li><a href="#adminoptions">Administration Options</a>
+ <ul>
+ <li><p><a href="#tools">Tools</a></p>
+ <ul>
+ <li><a href="#upservice">Upload Service</a></li>
+ </ul>
+ </li>
+ <li><p><a href="#syscomponents">System components</a></p>
+ <ul>
+ <li><a href="#heading1">Available services</a></li>
+ <li><a href="#servgroups">Available service groups</a></li>
+ <li><a href="#avmodules">Available modules</a></li>
+ <li><a href="#globalmodules">Globally engaged modules</a></li>
+ <li><a href="#phases">Available phases</a></li>
+ </ul>
+ </li>
+ <li><p><a href="#executionchains">Execution chains</a></p>
+ <ul>
+ <li><a href="#globalchains">Global chains</a></li>
+ <li><a href="#operationchains">Operation specific chains</a></li>
+ </ul>
+ </li>
+ <li><p><a href="#engaginmodule">Engage module</a></p>
+ </li>
+ <li><a href="#services">Services</a>
+ <ul>
+ <li><a href="#turnoffservice">Undeploy service</a></li>
+ <li><a href="#editservicepara">Edit service parameters</a></li>
+ </ul>
+ </li>
+ <li><p><a href="#context">Contexts</a></p>
+ <ul>
+ <li><a href="#viewhierarchy">View Hierarchy</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+</ul></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><p>Axis2 Web Administration Module provides a way to configure Axis2
+dynamically. It's important to note that this dynamic configuration will NOT
+be persistent, i.e. if the servlet container is restarted then all the
+dynamic configuration changes will be lost.</p></div><div class="subsection"><a name="Login_into_Administration_Site"></a><h3>Login into Administration Site</h3><p>From <a href="#homepage">Axis2 Web Application Home page</a> you can go to
+Administration page by following 'Administration' link, then login page shown
+below will appear requesting user name and a password. The default user name
+is 'admin' (without quotes) and default password is 'axis2' (without
+quotes).</p><p align="left"><strong><img src="images/adminlogin.jpg" alt=""></img></strong></p><p>You can change the user name & password values by changing following
+two parameters in axis2.xml as required.</p><p align="left"><strong><img src="images/parameters.jpg" alt=""></img></strong></p><p>If the login is successful you will see the screen below. This is where
+you can view the configuration and the state of the running system and
+dynamically configure it.</p><p align="left"><strong><img src="images/admin.jpg" alt=""></img></strong></p></div><div class="subsection"><a name="Administration_Options"></a><h3>Administration Options</h3><ul>
+ <b><a name="tools">Tools</a></b>
+ <ul>
+ <li><a href="#upservice">Upload Service</a></li>
+ </ul>
+ <b><a name="syscomponents">System components</a></b>
+ <ul>
+ <li><a href="#heading1">Available services</a></li>
+ <li><a href="#servgroups">Available service groups</a></li>
+ <li><a href="#avmodules">Available modules</a></li>
+ <li><a href="#globalmodules">Globally engaged modules</a></li>
+ <li><a href="#phases">Available phases</a></li>
+ </ul>
+ <b><a name="executionchains">Execution chains</a></b>
+ <ul>
+ <li><a href="#globalchains">Global chains</a></li>
+ <li><a href="#operationchains">Operation specific chains</a></li>
+ </ul>
+ <b><a href="#engaginmodule">Engage module</a></b> <br></br>
+ <br></br>
+ <b><a name="services">Services</a></b>
+ <ul>
+ <li><a href="#turnoffservice">Undeploy service</a></li>
+ <li><a href="#editservicepara">Edit service parameters</a></li>
+ </ul>
+ <b><a name="context">Contexts</a></b>
+ <ul>
+ <li><a href="#viewhierarchy">View Hierarchy</a></li>
+ </ul>
+</ul></div><div class="subsection"><a name="Axis2_Web_Application_Home_Page"></a><h3>Axis2 Web Application Home Page</h3><p align="left"><strong><img src="images/clip_image006.jpg" alt=""></img></strong></p></div><div class="subsection"><a name="Upload_Services"></a><h3>Upload Services</h3><p>You can upload packaged Axis2<em> </em>service archive files using this
+page. This can be done in two simple steps:</p><ul>
+ <li>Browse to the location and select the axisService archive file you wish
+ to upload</li>
+ <li>then click Upload</li>
+</ul><p align="left"><strong><img src="images/clip_image010.jpg" alt=""></img></strong></p></div><div class="subsection"><a name="Available_Services"></a><h3>Available Services</h3><p>The functionality of the 'Available Services' option is almost same as the
+functionality of Axis2 Web Application Home page 'Services' option where it
+displays the list of deployed services. But as an additional feature, if
+there are any modules engaged globally to services or operations those
+details will also be displayed here.</p><p align="left"><strong><img src="images/adminmain.jpg" alt=""></img></strong></p></div><div class="subsection"><a name="Available_Service_Groups"></a><h3>Available Service Groups</h3><p>Service group is a logical collection of set of services and 'Available
+Service Groups' link will list all the available service groups in the system
+.</p><p align="left"><strong><img src="images/servicegroups.jpg" alt=""></img></strong></p></div><div class="subsection"><a name="Available_Modules"></a><h3>Available Modules</h3><p>To view the available modules in the 'modules' directory of the
+'repository' click 'Available Modules' link. This will show you all the
+available modules in the system. Those modules can be engaged dynamically.</p><p align="left"><strong><img src="images/modules.jpg" alt=""></img></strong></p><br></br></div><div class="subsection"><a name="Globally_Engaged_Modules"></a><h3>Globally Engaged Modules</h3><p>From the 'Globally Engaged Modules' link you can view globally engaged
+modules, if any. If a module was engaged globally then the handlers that
+belong to that module will be executed irrespective of the service.</p><br></br></div><div class="subsection"><a name="Available_Phases"></a><h3>Available Phases</h3><p>'Available Phases' link will display all the avaliable phases. In Axis2
+there are two levels of phases:</p><ul>
+ <li>System predefined phases (not allowed to be changed)</li>
+ <li>User defined phases</li>
+</ul><p>The main difference between these two levels is that system predefined
+phases will be invoked irrespective of the services, while user defined
+phases will be invoked when the dispatcher finds the operation. Note that it
+is essential for module developers and service writers to have a good
+understanding of phases and phase ordering.</p><img src="images/viewphases.jpg" alt=""></img><br></br></div><div class="subsection"><a name="Global_Chains"></a><h3>Global Chains</h3><p>'Global Chains' link will display all the Global Execution Chains. The
+most interesting feature of Axis2 Web Administration Module is that it
+provides a very basic way of viewing the global phase list and handlers
+inside the phases depending on both phase and handler orders. This kind of
+information is extremely useful in debugging the system, as there is no other
+way to list out handlers in the global chains. If you engage a new module,
+the new handlers will be added to the global chains and displayed on this
+page.</p><p align="left"><strong><img src="images/globalchain.jpg" alt=""></img></strong></p><br></br></div><div class="subsection"><a name="Operation_Specific_Chains"></a><h3>Operation Specific Chains</h3><p>The 'Operation Specific Chains' link can be used to view the handlers
+corresponding to a given service in the same order as it is in the real
+execution chain.</p><p align="left"><strong><img src="images/serviceHandlers.jpg" alt=""></img></strong></p><br></br></div><div class="subsection"><a name="Engaging_Modules"></a><h3>Engaging Modules</h3><p>'Engaging Modules' link allows to engage modules either globally (to all
+services), to a service group, to a service or to an operation depending on
+the module implementation. If the module was designed to engage the handlers
+globally then handlers in the module can be included in any phase in the
+system. It can be either system predefined or user defined phase.</p><p>On the other hand, if the module was implemented in such a way that it is
+going to be deployed to a service or to an operation, then the module canNOT
+be included in any of the <a href="#phases">System Predefined Phases</a>.
+Thus it can only be included in <a href="#phases">User Defined Phases</a>.</p><p>Immediately after engaging the module you can see the status of engagement
+indicating whether it is engaged properly or not.</p><p align="left"><strong><img src="images/moduleengage.jpg" alt=""></img></strong></p><p> </p></div><div class="subsection"><a name="Undeploy_Service"></a><h3>Undeploy Service</h3><p>This functionality provide a way to remove unnecessary services from the
+running system, but the removal is transient which means if you restart the
+system the service will be available.</p><p align="left"><strong><img src="images/removeservice.jpg" alt=""></img></strong></p><br></br></div><div class="subsection"><a name="Edit_Service_Parameters"></a><h3>Edit Service Parameters</h3><p>This functionality provide a way to change parameters in a service or its
+operations.These changes will be transient too, which means if you restart
+the system changes will not be reflected.</p><p align="left"><strong><img src="images/editserviecpara.jpg" alt=""></img></strong></p></div><div class="subsection"><a name="View_Hierarchy"></a><h3>View Hierarchy</h3><p>By listing current context hierarchy 'View Hierarchy' link provides a
+means to look at the run time system. This will list out all the available
+service group contexts , service contexts , operation context and etc.</p><p></p></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2006, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file