axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From di...@apache.org
Subject svn commit: r382070 - in /webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp: arch/WSDL2Ws.ihtml arch/handler.ihtml arch/mem-management.ihtml clientuser-guide.ihtml install-guide.ihtml
Date Wed, 01 Mar 2006 16:15:24 GMT
Author: dicka
Date: Wed Mar  1 08:15:23 2006
New Revision: 382070

URL: http://svn.apache.org/viewcvs?rev=382070&view=rev
Log:
Update Axis C++ documentation.

Modified:
    webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/WSDL2Ws.ihtml
    webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/handler.ihtml
    webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/mem-management.ihtml
    webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/clientuser-guide.ihtml
    webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/install-guide.ihtml

Modified: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/WSDL2Ws.ihtml
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/WSDL2Ws.ihtml?rev=382070&r1=382069&r2=382070&view=diff
==============================================================================
--- webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/WSDL2Ws.ihtml
(original)
+++ webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/WSDL2Ws.ihtml
Wed Mar  1 08:15:23 2006
@@ -80,7 +80,7 @@
 <ul>
 <li> Wrapper classes for complex types with data members and constructors/destructors</li>
 <li> Helper functions for serializing/deserializing complex types</li>
-<li> Wrapper structs to handle arrays of complex types</li> 
+<li> Wrapper classes to handle arrays of complex types</li> 
 </ul>
 
 <p><a name="usage"></a></p>
@@ -90,7 +90,7 @@
 <h2>2.1 Dependencies on Axis Java tool</h2>
 
 <p>Apache Axis C++ uses WSDL processing tools from Axis Java project and extends those
for C/C++ code generation. </p>
-<p>The following jar files that comes with (or used by) Axis Java are required to run
Axis C++ WSDL2Ws tool:</p>
+<p>The following jar files that come with (or used by) Axis Java are required to run
Axis C++ WSDL2Ws tool:</p>
 <ul>
 <li>axis.jar</li>
 <li>wsdl4j.jar</li>
@@ -101,15 +101,13 @@
 <li>saaj.jar</li>
 </ul>
 
-<p>"SchemaUtils" (SchemaUtils.java) and "ElementDecl" (ElementDecl.java) classes of
Axis Java tools have been overridden by Axis C++ WSDL2Ws implementation.</p>
+<p>"SchemaUtils" and "ElementDecl" classes of Axis Java tools have been extended by
Axis C++ WSDL2Ws implementation.</p>
 
 <p>Other than the two classes mentioned above, no other class from Axis Java WSDL tool
implementation has been overridden or extended at present by Axis C++ WSDL2Ws tool; hence
all other classes in Axis Java tool are used as they are.</p>
 
-<p>Except for "SchemaUtils" and "ElementDecl" classes, the rest of the classes of Axis
C++ WSDL2Ws are unique to Axis C++ and they use functionality form Axis Java jars.</p>
-
 <p><a name="building"></a></p>
 <h2>2.2 Building the Tool</h2>
-<p>If you want to build the WSDL2Ws tool form source, there is an Apache Ant build
script to help you. 
+<p>If you want to build the WSDL2Ws tool from source, there is an Apache Ant build
script to help you. 
 Assuming that you have <a href="http://ant.apache.org/manual/install.html">installed
Ant</a> properly, what you have to do is to set the CLASSPATH to include <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2beta/">Axis
Java jar files</a> mentioned in the previous section and run ant command in $AXISCPP_HOME/src/wsdl
folder. Once you build the tool the generated wsdl2ws.jar file would be placed in $AXISCPP_HOME/lib/axis/
folder.
 </p>
 
@@ -124,10 +122,9 @@
 -help, -h              print a short help message<br>
 -o(folder)             target output folder - default is current folder<br>
 -l(c++|c)              target language (c++|c) - default is c++<br>
--s(server|client)      generate server skeletons or client stubs? (serve|client) - default
is server<br>
+-s(server|client)      generate server skeletons or client stubs? (server|client) - default
is server<br>
 -w(wrapped|nonwrapped) wrapping style of the WSDL (wrapped|nonwrapped) - default is wrapped<br>
 -verbose, -v           be verbose<br>
--m(none|gnu)           generate make files (none|gnu) - default is none<br>
 </pre>
 
 <p><a name="classpath"></a></p>
@@ -147,9 +144,6 @@
 set CLASSPATH=%AXISCPP_HOME%\lib\axis\wsdl2ws.jar;%CLASSPATH%
 </pre>
 <p>Alternatively, you can use the -classpath option of java command to specify the
CLASSPATH.</p>
-
-<p><strong>NOTE: It is a MUST that that you have wsdl2ws.jar from Axis C++ appearing
before all the jar files form Axis Java on the CLASSPATH.</strong> If not you will run
into trouble when generating code. This is a known problem and happens because the two classes,
"SchemaUtils" and "ElementDecl", of Axis C++ that overides Axis Java classes with the same
name have identical package names to that of Axis Java classes.
-</p>
 
 <p><a name="runtool"></a></p>
 <h2>2.5 Running the Tool</h2>

Modified: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/handler.ihtml
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/handler.ihtml?rev=382070&r1=382069&r2=382070&view=diff
==============================================================================
--- webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/handler.ihtml
(original)
+++ webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/handler.ihtml
Wed Mar  1 08:15:23 2006
@@ -42,57 +42,45 @@
 <P><A name="ServerHandlerSample"></A></P>
 <H2>Building the echoStringHeaderHandler</H2>
 <H3>Linux</H3>
-<P>
-<BLOCKQUOTE>The build files are available at</BLOCKQUOTE>
-<BLOCKQUOTE>
-<B>&lt;Axis install directory&gt;/samples/server/echoStringHeaderHandler</B></BR>
-Change your current directory to this directory and then execute the
-following...
-
+<P>The build files are available at:</P>
+<BLOCKQUOTE><B>&lt;Axis install directory&gt;/samples/server/echoStringHeaderHandler</B></BLOCKQUOTE>
+<P>Change your current directory to this directory and then execute the following...</P>
 <UL>
 	<LI>make</LI>
 	<LI>make install</LI>
 </UL>
-</BLOCKQUOTE>
-<BLOCKQUOTE>The handler <B>libeshhandler.so</B> file will be created at
<B>&lt;Axis
-install directory&gt;/lib directory</B></BLOCKQUOTE><H3>Windows</H3>
-<BLOCKQUOTE>The VC dsw file (ServerHandlers.dsw) is available at</BLOCKQUOTE>
-<BLOCKQUOTE><B>&lt;Axis Install directory&gt;/vc/samples/server/
-ServerHandlers.dsw</B>.</BLOCKQUOTE>
-<BLOCKQUOTE>Open this file and build the project <B>echoStringHeaderHandler</B>.
Once the build is successful you will find the DLL (
-<B>echoStringHeaderHandler.dll</B>) at<B>&lt;Axis install
-directory&gt;/bin</B></BLOCKQUOTE>
+<P>The handler <B>libeshhandler.so</B> file will be created at</P>
+<BLOCKQUOTE><B>&lt;Axis install directory&gt;/lib directory</B></BLOCKQUOTE>
+<H3>Windows</H3>
+<P>The VC dsw file (ServerHandlers.dsw) is available at</P>
+<BLOCKQUOTE><B>&lt;Axis Install directory&gt;/vc/samples/server/ServerHandlers.dsw.</B></BLOCKQUOTE>
+<P>Open this file and build the project <B>echoStringHeaderHandler</B>.
Once the build is successful you will find the DLL (
+<B>echoStringHeaderHandler.dll</B>) at:</P>
+<BLOCKQUOTE><B>&lt;Axis install directory&gt;/bin</B></BLOCKQUOTE>
 
 
 <H2>Configuring the echoStringHeader Handler</H2>
 <P>Edit the server.wsdd file
-<A href="../install-guide.html#Server installation and configuration">(as
+<A href="../serveruser-guide.html#Deploy_the_service">(as
 created when you configured your server</A>
 <A href="../serveruser-guide.html">)</A>
 to include the handler for a
 particular service.<BR/>
-In this instance we are using the Calculator server example that we have used in both the
client and server setup examples. The example below shows how a linux file would look e.g.
libeshhandler.so is used please vary the file according to the libraries you have created.
This example shows the handler being deployed on both the incoming and outgoing message.
+In this instance we are using the Calculator server example that we have used in both the
client and server setup examples. The example below shows how a linux file would look e.g.
libeshhandler.so is used please vary the file according to the libraries you have created.
This example shows the same handler being deployed on both the incoming and outgoing message.
 
 
-<P>&lt;service name="Calculator" provider="CPP:RPC" description="Simple Calculator
Axis C++ Service "&gt; </BR>
-<B></BR>
-&lt;requestFlow name="CalculatorHandlers"&gt;</BR>
-&lt;handler name="ESHHandler" type="&lt;Axis installation
-directory&gt;/handlers/custom/echoStringHeaderHandler/libeshhandler.so"&gt;
-</BR>
-&lt;/handler&gt; </BR>
-&lt;/requestFlow&gt; </BR>
-&lt;responseFlow name="CalculatorHandlers"&gt; </BR>
-&lt;handler name="ESHHandler" type="&lt;Axis installation
-directory&gt;AXISCPP_DEPLOY/lib/libeshhandler.so"&gt; </BR>
-&lt;/handler&gt; </BR>
-&lt;/responseFlow&gt; </B></BR>
-</BR>
-&lt;parameter name="allowedMethods" value="add sub mul div "/&gt; </BR>
-&lt;parameter name="className" value="&lt;Axis installation
-directory&gt;/webservices/libcalculator.so" /&gt; </BR>
-&lt;/service&gt; </BR>
-
+<PRE>&lt;service name="Calculator" provider="CPP:RPC" description="Simple Calculator
Axis C++ Service"&gt;
+  <B>&lt;requestFlow name="CalculatorHandlers"&gt;
+    &lt;handler name="ESHHandler" type="&lt;Axis installation directory&gt;/handlers/custom/echoStringHeaderHandler/libeshhandler.so"&gt;
+    &lt;/handler&gt;
+  &lt;/requestFlow&gt;
+  &lt;responseFlow name="CalculatorHandlers"&gt;
+    &lt;handler name="ESHHandler" type="&lt;Axis installation directory&gt;/handlers/custom/echoStringHeaderHandler/libeshhandler.so"&gt;
+    &lt;/handler&gt;
+  &lt;/responseFlow&gt;</B>
+  &lt;parameter name="allowedMethods" value="add sub mul div"/&gt;
+  &lt;parameter name="className" value="&lt;Axis installation directory&gt;/webservices/libcalculator.so"
/&gt;
+&lt;/service&gt;</PRE>
 
 
 
@@ -105,7 +93,7 @@
 <H2>Running the echoStringHeader Handler</H2>
 <P>
 Since this Handler is configured to the Calculator web service in the above step, this Handler
will be executed when a client sends a SOAP
-request to the Calculator web service. Use the <A href="clientuser-guide.html#Generating
and using client stubs">calculator
+request to the Calculator web service. Use the <A href="../clientuser-guide.html#Generating
and using client stubs">calculator
 client</A> you created earlier.
 </P>
 </P>
@@ -116,26 +104,22 @@
 <H2>Building the testHandler</H2>
 <P>
 The build files are available at
-<B>&lt;Axis installation directory&gt;/samples/client/testHandler</B>.
Change your current directory to this direcotory and then you could execute the following.
+<B>&lt;Axis installation directory&gt;/samples/client/testHandler</B>.
Change your current directory to this directory and then you can execute the following.
 </P>
-<H3>linux</H3>
-<P>
-<BLOCKQUOTE>
+<H3>Linux</H3>
 <UL>
 	<LI>make</LI>
 	<LI>make install</LI>
 </UL>
-</BLOCKQUOTE>
-<BLOCKQUOTE>The handler so file will be created at <B>&lt;Axis
-installation directory&gt;/lib/</BR>
-</B></BLOCKQUOTE><B></B><H3>windows</H3>
-<BLOCKQUOTE>The VC dsw file (ClientHandlers.dsw) is available at <B>&lt;Axis
-Installation directory&gt;/vc/samples/client/ClientHandlers.dsw</B>.Open this file
and
-build the project TestHandler.</BLOCKQUOTE>
-<BLOCKQUOTE>Once the build is successful you will find the DLL
-testHandler.dll) at <B>&lt;Axis Installation directory&gt;/bin</B>. If
you see this DLL at the above
-location you are done with the first step.</BLOCKQUOTE>
-</P>
+<P>The handler so file will be created at</P>
+<BLOCKQUOTE><B>&lt;Axis installation directory&gt;/lib/</B></BLOCKQUOTE>
+<H3>Windows</H3>
+<P>The VC dsw file (ClientHandlers.dsw) is available at:</P>
+<BLOCKQUOTE><B>&lt;Axis Installation directory&gt;/vc/samples/client/ClientHandlers.dsw</B></BLOCKQUOTE>
+<P>Open this file and build the project TestHandler.</P>
+<P>Once the build is successful you will find the DLL (<B>testHandler.dll</B>)
at:
+<BLOCKQUOTE><B>&lt;Axis Installation directory&gt;/bin</B></BLOCKQUOTE>
+<P>If you see this DLL at the above location you are done with the first step.</P>
 
 <H2>Configuring the testHandler</H2>
 <P>
@@ -148,14 +132,12 @@
 Up until this point you did not need a client wsdd file the client only requires a wsdd file
when it has handlers.
 </P>
 
-<P><B>&lt;service name="Calculator" provider="CPP:RPC"
-description="Calculator web service"&gt; </BR>
-&lt;requestFlow name="CalculatorHandlers"&gt; </BR>
-&lt;handler name="TestHandler"
-type="&lt;Axis Installation directory&gt;/lib/libtest_client_handler.so"&gt;
</BR>
-&lt;/handler&gt; </BR>
-&lt;/requestFlow&gt; </BR>
-&lt;/service&gt;</B></P>
+<PRE><B>&lt;service name="Calculator" provider="CPP:RPC" description="Calculator
web service"&gt;
+  &lt;requestFlow name="CalculatorHandlers"&gt;
+    &lt;handler name="TestHandler" type="&lt;Axis Installation directory&gt;/lib/libtest_client_handler.so"&gt;
+    &lt;/handler&gt;
+  &lt;/requestFlow&gt;
+&lt;/service&gt;</B></PRE>
 
 
 
@@ -164,14 +146,14 @@
 </BR>
 <B>Note:</B> If you are using Client side Handlers you need to enter the
 <B>ClientWSDDFilePath</B> entry in your <A
-	href="install-guide#Installing Client">axiscpp.conf</A> configuration file.</BR>
+	href="../install-guide.html#Installing_Client">axiscpp.conf</A> configuration file.</BR>
 </P>	
 </P>	
 <H2>Running the testHandler</H2>
 <P>
 Since this Handler is configured to the Calculator web service in the
 above step, this Handler will be executed when you run the <A
-	href="clientuser-guide.html#Generating and using client stubs">calculator
+	href="../clientuser-guide.html#Generating_and_using_client_stubs">calculator
 web service client</A>..
 </P>
 

Modified: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/mem-management.ihtml
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/mem-management.ihtml?rev=382070&r1=382069&r2=382070&view=diff
==============================================================================
--- webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/mem-management.ihtml
(original)
+++ webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/arch/mem-management.ihtml
Wed Mar  1 08:15:23 2006
@@ -1,111 +1,194 @@
 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
 <html>
 <head>
-   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
    <title>Axis C++ Memory Management Guide</title>
-<link href="axis.css" rel=stylesheet type=text/css>
+<link href="axis.css" rel="stylesheet" type="text/css"/>
 </head>
 <body>
 
 <center>
 <h1>
-<img SRC="../images/axis.jpg" height=96 width=176></h1></center>
+<img SRC="../images/axis.jpg" height="96" width="176"/></h1></center>
 
-<h1>
-Axis C++ Memory Management Guide</h1>
-<br><i>1.0 Version</i>
-<br><i>Feedback: <a href="mailto:axis-c-dev@ws.apache.org">axis-c-dev@ws.apache.org</a></i>
-<h3>
-Contents</h3>
-<a href="#Introduction">Introduction</a>
-<br><a href="#Semantics">Allocation/De-allocation Semantics</a>
-<br><a href="#IHeaderBlock">Dealing with SOAP Headers</a>
-<br><a href="#Open Issues">Open Issues</a>
+<h1>Axis C++ Memory Management Guide</h1>
+<P><i>1.0 Version</i></P>
+<P><i>Feedback: <a href="mailto:axis-c-dev@ws.apache.org">axis-c-dev@ws.apache.org</a></i></P>
+
+<h3>Contents</h3>
+<P><a href="#Introduction">Introduction</a><BR/>
+<a href="#Semantics">Allocation/De-allocation Semantics</a><BR/>
+<a href="#IHeaderBlock">Dealing with SOAP Headers</a><BR/>
+<a href="#Open Issues">Windows Issues</a></P>
 
 <h2><a NAME="Introduction"></a>Introduction</h2>
-<p> This guide records the memory management semantics and some of the rationales of
the design decisions on which memory management semantics are based on. Being a C/C++ application,
it is a must that all users as well as developers have a clear understanding on how to deal
with memory allocation and deallocation. 
-<p> The allocation and deallocation mechanisms are centered around the serializer and
deserializer operations in Axis C++. At the moment, because Axis C++ support both C and C++
clients and services, the deserializer uses <i>malloc()</i> for memory allocation.
Hence C++ users may have to live with <i>free()</i> (instead of <i>delete</i>)
for deallocation. Of course one could still use delete from C++ programs, however this may
not guarantee the cleanest memory deallocation.
-
-<h2><a NAME="Semantics"></a>Allocation/De-allocation Semantics</h2>
-<h3>Parameters</h3>
-On the server side all the parameters added to the serializer are de-allocated by the Axis
Engine after serializing. Hence the user would not have to destruct the parameters to a function
call after calling the function.
-
-On the client side, the user is responsibe for deallocating memory after a function call.
-Please have a look at the base sample ($AXIS_HOME/samples/client/interoptests/base/) for
a client side sample.
-
-Axis C++ does not provide a special function for dynamic allocation of objects.
-One can select his/her own allocation mechanism. (<i>malloc()</i> in case of
C programs and/or <i>new</i> in case of C++ programs)
-
-<h3>Other Objects</h3>
-For XML elements and attribute objects that are created by IHandlerSoapSerializer, HeaderBlock
and Attribute, the rules for deleting the objects when the request or response is processed
are as follows.
-<ol>
-<li> Any outbound objects created, either by a client application or by a handler,
must be managed by the creator him(her)self. The Axis C++ engine does not delete any objects
(HeaderBlocks, Attributes, BasicNodes etc.).</li> 
-<li> Any inbound objects that are created by the Axis C++ Engine as a result of deserialization
should be deallocated by a target handler or the client application. Axis C++ Engine deallocates
only the headerblocks that will remain in the deserializer (headerblocks with no target handler).</li>
-</ol>
-
-<h3>Return Values</h3>
-<p> The values returned by the Axis C++ engine must be memory cleaned by the user written
code.
-The C++ code generated by the WSDL2Ws tool does contain destructors. However, at the moment,
it is not gauranteed that the destructor of a generated class would clean all  the pointer
members (Some members are cleaned while others are not). Hence the users must have a look
at the generated code to understand the semantics of memory cleaning. In case of C code, of
course the user must take care of memory cleaning.
-<p> Please note that in case of arrays, both for C and C++, the Axis C++ engine returns
a struct. Hence it is a must that the memory is cleaned properly. 
-<br> C++ Example:<br>
-<pre>
-        // testing echoIntegerArray
-        xsd__int_Array arrint; // Parameter for method call
-        arrint.m_Array = new int[ARRAYSIZE];
-        arrint.m_Size = ARRAYSIZE;
-        
-	for (x = 0; x < ARRAYSIZE; x++)
-        {
-            arrint.m_Array[x] = x;
-        }
-        
-	printf ("invoking echoIntegerArray...\n");
-        
-	xsd__int_Array arrintResult = ws.echoIntegerArray (arrint);
-        
-	// Deal with the return value
-	if (arrintResult.m_Array != NULL)
-        {
-            printf ("successful\n");
-            // Clean memory of the returned array
-            free(arrintResult.m_Array);
-        }
-        else
-            printf ("failed\n");
-
-        // Clean memory allocated for parameter
-        delete [] arrint.m_Array;
-</pre>
-<br> Please have a look at the base sample ($AXIS_HOME/samples/client/interoptests/base/)
for more information.
+<p>Memory management is very important and if not handled correctly, 
+will quickly consume resources and slow down your application.&nbsp; The basic rules
are;-</p>
+<p> For client applications,</p>
+<ul>
+  <li>Any memory object that is created by the client to pass to a web service must
be deleted by the client.</li>
+  <li>Any memory object that is passed back from the web service must be deleted by
the client.</li>
+</ul>
+<p> For server applications,</p>
+<ul>
+    <li>Any memory object that is passed to the service from the engine must be deleted
by the service.</li>
+    <li>Any memory object that is created by the service and handed back to the engine
will be deleted by the engine (or generated wrappers).</li>
+</ul>
+<p> Within the client or service applications, all memory object <u>must</u>
be 
+created using 'new' and deleted using 'delete' (The C style memory functions 
+'malloc' and 'free', or any of their variants must not be used).</p>
+
+<h2><a NAME="Semantics"></a>new/delete Semantics</h2>
+<p>If you are using the wrappers produced by WSDL2Ws then a lot of the 
+memory management is handled for you within the generated code.&nbsp; You 
+still have to follow the rules for client or service, but there may be some 
+additional steps that you will have to follow.</p>
+
+<h3>Input Parameters</h3>
+<p>The following examples rely on the application is using the stubs generated 
+by the WSDL2Ws tool.&nbsp; If the user needs to use the Axis API directly, it is 
+assumed that they know what methods to call and how these methods have been 
+bundled by the generated code.</p>
+
+<h4>Simple Types</h4>
+<p>If the object is not nillable, then use the basic type.&nbsp; For example, if

+the web service requires an <CODE>xsd__byte</CODE> value, then the client/service
code would 
+be as follows;-</p>
+<BLOCKQUOTE>webService-&gt;asNonNillableElement( (xsd__byte) 127)</BLOCKQUOTE>
+<P>If the object is nillable, then use a pointer to the basic type.&nbsp; For 
+example, if the web service requires a pointer to a <CODE>xsd__byte</CODE> value,
then the 
+client/service code would be as follows;-</P>
+<PRE>xsd__byte * pNillableInput = new xsd__byte();<BR/>
+*(pNillableInput) = (xsd__byte) 123;<BR/><BR/>
+webService-&gt;asNillableElement( pNillableInput);<BR/><BR/>
+delete pNillableInput;</PRE>
+<p>Notice that once the client/service code no longer requires the 
+pNillableObject object, it is deleted (and must be deleted by the 
+client/service code).</p>
+
+<h4>Arrays and Complex Types</h4>
+<p>Arrays and Complex Types are treated as nillable, even if they are not.&nbsp;

+For example, if the web service requires an array of&nbsp; <CODE>xsd__byte</CODE>
values, 
+then the client/service code would be as follows;-</p>
+<PRE>// Need an xsd__byte array of 2 elements,<BR/>
+// each element is assigned the value 123.<BR/>
+int arraySize = 2;<BR/>
+xsd__byte ** array = new xsd__byte*[arraySize];<BR/>
+for ( int inputIndex = 0 ; inputIndex &lt; arraySize ; inputIndex++ )<BR/>
+array[inputIndex] = new xsd__byte( 123);<BR/><BR/>
+// Now copy this array into the xsd__byte_Array<BR/>
+// that will be used to pass to the web service.<BR/>
+xsd__byte_Array arrayInput;<BR/>
+arrayInput.set( array, arraySize);<BR/><BR/>
+// Call the web service.<BR/>
+webService-&gt;asArray( &amp;arrayInput);<BR/><BR/>
+// Clear up input array<BR/>
+for ( int deleteIndex = 0 ; deleteIndex &lt; arraySize ; deleteIndex++ )<BR/>
+{<BR/>
+&nbsp;&nbsp;&nbsp; delete<BR/>
+&nbsp;&nbsp;&nbsp; array[deleteIndex];<BR/>
+}<BR/>
+delete [] array;</PRE>
+<p>Which is exactly the same code as would be used if the array was not nillable.</p>
+<h3>Output Parameters</h3>
+<p>The following examples rely on the application is using the stubs generated 
+by the WSDL2Ws tool.&nbsp; If the user needs to use the Axis API directly, it is 
+assumed that they know what methods to call and how these methods have been 
+bundled by the generated code.</p>
+
+<h4>Simple Types</h4>
+<p>If the returned object is not nillable, then use the basic type.&nbsp; For 
+example, if the web service returns a <CODE>xsd__byte</CODE> value, then the
client/service 
+code would be as follows;-</p>
+<BLOCKQUOTE>xsd__byte result = webService-&gt;asNonNillableElement( (xsd__byte)
127);</BLOCKQUOTE>
+<p>If the object is nillable, then use a pointer to the basic type.&nbsp; For 
+example, if the web service returns a pointer to a <CODE>xsd__byte</CODE> value,
then the 
+client/service code would be as follows;-</p>
+<PRE>xsd__byte * pNillableOutput = webService-&gt;asNonNillableElement( (xsd__byte)
127);<BR/>
+delete pNillableOutput;</PRE>
+<p>Notice that once the client/service code no longer requires the 
+<CODE>pNillableOutput</CODE> object, it is deleted (and must be deleted by the
client/service code).</p>
+
+<h4>Arrays and Complex Types</h4>
+<p>Arrays and Complex Types are treated as nillable, even if they are not.&nbsp;

+For example, if the web service returns an array of&nbsp; <CODE>xsd__byte</CODE>
values, then 
+the client/service code would be as follows;-</p>
+<PRE>// Call the web service.<BR/>
+xsd__byte_Array * arrayOutput = webService-&gt;getArray();<BR/><BR/>
+// Retrieve the information within the array.<BR/>
+int byteArraySize = 0;<BR/>
+const xsd__byte ** byteArray = arrayOutput-&gt;get( byteArraySize);<BR/><BR/>
+// Clear up output array
+delete arrayOutput;</PRE>
+<p>Which is exactly the same code as would be used if the array was not 
+nillable.&nbsp; Notice that only the <CODE>arrayOutput</CODE> object (that
is returned 
+    by the web service) needs to be deleted.&nbsp; The <CODE>byteArray</CODE>
object is a 
+    pointer to the contents of the <CODE>arrayOutput</CODE> object so <u>must</u>
not be 
+    deleted.</p>
 
 <h2><a NAME="IHeaderBlock"></a>Dealing with SOAP Headers</h2>
 <h3>From Stubs</h3>
-<p> IHeaderBlock is a virtual class that defines the interface to deal with SOAP headers.
You can create an IHeaderBlock at the client side using the API provided with Stub classes.
<br>
-<pre>
-IHeaderBlock* Stub::createSOAPHeaderBlock(AxisChar * pachLocalName, AxisChar * pachUri);
-</pre>
-Here the Stub class will maintain a list of all the created Header Blocks, and in the destructor
of the Stub class, it will clean up memory by deleting all those Header Blocks that were created
by the user. 
-
-<p> <b>Note 1</b>: It is advisable that if a user wants to delete a Hheader
Block, (s)he uses the API provided by the Stub class to do so.<br>
-<pre>
-void deleteCurrentSOAPHeaderBlock();
-</pre>
-Stub class is also equipped with iterator methods to traverse through the current list of
Header Blocks created.
-<br>
-
-<p> <b>Note 2</b>: IHeaderBlock destructor will take care of the Header
Block member variables and cleans them; BasicNodes (i.e its children) and the Attributes.
<br>
+<P> IHeaderBlock is a virtual class that defines the interface to deal with SOAP headers.

+To create an IHeaderBlock in the client application, use the API provided with Stub classes,

+i.e. ;-</P>>
+<pre>IHeaderBlock * Stub::createSOAPHeaderBlock( AxisChar * pachLocalName, AxisChar
* pachUri);</pre>
+<P>    The Stub class methods that handle header blocks keeps a list of all the created

+    header blocks.&nbsp; When the destructor is called, it will clean up memory 
+    by deleting the header blocks that were created using the 
+    cerateSOAPHeaderBlock method.</P>
+<P> <b>Note 1</b>: The client/service 
+    application must use the appropriate Stub method to delete a header block, 
+    i.e. ;-</P>
+<pre>void deleteCurrentSOAPHeaderBlock();</pre>
+
+<p> <b>Note 2</b>: The IHeaderBlock destructor will take care of the header
block member variables 
+(for example, BasicNodes may have children and attributes.&nbsp; These will be 
+deleted when the parent is deleted.).<br/></p>
 
 <h3>From Handlers</h3>
-<p> If the Header Blocks are created within a Handler then it is the responsibility
of the Handler writer to clean those. For that the user can write the cleanup code either
in the fini() method or in the destructor of the Handler, depending on the following situations
+<p> If header blocks are created within a 'Handler' then it is the responsibility of
the 
+'Handler' writer to delete them. The deletion would occur in the 'clean-up' code either in
the fini() 
+method or in the destructor of the Handler, depending on the following rules;-</p>
 <nl>
-<li> If it is a session handler which needs to maintain its state, then the cleanup
has to be done in the destructor.</li>
-<li> If it is a request type handler the clean up can be done in the fini() mehtod
of the Handler. Here the writer has to explicitly write the clean up code.</li>
+	<li> If it is a Session Handler which needs to maintain its state, then the cleanup
has to be done in the destructor.</li>
+	<li>If it is a request type handler the clean up can be done in the fini() method
of the Handler.</li>
 </nl>
+<P> If a target handler access a header block created by the de-serializer then it
is the responsibility of the Handler to delete it.</P>
 
-<p> If a target handler access a Header Block created by the deserializer then it is
the responsibility of the Handler to delete it.
-
-<h2><a NAME="Open Issues"></a>Open Issues</h2><p> When an array
is de-serialized it uses C style memory re-allocation mechanism in the present code. C++ does
not support <i>realloc()</i> and if we use <i>new</i> instead we have
to allocate fresh memory blocks each time we need to increase the array size. This can be
more expensive than using <i>realloc()</i>. Again the price paid for efficiency
is that one has to use <i>free()</i> and not <i>delete []</i>  from
C++ code. 
-
+<h2><a NAME="Open Issues"></a>Windows Issues</h2>
+<P> For Windows platforms, everything must built with the compiler flag '/MD' 
+regardless whether it is a DLL or an EXE.&nbsp; There are still problems however 
+when passing objects over process boundaries.&nbsp; If an object is created in 
+one process (say the Axis engine DLL) and then passed to another (say the client 
+application) then when the client tries to delete that object, it cannot find it 
+on its own process heap and throws an exception.&nbsp; This is because the 
+client process does not own the memory object.&nbsp; To overcome this problem, 
+on the process boundary, the original object is cloned (the clone uses the 
+client heap) and then the original object is freed from the engine heap.&nbsp; 
+Here is an example taken from the wrapper code created by WSDL2Ws from the 
+Arrays unit test (Arrays.cpp);-</P>
+<PRE>xsd__int_Array * Arrays::simpleArray( xsd__int_Array* Value0)<BR/>
+{<BR/>
+&nbsp;&nbsp;&nbsp;xsd__int_Array * RetArray = new xsd__int_Array();<BR/>
+&nbsp;&nbsp;&nbsp;:<BR/>
+&nbsp;&nbsp;&nbsp;:<BR/>
+&nbsp;&nbsp;&nbsp;if ( AXIS_SUCCESS == m_pCall-&gt;invoke())<BR/>
+&nbsp;&nbsp;&nbsp;{<BR/>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if ( AXIS_SUCCESS == m_pCall-&gt;checkMessage(
&quot;simpleArrayResponse&quot;, &quot;http://org.apache.axis/Arrays/&quot;))<BR/>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{<BR/>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Axis_Array
* RetAxisArray = m_pCall-&gt;getBasicArray( XSD_INT, &quot;simpleType&quot;, 0);<BR/>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;RetArray-&gt;clone(
*RetAxisArray);<BR/>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Axis::AxisDelete(
(void*) RetAxisArray, XSD_ARRAY);<BR/>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
+}<BR/>&nbsp;&nbsp;&nbsp;}<BR/>
+&nbsp;&nbsp;&nbsp;m_pCall-&gt;unInitialize();
+<BR/>&nbsp;&nbsp;&nbsp;return
+RetArray;<BR/>
+}</PRE>
+<P> The two lines of interest are the cloning of the memory object (RetAxisArray 
+exists within the engine heap) into the RetArray memory object (that exists 
+within the client heap) and then the deletion of the RetAxisArray by calling the 
+AxisDelete method (which exists within the engine process and hence will be able 
+to delete the object from that heap).</P>
 </body>
-</html>
-
+</html>
\ No newline at end of file

Modified: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/clientuser-guide.ihtml
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/clientuser-guide.ihtml?rev=382070&r1=382069&r2=382070&view=diff
==============================================================================
--- webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/clientuser-guide.ihtml
(original)
+++ webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/clientuser-guide.ihtml
Wed Mar  1 08:15:23 2006
@@ -39,10 +39,10 @@
 <P>Firstly copy the Calculator wsdl to the client samples directory e.g. (linux)</P>
 <P><STRONG>cd &lt;Axis installation directory&gt;/samples/client/calculator</STRONG></P>
 <P><STRONG> cp -f &lt;Axis installation directory&gt;/wsdls/Calculator.wsdl
./</STRONG></P>
-<P><STRONG>IMPORTANT:In this example we are showing you how to use the WSDL2Ws
tooling to generate the stubs using
+<P><STRONG>IMPORTANT:</STRONG>In this example we are showing you how to
use the WSDL2Ws tooling to generate the stubs using
 Calculator.wsdl. However, in the &lt;Axis installation directory&gt;/samples/client/calculator
folder you will already find generated files. If you wish to use those without generating
new
 ones you can do so. We recommend that you run the calculator sample with the
-already generated files firstly and later practice using the tooling with Calculator.wsdl.</STRONG>
<BR/>
+already generated files firstly and later practice using the tooling with Calculator.wsdl.<BR/>
 <BR/>Next you create the client-side stubs that represent the Calculator service.
 </P>
 <P><B>Note: </B>Don't forget to add all of the <A href="#Pre-requisites">pre-requisite</A>
jar files into your classpath 

Modified: webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/install-guide.ihtml
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/install-guide.ihtml?rev=382070&r1=382069&r2=382070&view=diff
==============================================================================
--- webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/install-guide.ihtml
(original)
+++ webservices/axis/trunk/site/src/cpp/src/documentation/content/xdocs/cpp/install-guide.ihtml
Wed Mar  1 08:15:23 2006
@@ -47,7 +47,7 @@
 
 Axis C++ needs an XML parser to parse SOAP messages and WSDD files. It
 has a parser abstraction layer that helps users to select/switch between
-parsers. However only one parser library could be used at a time.
+parsers. However only one parser library can be used at a time.
 Currently Xerces parser is supported by Axis C++.
 </P>
 <H3>Server only</H3>
@@ -67,7 +67,9 @@
 <P><A name="Installing_Client"></A><A href="http://ws.apache.org/axis/cpp/download.html">Download
Axis
 C++</A> binary distribution and extract the package into a directory of your choice.
 </P>
-<H4><B>2. Configure environment variables</B></H4>
+<H4>2. Install Xerces C++ (2.2.0)</H4>
+<p>See the Xerces parser's documentation for installation instructions. </p>
+<H4><B>3. Configure environment variables</B></H4>
 <B>set AXISCPP_DEPLOY<BR/>
 <BR/></B>AXISCPP_DEPLOY="Path to the folder where you installed Axis C++
 <BR/>
@@ -79,7 +81,7 @@
 PATH=&lt;xerces installation directory&gt;/bin;%AXISCPP_DEPLOY/bin%;%PATH%<P>Linux:<BR/>LD_LIBRARY_PATH="&lt;xerces
installation directory&gt;/lib:$AXISCPP_DEPLOY/lib:$LD_LIBRARY_PATH"
 </P>
 
-<H4>3. Set Engine Wide Settings in Configuration File</H4>
+<H4>4. Set Engine Wide Settings in Configuration File</H4>
 <P>Axis C++ uses a configuration file to let the user specify
 preferences such as log file locations, transport and parser libs to be
 used and location of deployment descriptor files. <BR/>
@@ -92,6 +94,7 @@
 Configuration file has the following syntax on the client-side:</P>
 <P>The comment character is '#'<BR/>Transport_http - HTTP transport library:
Required<BR/>
 Channel_HTTP - Channel transport library: Required<BR/>
+Channel_HTTP_SSL - SSL channel transport library: Optional - only required is you are going
to use ssl<BR/>
 XMLParser - The Axis XML parser library that comes with your configuration: Required<BR/>
 SecureInfo: SSL configuration information: Optional - only required if you are going to use
ssl<BR/>
 ClientWSDDFilePath - Path to the client wsdd: Optional -  only required if you are using
client-side handlers<BR/>ClientLogPath - Path to the Axis C++ client log: Optional -
 only required if you want engine trace for debugging purposes</P>
@@ -99,9 +102,9 @@
 
 <PRE>
 
-Transport_http:/usr/local/axiscpp_deploy/lib/libaxis3_transport.so
-Channel_HTTP:/usr/local/axiscpp_deploy/lib/libaxis3_transport_channel.so
-XMLParser:/usr/local/axiscpp_deploy/lib/libaxis_xercesc.so
+Transport_http:/usr/local/axiscpp_deploy/lib/libhttp_transport.so
+Channel_HTTP:/usr/local/axiscpp_deploy/lib/libhttp_channel.so
+XMLParser:/usr/local/axiscpp_deploy/lib/libaxis_xerces.so
 ClientWSDDFilePath:/usr/local/axiscpp_deploy/etc/client.wsdd
 ClientLogPath:/usr/local/axiscpp_deploy/log/AxisClientLog</PRE><H3><I></I></H3><P><BR/>Once
you have completed the above steps you should be ready to <A
 	href="user-guide.html">create and run</A> your client application using AXIS C++
!<BR/>
@@ -195,7 +198,7 @@
 <b>LoadModule axis_module libexec/libaxiscpp_mod.so</b> </p><pre>
 </pre>
 
-<H4>7. Deploying Axis Module to Apache Web Server </H4>
+<H4>8. Deploying Axis Module to Apache Web Server </H4>
 
 <p>Now we need to copy Apache module (libaxiscpp_mod2.so - linux names- for Apache
2.0.x and 
 libaxiscpp_mod.so for Apache 1.3.x) to the correct places and start Apache web server.
@@ -216,7 +219,7 @@
 To deploy with Apache 1.3.x </p>
 <b>sh deploy_apache.sh </b>
 
-<H4>8. See Axis C++ in action</H4>
+<H4>9. See Axis C++ in action</H4>
 <p>
 Now the installation is complete. You can verify that the server side is working by accessing
the URL <a  href="http://localhost/axis">http://localhost/axis</a> using your
web browser. You should get the Axis C++ welcome page and this page will show you a list of
deployed services as specified by the
 &lt;Axis Installation directory&gt;/conf/server.wsdd file. Although at this stage
you won't have any services deployed yet.</p><p>Now you can <A



Mime
View raw message