axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d...@apache.org
Subject cvs commit: ws-axis/contrib/axisdocs/src/documentation/content/xdocs/cpp architecture-guide.ihtml developers-guide.ihtml integration-guide.ihtml user-guide.ihtml
Date Fri, 24 Oct 2003 13:14:05 GMT
dims        2003/10/24 06:14:05

  Added:       contrib/axisdocs/src/documentation/content/xdocs/cpp
                        architecture-guide.ihtml developers-guide.ihtml
                        integration-guide.ihtml user-guide.ihtml
  Log:
  axis c++ docs from tetsuya
  
  Revision  Changes    Path
  1.1                  ws-axis/contrib/axisdocs/src/documentation/content/xdocs/cpp/architecture-guide.ihtml
  
  Index: architecture-guide.ihtml
  ===================================================================
  <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  
  <HTML>
  <HEAD>
    <META name="generator" content=
    "HTML Tidy for Windows (vers 1st October 2003), see www.w3.org">
    <META http-equiv="Content-Type" content=
    "text/html; charset=us-ascii">
  
    <TITLE>Axis Architecture Guide</TITLE>
    <LINK href="axis.css" rel="stylesheet" type="text/css">
  </HEAD>
  
  <BODY>
    <CENTER>
      <H1><IMG src="images/axis.jpg" height="96" width="176"></H1>
    </CENTER>
  
    <H1>Axis C++ Architecture Guide</H1>
  		<font face="Lucida Sans"><font color="#cc0000"><font size="+3">Under construction ....</font></font></font>
  		<br>
  		<i>0.1 Version</i>
  		<br>
  		<i>Feedback: <a href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>
  		<h3>
  			Contents</h3>
  		<a href="#Introduction">Introduction</a>
  		<br>
  		<a href="#Overview">Architecture Overview</a>
  		<br>
  		<a href="#Subsystems">Subsystems</a>
  		<br>
  		&nbsp;&nbsp;&nbsp; <a href="#AxisEngine">AxisEngine</a>
  		<br>
  		&nbsp;&nbsp;&nbsp; <a href="#HandlerPool">HandlerPool</a>
  		<br>
  		&nbsp;&nbsp;&nbsp; <a href="#Deserializer">Soap Deserializer</a>
  		<br>
  		&nbsp;&nbsp;&nbsp; <a href="#Serializer">Soap Serializer</a>
  		<br>
  		&nbsp;&nbsp;&nbsp; <a href="#WSDD">WSDD Module&nbsp; </a>
  		<br>
  		&nbsp;&nbsp;&nbsp; <a href="#ServerConfig">Server Configuration</a>
  		<br>
  		&nbsp;&nbsp;&nbsp; <a href="#Logger">Logger</a>
  		<br>
  		<a href="#Deployment">Web Service Deployment&nbsp; </a>
  		<br>
  		<a href="#WrapClassGen">Wrapper Classes and WSDL Generation</a>
  		<br>
  		<a href="#ClientStubGen">Client Stub Generation</a>
  		<br>
  		<a href="#Open Issues">Open Issues</a>
  		<h2>
  			<a NAME="Introduction"></a>Introduction</h2>
  		This guide describes the architecture of Axis C++ implementation.<h2>
  			<a NAME="Overview"></a>Architectural Overview</h2>
  		Axis C++ is all about deploying C++ web services and processing SOAP messages. 
  		As you see later Axis C++ consists of several subsystems working together. Axis 
  		C++ architecture closely follows Axis Java in Handler and message paths.<h3>
  			Handlers and the Message Path in Axis</h3>
  		<p>
  			Axis C++ implementation follows how handlers and message paths work in Axis 
  			Java implementation.
  		</p>
  		<p>
  			When the central Axis processing logic runs, a series of <b>Handlers</b> are 
  			each invoked in order. The order of invocation is determined by two factors - 
  			deployment configuration and whether the engine is a client or a server. The 
  			object which is passed to each Handler invocation is a <b>MessageData</b>. A 
  			MessageData is a structure which contains several important parts: 1) 
  			Deserializer, 2) Serializer, and 3) a bag of properties. More on this in a bit.
  		</p>
  		<h3>
  			Message Path on the Server</h3>
  		The server side message path is shown in the following diagram. The small 
  		cylinders represent Handlers and the larger, enclosing cylinders represent <b>Chains</b>
  		(ordered collections of Handlers which will be described shortly).
  		<br>
  		<img SRC="images/ServerMessagePath.jpg" VSPACE="30" height="282" width="602">
  		<br>
  		A message arrives (in some protocol-specific manner) at a Transport Listener. 
  		In this case, let's assume the Listener is an apache module. It's the 
  		Listener's job to package the protocol-specific data into a <b>soapstream</b> object 
  		(specified in Packet.h), and pass it to AxisEngine to be processed. The <b>soapstream</b>
  		is also loaded with various <b>properties</b> by the Listener -&nbsp; in this 
  		example the property "trtype" would be set to the transport type and the value 
  		of the SOAPAction HTTP header is inserted in to a header list.
  		<p>The AxisEngine's first job is to check what the transport is. Then the 
  			MessageData object is created and populated (with Serializer, Deserializer 
  			etc). Also the Serializer and Deserializer is initialized. Then the configured 
  			handlers and the target web service handler are loaded. All transport, global 
  			and service specific handlers are loaded in to <b>Chains. </b>A <b>Chain</b>
  		is also a Handler consisting of a sequence of Handlers which are invoked in 
  		turn -- more on Chains later.
  		<p>Then the loaded handler chains are invoked in the order shown passing the 
  			MessageData object into the invoke().
  			<h2>
  				<a NAME="Subsystems"></a>Subsystems</h2>
  			Axis comprises several subsystems working together with the aim of separating 
  			responsibilities cleanly and making Axis modular. Subsystems which are properly 
  			layered enable parts of a system to be used without having to use the whole of 
  			it.
  			<h3><a name="AxisEngine"></a>AxisEngine
  			</h3>
  		<p>AxisEngine contains the core logic of the message flow. AxisEngine's "Process" 
  			method contains the message flow logic. Following sequence diagrams show the 
  			message flow logic.</p>
  		<p>Following Diagram shows how the transport listener passes the SOAP message to 
  			the AxisEngine. AxisEngine is a singleton object for a process.</p>
  		<p>
          <img border="0" src="images/translistner.jpg" width="637" height="378"></p>
  		<p>Now following diagram depicts the Engine Initialization.</p>
  		<div class="Section1">
  			<p class="MsoNormal">
              <img border="0" src="images/Engineinit.jpg" width="712" height="830"></p>
  		</div>
  		<p class="MsoNormal">Following diagram depicts the AxisEngine's message flow logic</p>
  		<p>
          <img border="0" src="images/messageflow.jpg" width="743" height="821"></p>
  		<h3><a name="HandlerPool"></a>HandlerPool
  		</h3>
  		<p>AxisEngine instantiates a HandlerPool object in its constructor. HandlerPool 
  			does the following 3 tasks,</p>
  		<ol>
  			<li>
  			Loads and keeps Transport and Global handlers.
  			<li>
  			Loads service specific handlers when needed and unloads when needed.
  			<li>
  				Loads target web service handler when needed and unloads when needed.</li>
  		</ol>
  		<p>To provide above functionality the HandlerPool makes use of other two classes 
  			HandlerChain and HandlerLoader. HandlerLoader loads holds and unloads the 
  			dynamic link library (or shared object) that contain either a handler or a web 
  			service. HandlerChain is used to keep a list of handlers to be invoked in 
  			order. HandlerChain itself is a handler.</p>
  		<p>In order for the HandlerLoader to dynamically load a class, every DLL (or Shared 
  			object) must have following <b>export functions</b>.&nbsp;</p>
  		<p>int GetClassInstance(DCLInterface **inst);
  		</p>
  		<p>int DestroyInstance(DCLInterface *inst);</p>
  		<p>AxisEngine has no idea of any web service methods in the deployed web service 
  			class that is dynamically loaded from a DLL. Therefore in order to communicate 
  			with loaded class we have to have a known interface. This interface is known as <b>
  				<span style="FONT-SIZE:10pt">BasicHandler </span></b>and is known to 
  			AxisEngine. This interface is implemented by every webservice and a handler.</p>
  		<p><img border="0" src="images/handlers.jpg" width="355" height="235"></p>
  		<h3><a name="Deserializer"></a>Soap Deserializer
  		</h3>
  		<p>Currently the Soap Deserializer is implemented using SAX2 parser. Soap 
  			Deserializer exposes and API such that the API is independent of the 
  			implementation. This API is decided with a view of using XML pull parsing for 
  			the implementation. Once the Deserializer is given a message with its 
  			SetStream(..) method its GetXXX methods can be called in sequence to get the 
  			parsed SOAP data.</p>
  		<h3>
  			<br>
  			<a name="Serializer"></a>Soap Serializer</h3>
  		<p>Soap Serializer's task is to generate SOAP stream to be sent. There are a set of 
  			functions (API that is the opposite functionality with Soap Deserializer). Once 
  			the Serializer is given all the information that is required to generate a SOAP 
  			using the API, the getStream(..) function can be used to get the SOAP message.</p>
  		<h3>
  			<br>
  			<a name="WSDD"></a>WSDD Module</h3>
  		<p>WSDD module is a set of classes that parses the deployment descriptor 
  			file(server.wsdd) and makes the information available to the AxisEngine.&nbsp; 
  			A WSDDDeployment object is instantiated in AxisEngine's constructor.
  		</p>
  		<h3>
  			<br>
  			<a name="ServerConfig"></a>Server Configuration
  		</h3>
  		<h3>
  			<br>
  			<a name="Logger"></a>Logger
  		</h3>
  		<h2><a name="Deployment"></a>Web Service Deployment&nbsp;
  		</h2>
  		<p class="MsoNormal" style="MARGIN-LEFT:0.3in">The solution is to write a wrapper 
  			class for each web service class. This wrapper class is written with full 
  			awareness of the actual web service class and the corresponding WSDD. Then this 
  			wrapper class is compiled to a DLL (Shared Library in Linux) and is deployed as 
  			the web service. Following diagram shows this process.</p>
  		<p>
          <img border="0" src="images/deployprocess.jpg" width="584" height="135"></p>
  		<p>&nbsp;</p>
  		<h2>
  			<a name="WrapClassGen"></a>Wrapper Classes and WSDL Generation</h2>
  		<p>
  			<b>WrapperClassGenerator </b>writes the wrapper class using only the web 
  			services include file and the deployment descriptor for that web service. The 
  			corresponding WSDL too is generated.</p>
  		<h3><a name="WrapClassMaping"></a>Web Service to Wrapper Class Mapping</h3>
  		<p>Following example shows how the Web service maps to the Wrapper class.</p>
  		<p><img border="0" src="images/Mappingheader.jpg" width="660" height="316"></p>
  		<p>The actual web service object is instantiated in the constructor of the wrapper 
  			class and is destroyed in the destructor. The Invoke method
  			<span style="FONT-SIZE: 12pt; FONT-FAMILY: Times New Roman">can be written 
  just by looking at the WSDD. Or else by looking at the exposed methods of the 
  web service class. The Invoke method chooses what method to be called as 
  follows.</span></p>
  		<p><img border="0" src="images/invokemethod.jpg" width="402" height="217"></p>
  		<p class="MsoNormal" style="MARGIN-LEFT:0.3in">Then each allowed method in the 
  			actual web service class is wrapped by a Wrapper method in the Wrapper class. 
  			Only a method signature is needed to write the corresponding wrapper method. 
  			This implies that following are needed,&nbsp;</p>
  		<ol>
  			<li>
  				<p class="MsoNormal" style="MARGIN-LEFT: 53.85pt; TEXT-INDENT: -0.25in">Method Name</p>
  			<li>
  				<p class="MsoNormal" style="MARGIN-LEFT: 53.85pt; TEXT-INDENT: -0.25in">No of 
  					parameters</p>
  			<li>
  				<p class="MsoNormal" style="MARGIN-LEFT: 53.85pt; TEXT-INDENT: -0.25in">
  					Sequence and types of the parameters</p>
  			<li>
  				<p class="MsoNormal" style="MARGIN-LEFT: 53.85pt; TEXT-INDENT: -0.25in">Return type</p>
  			</li>
  		</ol>
  		<p><img border="0" src="images/methodimpl.jpg" width="529" height="205"></p>
  		<h2><a name="ClientStubGen"></a>Client Stub Generation
  		</h2>
  		<p>&nbsp;</p>
  		<p></p>
  		<p>&nbsp;</p>
  		<h2>
  			<a NAME="Open Issues"></a>Open Issues</h2>
  		<p>
  			1.
  		</p>
  	</body>
  </html>
  
  
  
  1.1                  ws-axis/contrib/axisdocs/src/documentation/content/xdocs/cpp/developers-guide.ihtml
  
  Index: developers-guide.ihtml
  ===================================================================
  <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  
  <HTML>
  <HEAD>
    <TITLE>Axis C++ Developer's Guide</TITLE>
    <LINK href="axis.css" rel="stylesheet" type="text/css">
  </HEAD>
  
  <BODY>
    <CENTER>
      <H1><IMG src="images/axis.jpg" height="96" width="176"></H1>
    </CENTER>
  
    <H1>Axis C++ Developer's Guide</H1>
  
  <h2>0.1 Version</h2>
  
  <h3>Table of Contents</h3>
  
  <p><a href="#Introduction">Introduction</a>
  <br>
  <a href="#General_Guidelines">General Guidelines</a> <br>
  <a href="#Development_Environment">Development Environment</a> <br>
  <a href="#Configuration_Properties">Configuration Properties</a> <br>
  
  <a href="#Compile_And_Run">Compile and Run</a>
   <br>
  <a href="#Adding_Testcases">Adding Testcases</a> </p>
  
  <p><a href="#ModuleAPI">Writing
  Transport Modules</a><br>
  <a href="#TestStructure">Test and Samples Structure</a> <br>
  <a href="#CodeChecks">Adding Source Code Checks</a> <br>
  <a href="#JUnit">CUnit and Axis</a> <br>
  <a href="#Debugging">Debugging</a> <br>
  &nbsp; </p>
  
  <a name="Introduction"></a>
  <h2>Introduction</h2>
  
  <p>This document is intended
  for the developer who wish to download and compile and
  test the axis C++ server.</p>
  
  <a name="General_Guidelines"></a>
  <h2>General Guidelines</h2>
  
  <ul>
   <li>TO DO ...</li>
  </ul>
  
  <a name="Development_Environment"></a>
  <h2>Development Environment</h2>
  
  <p>The following packages are
  required for axis development: </p>
  
  <ul>
   <li><a href="http://xml.apache.org/dist/xerces-j">xerces</a>
       - xml processor</li>
  </ul>
  
  <a name="Configuration_Properties"></a>
  <h2>Configuration Properties</h2>
  
  <p>TO DO ... </p>
  
  <a name="Compile_And_Run"></a>
  <h2>Compile and Run</h2>
  
  <p>
  
  This document is intended for the developer who wish to download and test the axiscpp server.<br>
  
  Checkout axiscpp from cvs repository.<br><br>
  To build axisengine library<br>
  ==================<br><br>
  When you download the source you have only Makfile.am's and configure.ac and
  autogen.sh script for building.
  <br><br>
  make sure you create and  set the environment variable AXISCPP_HOME
  to reflect the path to the directory where you downloaded the axiscpp.
  for example I have it as following
  <br><br>
  AXISCPP_HOME="/home/damitha/projects/axiscpp/c" <br> <br>where c is the rood directory
  for axiscpp source. There you find autogen.sh, configure.ac etc.<br>
  
  <br>
  to build go to $AXISCPP_HOME dirctory.<br><br>
  sh autogen.sh
  <br><br>
  To avoid cluttering of the source with object files use the build directory
  to generate your object files.
  <br><br>
  Now from c/build directory run<br><br>
  sh runconfigure
  <br><br>
  This will create all the Makefiles in a tree starting from build directory.<br><br>
  make<br>
  then<br>
  make install<br>
  <br>
  this will install libaxiscpp_mod.so in c/release directory.<br><br>
  copy this to <apache home>/libexec directory and restart apache
  to load the axisengine in apache.
  <br><br>
  Note: in $AXISCPP_HOME/include you have folder called xercesc apache1_3
  apache2_0. Copy the corresponding include files into them.
  <br><br><br>
  To build samples<br>
  ===========<br>
  Go to the samples folder<br><br>
  $(AXISCPP_HOME)/src/server/samples<br><br>
  and select the sample you want. As an example we try on
  simplewebservice<br>
  type the following commands in that order<br><br>
  sh autogen.sh<br>
  sh runconfig<br>
  make<br>
  make install<br>
  <br>
  this will install the sample library in /usr/local/apache/Axis/webservices 
  <br><br>
  note: the server.wsdd file for this sample has to be put in<br><br>
  /usr/local/apache/Axis/conf folder.<br><br>
  This path is hardcoded in Axis.cpp file as following
  <br><br>
  #define WSDDFILEPATH "/usr/local/apache/Axis/conf/server.wsdd"<br>
  
  </p>
  
  <a name="Adding_Testcases"></a>
  <h2>Adding Testcases</h2>
  
  <p>See Also: <a href="#TestStructure">Test
  and Samples Structure</a></p>
  
  <a name="ModuleAPI"></a>
  <h2>Writing Transport Modules</h2>
  
  <p>Axis C++ is plugged-in to any transport listener
  such as Apache Web Server or IIS through a Transport Module. Axis Engine and
  the Transport Module can be developed in 2 ways.</p>
  
  <p>They can be
  compiled and linked together into a single DLL (or Shared Object) which is
  plugged into the Transport Listener. This way reduces one level of indirection
  and leads to performance.</p>
  
  <p>They can be
  made 2 separate DLLs (or Shared Objects). Advantage of this method is that the
  2 modules can be developed separately.</p>
  
  <p>Module should be written specifically for
  each kind of Transport Listener (Apache or IIS) whereas the AxisEngine
  is not specific to Transport Listener. </p>
  
  <p>So this API defines the way that Transport
  Module communicates with the AxisEngine. </p>
  
  <h3>Module side API</h3>
  
  <p>There is a set of functions to be
  implemented by each module. AxisEngine needs the
  module to implement them.</p>
  
  <p>int send_transport_information(TransportInfo*)</p>
  
  <p>int get_request_bytes(char*, int, int*)</p>
  
  <p>int send_response_bytes(char*)</p>
  
  <p><b>send_transport_information</b><b></b></p>
  
  <p>AxisEngine may call this function to send transport specific
  information of the response (Ex : http headers for
  HTTP transport).</p>
  
  <p><b>get_request_bytes</b><b></b></p>
  
  <p>AxisEngine calls this function whenever it needs more soap
  request bytes in the incoming stream. AxisEngine may
  call this function more than once. </p>
  
  <p><b>send_response_bytes</b><b></b></p>
  
  <p>AxisEngine calls this function whenever it wants to send a
  fragment of soap response to the Transport Listener. This function may also be
  called by the AxisEngine more than once depending on
  the size of the response. The transport listener may accumulate or send each
  fragment at each function call.</p>
  
  <h3>AxisEngine side API</h3>
  
  <p>AxisEngine has implemented following functions to be used by
  any Transport Module.</p>
  
  <p> 1. int initialize_module()</p>
  
  <p> 2. int initialize_process()</p>
  
  <p> 3. int process_request(TransportInfo*)</p>
  
  <p> 4. int finalize_process()</p>
  
  <p><b>initialize_module</b><b></b></p>
  
  <p>Transport Module <b>MUST </b>call this function when it loads the AxisEngine.
  If this function returns FAIL it cannot be assured that the AxisEngine
  works properly. Loading of all AxisEngine&#8217;s
  components (DLLs) are done within this function.</p>
  
  <p><b>initialize_process</b><b></b></p>
  
  <p>As the AxisEngine
  is single threaded model, simultaneous requests are served by several processes
  spawned. So when each process is spawned, its initialization should be done.
  Therefore the Transport Module <b>MUST </b>call
  this API function when it spawns a new AxisEngine
  process.</p>
  
  <p><b>process_request</b><b></b></p>
  
  <p>Transport Module calls this function for
  each soap request. Transport Module should fill a TransportInfo
  structure with the relevant transport information and pass it to the process_request function. Returning FAIL indicates a
  critical error in processing the soap request (not a generation of Soap Fault).</p>
  
  <p><b>finalize_process</b><b> </b></p>
  
  <p>This function does the opposite of what initialize_process does and <b>MUST </b>be
  called by Transport Module for the process end.</p>
  
  <p><o:p>&nbsp;</o:p></p>
  
  <a name="TestStructure"></a>
  <h2>Test Structure</h2>
  
  <p>&nbsp;</p>
  
  <a name="CodeChecks"></a>
  <h2>Adding Source Code Checks</h2>
  
  <p>&nbsp;</p>
  
  <a name="JUnit"></a>
  <h2>CUnit and Axis</h2>
  
  <p>&nbsp;</p>
  
  <a name="Debugging"></a>
  <h2>Debugging</h2>
  
  </div>
  
  </body>
  
  </html>
  
  
  
  1.1                  ws-axis/contrib/axisdocs/src/documentation/content/xdocs/cpp/integration-guide.ihtml
  
  Index: integration-guide.ihtml
  ===================================================================
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
  <HTML>
  <HEAD>
  	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
  	<TITLE>Axis System Integration Guide</TITLE>
  	<STYLE>
  	<!--
  		H1 { color: #000000 }
  		P { margin-left: 0.98cm; color: #000000; font-family: "Verdana", "Arial", "Helvetica", sans-serif }
  		H2 { color: #000000; text-decoration: underline }
  		H3 { color: #000000 }
  	-->
  	</STYLE>
  </HEAD>
  <BODY LANG="en-US" TEXT="#000000" BGCOLOR="#ffffff">
  <H1 ALIGN=CENTER><IMG SRC="../../../usr/local/axis/docs/axis.jpg" NAME="Graphic1" ALIGN=BOTTOM WIDTH=222 HEIGHT=96 BORDER=0></H1>
  <H1>Axis C++ Integration Guide</H1>
  <P><I>0.1 Version</I> 
  </P>
  <H3>Table of Contents</H3>
  <P><A HREF="#Introduction">Introduction</A> <BR><A HREF="#Pluggable APIs">Pluggable
  APIs</A> <BR>&nbsp; <A HREF="#Components">Components<!-- <br>&nbsp; <a href="#System Management Plug">System Management</a>
  --></A>
  <BR>&nbsp; <A HREF="#Logging/Tracing Plug">Logging/Tracing</A> <BR>&nbsp;
  <A HREF="#Configuration" NAME="Configuration">Configuration</A><BR>&nbsp;
  <A HREF="#Handlers Plug">Handlers</A> <BR>&nbsp; <A HREF="#Internationalization Plug">Internationalization</A>
  <BR>&nbsp; <A HREF="#Performance Monitoring Plug">Performance
  Monitoring</A> <BR>&nbsp; <A HREF="#Encoding Plug">Encoding</A> <BR>&nbsp;
  <A HREF="#WSDL plug">WSDL Parser and Code Generator Framework</A> 
  </P>
  <H2><A NAME="Introduction"></A>Introduction</H2>
  <P>The primary purpose of this guide is to present how AXISCPP can be
  integrated into an existing web application server, such as Apache,
  Netscape web server for example.&nbsp; AXIS has a number of Pluggable
  APIs that are necessary for such an integration. 
  </P>
  <P>The reader may find useful background information in the
  <A HREF="architecture-guide.html">Architecture Guide</A></P>
  <H2><A NAME="Pluggable APIs"></A>Pluggable APIs</H2>
  <P>The following are the points that are pluggable in order to
  integrate AXIS into a web application server. The first subsection
  details a number of pluggable components in general. More details are
  provided for other components in the remaining subsections. 
  </P>
  <H3><A NAME="Handlers Plug"></A>Handlers</H3>
  <P>See the <A HREF="architecture-guide.html">Architecture Guide </A>for
  current information on Handlers. <!-- How can a system integrator plug in other encoding mechanisms such as SOAP
  1.2 or optimized XML-based encoding?
  <ul>
  <li>
  Justification/Rationale - why is this plug point necessary?&nbsp; Spec
  compliance?</li>
  
  <li>
  Interfaces</li>
  
  <li>
  Mechanism</li>
  
  <ul>
  <li>
  Life cycle</li>
  
  <li>
  Exception handling - in general; plug-in shouldn't throw any exceptions
  - does runtime ignore? Log?)</li>
  
  <li>
  Multiple thread support?&nbsp; Ie., is synchronization required?</li>
  </ul>
  
  <li>
  Configuration/reconfiguration</li>
  
  <li>
  Default behavior if not plugged.</li>
  
  <li>
  Example</li>
  </ul>
  -->
  </P>
  <H3><A NAME="Configuration"></A><FONT SIZE=4>Configuration</FONT></H3>
  <P><FONT SIZE=4>Axis C++ server can be configured to run on Aapache,
  Netscape web server(Not implemented yet) and Microsoft IIS(Not yet
  implemented. Also it is expected to run on Solaris, IBM AIX,
  HPUnix,FreeBSD, Linux and Windows. Currently it is tested only on
  RedHat Linux(8).</FONT></P>
  <P STYLE="margin-bottom: 0cm; line-height: 0.5cm"><FONT SIZE=4 STYLE="font-size: 15pt">Linux
   :Apache web server</FONT></P>
  
  <P STYLE="margin-bottom: 0cm; line-height: 0.5cm"><FONT SIZE=3>This document is intended for the developer who wish to download and test the axiscpp server.
  </FONT></P>
  <P STYLE="line-height: 100%"><FONT SIZE=4>Checkout axiscpp from cvs repository.</FONT></P>
  
  <P STYLE="margin-bottom: 0cm">
  <FONT SIZE=3>
  for simplicity assume that your axiscpp is now /usr/local/axiscpp</FONT>
  
  
  </P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>From now on I call this
  &lt;axiscpp_home&gt;</FONT></P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>goto
  &lt;axiscpp_home&gt;/release</FONT></P>
  <P STYLE="margin-bottom: 0cm"><BR>
  </P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>copy the libaxiscpp_mod.so
  file into &lt;apache home directory&gt;/libexec directory.</FONT></P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>For the apache server to
  load this shared module it (the apache web server) must be compiled
  with shareable module support (To do this, when running the configure
  script pass it the option &quot;--enable-module=so&quot;) For further
  information on comipiling and installing the apache web server please
  visit http://httpd.apache.org .</FONT></P>
  <P STYLE="margin-bottom: 0cm"><BR>
  </P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>open the httpd.conf file
  in &lt;apache directory&gt;/conf/</FONT></P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>add the following lines</FONT></P>
  <P STYLE="margin-bottom: 0cm"><BR>
  </P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>LoadFile
  /usr/local/apache/libexec/libaxiscpp_mod.so</FONT></P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>LoadModule axis_module    
  libexec/libaxiscpp_mod.so</FONT></P>
  <P STYLE="margin-bottom: 0cm"><BR>
  </P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>&lt;Location /axis&gt;</FONT></P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>SetHandler axis</FONT></P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>&lt;/Location&gt;</FONT></P>
  <P STYLE="margin-bottom: 0cm"><BR>
  </P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>where /axis is context
  path where the apache|axiscpp is listening to webservice requests.</FONT></P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>Now stop the apache web
  server if it is already started.</FONT></P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>Start the apache web
  server. If it starts without giving problem the module is
  successfully loaded.</FONT></P>
  <P STYLE="margin-bottom: 0cm"><FONT SIZE=3>Read the userguide for
  information on how to test the webservices on your newly installed
  soap server.</FONT></P>
  <P><BR><BR>
  </P>
  </BODY>
  </HTML>
  
  
  1.1                  ws-axis/contrib/axisdocs/src/documentation/content/xdocs/cpp/user-guide.ihtml
  
  Index: user-guide.ihtml
  ===================================================================
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
  <HTML>
  <HEAD>
  	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
  	<TITLE>Axis User</TITLE>
  	<META NAME="GENERATOR" CONTENT="Microsoft FrontPage 5.0">
  	<META NAME="CREATED" CONTENT="20030725;12341600">
  	<META NAME="CHANGED" CONTENT="20030725;16060000">
  	<META NAME="ProgId" CONTENT="FrontPage.Editor.Document">
  	<META HTTP-EQUIV="Content-Language" CONTENT="en-us">
  	<STYLE>
  	<!--
  		TD P { margin-left: 0.98cm; color: #000000; font-family: "Verdana", "Arial", "Helvetica", sans-serif }
  		H1 { color: #000000 }
  		P { margin-left: 0.98cm; color: #000000; font-family: "Verdana", "Arial", "Helvetica", sans-serif }
  		H3 { color: #000000 }
  		H2 { color: #000000; text-decoration: underline }
  		H4 { margin-left: 0.98cm; color: #000000 }
  		PRE { margin-left: 0.98cm; color: #000000 }
  	-->
  	</STYLE>
  </HEAD>
  <BODY LANG="en-US">
  <H1 ALIGN=CENTER><IMG SRC="images/axis.jpg" NAME="Graphic1" ALIGN=BOTTOM WIDTH=176 HEIGHT=96 BORDER=0></H1>
  <H1>Axis C++ User's Guide</H1>
  <H3>Table of Contents</H3>
  <UL>
  	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#Introduction">Introduction</A>
  		</P>
  	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#ConsumingServices">Consuming
  	Web Services with Axis</A> 
  	</P>
  	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#PublishingServices">Publishing
  	Web Services with Axis</A> 
  	</P>
  	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#DataMapping">XML &lt;-&gt;
  	C++ Data Mapping in Axis</A> 
  	</P>
  	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#WSDL">Using WSDL with
  	Axis</A> 
  	</P>
  	<UL>
  		<LI><P STYLE="margin-bottom: 0cm">&nbsp;<A HREF="#WSDL: Obtaining WSDL for deployed services">?WSDL:
  		Obtaining WSDL for deployed services</A> 
  		</P>
  		<LI><P STYLE="margin-bottom: 0cm">&nbsp;<A HREF="#WSDL2Java: Building stubs, skeletons, and data">WSDL2C++:
  		Building stubs, skeletons, and data</A> 
  		</P>
  		<LI><P STYLE="margin-bottom: 0cm">&nbsp;<A HREF="#Java2WSDL: Building WSDL from Java">C++2WSDL:
  		Building WSDL from C++</A> 
  		</P>
  	</UL>
  	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#published interfaces">Published
  	Interfaces</A> 
  	</P>
  	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#newbie">Newbie Tips:
  	Finding Your Way Around</A> 
  	</P>
  	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#tcpmon">Appendix : Using
  	TCPMon</A> 
  	</P>
  	<LI><P STYLE="margin-bottom: 0cm"><A HREF="#soapmon">Appendix :
  	Using SOAP Monitor</A> 
  	</P>
  	<LI><P><A HREF="#Glossary">Glossary</A> 
  	</P>
  </UL>
  <H2><A NAME="Introduction"></A>Introduction</H2>
  <P>Welcome to Axis C++, a c++ implementation of SOAP ! 
  </P>
  <H3>What is SOAP?</H3>
  <P>SOAP is an XML<I>-</I>based communication protocol and encoding
  format for inter-application communication. Originally conceived by
  Microsoft and Userland software, it has evolved through several
  generations and the current spec, <A HREF="http://w3.org/TR/soap">SOAP
  1.1</A>, is fast growing in popularity and usage. The W3C's <A HREF="http://www.w3.org/2000/xp/Group/">XML
  Protocol working group</A> is in the process of turning SOAP into a
  true open standard, and as of this writing has released a working
  draft of SOAP 1.2, which cleans up some of the more confusing areas
  of the 1.1 spec. 
  </P>
  <P>SOAP is widely viewed as the backbone to a new generation of
  cross-platform cross-language distributed computing applications,
  termed Web Services. 
  </P>
  <H3>What is Axis c++?</H3>
  <P>Axis is essentially a <I>SOAP engine</I>. The more complete
  version of axis is written in java.This version is written in c++ and
  will continue to be developed. 
  </P>
  <P>Axis c++ includes</P>
  <UL>
  	<LI><P STYLE="margin-bottom: 0cm">an apache module that can be
  	plugged in to the apache webserver on linux, 
  	</P>
  	<LI><P>A set of sample web service classes and their handwritten
  	wrapper classes. 
  	</P>
  </UL>
  <P>We hope you enjoy using Axis c++. 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>
  <H4><B>Let us know what you think!</B></H4>
  <P>Please send feedback about the package to
  &quot;<A HREF="mailto:axis-user@xml.apache.org">axis-user@xml.apache.org</A>&quot;.
  </P>
  <H3>What's in Axis c++ at this moment?</H3>
  <P>Axis c++ includes the following features: 
  </P>
  <UL>
  	<LI><P STYLE="margin-bottom: 0cm">Partial SOAP 1.1 compliant engine 
  	</P>
  	<LI><P STYLE="margin-bottom: 0cm">Support for all basic types 
  	</P>
  	<LI><P STYLE="margin-bottom: 0cm">Automatic
  	serialization/deserialization of Java Beans, including customizable
  	mapping of fields to XML elements/attributes 
  	</P>
  	<LI><P>Provider for RPC and based SOAP services 
  	</P>
  </UL>
  <H2><A NAME="ConsumingServices"></A>Consuming Web Services with Axis
  C++</H2>
  <H2><A NAME="PublishingServices"></A>Publishing Web Services with
  Axis C++</H2>
  <P>This chapter explains how to deploy the sample web services
  included with Axis C++.</P>
  <P>Hopefully by now you have installed Axis C++.<BR><BR>If you
  haven't already done so download the binary version of Axis C++ and
  follow the instructions in the integration-guide to install it.<BR>&nbsp;</P>
  <P>From here onwards the folder in which Axis C++ is installed by
  being extracted from the Axis C++ installation package will be
  referred to as <BR>&lt;axiscpp_home&gt;.<BR><BR>sample webservice
  modules are included in &lt;axiscpp_home&gt;/src/server/samples/<BR><BR>in
  this folder you will find two subfolders called webservice and
  webservicewrapper and <BR>service.wsdd file written by the service
  provider for his service.</P>
  <P>In the webservice folder, the header files and cpp files written
  in c++, for each of the webservice can be found. In the
  webservicewrapper folder the corresponding the wrapper classes for
  each of the webservices can be found. The wrapper classes are supposed to be 
  generated by a tool called WCG (Wrapper Class
  Generator).  
  </P>
  <P><U>Using WCG</U> 
  </P>
  <P>Suppose you have a C++ web service to be deployed called SimpleService. And 
  the SimpleService.h and SimpleService.cpp are the source files. And SimpleService.cpp contains the implementation for
  the intended service. SimpeService.h contains only the declarations of the class. You need only this SimpleService.h to generate
  your wrapper classes.  </P>
  <P>So you compile the sources and create a static library SimpleService.lib (or 
  SimpleService.a in Linux) first using the compiler.&nbsp; Now wcg can create the 
  service DLL for you with SimpleService.h and SimpleService.lib.</P>
  <P>Unwrap the WCG tool downloaded, into a working
  folder of your choice. Hereafter I name this folder as &lt;work&gt;.</P>
  <P>Unzip wcg.zip</P>
  <P>&gt;cd &lt;work&gt;/wcg</P>
  <P>&gt;dir</P>
  <P>&nbsp;Directory of E:\Axiswcg<br>
  <br>
  07/25/2003 08:32p &lt;DIR&gt; .<br>
  07/25/2003 08:32p &lt;DIR&gt; ..<br>
  07/24/2003 09:09p &lt;DIR&gt; common<br>
  07/25/2003 08:21p 249,856 wcg.exe</P>
  <P>This will contain the tool itself (wcg.exe) and the Axis common include
  files that are needed by the WCG to make the service DLL. </P>
  <P>Now run the wcg.exe with the following options.</P>
  <P>In linux</P>
  <P>&lt;work&gt;/wcg&gt;wcg -L&lt;path to directory where the SimpleService.a is&gt; -ISimpleService.lib -oMyService 
  -I. -I&lt;path to directory where the SimpeWebService.h is&gt;</P>
  <P>In windows</P>
  <P>&lt;work&gt;/wcg&gt;wcg /L&lt;path to directory where the SimpleService.a is&gt; /ISimpleService.lib 
  /oMyService /I. /I&lt;path to directory where the SimpeWebService.h is&gt;</P>
  <P> -L&lt;path to your service lib&gt; and -l&lt;your service lib name&gt;
  option tells wcg where your service library is.</P>
  <P>-I&lt;include file path&gt; option let you include additional
  header files. You can have multiple include paths.</P>
  <P>-o&lt;generated so/dll name&gt; will specify the name you want for
  your generated so/dll without extension.</P>
  <P>After executing this command you will find MyService.so (MyService.dll
  in windows) created in the current folder where you ran the wcg.exe.</P>
  <P><BR>Copy this so/dll into where apache will be serching for
  deployed services.</P>
  <P> <BR>&nbsp;<U>Guidelines to follow in order to use WCG tool</U></P>
  <UL>
  	<P>Web service header files should follow following guidelines in
  	order to use wrapper class generater tool. Most of the limitations
  	imposed here are due to the fact that wrapper class is still young
  	and evolving. Please feel free to report any other limitations you
  	come across when using the WCG tool to <A HREF="mailto:axis-dev@ws.apache.org?subject=[AxisC++] Reporting  limitations in WCG tool">axis-dev@ws.apache.org</A></P>
  	<LI><P>axis includes should be included as from standard include
  	directories using '&lt;' and '&gt;'(not “.....”)</P>
  	<LI><P>All user types should derive from IAccessBean interface and
  	inside the class predefined macro ACCESSBEAN_SERIALIZABLE should be
  	declared.(See example)</P>
  	<LI><P>Basic data types shoud be passed and returned by value or by
  	reference(using &amp;)</P>
  	<LI><P>User data types shoud be passed and returned by pointers
  	(using *).</P>
  	<LI><P>No variable qualifiers should be used such as const, static,
  	volatile etc.</P>
  	<LI><P>No function qualifiers should be used such as const, static
  	etc. except virtual.</P>
  	<LI><P>Should not use extern keyword.</P>
  	<LI><P>Defining macros is OK but using macros is not allowed.</P>
  	<LI><P>No global or static variables outside classes.</P>
  	<LI><P>Only integer default values are allowed for method
  	parameters.</P>
  	<LI><P>No initialization lists for constructors.</P>
  	<LI><P>Member variables of basic types should be value types.</P>
  	<LI><P>Member variables of user types should be pointer types. Also 
  	constructors should allocate memory for these members and
  	destructors should delete them.</P>
  	<LI><P>Namespace directives are allowed but no namespace
  	declarations. 
  	</P>
  	<LI><P>Scope resolution operator(::) is not allowed anywhere.</P>
  	<LI><P>No enumerations allowed.</P>
  	<LI><P>No inline functions allowed.</P>
  	<LI><P>No type defs allowed.</P>
  	<LI><P>No operator overloading allowed.</P>
  	<LI><P>Using template keyword is not allowed. But using STL is OK.</P>
  </UL>
  <P>Restart apache web server and test the web service using the java
  webservice client. For infromation on how to use the java web service
  client refer to the Axis java user guide which can be found at
  http://ws.apache.org/axis/.<BR><BR>If you want to test handlers go
  into the &lt;axiscpp_home&gt;/src/servcer/handlers folder where
  example handlers are included. Change to a particular example
  directory of your choice and type the following</P>
  <P>make clean<BR>make</P>
  <P>You will find the corresponding handler generated in
  &lt;axiscpp_home&gt;axis/handlers directory.<BR>Restart the apache
  web server and test your handler using the web service client in Axis
  java.For infromation on how to use the java web service client refer
  to the Axis java user guide which can be found at
  http://ws.apache.org/axis/.<BR><BR>Happy Axis!!!<BR><BR><BR>&nbsp;</P>
  <P>&nbsp;</P>
  <H2><A NAME="DataMapping"></A>XML &lt;-&gt; C++ Data Mapping in Axis
  C++</H2>
  <H3>How your&nbsp; C++ types map to SOAP/XML types</H3>
  <H4>Standard mappings from WSDL to C++</H4>
  <TABLE CELLPADDING=2 CELLSPACING=2>
  	<TR>
  		<TD>
  			<P>xsd:base64Binary 
  			</P>
  		</TD>
  		<TD>
  			<P>Not implemented yet</P>
  		</TD>
  	</TR>
  	<TR>
  		<TD>
  			<P>xsd:boolean 
  			</P>
  		</TD>
  		<TD>
  			<P>int</P>
  		</TD>
  	</TR>
  	<TR>
  		<TD>
  			<P>xsd:byte 
  			</P>
  		</TD>
  		<TD>
  			<P>unsigned char</P>
  		</TD>
  	</TR>
  	<TR>
  		<TD>
  			<P>xsd:dateTime 
  			</P>
  		</TD>
  		<TD>
  			<P>Not implemented yet</P>
  		</TD>
  	</TR>
  	<TR>
  		<TD>
  			<P>xsd:decimal 
  			</P>
  		</TD>
  		<TD>
  			<P>Not implemented yet</P>
  		</TD>
  	</TR>
  	<TR>
  		<TD>
  			<P>xsd:double 
  			</P>
  		</TD>
  		<TD>
  			<P><TT>double</TT></P>
  		</TD>
  	</TR>
  	<TR>
  		<TD>
  			<P>xsd:float 
  			</P>
  		</TD>
  		<TD>
  			<P><TT>float</TT></P>
  		</TD>
  	</TR>
  	<TR>
  		<TD>
  			<P>xsd:hexBinary 
  			</P>
  		</TD>
  		<TD>
  			<P>Not implemented yet</P>
  		</TD>
  	</TR>
  	<TR>
  		<TD>
  			<P>xsd:int</P>
  		</TD>
  		<TD>
  			<P><TT>int</TT></P>
  		</TD>
  	</TR>
  	<TR>
  		<TD>
  			<P>xsd:integer</P>
  		</TD>
  		<TD>
  			<P>int</P>
  		</TD>
  	</TR>
  	<TR>
  		<TD>
  			<P>xsd:long 
  			</P>
  		</TD>
  		<TD>
  			<P><TT>long</TT></P>
  		</TD>
  	</TR>
  	<TR>
  		<TD>
  			<P>xsd:QName 
  			</P>
  		</TD>
  		<TD>
  			<P>Not implemented yet</P>
  		</TD>
  	</TR>
  	<TR>
  		<TD>
  			<P>xsd:short 
  			</P>
  		</TD>
  		<TD>
  			<P><TT>short</TT></P>
  		</TD>
  	</TR>
  	<TR>
  		<TD>
  			<P>xsd:string</P>
  		</TD>
  		<TD>
  			<P>stl::string</P>
  		</TD>
  	</TR>
  </TABLE>
  <H2><A NAME="WSDL"></A>Using WSDL with Axis</H2>
  <H2><A NAME="published interfaces"></A>Published Axis Interfaces</H2>
  <H2><A NAME="newbie"></A>Newbie Tips: Finding Your Way Around</H2>
  <H2><A NAME="tcpmon"></A>Appendix : Using the Axis TCP Monitor
  (tcpmon)</H2>
  <P>This section describe a java tool that is included with Axis java
  that can be used to view what goes on the wire when a soap
  transaction is taking place. Please visit <A HREF="http://ws.apache.org/axis/">http://ws.apache.org/axis/</A>
  and get Axis java, to obtain tcpmon.</P>
  <P>The &quot;tcpmon&quot; utility can be found in the
  org.apache.axis.utils package. To run it from the command line: 
  </P>
  <PRE STYLE="margin-left: 1.96cm; margin-bottom: 0.5cm"><FONT COLOR="#000000">% java org.apache.axis.utils.tcpmon [listenPort targetHost targetPort]</FONT></PRE><P>
  Without any of the optional arguments, you will get a gui which looks
  like this: 
  </P>
  <P ALIGN=CENTER><IMG SRC="images/tcpmon1.jpg" NAME="Graphic2" ALIGN=BOTTOM WIDTH=599 HEIGHT=599 BORDER=0></P>
  <P>To use the program, you should select a local port which tcpmon
  will monitor for incoming connections, a target host where it will
  forward such connections, and the port number on the target machine
  which should be &quot;tunneled&quot; to. Then click &quot;add&quot;.
  You should then notice another tab appearing in the window for your
  new tunneled connection. Looking at that panel, you'll see something
  like this: 
  </P>
  <P ALIGN=CENTER><IMG SRC="images/tcpmon2.jpg" NAME="Graphic3" ALIGN=BOTTOM WIDTH=599 HEIGHT=600 BORDER=0></P>
  <P>Now each time a SOAP connection is made to the local port, you
  will see the request appear in the &quot;Request&quot; panel, and the
  response from the server in the &quot;Response&quot; panel. Tcpmon
  keeps a log of all request/response pairs, and allows you to view any
  particular pair by selecting an entry in the top panel. You may also
  remove selected entries, or all of them, or choose to save to a file
  for later viewing. 
  </P>
  <P>The &quot;resend&quot; button will resend the request you are
  currently viewing, and record a new response. This is particularly
  handy in that you can edit the XML in the request window before
  resending - so you can use this as a great tool for testing the
  effects of different XML on SOAP servers. Note that you may need to
  change the content-length HTTP header value before resending an
  edited request. 
  </P>
  </BODY>
  </HTML>
  
  

Mime
View raw message