axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sam...@apache.org
Subject cvs commit: ws-axis/site/src/documentation/content/xdocs/cpp/arch WSDL2Ws.ihtml
Date Fri, 22 Oct 2004 04:48:16 GMT
samisa      2004/10/21 21:48:16

  Modified:    site/src/documentation/content/xdocs/cpp/arch WSDL2Ws.ihtml
  Log:
  Added usage information and did some formatting fixes
  
  Revision  Changes    Path
  1.3       +193 -165  ws-axis/site/src/documentation/content/xdocs/cpp/arch/WSDL2Ws.ihtml
  
  Index: WSDL2Ws.ihtml
  ===================================================================
  RCS file: /home/cvs/ws-axis/site/src/documentation/content/xdocs/cpp/arch/WSDL2Ws.ihtml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- WSDL2Ws.ihtml	9 Aug 2004 04:45:00 -0000	1.2
  +++ WSDL2Ws.ihtml	22 Oct 2004 04:48:15 -0000	1.3
  @@ -1,246 +1,274 @@
   <html>
     <head>
       <title>WSDL2Ws Tool </title>
  -
  -    <link href="axis.css" rel=stylesheet type=text/css>
     </head>
  -
     <body>
   
  -<table cellspacing=0 width=100% border=0>
  -<tr>
  -<td colspan=2>
  -<a href="http://xml.apache.org/axis">
  -
  -</a>
  -
  -<h1>
  -WSDL2Ws
  -</h1>
  -</td>
  -</tr>
  -</table>
  -
  -<hr size=1 noshade= />
  -<strong>
  -Contents
  -</strong>
  +<h1>Axis C++ WSDL2Ws Tool</h1>
  +<HR size="1" noshade="noshade">
  +<p><strong>Contents</strong></p>
   
   <p>
  -<a href="#intro">1.Functionality</a> 
  +<a href="#intro">1 Introduction</a> 
   </p>
   
  -<p><a href="#webapp">1.1Types Of Classes</a>
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#codegen">1.1 Source Code Generation</a>
   </p>
   
  -<p><a href="#depend">1.2Programming Languages</a>
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#proglang">1.2 Programming Languages</a>
   </p>
   
  -<p><a href="#websvc">1.3Encoding Style</a>
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#encode">1.3 Encoding Styles</a>
   </p>
   
  -<p><a href="#start">1.4Style Of the Service</a>
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#svcstyle">1.4 Styles of Services</a>
   </p>
   
  -<p><a href="#install-test">1.5Supports for Making Simple Custom Types </a>
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#complext">1.5 Support for Complex
Types </a>
   </p>
   
  -<p><a href="#test">2.Architecture</a>
  +<p>
  +<a href="#usage">2 Using the Tool</a> 
   </p>
   
  -<p><a href="#test1">2.1 Out Line</a>
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#dependencies">2.1 Dependencies
on Axis Java tool</a>
   </p>
   
  -<p><a href="#test2">2.2 Mediator WsContext</a>
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#building">2.2 Building the Tool</a>
   </p>
   
  -<p><a href="#test3">2.3 Generator</a>
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#synopsis">2.3 Synopsis</a>
   </p>
   
  -<p><a href="#test4">2.4 Flow Of Execution</a>
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#classpath">2.4 Setting up CLASSPATH</a>
   </p>
   
  -<p><a href="#test5">2.5 Sequence Diagram</a>
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#runtool">2.5 Running the Tool</a>
   </p>
   
  -<p><a href="#test6">3.Dependencies on Axis Java tool</a>
  +<p>
  +<a href="#test">3 Architecture</a>
   </p>
   
  -<p class="MsoNormal"><span style="font-family:Verdana;color:black">
  -    <a name="intro"></a>
  -      <h1>1. Functionality </h1></P>
  -
  -<p class="MsoNormal"><span style="font-family:Verdana;color:black">
  -
  -      <p>The tool should be able to generate different types of Wrappers and Skeletons
for the server side and client’s stubs for the client’s Side.WSDL2Ws tool in Axis C++  is
written in  Java.
  -    
  -      
  -      
  -      <a name= "webapp"/></a>    
  -    <h2>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1 Types Of
Classes</h2></p>
  -
  -
  -
  -    <p>The tool should start with a WSDL document and generate following classes.</p>
  -     
  -
  -<P class=MsoNormal style="MARGIN-LEFT: 76pt; TEXT-INDENT: -18pt">
  -<SPAN 
  -style="COLOR: black; FONT-FAMILY: Symbol; FONT-SIZE: 10pt">·<SPAN 
  -style="FONT: 7pt 'Times New Roman'">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;

  -</SPAN></SPAN><SPAN style="COLOR: black; FONT-FAMILY: Verdana">WSDL2WS
tool is used for building following C/C++ components<p>
  - &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  o Server side – Skeletons and Wrappers</p>
   <p>
  - &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 o Client side – Stubs</p>
  - </SPAN></P>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#test1">3.1 Outline</a>
  +</p>
   
  -<SPAN 
  -style="COLOR: black; FONT-FAMILY: Symbol; FONT-SIZE: 10pt">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;><SPAN

  -style="FONT: 7pt 'Times New Roman'">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;>

  -</SPAN></SPAN><SPAN style="COLOR: black; FONT-FAMILY: Verdana"> <b>WSDL2WS
tool</b> that generates wrappers which are used to deploy the Service in the Axis C++
engine. (Please refer the Wrapper Specification for more information) </SPAN>
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#test2">3.2 Mediator WebServiceContext</a>
  +</p>
   
  -  <p>The generated Wrappers perform the following functions. These wrappers act as
RPC Providers. </p>
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#test3">3.3 Generator</a>
  +</p>
   
  -<p>o  Serialization</p>
  -<p>o  Deserialization</p>
  -<p>o  Method invocation</p>
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#test4">3.4 Flow of Execution</a>
  +</p>
   
  +<p>
  +&nbsp;&nbsp;&nbsp;&nbsp;<a href="#test5">3.5 Sequence Diagram</a>
  +</p>
   
  +<p><a name="intro"></a></p>
   
  +<h1>1 Introduction</h1>
   
  +      <p>The WSDL2Ws tool that comes with Axis C++ can be used to generate different
types of wrapper classes / skeletons for the server side and wrapper classes / stubs for the
client side for a given WSDL file. WSDL2Ws tool is written in  Java and is based on the WSDL
tools by Axis Java project.
  +      
  +<p><a name= "codegen"></a></p>
   
  +<h2>1.1 Source Code Generation</h2>
   
  +    <p> WSDL2WS tool can be used for generating the following C/C++ source files
for a given WSDL file : <p>
  +<ul>
  +<li>Server side  skeletons and wrappers</li>
  +<li>Client side stubs and wrappers</li>
  +</ul>
  +
  +  <p>The generated Wrappers support the following functions : <p>
  +<ul>
  +<li>Method invocation</li>
  +<li>Serialization</li>
  +<li>Deserialization</li>
  +</ul>
   
  -    <a name="depend"/></a>
  -    <h2>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 1.2  Programming
Languages </h2>
  +<p><a name="proglang"></a></p>
  +    <h2>1.2  Programming Languages </h2>
       
  -<p> The tool should be able to generate classes for 
  -<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; •	C++ </p>
  -<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; •	C </p>
  -  </p>  
  -
  -<p><b>The tool should be extensible to support other programming languages
if required.</b></p>
  -
  -
  -
  +<p> The tool is capable of generating source code for both C++ and C</p>
       
  -    <a name="websvc"/></a>
  -    <h2>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 1.3 encoding
style</h2>
  +<p><a name="encode"></a></p>
  +    <h2>1.3 Encoding Styles</h2>
   
  -    <p>The tool should be able to support SOAP1.2 encoding style and extensible to
support other encoding styles as well.
  +    <p>The tool should be able to support SOAP 1.2 encoding style and extensible
to support other encoding styles as well. However verifying the compliance with SOAP 1.1 /
SOAP 1.2 and WS-I Basic Profile remains a TODO.
    </p>
   
  +<p><a name="svcstyle"></a></p>
  +    <h2>1.4 Styles of Services</h2>
   
  -    <a name="start"/></a>
  -    <h2>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.4 Style Of
the Service</h2>
  -
  -    <p>The tool should be able to generate classes for following styles</p>
  -<p>•	RPC </p>
  -<p>•	Document </p>
  -<p>•	Messaging </P>
  +    <p>The tool is able to generate code for RPC (encoded) and Document Literal style
WSDLs </p>
    
  +<p><a name="complext"></a></p>
  +    <h2>1.5 Support for Complex Types</h2>
  +     <p>The tool generates wrapper classes / structs / functions for complex types.
The generated source include: </p>
  +<ul>
  +<li> Wrapper classes for complex types with data members and constructors/destructors</li>
  +<li> Helper functions for serializing/deserializing complex types</li>
  +<li> Wrapper structs to handle arrays of complex types</li> 
  +</ul>
  +
  +<p><a name="usage"></a></p>
  +    <h1>2 Using the Tool</h1>
  +
  +<p><a name="dependencies"></a></p>
  +<h2>2.1 Dependencies on Axis Java tool</h2>
  +
  +<p>Apache Axis C++ uses WSDL processing tools from Axis Java project and extends
those for C/C++ code generation. </p>
  +<p>The following jar files that comes with (or used by) Axis Java are required to
run Axis C++ WSDL2Ws tool:</p>
  +<ul>
  +<li>axis.jar</li>
  +<li>wsdl4j.jar</li>
  +<li>commons-discovery.jar</li>
  +<li>commons-logging.jar</li>
  +<li>log4j-1.2.8.jar</li>
  +<li>jaxrpc.jar</li>
  +<li>saaj.jar</li>
  +</ul>
  +
  +<p>"SchemaUtils" (SchemaUtils.java) and "ElementDecl" (ElementDecl.java) classes
of Axis Java tools have been overridden by Axis C++ WSDL2Ws implementation.</p>
  +
  +<p>Other than the two classes mentioned above, no other class from Axis Java WSDL
tool implementation has been overridden or extended at present by Axis C++ WSDL2Ws tool; hence
all other classes in Axis Java tool are used as they are.</p>
  +
  +<p>Except for "SchemaUtils" and "ElementDecl" classes, the rest of the classes of
Axis C++ WSDL2Ws are unique to Axis C++ and they use functionality form Axis Java jars.</p>
  +
  +<p><a name="building"></a></p>
  +<h2>2.2 Building the Tool</h2>
  +<p>If you want to build the WSDL2Ws tool form source, there is an Apache Ant build
script to help you. 
  +Assuming that you have <a href="http://ant.apache.org/manual/install.html">installed
Ant</a> properly, what you have to do is to set the CLASSPATH to include <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2beta/">Axis
Java jar files</a> mentioned in the previous section and run ant command in $AXISCPP_HOME/src/wsdl
folder. Once you build the tool the generated wsdl2ws.jar file would be placed in $AXISCPP_HOME/lib/axis/
folder.
  +</p>
   
  - 
  -        <a name="install-test"/></a>
  -    <h2>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 1.5 Supports
for making simple custom types</h2>
  -
  -
  -
  -   
  -     <p>Tool generates Wrappers for custom types in following conditions</p>
  -<p>•	Generates the method signatures of the types (serialize(), deserialize()) so
that developer &nbsp;&nbsp; can write serialize desirialize code in most efficient
way.</P> 
  -<p>•	Generates the complete wrappers for WSDL types like struts
  -   </p>
  -
  -<p>•	Generates the complete wrappers for Array of any simple or WSDL types like struts
</p> 
  -
  +<p><a name="synopsis"></a></p>
  +<h2>2.3 Synopsis</h2>
  +<p>
  +<strong>java WSDL2Ws [options] wsdl-file</strong>
  +</p>
  +<p><strong>Options</strong></p>
   
  -    
  +<pre>
  +-help, -h              print a short help message<br>
  +-o(folder)             target output folder - default is current folder<br>
  +-l(c++|c)              target language (c++|c) - default is c++<br>
  +-s(server|client)      generate server skeletons or client stubs? (serve|client) - default
is server<br>
  +-w(wrapped|nonwrapped) wrapping style of the WSDL (wrapped|nonwrapped) - default is wrapped<br>
  +-verbose, -v           be verbose<br>
  +-m(none|gnu)           generate make files (none|gnu) - default is none<br>
  +</pre>
  +
  +<p><a name="classpath"></a></p>
  +<h2>2.4 Setting up CLASSPATH</h2>
  +<p>Make sure that your CLASSPATH environment variable has all the jar files mentioned
in section 2.1 above.
  +Then modify your CLASSPATH to include the wsdl2ws.jar file from Axis C++:
  +</p>
  +
  +<p>On Linux: </p>
  +<pre>
  +CLASSPATH=$AXISCPP_HOME/lib/axis/wsdl2ws.jar:$CLASSPATH
  +export CLASSPATH
  +</pre>
  +
  +<p>On Windows: </p>
  +<pre>
  +set CLASSPATH=%AXISCPP_HOME%\lib\axis\wsdl2ws.jar;%CLASSPATH%
  +</pre>
  +<p>Alternatively, you can use the -classpath option of java command to specify the
CLASSPATH.</p>
  +
  +<p><strong>NOTE: It is a MUST that that you have wsdl2ws.jar from Axis C++
appearing before all the jar files form Axis Java on the CLASSPATH.</strong> If not
you will run into trouble when generating code. This is a known problem and happens because
the two classes, "SchemaUtils" and "ElementDecl", of Axis C++ that overides Axis Java classes
with the same name have identical package names to that of Axis Java classes.
  +</p>
  +
  +<p><a name="runtool"></a></p>
  +<h2>2.5 Running the Tool</h2>
  +
  +<p>You could run the tool as shown in the following example. Assuming you have not
included wsdl2ws.jar in your class path:</p>
  +
  +<pre>
  +java -classpath $AXISCPP_HOME/lib/axis/wsdl2ws.jar:$CLASSPATH org.apache.axis.wsdl.wsdl2ws.WSDL2Ws
\
  +     -obaseServerOut $AXISCPP_DEPLOY/wsdls/base.wsdl
  +</pre>
   
  +<p>
  +The above command will generate C++ server side skeleton and wrapper classes and place
the generated source files in a folder named baseServerOut. You could have also used -sserver
and -lc++ options to generate the same. To generate client side C++ code for the same WSDL
file and place the generated code in baseClientOut folder, you could run:
  +</p>
   
  +<pre>
  +java -classpath $AXISCPP_HOME/lib/axis/wsdl2ws.jar:$CLASSPATH org.apache.axis.wsdl.wsdl2ws.WSDL2Ws
\
  +     -obaseClientOut -sclient -lc++ $AXISCPP_DEPLOY/wsdls/base.wsdl
  +</pre>
   
   
  -      <a name="test"/></a>
  -    <h1>2.Architecture</h1>
  +<p><a name="test"/></p>
  +    <h1>3 Architecture</h1>
       
      
  - <a name="test1"/></a>
  -    <h2>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;2.1 Outline</h2>
  +<p><a name="test1"/>
  +    <h2>3.1 Outline</h2>
   
   
  -<p>The tool takes a top down approach. It starts with a wsdl document and generates
all the classes necessary to deploy the web service. It generates </p>
  -<p>•	Skeleton (wrapper class) </p>
  -            
  -<p>•	Wrapper classes for complex types </p>
  -<p>•	Server side and client Side stubs 
  -<br>
  -The tool can be extensible to generate Service classes to be published 
  -For more information about the generated classes please refer to the architecture documentation.
  +<p>The tool takes a top down approach. It starts with a WSDL document and generates
all the classes (skeletons, wrapper classes for complex types and stubs) necessary to deploy
(server side) and consume (client side) the web service. For more information about the generated
classes please refer to the architecture documentation.</p>
  +
  +<p> The following figure shows the high level architecture of the WSDL2Ws tool</p>
   <align="left">
   <img SRC="../images/c/ag/wsdl2ws.jpg" ></align></p>
   
  +<p><a name="test2"/>
  +    <h2>3.2 Mediator WebServiceContext</h2>
   
  -<a name="test2"/></a>
  -    <h2>&nbsp;&nbsp;2.1 Mediator WsContext</h2>
  -
  -
  -
  -<p>The WSDL file and the user options are processed by the WSDLWs. The WSDL creates
a class called wsContext(WebServiceContext) which is the runtime representation of the processed
data. This wsContext passes to the generators.  The generators extract the information from
the wsContext and creates the files.The wsContext acts as a mediator and creates a loosely
coupled system.</p>
  -
  -<h3>wsContext has following components</h3>
  -
  -<p>1.  ServiceInfo –  information about service </p>
  -<p>2.  WrapperInfo – information about wrapper options</p> 
  -<p>3.  TypeMap – information about custom types </p>
  -
  -
  -
  -<a name="test3"/></a>
  -    <h2>&nbsp;&nbsp;&nbsp;2.2 Genarator
  -</h2>
  -
  -<p>Generator generates a class which depends on the options, It contains a class
called SourceWriter and the concrete implementation of the SourceWriter decides what the Genarator
generates. The SourceWriter factory creates a correct type of generator which depends on the
options.</p>
  +<p>The WSDL file and the user options are processed by the WSDL2Ws class. Then WSDL2Ws
creates an instance of WebServiceContext class (wscontext), which is the runtime representation
of the processed data. This WebServiceContext instance selects the Generator to be used. The
Generators extract the information from the WebServiceContext instance and creates the files.
The WebServiceContext instance acts as a mediator and creates a loosely coupled system.</p>
  +<p>
  +<strong>WebServiceContext has the following components</strong>
  +</p>
  +<ol>
  +<li>  ServiceInfo - information about service </li>
  +<li>  WrapperInfo - information about wrapper options</li> 
  +<li>  TypeMap - information about custom types </li>
  +</ol>
   
  -<a name="test4"/></a>
  -    <h2>&nbsp;&nbsp;&nbsp;2.4 flow of execution
  +<p><a name="test3"></a></p>
  +    <h2>3.2 Generator
   </h2>
   
  -<p>1.WSDL file and user options are processed by the WSDL2Ws and WSContext object
is created.</p> 
  -<p>2. WebServiceGenaratorFactory will create WebServiceGenarator which depends on
the service style </p>
  -<p>3. Then the WebServiceGenarator will create a right set of Generators to create
the set of files</p> 
  -<p>4.Each generator will invoke SourceWriter which is capable of writing each type
of file. 
  -Rest of the logic is upto the developer to decide (He has all the needed info as WsContext).

  +<p>Generator generates a class based on the options passed by user. It contains a
class called SourceWriter and the concrete implementation of the SourceWriter decides what
the Generator generates. </p>
   
  +<p><a name="test4"></a></p>
  +    <h2>3.4 flow of Execution</h2>
  +<p>
  +<ol>
  +<li>WSDL file and user options are processed by the WSDL2Ws and WebServiceContext
object is created</li> 
  +<li>WebServiceGenaratorFactory will create WebServiceGenerator based on the service
style </li>
  +<li>Then the WebServiceGenarator will create the right set of Generators that will
take care of generating C/C++ source files</li> 
  +<li>Each Generator will invoke SourceWriter which is capable of writing the given
type of file</li>
  +</ol>
   </p>
   
   
  -<a name="test5"/></a>
  -    <h2>&nbsp;&nbsp;&nbsp;2.5 Sequence Diagram
  +<p><a name="test5"/>
  +    <h2>3.5 Sequence Diagram
   </h2>
   
   <p><center>
   
   <img SRC="../images/c/ag/sequence.jpg" ></center></p>
   
  -<a name="test6"></a>
  -<h1>Dependencies on Axis Java tool</h1>
  -
  -<p>The document below describes the areas where Apache Axis C++ is dependant upon
the Axis Java tool. </p>
  -<p>The Axis jars given below are used as they are in the Axis Java tool:</p>
  -<br>
  -<p> &nbsp &nbsp axis.jar <br>
  -&nbsp &nbsp commons-discovery.jar <br>
  -&nbsp &nbsp commons-logging.jar <br>
  -&nbsp &nbsp jaxrpc.jar <br>
  -&nbsp &nbsp saaj.jar <br>
  -&nbsp &nbsp wsdl4j.jar <br>
  -&nbsp &nbsp xml-apis.jar <br> </p>
  -<p>"SchemaUtils.java" and "ElementDecl.java" files have been overridden and their
original implementations are no longer used even though they exist in the above mentioned
jars.</p>
  -
  -<p>No classes have been extended at the present time.</p>
  -
  -<p>Except for "SchemaUtils.java" and "ElementDecl.java" the rest of the code has
been developed for the Axis C++ tool and is not present in the current Axis Java tool.</p>
  -
  -<hr size=1 noshade= />
  +<HR size="1" noshade="noshade">
     </body>
   </html>
  
  
  

Mime
View raw message