blob: 05cef96bfdc7b5db71cdc47dbf6bb502ab7d2ef1 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../skin/tigris.css" type="text/css">
<link rel="stylesheet" href="../skin/mysite.css" type="text/css">
<link rel="stylesheet" href="../skin/site.css" type="text/css">
<link media="print" rel="stylesheet" href="../skin/print.css" type="text/css">
<title>Axis C++ Developer's Guide</title>
</head>
<body bgcolor="white" class="composite">
<div id="banner">
<table width="100%" cellpadding="8" cellspacing="0" summary="banner" border="0">
<tbody>
<tr>
<td align="left">
<div class="groupLogo">
<a href="http://ws.apache.org/"><img border="0" class="logoImage" alt="The Apache WebServices Project" src="../images/project-logo.jpg"></a>
</div>
</td><td align="right">
<div class="projectLogo">
<a href="http://ws.apache.org/axis/"><img border="0" class="logoImage" alt="The Apache Axis Project" src="../images/axis.jpg"></a>
</div>
</td><td valign="top" rowspan="2" align="right" class="search">
<form target="_blank" action="http://www.google.com/search" method="get">
<table summary="search" border="0" cellspacing="0" cellpadding="0">
<tr>
<td bgcolor="#a5b6c6" colspan="3"><img height="10" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td>
</tr>
<tr>
<td colspan="3"><img height="8" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td>
</tr>
<tr>
<td><img height="1" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td><td nowrap="nowrap"><input value="ws.apache.org" name="sitesearch" type="hidden"><input size="10" name="q" id="query" type="text"><img height="1" width="5" alt="" src="../skin/images/spacer.gif" class="spacer"><input name="Search" value="GO" type="submit">
<br>
Search WS</td><td><img height="1" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td>
</tr>
<tr>
<td colspan="3"><img height="7" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td>
</tr>
<tr>
<td class="bottom-left-thick"></td><td bgcolor="#a5b6c6"><img height="1" width="1" alt="" src="../skin/images/spacer.gif" class="spacer"></td><td class="bottom-right-thick"></td>
</tr>
</table>
</form>
</td>
</tr>
</tbody>
</table>
</div>
<table width="100%" cellpadding="0" cellspacing="0" border="0" summary="nav" id="breadcrumbs">
<tbody>
<tr class="status">
<td><a href="http://www.apache.org/">Apache</a> | <a href="http://ws.apache.org/">WS</a><a href=""></a></td><td id="tabs">
<div class="tab">
<span class="selectedTab"><a class="base-selected" href="../index.html">WebServices-Axis</a></span>
</div>
</td>
</tr>
</tbody>
</table>
<table id="main" width="100%" cellpadding="8" cellspacing="0" summary="" border="0">
<tbody>
<tr valign="top">
<td id="leftcol">
<div id="navcolumn">
<div class="menuBar">
<div class="menu">
<span class="menuLabel">Axis</span>
<div class="menuItem">
<a href="http://ws.apache.org/axis/index.html">Introduction</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/news.html">News</a>
</div>
<div class="menuItem">
<a href="http://wiki.apache.org/ws/FrontPage/Axis">FAQ/Wiki</a>
</div>
<div class="menu">
<span class="menuLabel">Get Involved</span>
<div class="menuItem">
<a href="http://ws.apache.org/axis/overview.html">Overview</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/cvs.html">CVS Repository</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/mail.html">Mailing Lists</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/ref.html">Reference Library</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/bugs.html">Bugs</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/howtobuild.html">HowToBuildSite</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Axis (Java)</span>
<div class="menuItem">
<a href="http://ws.apache.org/axis/java/index.html">Documentation</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/java/install.html">Installation</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/java/user-guide.html">User's Guide</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/java/developers-guide.html">Developer's Guide</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/java/integration-guide.html">Integration Guide</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/java/architecture-guide.html">Architecture Guide</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/java/reference.html">Reference Guide</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/java/reading.html">Reading Guide</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/java/requirements.html">Requirements</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Axis (C++)</span>
<div class="menuItem">
<a href="../cpp/index.html">Home</a>
</div>
<div class="menuItem">
<a href="../cpp/documentation.html">Documentation</a>
</div>
<div class="menuItem">
<a href="../cpp/download.html">Download</a>
</div>
<div class="menuItem">
<a href="http://wiki.apache.org/ws/FrontPage/AxisCPP">Wiki Pages</a>
</div>
<div class="menuItem">
<a href="../cpp/who.html">Who we are</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Downloads</span>
<div class="menuItem">
<a href="http://ws.apache.org/axis/releases.html">Releases</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/interim.html">Interim Drops</a>
</div>
<div class="menuItem">
<a href="http://cvs.apache.org/viewcvs/ws-axis/">Source Code</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Translation</span>
<div class="menuItem">
<a href="http://ws.apache.org/axis/ja/index.html">Japanese</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Related Projects</span>
<div class="menuItem">
<a href="http://ws.apache.org/wsif/">WSIF</a>
</div>
<div class="menuItem">
<a href="http://cvs.apache.org/viewcvs/*checkout*/ws-wsil/java/README.htm">WSIL</a>
</div>
<div class="menuItem">
<a href="http://www-124.ibm.com/developerworks/projects/wsdl4j/">WSDL4J</a>
</div>
<div class="menuItem">
<a href="http://www.uddi4j.org/">UDDI4J</a>
</div>
</div>
<div class="menu">
<span class="menuLabel">Misc</span>
<div class="menuItem">
<a href="http://ws.apache.org/axis/who.html">Who We Are</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/contact.html">Contact</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/legal.html">Legal</a>
</div>
<div class="menuItem">
<a href="http://ws.apache.org/axis/docs.html">Notes/Docs</a>
</div>
</div>
</div>
</div>
</div>
</td><td>
<div id="bodycol">
<div class="app">
<div align="center">
<h1>Axis C++ Developer's Guide</h1>
</div>
<div class="h3">
<div class="h3">
<h3>Contents</h3>
</div>
<p>This guide is meant to be read by those of you who would like to check out the code and create either a new transport layer or new parser layer. If you just want to check out the code and build it yourself e.g. because you want to port it to a new new platform then please see the <a href="antbuild-guide.html">build guide.</a>
</p>
<ul>
<li>
<a href="#checkingOut">Checking out source code</a>
</li>
<li>
<a href="#transport">Build your own transport layer</a>
</li>
<li>
<a href="#parser">Build your own parser layer</a>
</li>
<li>
<a href="#extraPlatforms">Adding support for extra platforms</a>
</li>
</ul>
<strong>Before going through this guide, please go through the Windows User Guide and also be familiar with how to use binaries.</strong>
<br>
<br>
<div class="h3">
<h3>Checking out source code</h3>
</div>
<p>
<a name="checkingOut"></a>The source code for Axis C++ is held in SVN. Instructions for using the Apache SVN system can be found <a href="http://www.apache.org/dev/version-control.html#anon-svn">here</a>. The Axis C++ repository is <a href="http://svn.apache.org/repos/asf/webservices/axis/trunk/c">http://svn.apache.org/repos/asf/webservices/axis/trunk/c</a>.</p>
<div class="h3">
<h3>Creating and Building your own transport layer</h3>
</div>
<p>
<a name="transport"></a>In very extreme cicumstances you might need to implement your own transport layer. If this is the case then you need to read thie following section.</p>
<p>
<img alt="" src="images/c/parserd/transport.jpg"></p>
<p>When creating your own transport layer refer SoapTransport.h header file for API.To see an example implementation refer AxisTransport.h and AxisTransport.cpp</p>
<p>Implement SoapTransport.h interface according to rules described in the header file.<br>Transport layer is built separately from Axis. Then Axis loads transport dynamic library through following export functions which you also have to implement.</p>
<p>CreateInstance (SoapTransport *pOut)- Used by Axis to create an instance of your transport class<br>DestroyInstance (SoapTransport *pIn) - Used by Axis to destroy the created transport class instance</p>
<p>Compile your transport code and build a dynamic library. Add the name of your transport library to axis configuration file (axiscpp.conf) so that Axis can find your library at runtime.</p>
<div class="h3">
<h3>Debugging client problems using the MockServer</h3>
</div>
<p>
<a name="mockserver"></a>Within the ant test framework we have what we call a 'MockServer'. This is a 100 percent Java tool that allows you to send back any response that you wish to the client. This tool can be particularly useful for debugging problems in the client that come from the mailing list. You need the users WSDL (to create the stubs) and ask them to capture the response from the server (or you can make this by-hand if you wish it's just a bit harder).</p>
<p>Here are some simple instruction on using the MockServer utility we use for testing Axis c++ client without a server outside of the mockserver. Compile mock server java code (found within <strong>&lt;Axis extract root &gt;/tests/utils/monitor</strong> )</p>
<p>Run the mock server: <strong>java org.apache.test.MockServer -p &lt;port&gt; -r &lt;server response file</strong>&gt;</p>
<p>The server response file is a text file containing the full HTTP response, it will look something like this:<br>
<br> HTTP/1.1 200 OK<br>Server: WebSphere Application Server/5.1<br>Content-Type: text/xml; charset=utf-8<br>Content-Language: en-GB<br>Transfer-Encoding: chunked<br>
<br>1ad<br>&lt;?xml version="1.0" encoding="utf-8"?&gt;<br>&lt;soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;<br>&lt;soapenv:Header/&gt;<br>&lt;soapenv:Body&gt;<br>&lt;addResponse xmlns="http://localhost/axis/Calculator"&gt;<br>&lt;addReturn&gt;5&lt;/addReturn&gt;<br>&lt;/addResponse&gt;<br>&lt;/soapenv:Body&gt;<br>&lt;/soapenv:Envelope&gt; 0</p>
<p>The easiest way to generate this file is to capture the communication from a real server but if that isn't possible you will need to generate by hand (plenty of examples within &lt;extract root&gt;/test/auto_build/testcases/output ) Rather than providing the specific chunk size (1ad, on the line ahead of the payload) you can provide ### and the MockServer will calculate the correct size.</p>
<p>If your testcase makes multiple calls to the web service, you can simply append all the requests (in the correct order!) within the server response file.</p>
<p>Once the test has been completed you need to run the following to stop the server:<br>
<strong>java org.apache.test.StopMockServer -p &lt;port&gt; -h &lt;host&gt;</strong>
</p>
<div class="h3">
<h3>Creating and Building your own parser</h3>
</div>
<p>
<a name="parser"></a>In very extreme cirumstances you may want to write your own parser layer. If you do then you need to read this section.</p>
<p>
<img alt="" src="images/c/parserd/parser.jpg"></p>
<p>
<strong>Note:Implement XMLParser.h interface according to the rules described in the header file.</strong>
<br>
</p>
<p>When creating your own parser refer XMLParser.h header file for API. To see an example implementation refer SoapParserXerces.h and SoapParserXerces.cpp.</p>
<p>Axis loads the parser dynamic library through following export functions which you also have to implement.</p>
<p>CreateInstance() - Used by Axis to create an instance of your parser class<br>DestroyInstance() - Used by Axis to destroy the created parser class instance</p>
<p>Compile your parser code and build a dynamic library. Add the name of your parser library to Axis configuration file (axiscpp.conf) so that Axis can find your library at runtime</p>
<div class="h3">
<h3>Adding support for extra platforms</h3>
</div>
<p>
<a name="extraPlatforms"></a>If you are working on a platform not currently supported by Axis C++ the community would be very grateful for your assistance in providing support for that platform.</p>
<p>Instructions for adding an extra platform to the ANT build scripts can found <a href="antbuild-guide.html#addingExtraPlatform">here</a>.</p>
<p>If you need to make any modifications to the code specific to your platform we ask that you make the appropriate updates in the platform abstraction layer, by doing the following:</p>
<ul>
<li>Create new <span class="codefrag">platforms\[platform]\PlatformSpecific[platform].hpp</span> file (and possibly also <span class="codefrag">.cpp</span> file), ensuring all macros and methods already in platform abstraction layer a copied across and updated as required.</li>
<li>Update <span class="codefrag">platforms\PlatformAutoSense.hpp</span> to correctly detect platform and include correct header file.</li>
</ul>
<p>If you need to change something that has not been previously abstracted please ensure you update the other platforms to contain the existing code.</p>
<div id="pdf" align="right">
<a href="developers-guide.pdf"><img alt="PDF" src="../skin/images/pdfdoc.gif" class="skin"><br>
PDF</a>
</div>
</div>
</div>
</div>
</td>
</tr>
</tbody>
</table>
<div id="footer">
<table summary="footer" cellspacing="0" cellpadding="4" width="100%" border="0">
<tbody>
<tr>
<td colspan="2">
<div align="center">
<div class="copyright">
Copyright &copy; 2000-2005&nbsp;The Apache Software Foundation. All rights reserved.
</div>
</div>
</td>
</tr>
<tr>
<td align="left"></td><td align="right">
<div align="right">
<div class="credit"></div>
</div>
</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>