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 2005/09/26 15:47:03 UTC
svn commit: r291622 [12/13] - in /webservices/site/trunk/targets/axis2: ./
images/archi-guide/ multiproject/axis2-Samples/ multiproject/axis2-Tools/
multiproject/axis2-addressing/ multiproject/axis2-common/
multiproject/axis2-core/ multiproject/axis2-c...
Modified: webservices/site/trunk/targets/axis2/userguide.html
URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/userguide.html?rev=291622&r1=291621&r2=291622&view=diff
==============================================================================
--- webservices/site/trunk/targets/axis2/userguide.html (original)
+++ webservices/site/trunk/targets/axis2/userguide.html Mon Sep 26 06:46:26 2005
@@ -2,83 +2,206 @@
@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/axis/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
- Last published: 09 September 2005
- | Doc for 0.91</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><li class="none"><a href="axis2tools.html">Tools</a></li></ul></li><li class="expanded"><a href="">Getting Started with Axis2</a><ul><li class="none"><a href="installationguide.html">Installation Guide</a></li><li class="none"><a href="userguide.html">User Guide</a></li><li class="none"><a href="webadminguide.html">Web Administration Guide</a></li></ul></li><li class="expanded"><a href="docs.html">Additional Reference</a><ul><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2" class="externalLink" title="External Link">Axis2 Wiki</a></li><li class="none"><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li><li class="none"><a href="OMTutorial.html">AXIOM Tutorial</a></li><li class="none"><a href="CodegenToolReference.html">Code Generation Tutorial</a></li><li class="none"><a href="rest-ws.html">REST Support</a></li><li class="none"><a href="mtom-guide.html">Handling Binary Data with Axis2</a></li><li class="none"><a href="axis2config.html">Axis2 Configuration Guide</a></li><li class="none"><a href="migration.html">Migrating from Axis 1.x</a></li><li class="none"><a href="api/index.html">Online Java Docs</a></li><li class="none"><a href="otherTutorials.html">Other Tutorials</a></li></ul></li><li class="expanded"><a href="overview.html">Get Invloved</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 class="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="expanded"><a href="">Project Information</a><ul><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><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="Axis_2_0_User_s_Guide_"></a><h2>Axis 2.0 User's Guide </h2><p> </p><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><p>Welcome to Axis 2.0, the next generation of Apache Axis !!! This User Guide will help you to understand what you will get from Axis 2.0 and how to get started. We hope you will benefit from the power of Axis 2.0. </p></div><div class="subsection"><a name="Attention"></a><h3>Attention</h3><ul>
-<li>This User Guide is written based on the Axis2 binary distribution, the Binary distribution can be created from the
-source distribution using the maven goal <code>$maven dist-bin</code></li>
-<li>Before we start, its highly recommended to read <a href="http://ws.apache.org/axis/java/user-guide.html" class="externalLink" title="External Link">Axis 1.x User's guide </a>, if you are new to Axis.</li>
-</ul></div><div class="subsection"><a name="What_is_Axis_2_0__"></a><h3>What is Axis 2.0 ?</h3><p>Axis 2.0 is the next generation of Apache Axis. In late August 2004, during the Axis Summit held in Colombo, Sri Lanka, a new architecture was introduced to have a much more flexible, efficient and configurable Axis. Even though the architecture is new, some of the well established concepts from Axis 1.x, like handlers are preserved in Axis 2.0 also. Axis 2.0 comes with lots of new features, enhancements and new industry specification implementations. </p><p>After months of continued discussion and coding effort in this direction, Axis 2.0 now delivers the following key features: </p><ul>
- <li><strong>Speed</strong>. Axis uses its own object model and StAX (streaming) parsing to achieve significantly greater speed than earlier versions of Apache AXIS. </li>
- <li><strong>Low memory foot print</strong>. Axis 2.0 was designed ground-up keeping low memory foot print in mind. </li>
- <li><strong>AXIOM</strong>. Axis 2.0 comes with its own light-weight object model, AXIOM, for message processing which is extensible, high performance and developer convenient </li>
- <li><strong>Hot Deployment.</strong> One can now hot deploy web services and handlers. </li>
- <li><strong>Asynchronous Web Services</strong>. Axis 2.0 now support asynchronous web services invocation and asynchronous web services. </li>
- <li><strong>MEP Support. </strong>Axis 2.0 now comes handy with support for Message Exchange Patterns. </li>
- <li><strong>Flexibility</strong>. The Axis architecture gives the developer complete freedom to insert extensions into the engine for custom header processing, system management, or anything else you can imagine. </li>
- <li><strong>Stability</strong>. Axis defines a set of published interfaces which change relatively slowly compared to the rest of Axis. </li>
- <li><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. </li>
- <li><strong>Transport framework</strong>. We have a clean and simple abstraction for designing 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. </li>
- <li><strong>WSDL support.</strong> Axis 2.0 supports the <a href="http://www.w3.org/TR/wsdl" class="externalLink" title="External Link">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 Axis. </li>
-</ul><p>We hope you enjoy using Axis. 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 feedback about the package 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="What_s_in_this_release_"></a><h3>What's in this release?</h3><p>This release includes the following features:</p><ul>
- <li>AXIOM, a SOAP specific streaming XML infoset model for SOAP 1.1/1.2 Messages</li>
- <li>Support for One-Way Messaging and Request Response Messaging</li>
- <li>Modules, mechanism to extend the SOAP Processing Model</li>
- <li>Archives based deployment Model </li>
- <li>WSDL Code Generation Tool for Stub and skeltons</li>
- <li>XML Beans based data binding support</li>
- <li>Support for WS-Addressing, both the submission and final versions</li>
- <li>Client API</li>
- <li>REST Web Service Support</li>
- <li>HTTP transport Support</li>
- <li>SMTP transport Support</li>
- <li>TCP transport Support</li>
- <li>MTOM/SWA attachments support</li>
- <li>SAAJ implementation</li>
+ Last published: 26 September 2005
+ | Doc for 0.92</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="">Getting Started with Axis2</a><ul><li class="none"><a href="installationguide.html">Installation Guide</a></li><li class="none"><a href="userguide.html">User Guide</a></li><li class="none"><a href="webadminguide.html">Web Administration Guide</a></li></ul></li><li class="expanded"><a href="docs.html">Additional Reference</a><ul><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2" class="externalLink" title="External Link">Axis2 Wiki</a></li><li class="none"><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li><li class="none"><a href="OMTutorial.html">AXIOM Tutorial</a></li><li class="none"><a href="CodegenToolReference.html">Code Generation Tutorial</a></li><li class="none"><a href="rest-ws.html">REST Support</a></li><li class="none"><a href="mtom-guide.html">Handling Binary Data with Axis2</a></li><li class="none"><a href="axis2config.html">Axis2 Configuration Guide</a></li><li class="none"><a href="migration.html">Migrating from Axis 1.x</a></li><li class="none"><a href="api/index.html">Online Java Docs</a></li><li class="none"><a href="otherTutorials.html">Other Tutorials</a></li></ul></li><li class="expanded"><a href="overview.html">Get Invloved</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 class="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="expanded"><a href="">Project Information</a><ul><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><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="Axis_2_0_User_s_Guide"></a><h2>Axis 2.0 User's Guide</h2><div class="subsection"><a name="Contents"></a><h3>Contents</h3><ul>
+ <li><p><a href="#Introduction">Introduction</a></p>
+ </li>
+ <li><p><a href="#What_is_Axis_2_0__">What is Axis 2.0 ?</a></p>
+ </li>
+ <li><p><a href="#Web_Services_Using_Axis2">Web Services Using Axis2</a></p>
+ </li>
+ <li><p><a href="#Web_Service_Clients_Using_Axis2">Web Service Clients Using Axis2</a></p>
+ </li>
+ <li><p><a href="#Modules">Modules</a></p>
+ </li>
+ <li><p><a href="#Other_Samples">Other Samples</a></p>
+ </li>
+ <li><p><a href="#Tools">Tools</a></p>
+ </li>
+ <li><p><a href="#Advanced_Topics">Advanced Topics</a></p>
+ </li>
+</ul><p><br></br>
+<br></br>
+</p></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><p>Welcome to Axis 2.0, the next generation of Apache Axis !!! This User
+Guide will help you to understand what you will get from Axis 2.0 and how to
+get started. We hope you will benefit from the power of Axis 2.0.</p></div><div class="subsection"><a name="Attention"></a><h3>Attention</h3><ul>
+ <li><p style="margin-bottom: 0in">This User Guide is written based on the
+ Axis2 binary distribution, the Binary distribution can be created from
+ the source distribution using the maven goal <code>$maven
+ dist-bin</code></p>
+ </li>
+ <li><p>Before we start, its highly recommended to read <a href="http://ws.apache.org/axis/java/user-guide.html" class="externalLink" title="External Link">Axis 1.x User's
+ guide </a>, if you are new to Axis.</p>
+ </li>
+</ul></div><div class="subsection"><a name="What_is_Axis_2_0__"></a><h3>What is Axis 2.0 ?</h3><p>Axis 2.0 is the next generation of Apache Axis. In late August 2004,
+during the Axis Summit held in Colombo, Sri Lanka, a new architecture was
+introduced to have a much more flexible, efficient and configurable Axis.
+Even though the architecture is new, some of the well established concepts
+from Axis 1.x, like handlers are preserved in Axis 2.0 also. Axis 2.0 comes
+with lots of new features, enhancements and new industry specification
+implementations.</p><p>After months of continued discussion and coding effort in this direction,
+Axis 2.0 now delivers the following key features:</p><ul>
+ <li><p style="margin-bottom: 0in"><strong>Speed</strong>. Axis uses its own
+ object model and StAX (streaming) 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>.
+ Axis 2.0 was designed ground-up keeping low memory foot print in mind.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>AXIOM</strong>. Axis 2.0 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>Hot Deployment.</strong> One can
+ now hot deploy web services and handlers.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>Asynchronous Web
+ Services</strong>. Axis 2.0 now support asynchronous web services
+ invocation and asynchronous web services.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>MEP Support. </strong>Axis 2.0
+ now comes handy with support for Message Exchange Patterns.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>Flexibility</strong>. The Axis
+ architecture gives the developer complete freedom to insert extensions
+ into the engine for custom header processing, system management, or
+ anything else you can imagine.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><strong>Stability</strong>. Axis 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 designing 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><strong>WSDL support.</strong> Axis 2.0 supports the <a href="http://www.w3.org/TR/wsdl" class="externalLink" title="External Link">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 Axis.</p>
+ </li>
+</ul><p>We hope you enjoy using Axis. 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 feedback about the package 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="What_s_in_this_release_"></a><h3>What's in this release?</h3><p>This release includes the following features:</p><ul>
+ <li><p style="margin-bottom: 0in">AXIOM, a SOAP specific streaming XML
+ infoset model for SOAP 1.1/1.2 Messages</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Support for One-Way Messaging and Request
+ Response Messaging</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Modules, mechanism to extend the SOAP
+ Processing Model</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Archives 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">XML Beans based data binding support</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Support for WS-Addressing, both the
+ submission and final versions</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Client API</p>
+ </li>
+ <li><p style="margin-bottom: 0in">REST Web Service Support</p>
+ </li>
+ <li><p style="margin-bottom: 0in">HTTP transport Support</p>
+ </li>
+ <li><p style="margin-bottom: 0in">SMTP transport Support</p>
+ </li>
+ <li><p style="margin-bottom: 0in">TCP transport Support</p>
+ </li>
+ <li><p style="margin-bottom: 0in">MTOM/SWA attachments support</p>
+ </li>
+ <li><p>SAAJ implementation</p>
+ </li>
</ul><p>The release include following tools</p><ol>
- <li>Admin Web App</li>
- <li>WSDL2WS, eclipe Plugin/Command line version</li>
- <li>Service Archive Wizard, eclipe Plugin</li>
- <li>Module Archive Wizard, eclipe Plugin</li>
-</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> JAX-RPC 1.1 and/or JAX-WS compliance</li>
- <li> Pluggable Data binding support</li>
- <li> SOAP Encoding</li>
- <li> Binary serialization and deserialization support</li>
- <li> Management Interface for Axis2</li>
- <li> Complete XML infoset support for AXIOM</li>
- <li> Implementation of other transports. e.g. JMS..</li>
- <li> Web Service Policy Support</li>
-</ul><p>
-
-</p></div><div class="subsection"><a name="Samples"></a><h3>Samples</h3><p>In this section of the user guide we will look at how to write and deploy Web Services and how to write Web Service Clients using Axis2. All the
-user guide samples are located at the <b> <span class="style9">
-<font color="#000000">"samples/userguide/src"</font></span></b> directory
-of the binary distribution. So.. let's explore the samples.</p><p>Note: Please note that the rest of this user guide assumes that the user has downloaded the binary distribution of Axis2. If you have already downloaded the source tree of Axis2 then please create the binary distribution by simply using the maven command <strong>maven dist-bin </strong>This will create the "axis2-0.91-bin.zip" and "axis2-0.91-bin.tar" in the "target/dist" directory. Extract the zip or the tar ball to any
-directory in your machine and for the explanations purposes we will name this
-directory as "Axis2Home". </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">Installation Guide</a>). User can
-select any of the following two ways of writing web services using Axis2. </p><ul>
- <li>Use Axis2's primary interfaces and implement the business logic.</li>
- <li>Start from the WSDL ->Code generate the Skeleton ->Implement the
- Business Logic.</li>
-</ul></div><div class="subsection"><a name="Write_My_Service_using_Axis2"></a><h3>Write My Service using Axis2</h3></div><div class="subsection"><a name="MyService"></a><h3>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><pre>public void ping(OMElement element){} //IN-ONLY operation, just accepts the OMElement and do some processing.
+ <li><p style="margin-bottom: 0in">Admin Web App</p>
+ </li>
+ <li><p style="margin-bottom: 0in">WSDL2WS, eclipse Plugin/Command line
+ version</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Service Archive Wizard, eclipse Plugin</p>
+ </li>
+ <li><p>Module Archive Wizard, eclipse Plugin</p>
+ </li>
+</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">Pluggable Data binding support</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">Complete XML infoset support for AXIOM</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Implementation of other transports. e.g.
+ JMS..</p>
+ </li>
+ <li><p>Web Service Policy Support</p>
+ </li>
+</ul></div><div class="subsection"><a name="Samples"></a><h3>Samples</h3><p>In this section of the user guide we will look at how to write and deploy
+Web Services and how to write Web Service Clients using Axis2. All the user
+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><p>Note: Please note that the rest of this user guide assumes that the user
+has downloaded the binary distribution of Axis2. If you have already
+downloaded the source tree of Axis2 then please create the binary
+distribution by simply using the maven command <strong>maven dist-bin
+</strong>This will create the "axis2-0.91-bin.zip" and "axis2-0.91-bin.tar"
+in the "target/dist" directory. Extract the zip or the tar ball to any
+directory in your machine and for the explanations purposes we will name this
+directory as "Axis2Home".</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">Installation Guide</a>). User can select any of
+the following two ways of writing web services using Axis2. </p><ul>
+ <li><p style="margin-bottom: 0in">Use Axis2's primary interfaces and
+ implement the business logic.</p>
+ </li>
+ <li><p>Start from the WSDL ->Code generate the Skeleton ->Implement
+ the Business Logic.</p>
+ </li>
+</ul></div><div class="subsection"><a name="Write_My_Service_using_Axis2"></a><h3>Write My Service using Axis2</h3></div><div class="subsection"><a name="MyService"></a><h3>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></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 are doing. So 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>Write a new Web Service with Axis2 involve four steps</p><ol>
- <li>Write the Implementation Class</li>
- <li>Write a service.xml file to explain the Web Service</li>
- <li>create a *.aar archive for the Web Service</li>
- <li>Deploy the Web Service</li>
-</ol></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><pre>
-public class MyService{
+ //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 are doing. So 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>Write a new Web Service with Axis2 involve four steps</p><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 for the Web
+ Service</p>
+ </li>
+ <li><p>Deploy the Web Service</p>
+ </li>
+</ol></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){
......
}
@@ -86,98 +209,139 @@
......
}
}
-</pre></pre></div>
- </div><div class="subsection"><a name="Step2_:Write_the_service_xml_file"></a><h3>Step2 :Write the service.xml file</h3><p>Axis2 uses "service.xml" to keep configurations for a Web Service. Each Web Service deployed
-in Axis2 needs a "service.xml" containing the configurations. "service.xml" for MyService will be as follows; we will see what each parameter means later.</p>
- <div class="source"><pre><pre><service name="MyService"><br></br> <description><br></br> This is a sample Web Service with two operations, echo and ping.<br></br> </description><br></br> <parameter name="ServiceClass" locked="xsd:false">userguide.example1.MyService</parameter><br></br> <operation name="echo"><br></br> <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/><br></br> </operation><br></br> <operation name="ping"><br></br> <messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/><br></br> </operation><br></br> </service></pre></pre></div>
- <p>As it can be seen, first line of the "service.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 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></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. So,
-for MyService we will use "MyService.aar" with the "service.xml" packaged
-in the META-INF as shown in the following picture.</p><p><img src="images/userguide/ServiceItems.jpg" width="176" height="91" 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,
-and let's use it.. </p></div><div class="subsection"><a name="Step4_:Depoly_the_Web_Service"></a><h3>Step4 :Depoly 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 and hence please copy the "MyService.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 "List Available services" in the page http://localhost:8080/axis2/index.jsp and see whether the MyService is deployed properly. If
-everything is ok, you will see the following out put.. </p><p align="center"><img src="images/userguide/MyServiceDeployed.jpg" alt=""></img> </p><p>If you can see the above output then you have successfully deployed MyService on Axis2. Now let's see how we can write Web Service client to use this services.
-Axis2 provides an easy way to deploy a Web Services using, index.jsp. (See the
-installation guide for more information on this)</p></div><div class="subsection"><a name="Axis2SampleDocLitPortType"></a><h3>Axis2SampleDocLitPortType</h3><p>Now 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="Generating_Skeleton"></a><h3>Generating Skeleton</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><pre>
-Usage WSDL2Code -uri <location of="" wsdl=""> :WSDL file location
--o <output location=""> : output file location
+
+</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; we will see
+what each parameter means later.</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>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. Next
+comes the description and the service class. 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>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. So, 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, and let's use it..</p></div><div class="subsection"><a name="Step4_:Depoly_the_Web_Service"></a><h3>Step4 :Depoly 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 and hence please copy the "MyService.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 "List
+Available services" in the page http://localhost:8080/axis2/index.jsp and see
+whether the MyService is deployed properly. If everything is ok, you will see
+the following out put..</p><p align="center"><img src="images/userguide/MyServiceDeployed.jpg" name="Graphic2" align="bottom" width="734" height="766" border="0" alt=""></img></p><p>If you can see the above output then you have successfully deployed
+MyService on Axis2. Now let's see how we can write Web Service client to use
+this services. Axis2 provides an easy way to deploy a Web Services using,
+index.jsp. (See the installation guide for more information on this)</p></div><div class="subsection"><a name="Axis2SampleDocLitPortType"></a><h3>Axis2SampleDocLitPortType</h3><p>Now 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="Generating_Skeleton"></a><h3>Generating Skeleton</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 <package name=""> : set custom package name
--l <language> : valid languages are java and csharp. Default is java
+-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
-</language></package></output></location></pre>
+
</pre></div>
- <p>We will use the tool with the following parameters and generate the skeleton and the other
-required classes.</p>
- <div class="source"><pre><pre>
-WSDL2Java -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -ss -sd -o ..\samples\src -p org.apache.axis2.userguide
-</pre></pre></div>
- <p>This will generate the required classes in the <b>src</b> directory inside
-samples. This will also generate the schema classes in a directory named <b>
-schema</b> and please 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/usreguide directory
-with the name "Axis2SampleDocLitPortTypeSkeleton.java". This is the skeleton for
-our web service and we can easily fill the business logic now. The WSDL we have
-used has four operations as follows.</p><ul>
- <li>echoVoid - Operation that does not accept any input
- parameters and also provide no out put parameters. Just perform some
- task</li>
- <li>echoString - Operation that echos a String value </li>
- <li>echoStringArray - Operation that accept string array as the input and
- echos them back</li>
- <li>echoStruct - Operation that accept a Struct as the input and echos them
- back.</li>
-</ul></div><div class="subsection"><a name="echoVoid "></a><h3>echoVoid </h3><p>Locate the following code segment in the
-"Axis2SampleDocLitPortTypeSkeleton.java" and fill the business
-logic. For the explanation purpose we do not need anything to be implemented
-here.</p>
- <div class="source"><pre><pre>
-public void echoVoid(){
- //Todo fill this with the necessary business logic
-}
-</pre></pre></div>
- </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><pre>
- public org.soapinterop.xsd.EchoStringArrayReturnDocument
- echoStringArray(org.soapinterop.xsd.EchoStringArrayParamDocument param2){
+ <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 seperator</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. This will also generate the schema classes in a directory named
+<b>schema</b> and please 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 easily fill the business logic now. The WSDL
+we have used has three operations as follows.</p><ul>
+
+ <li><p style="margin-bottom: 0in">echoString - Operation that echos a
+ String value </p>
+ </li>
+ <li><p style="margin-bottom: 0in">echoStringArray - Operation that accept
+ string array as the input and echos them back</p>
+ </li>
+ <li><p>echoStruct - Operation that accept a Struct as the input and echos
+ 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){
//Todo fill this with the necessary business logic
return null;
}
-</pre>
+
</pre></div>
- <p>Once filled with the business logic it will be as follows. The code is simple
-and the explanations are given in the comments.</p>
- <div class="source"><pre><pre>
-public org.soapinterop.xsd.EchoStringReturnDocument
- echoString(org.soapinterop.xsd.EchoStringParamDocument param6) {
+ <p>Once filled with the business logic it will be as follows. The code is
+simple and the explanations are given in the 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></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><pre>
-public org.soapinterop.xsd.EchoStringArrayReturnDocument
- echoStringArray(org.soapinterop.xsd.EchoStringArrayParamDocument param2) {
+
+</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();
@@ -193,12 +357,12 @@
//return the output document.
retDoc.setEchoStringArrayReturn(retParams);
return retDoc;
-}</pre>
+}
+
</pre></div>
</div><div class="subsection"><a name="echoStruct"></a><h3>echoStruct</h3>
- <div class="source"><pre><pre>
-public org.soapinterop.xsd.EchoStructReturnDocument
- echoStruct(org.soapinterop.xsd.EchoStructParamDocument param4) {
+ <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();
@@ -217,20 +381,17 @@
retDoc.setEchoStructReturn(outStruct);
return retDoc;
-}</pre></pre></div>
- </div><div class="subsection"><a name="service_xml"></a><h3>service.xml</h3><p> Axis2 uses "service.xml" to hold the
-configuretions 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 service.xml for this web service as well and it can be found in the
-same directory as the skeleton. The generated service.xml is as follows.</p>
- <div class="source"><pre><pre>
-<!--Auto generated Axis Service XML-->
+}
+
+</pre></div>
+ </div><div class="subsection"><a name="services_xml"></a><h3>services.xml</h3><p> Axis2 uses "services.xml" to hold the configuretions 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 and it 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 echoVoid-->
-<operation name="echoVoid">
-<messageReceiver class="userguide.Axis2SampleDocLitPortTypeMessageReceiver"/>
-</operation>
<!--Mounting the method echoStringArray-->
<operation name="echoStringArray">
<messageReceiver class="userguide.Axis2SampleDocLitPortTypeMessageReceiver"/>
@@ -244,81 +405,116 @@
<messageReceiver class="userguide.Axis2SampleDocLitPortTypeMessageReceiver"/>
</operation>
</service>
-</pre></pre></div>
- <p>As it can be seen, first line of the "service.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 as well. These schema related
-classes are located in the <b>schema </b>directory of the generated code. Copy
-this to your class path and 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 border="0" src="images/userguide/DirectoryStructure.JPG" width="164" height="142" 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 in the directory structure shown above) and
+
+</pre></div>
+ <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. 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 as well.
+These schema related classes are located in the <b>schema </b>directory of
+the generated code. Copy this to your class path and 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" name="Graphic3" 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 in the directory structure shown above) and
type the following command in a command line.</p>
- <div class="source"><pre><pre>
-jar -cf echo.aar .
-</pre></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 and hence please 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 "List Available services" in the page http://localhost:8080/axis2/index.jsp and see whether the
-Axis2SampleDocLitPortType is deployed properly. If
-everything is ok, you will see the following out put.. </p><p align="center">
-<img border="0" src="images/userguide/ServiceDeployed.JPG" alt=""></img> </p><p>If you can see the above output then you have successfully deployed
-Axis2SampleDocLitPortType on Axis2. Now let's see how we can write Web Service client to use this services.
-Axis2 provides an easy way to deploy a Web Services using, index.jsp. (See the
-installation guide 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> 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 in 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 '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><b>Blocking API</b> -Once the service invocation is called, the client
- application hangs and gets the control back only when the operation completes
- and the client receives a response or a fault. This is the simplest way of
- invoking Web Services and suites many business situations.</li>
- <li><b>Non-Blocking API </b>- A callback or polling based API and 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 with out blocking on the operation already
- invoked.</li>
-</ul><p> Both these mechanism works in the API level and let's name the
-asynchronous behavior that we can get using the Non-Blocking API 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 of these mechanisms fail to address the problem of long
-running transactions (the transport connection may times-out before the
-operation completes). A possible solution would be to use two separate transport
-connections for request and response. The asynchronous behavior that we gain
-using can be called, <b>Transport Level Asynchrony</b>.</p><p> By combining the two we can obtain four different invocation patterns for web
-services as shown in the following table.</p><table class="bodyTable"><tr class="b"><td width="33%" height="19">API (Blocking/Non-Blocking)</td><td width="33%" height="19"> Dual Transports (Yes/No)</td><td width="33%" height="19">Description</td></tr><tr class="a"><td width="33%" height="19">Blocking</td><td width="33%" height="19">No</td><td width="33%" height="19">Simplest and the familiar invocation pattern</td></tr><tr class="b"><td width="33%" height="19">Non-Blocking</td><td width="33%" height="19">No</td><td width="33%" height="19">Using callbacks or polling</td></tr><tr class="a"><td width="33%" height="19">Blocking</td><td width="33%" height="19">Yes</td><td width="33%" height="19">This is useful when the service operation is
- IN-OUT in nature but the transport used is One-Way (e.g. SMTP)</td></tr><tr class="b"><td width="33%" height="19">Non-Blocking</td><td width="33%" height="19">Yes</td><td width="33%" height="19">This is can be used to gain the maximum
- asynchronous behavior. No blocking in the API level and also in the
- transport level</td></tr></table><p>Axis2 provides the user with all these possibilities to invoke Web Services.
-In addition Axis2 provides a data binding support making the life easy for
-developers writing Web Service client applications. In this user guide we will
-first see how we can write Web Service clients using the Axis2's primary APIs
-and later we will see how we can use generated stubs to simply write Web Service
-Clients.</p></div><div class="subsection"><a name="Using_Axis2_s_Primary_APIs"></a><h3>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. First let's see how we can write a client to invoke "echo" operation of "MyService" using the simplest good old blocking invocation. The client code that you need to write will be as follows.</p>
- <div class="source"><pre><pre> try {
+ <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 and hence please 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 "List
+Available services" in the page http://localhost:8080/axis2/index.jsp and see
+whether the Axis2SampleDocLitPortType is deployed properly. If everything is
+ok, you will see the following out put..</p><p align="center"><img src="images/userguide/ServiceDeployed.JPG" name="Graphic4" align="bottom" width="734" height="764" border="0" alt=""></img></p><p>If you can see the above output then you have successfully deployed
+Axis2SampleDocLitPortType on Axis2. Now let's see how we can write Web
+Service client to use this services. Axis2 provides an easy way to deploy a
+Web Services using, index.jsp. (See the installation guide 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>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 in 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 '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 gets the control
+ back only when the operation completes and the client receives a response
+ or a fault. This is the simplest way of invoking Web Services and suites
+ many business situations.</p>
+ </li>
+ <li><p><b>Non-Blocking API </b>- A callback or polling based API and 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 with out
+ blocking on the operation already invoked.</p>
+ </li>
+</ul><p>Both these mechanism works in the API level and let's name the
+asynchronous behavior that we can get using the Non-Blocking API 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 of these mechanisms fail to address the problem of long
+running transactions (the transport connection may times-out before the
+operation completes). A possible solution would be to use two separate
+transport connections for request and response. The asynchronous behavior
+that we gain using can be called, <b>Transport Level Asynchrony</b>.</p><p>By combining the two 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>API (Blocking/Non-Blocking)</p>
+ </td><td width="33%"><p> Dual Transports (Yes/No)</p>
+ </td><td width="33%"><p>Description</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. In addition Axis2 provides a data binding support making the life
+easy for developers writing Web Service client applications. In this user
+guide we will first see how we can write Web Service clients using the
+Axis2's primary APIs and later we will see how we can use generated stubs to
+simply write Web Service Clients.</p></div><div class="subsection"><a name="Using_Axis2_s_Primary_APIs"></a><h3>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. First let's see how we can write a client to invoke
+"echo" operation of "MyService" using the simplest good old blocking
+invocation. The client code that you need to write will be as follows.</p>
+ <div class="source"><pre> try {
OMElement payload = ClientUtil.getEchoOMElement();
- <span class="style10">Call call = new Call();
- call.setTo(targetEPR);
- call.setTransportInfo(Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, false);
+
+
+
+
+
- OMElement result = (OMElement) call.invokeBlocking("echo", payload);
-</span>
StringWriter writer = new StringWriter();
result.serializeWithCache(new OMOutput(XMLOutputFactory.newInstance().createXMLStreamWriter(writer)));
writer.flush();
@@ -331,12 +527,18 @@
e.printStackTrace();
}
}
-</pre></pre></div>
- <p>The green lines shows the set of operations that you need to perform in-order to invoke a web service while the rest is used to create the OMElement that needs to be sent and to display the response OMElement. To test this
-client you can 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 as well. </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 Web Services Using Axis2). So let's write a client to invoke this operation as well.
-The client code will be as follows.</p>
- <div class="source"><pre><pre> try {
+
+</pre></div>
+ <p>The green lines shows the set of operations that you need to perform
+in-order to invoke a web service while the rest is used to create the
+OMElement that needs to be sent and to display the response OMElement. To
+test this client you can 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 as well. </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 Web Services Using Axis2). So let's write a client to invoke this
+operation as well. The client code will be as follows.</p>
+ <div class="source"><pre> try {
OMElement payload = ClientUtil.getPingOMElement();
MessageSender msgSender = new MessageSender();
@@ -347,37 +549,67 @@
} catch (AxisFault axisFault) {
axisFault.printStackTrace();
}
-</pre></pre></div>
- <p>Since we are accessing a IN-ONLY operation we can directly use the "MessageSender" to invoke this operation. As it can be seen in the above code , it is very straight forward to invoke this type of 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>Ok, 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 the 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><pre>call.invokeNonBlocking("echo", payload, callback);</pre></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><pre>public abstract void onComplete(AsyncResult result);
+
+</pre></div>
+ <p>Since we are accessing a IN-ONLY operation we can directly use the
+"MessageSender" to invoke this operation. As it can be seen in the above code
+, it is very straight forward to invoke this type of 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>Ok, 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 the 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></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 connection (needs two way transports 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="externalLink" title="External Link">WS-Addressing</a> provides a neat solution to above 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, and it is the addressing like
-properties, 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 we can do it 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><pre> try {
+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 connection (needs two way transports
+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="externalLink" title="External Link">WS-Addressing</a>
+provides a neat solution to above 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,
+and it is the addressing like properties, 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 we can do it 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();
Call call = new Call();
@@ -385,8 +617,8 @@
//The boolean flag informs the axis2 engine to use two separate transport connection
//to retrieve the response.
- <font color="#33CC00">call.engageModule(new QName(Constants.MODULE_ADDRESSING));</font>
- call.setTransportInfo(Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, <span class="style13">true</span>);
+
+ call.setTransportInfo(Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, );
//Callback to handle the response
Callback callback = new Callback() {
@@ -394,7 +626,7 @@
try {
StringWriter writer = new StringWriter();
result.serializeWithCache(new OMOutput(XMLOutputFactory.newInstance()
- .createXMLStreamWriter(writer)));
+ .createXMLStreamWriter(writer)));
writer.flush();
System.out.println(writer.toString());
@@ -415,82 +647,92 @@
//Wait till the callback receives the response.
while (!callback.isComplete()) {
Thread.sleep(1000);
- }</pre></pre></div>
-
- <div class="source"><pre><pre> <font color="#33CC00">call.close();</font>
+ }
+
} catch (AxisFault axisFault) {
axisFault.printStackTrace();
} catch (Exception ex) {
ex.printStackTrace();
}
-</pre></pre></div>
- <p>The three changes that we need do to the EchoNonBlockingClient are shown in the "green" color. Since our correlation mechanism is based on addressing we need
-to first "<strong>engage</strong>" the addressing module.<span class="style15">
-<font color="#000000"><b>"call.engageModule(new
-QName(Constants.MODULE_ADDRESSING));" </b>informs the Axis2 engine to engage the
-addressing module at the client side. The boolean flag (value true) in the "<br></br>
-<b>call.setTransportInfo(...)</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></span></p><p>Before we run the sample client we need one more step to perform. As mentioned earlier Axis2 uses addressing based correlation
-mechanism and 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="file:///G:/Documents%20and%20Settings/Jaliya/Desktop/Axis2ArchitectureGuide.html">Architecture Guide</a> for more
-details about phases) and hence "engaging" means simply adding module reference in the "axis2.xml" (NOT the "service.xml"). Please 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><pre> <module ref="addressing"/></pre></pre></div>
- <p>Note: Please note that<span class="style15"><font color="#000000"> once you change the "axis2.xml" you need to restart the servlet container.</font></span></p><p>This will enable the addressing in the server side and now you can test the "TestEchoNonBlockingDualClient" using the "testEchoNonBlockingDualClient"
-target of the ant file found at "Axis2Home/samples" directory.
-If you can see the response OMElement printed in the client side, that means 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 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 EchoNonBlockingDualClient, 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="#configTransport">Configuring Transports</a> for use different transports.</p></div><div class="subsection"><a name="With_Data_Binding"></a><h3>With Data Binding</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 see how we can generate the stubs for the
-WSDL we have 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><pre>
-WSDL2Java -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -o ..\samples\src -p org.apache.axis2.userguide
-</pre></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>
-<pre>
- try {
+
+</pre></div>
+ <p>The three changes that we need do to the EchoNonBlockingClient are shown
+in the "green" color. Since our correlation mechanism is based on addressing
+we need to first "<strong>engage</strong>" the addressing module.<font color="#0000ff"> <font color="#000000"><b>"call.engageModule(new
+QName(Constants.MODULE_ADDRESSING));" </b>informs the Axis2 engine to engage
+the addressing module at the client side. The boolean flag (value true) in
+the "<br></br>
+<b>call.setTransportInfo(...)</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 need one more step to perform. As
+mentioned earlier Axis2 uses addressing based correlation mechanism and 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="file:///G:/Documents and Settings/Jaliya/Desktop/Axis2ArchitectureGuide.html">Architecture
+Guide</a> for more details about phases) and hence "engaging" means simply
+adding module reference in the "axis2.xml" (NOT the "services.xml"). Please
+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: Please note that<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 and now you can test
+the "TestEchoNonBlockingDualClient" using the "testEchoNonBlockingDualClient"
+target of the ant file found at "Axis2Home/samples" directory. If you can see
+the response OMElement printed in the client side, that means 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 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 EchoNonBlockingDualClient, 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="#configTransport">Configuring Transports</a> for use
+different transports.</p></div><div class="subsection"><a name="With_Data_Binding"></a><h3>With Data Binding</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 see how we can generate the stubs for the WSDL we
+have 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 sa the AXIS_HOME
Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
- "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
stub.echoVoid();
} catch (Exception e) {
e.printStackTrace();
}
-</pre></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 given in the
-comments.</p>
- <div class="source"><pre><pre>
-try {
+
+</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
+given in the 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 sa the AXIS_HOME
Axis2SampleDocLitPortTypeStub stub= new Axis2SampleDocLitPortTypeStub(null,
- "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
//Create the request document to be sent.
EchoStringParamDocument reqDoc= EchoStringParamDocument.Factory.newInstance();
reqDoc.setEchoStringParam("Axis2 Echo");
@@ -501,16 +743,15 @@
} catch (Exception e) {
e.printStackTrace();
}
-</pre></pre></div>
- <p>Similarly following code fragments shows 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>
-<pre>
-try {
+
+</pre></div>
+ <p>Similarly following code fragments shows 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 sa the AXIS_HOME
Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
- "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
//Create the request document to be sent.
EchoStringArrayParamDocument reqDoc = EchoStringArrayParamDocument.Factory.newInstance();
@@ -531,14 +772,14 @@
} catch (Exception e) {
e.printStackTrace();
}
-</pre></pre></div>
+
+</pre></div>
</div><div class="subsection"><a name="Client_for_echoStruct_Operation"></a><h3>Client for echoStruct Operation</h3>
- <div class="source"><pre><pre>
-try {
+ <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 sa the AXIS_HOME
Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
- "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
//Create the request Document
EchoStructParamDocument reqDoc = EchoStructParamDocument.Factory.newInstance();
@@ -561,42 +802,53 @@
} catch (Exception e) {
e.printStackTrace();
-}</pre></pre></div>
- </div><div class="subsection"><a name="Modules"></a><h3>Modules</h3><p>Axis2 provides an extended support for modules (See
-<a href="file:///G:/Documents%20and%20Settings/Jaliya/Desktop/Axis2ArchitectureGuide.html">Architecture Guide</a> for more details
-about modules in axis2). Let's see how we can create a custom module and deploy
-it to the MyService that we have created earlier. Following steps shows the
-actions that needs to be performed to deploy a custom module for a given Web
-Service.</p><ol>
- <li>Create the Module Implementation</li>
- <li>Create the Handlers</li>
- <li>Create the moduel.xml</li>
- <li>Modify the "axis2.xml" (if you need custom phases)</li>
- <li>Modify the "service.xml" to engage modules at the deployment time.</li>
- <li>Package in a ".mar" (Module Archive)</li>
- <li>Deploy the module in Axis2</li>
-</ol></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 though 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 border="0" src="images/userguide/ModuleView.jpg" width="185" height="120" 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><pre>public void init(AxisConfiguration axisSystem) throws AxisFault;//Initialize the module
+}
+
+</pre></div>
+ </div><div class="subsection"><a name="Modules"></a><h3>Modules</h3><p>Axis2 provides an extended support for modules (See <a href="file:///G:/Documents and Settings/Jaliya/Desktop/Axis2ArchitectureGuide.html">Architecture
+Guide</a> for more details about modules in axis2). Let's see how we can
+create a custom module and deploy it to the MyService that we have created
+earlier. Following steps shows the actions that needs 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>
[... 383 lines stripped ...]