You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by ch...@apache.org on 2006/11/01 10:44:00 UTC
svn commit: r469839 -
/webservices/axis2/branches/java/1_1/xdocs/1_1/userguide.html
Author: chatra
Date: Wed Nov 1 01:44:00 2006
New Revision: 469839
URL: http://svn.apache.org/viewvc?view=rev&rev=469839
Log:
reviewed and committing patch in jira AXIS2-1562. Thanks karthiga.
Modified:
webservices/axis2/branches/java/1_1/xdocs/1_1/userguide.html
Modified: webservices/axis2/branches/java/1_1/xdocs/1_1/userguide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/userguide.html?view=diff&rev=469839&r1=469838&r2=469839
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/userguide.html (original)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/userguide.html Wed Nov 1 01:44:00 2006
@@ -6,16 +6,17 @@
</head>
<body dir="ltr" lang="en-US">
-<h1 align="center"><a name="_Toc96697849" id="_Toc96697849">Apache</a> Axis2
-User's Guide</h1>
+<a name="_Toc96697849" id="_Toc96697849"></a>
+<h1 align="center"> Apache Axis2 User's Guide</h1>
<p>This guide will help you get started with Axis2, the next generation of
-Apache Axis! It describes in details how to write Web services and Web
+Apache Axis! It describes in detail how to write Web services and Web
service clients using Axis2; how to write custom modules and how to use them
with a Web service. Advanced Topics and Samples which are shipped with the
binary distribution of Axis2, are also discussed.</p>
-<h2><a name="Introduction">Introduction</a></h2>
+<a name="Introduction"></a>
+<h2>Introduction</h2>
<p>This User's Guide is written based on <a
href="../download/1_1/download.html/#std-bin">Axis2 Standard Binary
@@ -35,7 +36,8 @@
href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a>". Make sure
to prefix the subject of the mail with [Axis2].</p>
-<h2><a name="Web_Services_Using_Axis2">Getting Started</a></h2>
+<a name="Web_Services_Using_Axis2"></a>
+<h2>Getting Started</h2>
<p>First two sections of the user guide will walk you through writing and
deploying a new Web Service using Axis2, and writing a Web Service client
@@ -60,8 +62,8 @@
<p>If you are looking for "How to Write a Web Service Client using Axis2?"
please go to the <a href="#client">next section</a>. Axis2 provides two ways
to create new Web Services, using code generation and using XML based primary
-APIs. Following section explains how to start from a WSDL, and create a new
-Service with code generation. For the XML based primary API Please refer to
+APIs. The following section explains how to start from a WSDL, and create a new
+Service with code generation. For the XML based primary API please refer to
the section <a href="xmlbased-server.html">Writing Web Services Using Axis2's
Primary APIs</a> for more information. However if you are a new user it is
better to follow the code generation approach first (given below)</p>
@@ -83,7 +85,8 @@
<li>Deploy the Web service</li>
</ol>
-<h3><a name="Step1_:Generate_skeleton">Step1: Generate Skeleton Code</a></h3>
+<a name="Step1_:Generate_skeleton"></a>
+<h3>Step1: Generate Skeleton Code</h3>
<p>To generate the skeleton and required classes, you can use the WSDL2Java
tool provided in Axis2. This tool is located in the bin directory of the
@@ -92,7 +95,7 @@
href="reference.html#wsdl2code">Axis2 Reference Document</a>.</p>
<p>The parameters for wsdl2java tool in our example are as follows. Please
-not that, we use xmlbeans as the data binding framework and generated code
+note that we use xmlbeans as the data binding framework and generated code
will be sent to samples directory. Other data binding tools you could use are
adb (Axis data binding) and jaxme (<a
href="http://ws.apache.org/jaxme/">JaxMe data binding</a>)</p>
@@ -104,14 +107,15 @@
directory<strong></strong>. Note that these are not source files and should
be available in the class path in order to compile the generated classes.</p>
-<h3><a name="Step2_Implement_Business_Logic">Step 2: Implement Business
-Logic</a></h3>
+<a name="Step2_Implement_Business_Logic"></a>
+<h3>Step 2: Implement Business
+Logic</h3>
-<p>Now you should fill in the business logic in the skeleton class. You can
+<p>Now you should fill the business logic in the skeleton class. You can
find the skeleton class -Axis2SampleDocLitServiceSkeleton.java- among the
generated classes in the
<strong>"samples/src/org/apache/axis2/userguide</strong> directory. Let's
-fill the echoString(..) method in the skeleton as shown below. Our sample
+fill the <code>echoString(..)</code> method in the skeleton as shown below. Our sample
WSDL-Axis2SampleDocLit.wsdl in <strong>"samples/wsdl"</strong> directory has
three operations: echoString, echoStringArray, echoStruct. To see how others
will look when they are filled up see <a
@@ -119,13 +123,14 @@
Axis2SampleDocLitService Service</a></p>
<pre>public org.apache.axis2.userguide.xsd.EchoStringReturnDocument echoString<br> (org.apache.axis2.userguide.xsd.EchoStringParamDocument param4) throws Exception {<br> //Use the factory to create the output document.<br> org.apache.axis2.userguide.xsd.EchoStringReturnDocument retDoc = org.apache.axis2.userguide.xsd.EchoStringReturnDocument.Factory.newInstance();<br> //send the string back.<br> retDoc.setEchoStringReturn(param4.getEchoStringParam());<br> return retDoc;<br> }</pre>
-<h3><a name="Step4_Create_archive">Step 3: Create Archive File</a></h3>
+<a name="Step4_Create_archive"></a>
+<h3>Step 3: Create Archive File</h3>
<p>An Axis2 service must be bundled as a service archive. The next step is to
package the classes in an .aar (axis2 archive) and deploy it in Axis2. There
-is an ant file generated with the code, that will generate the Axis2 service
+is an ant file generated with the code, this will generate the Axis2 service
archive for you. However if you do not want to use ant, you could create
-archive with following steps</p>
+archive with following steps :</p>
<ol>
<li>Compile the generated code</li>
<li>Copy <strong>"resources/schemaorg_apache_xmlbeans</strong>" xmlbeans
@@ -146,14 +151,15 @@
<p><img src="images/userguide/DirectoryStructure.jpg" align="bottom"
border="0"></p>
-<h3><a name="Step5_Deploy_web_service">Step 4: Deploy Web Service</a></h3>
+<a name="Step5_Deploy_web_service"></a>
+<h3>Step 4: Deploy Web Service</h3>
-<p>The service can be deployed by simply dropping the ".aar" file in to
+<p>The service can be deployed by simply dropping the ".aar" file into
"services" directory in "/webapps/axis2/WEB-INF" of your servlet container.
We recommend using <a href="http://tomcat.apache.org/">Apache Tomcat</a> as
servlet container. <strong>Please Note that the services directory is
-available only after axis2.war is exploded by Tomcat. However the easiest way
-to do it is to start tomcat after axis2.war is copied to the webapps
+available only after axis2.war is exploded by Tomcat. However, the easiest way
+to do it is to start Tomcat after axis2.war is copied to the webapps
directory</strong> (if you have not already started). Check the link
"Services" on the <a href="http://localhost:8080/axis2/" target="_blank">Home
Page of Axis2 Web Application</a> (http://localhost:8080/axis2) and see
@@ -169,17 +175,18 @@
href="webadminguide.html" target="_blank">Web Administration Guide</a> for
more information on this)</p>
-<h2><a name="client">Writing a Web Service Client</a></h2>
+<a name="client"></a>
+<h2>Writing a Web Service Client</h2>
<p>Axis2 also provides a more complex, yet powerful <strong>XML based client
API</strong> which is intended for advanced users. Read <a
href="dii.html">Writing Web Service Clients Using Axis2's Primary APIs</a> to
-learn more about it. However, if you are a new user we recommend using code
-generation approach presented below</p>
+learn more about it. However, if you are a new user we recommend using the code
+generation approach presented below.</p>
<h3>Generate Stubs</h3>
-<p>Lets see how we could generate java code (Stub) to handle the client side
+<p>Let's see how we could generate java code (Stub) to handle the client side
Web Service invocation for you. That can be done by running the WSDL2Java
tool using following arguments</p>
<pre style="margin-bottom: 0.2in;">WSDL2Java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -d xmlbeans -o ../samples/src -p org.apache.axis2.userguide</pre>
@@ -190,9 +197,9 @@
"Axis2SampleDocLitServiceStub.java"</p>
<p>Axis2 clients can invoke Web Services both in blocking and non-blocking
-manner. In a blocking invocation the client waits till the service performs
+manner. In a blocking invocation, the client waits till the service performs
its task without proceeding to the next step. Normally the client waits till
-the response to the particular request arrives. In a non-blocking invocation
+the response to the particular request arrives. In a non-blocking invocation,
the client proceeds to the next step immediately and any responses (if any)
are handled using a Callback mechanism. Please note that some explanations
use the terms Synchronous and Asynchronous to describe the similar invocation
@@ -203,7 +210,7 @@
<p>The following code fragment shows the necessary code calling
<code>echoString</code> operation of the
<code>Axis2SampleDocLitService</code> that we have already deployed. The code
-is very simple to understand and the explanations are in the form of
+is extremely simple to understand and the explanations are in the form of
comments.</p>
<pre> try {<br> org.apache.axis2.userguide.Axis2SampleDocLitServiceStub stub = new<br> org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,<br> "http://localhost:8080/axis2/services/Axis2SampleDocLitService");<br> <br> //Create the request document to be sent.<br> org.apache.axis2.userguide.xsd.EchoStringParamDocument reqDoc =<br> org.apache.axis2.userguide.xsd.EchoStringParamDocument.Factory.newInstance();<br> reqDoc.setEchoStringParam("Axis2 Echo");<br> <br> //invokes the Web service.<br> org.apache.axis2.userguide.xsd.EchoStringReturnDocument resDoc = stub.echoString(reqDoc);<br> System.out.println(resDoc.getEchoStringReturn());<br><br> } catch (java.rmi.RemoteException e) {<br> e.printStackTrace();<br> }<br></pre>
@@ -217,7 +224,7 @@
<h3>Do a Non-Blocking Invocation</h3>
-<p>The stubs also includes a method that allows you to do a non-blocking
+<p>The stubs also include a method that allows you to do a non-blocking
innovation, for each method in the Service there will be a method
<strong>start<method-name></strong>. These methods accept a callback
object which would be called when the response is received. Sample code that
@@ -225,8 +232,8 @@
<pre> try {<br> org.apache.axis2.userguide.Axis2SampleDocLitServiceStub stub = new<br> org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,<br> "http://localhost:8080/axis2/services/Axis2SampleDocLitService");<br><br> //implementing the callback online<br> org.apache.axis2.userguide.Axis2SampleDocLitServiceCallbackHandler callback =<br> new org.apache.axis2.userguide.Axis2SampleDocLitServiceCallbackHandler() {<br><br> public void receiveResultechoString(org.apache.axis2.userguide.xsd.EchoStringReturnDocument resDoc) {<br> System.out.println(resDoc.getEchoStringReturn());<br> }<br> };<br><br> org.apache.axis2.userguide.xsd.EchoStringParamDocument reqDoc = <br> org.apache.axis2.userguide.xsd.EchoStringParamDocument.Factory.newInstance();<br> reqDoc.setEchoStringParam("Axis2
Echo");<br> stub.startechoString(reqDoc, callback);<br> } catch (java.rmi.RemoteException e) {<br> e.printStackTrace();<br> }<br></pre>
<p>Even though the above code does a non-blocking invocation at the client
-API, still the transport connection may operate in blocking fashion; for
-example a single HTTP connection can be used to make the Web Service request
+API, the transport connection may still operate in blocking fashion. For
+example, a single HTTP connection can be used to make the Web Service request
and to get the response where a blocking invocation happens at the transport
level. To perform a "true" Non-Blocking invocation in which two separate
transport connections are used for the request and the response please add
@@ -235,7 +242,7 @@
client uses a Callback to process the response.</p>
<pre>stub._getServiceClient().engageModule(new QName("addressing"));<br>stub._getServiceClient().getOptions().setUseSeparateListener(true);<br></pre>
-<p>Once those options are set, Axis2 client does following</p>
+<p>Once those options are set, Axis2 client does the following:</p>
<ol>
<li>Start a new Transport Listener(Server) at the client side</li>
<li>Set the address of the Transport Listener, as the ReplyTo WS-Addressing
@@ -248,22 +255,23 @@
<h3>Using Your Own Repository</h3>
-<p>You could use your own repository with Axis2 Client, Following code shows
+<p>You could use your own repository with Axis2 Client, code below shows
how to do this.</p>
<pre>String axis2Repo = ...<br>String axis2xml = ...<br>ConfigurationContext configContext = <br> ConfigurationContextFactory.createConfigurationContextFromFileSystem(axis2Repo, axis2xml);<br>Service1Stub stub1 = new Service1Stub(configContext,...);<br>//invoke Service1<br><br>Service2Stub stub2 = new Service2Stub(configContext,...);<br>//invoke Service2<br>.....<br></pre>
-<p>Note by creating the the <code>ConfigurationContext</code> out side and
+<p>Note by creating the <code>ConfigurationContext</code> outside and
passing it to the stubs, you could make number of stubs to use same
repository, thus saving the configuration loading overhead from each
request.</p>
-<h2><a name="config">Configuring Axis2</a></h2>
+<a name="config"></a>
+<h2>Configuring Axis2</h2>
<h3>Axis2 Repository</h3>
<p>Axis2 configuration is based on a repository and standard archives
formats. A repository is a directory in the file system and it should have
-the followings.</p>
+the following:</p>
<ol>
<li><strong>axis2.xml</strong>, the Axis2 global deployment descriptor in
conf/axis2.xml file</li>
@@ -305,7 +313,7 @@
becomes available and can be engaged at global, service or operation scopes.
Once engaged it becomes active (add handlers to the execution flow) at the
respective scope. Please refer to <a href="Axis2ArchitectureGuide.html">Axis2
-architecture guide</a> for detailed explanation. Following table explains the
+architecture guide</a> for detailed explanation. The following table explains the
semantics of scope and how to engage modules in those scopes.</p>
<table border="1">
@@ -339,10 +347,10 @@
</tbody>
</table>
-<p>* If a handler is added to a service, or a operation it will be invoked
+<p>* If a handler is added to a service or an operation, it will be invoked
for every request received by that service or operation</p>
-<p>Axis2 provides number of built in Modules such as (<a
+<p>Axis2 provides a number of built in Modules such as (<a
href="">addressing</a>,<a href="">Security</a>, <a href="">WS-Reliable
Messaging</a> ...), and they can be engaged as shown above. Please refer to
each module for how to use and configure them. You can also <a
@@ -354,11 +362,11 @@
<p>WS-Addressing support for Axis2 is implemented by the addressing module.
To enable addressing you need to engage the addressing module in both server
-and client sides. In order to do this</p>
+and client sides. In order to do this:</p>
<ol>
<li>To <strong>enable</strong> addressing at the server side you need to
copy addressing.mar file to modules directory of server's axis2
- repository. To engage module add a <module ref="addressing"/> to
+ repository. To engage the module, add a <module ref="addressing"/> to
axis2.xml. <strong>Addressing module can be engaged only at global
level</strong></li>
<li>To <strong>enable</strong> addressing at the client side you should add
@@ -372,7 +380,8 @@
</li>
</ol>
-<h2><a name="advanced">Advanced Topics</a></h2>
+<a name="advanced"></a>
+<h2>Advanced Topics</h2>
<h3>Transports</h3>
@@ -380,7 +389,7 @@
supports HTTP, SMTP, TCP and JMS transports. You can also write your own
transports, and deploy them by adding new transportReceiver or
transportSender tags to axis2.xml. To learn how to configure and use
-different transports please refer to following documents.</p>
+different transports please refer the following documents.</p>
<ol>
<li><a href="tcp-transport.html" target="_blank">TCP Transport</a></li>
<li><a href="mail-transport.html" target="_blank">Mail Transport</a></li>
@@ -410,9 +419,9 @@
<h3>Pluggable Data Binding</h3>
-<p>Axis2 ship with Axis Data Binding(ADB) as the default data binding
-framework, however the data binding frameworks are pluggable to axis2, and
-you could use other data binding frameworks with Axis2. Please refer to
+<p>Axis2 ships with Axis Data Binding(ADB) as the default data binding
+framework, however the data binding frameworks are pluggable to Axis2, and
+you could use other data binding frameworks with Axis2. Please refer the
following documents for more information.</p>
<h4>Axis2 Data Binding(ADB)</h4>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org