You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by di...@apache.org on 2003/10/24 15:14:05 UTC
cvs commit: ws-axis/contrib/axisdocs/src/documentation/content/xdocs/cpp architecture-guide.ihtml developers-guide.ihtml integration-guide.ihtml user-guide.ihtml
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>
<a href="#AxisEngine">AxisEngine</a>
<br>
<a href="#HandlerPool">HandlerPool</a>
<br>
<a href="#Deserializer">Soap Deserializer</a>
<br>
<a href="#Serializer">Soap Serializer</a>
<br>
<a href="#WSDD">WSDD Module </a>
<br>
<a href="#ServerConfig">Server Configuration</a>
<br>
<a href="#Logger">Logger</a>
<br>
<a href="#Deployment">Web Service Deployment </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 - 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>. </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.
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
</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> </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, </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> </p>
<p></p>
<p> </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>
</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’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> </o:p></p>
<a name="TestStructure"></a>
<h2>Test Structure</h2>
<p> </p>
<a name="CodeChecks"></a>
<h2>Adding Source Code Checks</h2>
<p> </p>
<a name="JUnit"></a>
<h2>CUnit and Axis</h2>
<p> </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> <A HREF="#Components">Components<!-- <br> <a href="#System Management Plug">System Management</a>
--></A>
<BR> <A HREF="#Logging/Tracing Plug">Logging/Tracing</A> <BR>
<A HREF="#Configuration" NAME="Configuration">Configuration</A><BR>
<A HREF="#Handlers Plug">Handlers</A> <BR> <A HREF="#Internationalization Plug">Internationalization</A>
<BR> <A HREF="#Performance Monitoring Plug">Performance
Monitoring</A> <BR> <A HREF="#Encoding Plug">Encoding</A> <BR>
<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. 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? 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? 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
<axiscpp_home></FONT></P>
<P STYLE="margin-bottom: 0cm"><FONT SIZE=3>goto
<axiscpp_home>/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 <apache home directory>/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 "--enable-module=so") 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 <apache directory>/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><Location /axis></FONT></P>
<P STYLE="margin-bottom: 0cm"><FONT SIZE=3>SetHandler axis</FONT></P>
<P STYLE="margin-bottom: 0cm"><FONT SIZE=3></Location></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 <->
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"> <A HREF="#WSDL: Obtaining WSDL for deployed services">?WSDL:
Obtaining WSDL for deployed services</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"> <A HREF="#WSDL2Java: Building stubs, skeletons, and data">WSDL2C++:
Building stubs, skeletons, and data</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"> <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
"<A HREF="mailto:axis-user@xml.apache.org">axis-user@xml.apache.org</A>".
</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> </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><axiscpp_home>.<BR><BR>sample webservice
modules are included in <axiscpp_home>/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. 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 <work>.</P>
<P>Unzip wcg.zip</P>
<P>>cd <work>/wcg</P>
<P>>dir</P>
<P> Directory of E:\Axiswcg<br>
<br>
07/25/2003 08:32p <DIR> .<br>
07/25/2003 08:32p <DIR> ..<br>
07/24/2003 09:09p <DIR> 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><work>/wcg>wcg -L<path to directory where the SimpleService.a is> -ISimpleService.lib -oMyService
-I. -I<path to directory where the SimpeWebService.h is></P>
<P>In windows</P>
<P><work>/wcg>wcg /L<path to directory where the SimpleService.a is> /ISimpleService.lib
/oMyService /I. /I<path to directory where the SimpeWebService.h is></P>
<P> -L<path to your service lib> and -l<your service lib name>
option tells wcg where your service library is.</P>
<P>-I<include file path> option let you include additional
header files. You can have multiple include paths.</P>
<P>-o<generated so/dll name> 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> <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 '<' and '>'(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 &)</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 <axiscpp_home>/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
<axiscpp_home>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> </P>
<P> </P>
<H2><A NAME="DataMapping"></A>XML <-> C++ Data Mapping in Axis
C++</H2>
<H3>How your 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 "tcpmon" 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 "tunneled" to. Then click "add".
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 "Request" panel, and the
response from the server in the "Response" 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 "resend" 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>