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/12/21 12:07:37 UTC
svn commit: r489321 -
/webservices/axis2/branches/java/1_1/xdocs/1_1/adv-userguide.html
Author: chatra
Date: Thu Dec 21 03:07:36 2006
New Revision: 489321
URL: http://svn.apache.org/viewvc?view=rev&rev=489321
Log:
wsdl2java was made lower case in code
Modified:
webservices/axis2/branches/java/1_1/xdocs/1_1/adv-userguide.html
Modified: webservices/axis2/branches/java/1_1/xdocs/1_1/adv-userguide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/adv-userguide.html?view=diff&rev=489321&r1=489320&r2=489321
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/adv-userguide.html (original)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/adv-userguide.html Thu Dec 21 03:07:36 2006
@@ -1,29 +1,32 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
+ <meta http-equiv="content-type" content="">
<title>Axis2 Advance User's Guide</title>
- <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
</head>
<body dir="ltr" lang="en-US">
<a name="_Toc96697849" id="_Toc96697849"></a>
-<h1 align="center"> Apache Axis2 Advance User's Guide</h1>
-<p>This guide will help you get started with Axis2, the next generation of
-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>
+<h1 align="center">Apache Axis2 Advance User's Guide</h1>
+<p>This guide will help you get started with Axis2, the next generation of
+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>
<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
Distribution</a>. The Standard Binary Distribution can be directly <a
-href="../download/1_1/download.html/#std-bin">downloaded</a> or
-built using the <a href="../download/1_1/download.html#src">Source
-Distribution</a>. If you choose to go for the latter, then <a
+href="../download/1_1/download.html/#std-bin">downloaded</a> or built using
+the <a href="../download/1_1/download.html#src">Source Distribution</a>. If
+you choose to go for the latter, then <a
href="installationguide.html">Installation Guide</a> will instruct you on how
to build Axis2 Standard Binary Distribution using the Source.</p>
@@ -56,16 +59,18 @@
gives you step by step instructions on just how to build axis2.war and deploy
it in your servlet container.</p>
<a name="ws_codegen"></a><a name="Web_Services_Using_Axis2"></a>
+
<h2>Creating a New Web Service</h2>
<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 <strong>code generation</strong> and using XML based primary
-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>
+to create new Web Services, using <strong>code generation</strong> and using
+XML based primary 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>
<h3>Starting with WSDL, Create and Deploy a Service</h3>
@@ -83,8 +88,8 @@
<li>Create a *.aar archive (Axis Archive) for the Web service</li>
<li>Deploy the Web service</li>
</ol>
-
<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
@@ -98,44 +103,38 @@
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>
-<pre>
-WSDL2Java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans
--o ../samples -p org.apache.axis2.userguide
-</pre>
+<pre>wsdl2java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans
+-o ../samples -p org.apache.axis2.userguide</pre>
<p>This will generate the required classes in the <b>"sample/src"</b>
directory, and the schema classes in
<strong>"samples/resources/schemaorg_apache_xmlbeans"</strong>
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>
-
<a name="Step2_Implement_Business_Logic"></a>
-<h3>Step 2: Implement Business
-Logic</h3>
-<p>Now you should fill the business logic in the skeleton class. You can
-find the skeleton class -Axis2SampleDocLitServiceSkeleton.java- among the
+<h3>Step 2: Implement Business Logic</h3>
+
+<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 <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
+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
href="src/Axis2SampleDocLitServiceCode.html">Code Listing For
Axis2SampleDocLitService Service</a></p>
-<source>
-<pre>
-public org.apache.axis2.userguide.xsd.EchoStringReturnDocument
+<source><pre>public org.apache.axis2.userguide.xsd.EchoStringReturnDocument
echoString(org.apache.axis2.userguide.xsd.EchoStringParamDocument param4) throws Exception {
//Use the factory to create the output document.
org.apache.axis2.userguide.xsd.EchoStringReturnDocument retDoc =
org.apache.axis2.userguide.xsd.EchoStringReturnDocument.Factory.newInstance();
//send the string back.
retDoc.setEchoStringReturn(param4.getEchoStringParam());
- return retDoc;<br>
-</pre></source>
+ return retDoc;<br></pre>
+</source><a name="Step4_Create_archive"></a>
-<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
@@ -147,11 +146,14 @@
<li>Compile the generated code</li>
<li>Copy <strong>"resources/schemaorg_apache_xmlbeans</strong>" xmlbeans
classes to your class folder</li>
- <li>Among the generated files, there will be services.xml file, which is the
- deployment descriptor for Axis2 service.[<a
+ <li>Among the generated files, there will be services.xml file, which is
+ the deployment descriptor for Axis2 service.[<a
href="reference.html#servicedd">learn more about it</a>]. Copy the
resources/service.xml to META-INF/services.xml</li>
- <p>(To write your own service.xml file see sub section in <a href="xmlbased-server.html#Step2_:Write_the_services_xml_file">Writing Web Services Using Axis2's Primary APIs</a> section.)</p>
+
+ <p>(To write your own service.xml file see sub section in <a
+ href="xmlbased-server.html#Step2_:Write_the_services_xml_file">Writing Web
+ Services Using Axis2's Primary APIs</a> section.)</p>
<li>Create the archive using content of the class folder. Change directory
to class folder and run <code>jar -cf <service-name>.aar</code> to
create the archive</li>
@@ -162,16 +164,16 @@
<p><img src="images/userguide/DirectoryStructure.jpg" align="bottom"
border="0"></p>
-
<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 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
@@ -179,21 +181,22 @@
<p>We recommend using the exploded configuration to deploy Axis2 WAR in
<strong>WebLogic and WebSphere</strong> application servers to support the
-hotupdate/ hotdeployment features in Axis2. See <a href="app_server.html#weblogic_websphere">Application Server Specific
+hotupdate/ hotdeployment features in Axis2. See <a
+href="app_server.html#weblogic_websphere">Application Server Specific
Configuration Guide</a> for details.</p>
<p>Note: Axis2 provides an easy way to deploy Web Services using the "Upload
Service" tool on Axis2 Web Application's Administration module. (See the <a
href="webadminguide.html" target="_blank">Web Administration Guide</a> for
more information on this)</p>
-
<a name="client"></a>
+
<h2>Writing a Web Service Client</h2>
-<p>Axis2 also provides a more complex, yet powerful XML based client
-API 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 the <strong>code
+<p>Axis2 also provides a more complex, yet powerful XML based client API
+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 the <strong>code
generation</strong> approach presented below.</p>
<h3>Generate Stubs</h3>
@@ -201,12 +204,9 @@
<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>
-<source>
-<pre>WSDL2Java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -d xmlbeans
- -o ../samples/src -p org.apache.axis2.userguide
-</pre></source>
-
-
+<source><pre>wsdl2java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -d xmlbeans
+ -o ../samples/src -p org.apache.axis2.userguide</pre>
+</source>
<p>This will generate client side stubs and xmlbeans types for your types.
The Stub class that you need to use will be of the form
<strong><service-name>Stub</strong>. For our example it will be called
@@ -228,8 +228,7 @@
<code>Axis2SampleDocLitService</code> that we have already deployed. The code
is extremely simple to understand and the explanations are in the form of
comments.</p>
-<source>
-<pre> try {
+<source><pre> try {
org.apache.axis2.userguide.Axis2SampleDocLitServiceStub stub
= new org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,
"http://localhost:8080/axis2/services/Axis2SampleDocLitService");
@@ -243,9 +242,8 @@
System.out.println(resDoc.getEchoStringReturn());
} catch (java.rmi.RemoteException e) {
e.printStackTrace();
- }
-</pre></source>
-
+ }</pre>
+</source>
<p>First argument of <code>Axis2SampleDocLitPortTypeStub</code> should be the
Axis2 repository for the client. Here we use null to make the stub use
default configurations. However you could make Axis2 use your own repository
@@ -261,8 +259,7 @@
<strong>start<method-name></strong>. These methods accept a callback
object which would be called when the response is received. Sample code that
does an asynchronous interaction is given below.</p>
-<source>
-<pre>try {
+<source><pre>try {
org.apache.axis2.userguide.Axis2SampleDocLitServiceStub stub
= new org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,
"http://localhost:8080/axis2/services/Axis2SampleDocLitService");
@@ -280,11 +277,8 @@
stub.startechoString(reqDoc, callback);
} catch (java.rmi.RemoteException e) {
e.printStackTrace();
- }
-</pre>
+ }</pre>
</source>
-
-
<p>Even though the above code does a non-blocking invocation at the client
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
@@ -294,14 +288,9 @@
the following code segment after creating the stub. These will force Axis2 to
use two transport connections for the request and the response while the
client uses a Callback to process the response.</p>
-<source>
-<pre>
-stub._getServiceClient().engageModule(new QName("addressing"));
-stub._getServiceClient().getOptions().setUseSeparateListener(true);
-</pre>
+<source><pre>stub._getServiceClient().engageModule(new QName("addressing"));
+stub._getServiceClient().getOptions().setUseSeparateListener(true);</pre>
</source>
-
-
<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>
@@ -315,28 +304,22 @@
<h3>Using Your Own Repository</h3>
-<p>You could use your own repository with Axis2 Client, code below shows
-how to do this.</p>
-<source>
-<pre>
-String axis2Repo = ...
+<p>You could use your own repository with Axis2 Client, code below shows how
+to do this.</p>
+<source><pre>String axis2Repo = ...
String axis2xml = ...
ConfigurationContext configContext =
ConfigurationContextFactory.createConfigurationContextFromFileSystem(axis2Repo, axis2xml);
Service1Stub stub1 = new Service1Stub(configContext,...);
//invoke Service1
Service2Stub stub2 = new Service2Stub(configContext,...);
-//invoke Service2
-</pre>
+//invoke Service2</pre>
</source>
-
-
-<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>
-
+<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>
<a name="config"></a>
+
<h2>Configuring Axis2</h2>
<h3>Axis2 Repository</h3>
@@ -385,8 +368,8 @@
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. The following table explains the
-semantics of scope and how to engage modules in those scopes.</p>
+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">
<tbody>
@@ -438,8 +421,8 @@
<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 the module, add a <module ref="addressing"/> to
- axis2.xml. <strong>Addressing module can be engaged only at global
+ 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
it to the repository and provide the repository as argument to the <a
@@ -451,8 +434,8 @@
<pre>stub._getServiceClient().engageModule(moduleName)</pre>
</li>
</ol>
-
<a name="advanced"></a>
+
<h2>Advanced Topics</h2>
<h3>Transports</h3>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org