You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by to...@apache.org on 2005/01/26 10:10:22 UTC
cvs commit: ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch ArchitectureGuide.ihtml client.ihtml CommonMainCD.ihtml d1-2.ihtml d1-3.ihtml d1-4.ihtml d1-5.ihtml d1-6.ihtml d1-7.ihtml d1-8.ihtml d1-9.ihtml d1.ihtml deploy.ihtml EngineMainCD.ihtml h2i.bat handler.ihtml i2h.bat maincd.ihtml mem-management.ihtml server.ihtml soapE_AxisModule.ihtml soapEngine.ihtml usecase.ihtml WSDL2Ws.ihtml
toshi 2005/01/26 01:10:22
Added: site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch
ArchitectureGuide.ihtml client.ihtml
CommonMainCD.ihtml d1-2.ihtml d1-3.ihtml d1-4.ihtml
d1-5.ihtml d1-6.ihtml d1-7.ihtml d1-8.ihtml
d1-9.ihtml d1.ihtml deploy.ihtml EngineMainCD.ihtml
h2i.bat handler.ihtml i2h.bat maincd.ihtml
mem-management.ihtml server.ihtml
soapE_AxisModule.ihtml soapEngine.ihtml
usecase.ihtml WSDL2Ws.ihtml
Log:
A feedback from the i18n task on the Japanese Axis Community.
The translation was made by Youhei Kawada [kawadayu@nttdata.co.jp].
Revision Changes Path
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/ArchitectureGuide.ihtml
Index: ArchitectureGuide.ihtml
===================================================================
<html>
<head>
<title>Architecture Guide</title>
</head>
<body>
<h1>Architecture Guide</h1>
<h2>
Contents
</h2>
<ul>
<li>
<a href="#intro">Introduction</a>
</li>
<li>
<a href="#webapp">Architecture Overview</a>
</li>
<li><a href="#depend"> 1.AxisEngine</a>
</li>
<li>
<a href="#start"> 2.HandlerPool</a>
</li>
<li>
<a href="#msoap"> 3.Message Model</a>
</li>
<li>
<a href="#install-test"> 4.Soap Deserializer</a>
</li>
<li>
<a href="#deploy"> 5.Soap Serializer</a>
</li>
<li>
<a href="#test"> 6.WSDD Module</a>
</li>
<li>
<a href="#massagef">Message Flow</a>
</li>
<li>
<a href="#wrapper">WSDL2Ws Tool</a>
</li>
<li>
<a href="#Dbook">Diagram Book</a>
</li>
<li>
<a href="#open">Open Issues</a>
</li>
</ul>
<p><a name="intro"/></a></p>
<h2>Introduction</h2>
<p> This guide describes the architecture of Axis C++ implementation. </p>
<br>
<p><a name= "webapp"/></a></p>
<h2>Architecture Overview</h2>
<p>Axis C++ is all about deploying C++ web services and processing SOAP messages. Axis C++ architecture closely follows Axis Java in Handler and message paths. </p>
<h3>Handlers and the Message Path in Axis</h3>
<p>Axis C++ implementation follows how handlers and message paths work in Axis Java implementation.
When the central Axis processing logic runs, a series of Handlers 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></p>
<br>A MessageData is a structure which contains several important parts:
<a><li> Deserializer</li></a>
<a><li> Serializer</li></a>
<a><li>A bag of properties</li></a>
<br><br> We will be discussing more on each of this later on this Architecture Guide.
<h3>Message Path on the Server</h3>
<br>The server side message path is shown in the following diagram. The small cylinders represent Handlers and the larger, enclosing cylinders represent Chains (ordered collections of Handlers which will be described shortly).
<p><center>
<img SRC="../images/c/ag/massagep.jpg" ></center></p>
<br>
<center> figure 1.0</center>
<p>Above diagram shows you how the Axis C++ Engine architecture works to invoke functions of AxisC++ Server Engine.</p>
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 soapstream object (specified in Packet.h), and pass it to Axis C++ Engine to be processed. The soapstream is also loaded with various properties 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.
The Axis C++ Server Engine'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 Chains. A Chain is also a Handler consisting of a sequence of Handlers which are invoked in turn -- more on Chains later. Transport request handlers are invoked.
<br>Then the loaded handler chains are invoked in the order as shown in the diagram, passing the MessageData object into the invoke().
<br><b>Note:</b>
<br>Service Specific Layer
<br>Actual Web service provider is wrapper Class. Handler Chains invoke a list of Handlers in a while loop and HandlerChains.cpp invoke handler one by one.
<p><a name="#massagef"/></a></p>
<h2>Message Flow</h2>
<h3>Handlers and Chains</h3>
Handlers are invoked in sequence to process messages. At some point in the sequence a Handler may send a request and receive a response or else process a request and produce a response. Such a Handler is known as the pivot point of the sequence. As described above, Handlers are either transport-specific, service-specific, or global. The Handlers of each of these three different kinds are combined together into Chains. So the overall sequence of Handlers comprises three Chains: transport, global, and service. The following diagram shows two sequences of handlers: the client-side sequence on the left and the server-side sequence on the right.
<p><center>
<img SRC="../images/c/ag/pivots.jpg" ></center></p>
<center>figure 3.0</center>
<p>A web service does not necessarily send a response message to each request message, although many do. However, response Handlers are still useful in the message path even when there isn't a response message, e.g. to stop timers, clean up resources, etc.
A Chain is a composite Handler, i.e. it aggregates a collection of Handlers as well as implementing the Handler interface</p>
<p>A Chain also has similarities to the Chain of Responsibility design pattern in which a request flows along a sequence of Handlers until it is processed. Although an Axis Chain may process a request in stages over a succession of Handlers, it has the same advantages as Chain of Responsibility: flexibility and the ease with which new function can be added.
Back to message processing -- a message is processed by passing through the appropriate Chains. A message Data is used to pass the message and associated environment through the sequence of Handlers. The model is that Axis Chains are constructed offline by having Handlers added to them one at a time. Then they are turned online and message data start to flow through the Chains.
Handlers and Chains can be defined to have 'request', 'session', or 'application' scope.
<p><a name="depend"/></a></p>
<h2>1.Axis Engine</h2>
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.
Following Diagram shows how the transport listener passes the SOAP message to the AxisEngine. AxisEngine is a singleton object for a process.
<p><center>
<img SRC="../images/c/ag/d1-3.jpg"></center></p>
<p><a name="start"/></a></p>
<h2>2.HandlerPool</h2>
AxisEngine instantiates a HandlerPool object in its constructor. HandlerPool does the following 3 tasks,<p>
<br>1. Loads and keeps Transport and Global handlers.
<br>2. Loads service specific handlers when needed and unloads when needed.
<br>3. Loads target web service handler when needed and unloads when needed. </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>
In order for the HandlerLoader to dynamically load a class, every DLL (or Shared object) must have following export functions. </p>
<p>int GetClassInstance(DCLInterface **inst);
<p>int DestroyInstance(DCLInterface *inst);
<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>BasicHandler</b>and is known to AxisEngine. This interface is implemented by every webservice and a handler.</p>
<p><a name="msoap"/></a></p>
<h2>3.Message Model</h2>
The XML syntax of a SOAP message is fairly simple. A SOAP message consists of an envelope containing:
<br>� an optional header containing zero or more header entries (sometimes ambiguously referred to as headers),
<br>� a body containing zero or more body entries, and
<br>� zero or more additional, non-standard elements.
<br><br>The only body entry defined by SOAP is a SOAP fault which is used for reporting errors.
Some of the XML elements of a SOAP message define namespaces, each in terms of a URI and a local name, and encoding styles, a standard one of which is defined by SOAP.
Header entries may be tagged with the following optional SOAP attributes:
� actor which specifies the intended recipient of the header entry in terms of a URI, and
� mustUnderstand which specifies whether or not the intended recipient of the header entry is required to process the header entry.
So the SOAP message model looks like this:
<p><center>
<img SRC="../images/c/ag/soap.jpg" ></center></p>
<p><a name="install-test"/></a>
<h2> 4.Soap Deserializer</h2>
<p>Currently the Soap Deserializer is implemented using SAX2 parser. Soap Deserializer exposes and API such that the API is independent of the implementation.</p>
<p><a name="deploy"/></a></p>
<h2>5.Soap Serializer </h2>
<p>Soap Serializer's task is to generate the 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 generate the SOAP message.</p>
<p><a name="test"/></a></p>
<h2>6.WSDD Module </h2>
WSDD module is a set of classes that parses the deployment descriptor file(server.wsdd) which, is a XML file and makes the information available to the AxisEngine. The WSDD module represents the structure of a WSDD file.
<p><a name="wrapper"/></a></p>
<h2>WSDL2Ws Tool</h2>
WSDL2Ws Tool is generated Client Side stubs and server side skeletons and wrappers.It's architecture is described in
<a href ="WSDL2Ws.html"> WSDL2Ws.html </a></p>
<p><a name="Dbook"/></a></p>
<h2>Diagram Book</h2>
<p> This<a href ="usecase.html"> Diagram Book </a>includes Following Diagrames which are drawn to describe Axis Cpp Engine and it's process.</p>
<p>1) Use case diagram(s)</p>
<p>2) Sequence diagrams</p>
<p>3) Class diagrams(s)</p>
<p>4) Deployment diagram(s)</p>
<p><a name="open"/></a></p>
<h2>Open Issues</h2>
<hr size=1 noshade= />
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/client.ihtml
Index: client.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book-Page 11</h1>
<h2>Sequence Diagram:Create Stubs</h2>
<center>
<img SRC="../images/c/ag/d2-1.jpg"></center>
<a href="soapEngine.html">goto>> page No.12</a>
<br><br>
<a href="d1-9.html">Back</a>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/CommonMainCD.ihtml
Index: CommonMainCD.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book-Page 16</h1>
<h2>Class Diagram:Common/Main</h2>
<center>
<img SRC="../images/c/ag/d5.jpg"></center>
<a href="deploy.html">goto>> page No.17</a>
<br><br>
<a href="EngineMainCD.html">Back</a>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/d1-2.ihtml
Index: d1-2.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book-Page 03</h1>
<h2>Server Side Invokation Process/Invoke Web Service</h2>
<center>
<img SRC="../images/c/ag/d1-0.jpg"></center>
<a href="d1.html">goto>> page No.04.</a>
<br><br>
<a href="server.html">Back</a>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/d1-3.ihtml
Index: d1-3.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book Page-05</h1>
<h2>Server Side Invokation Process/ServerAxisEngineProcess</h2>
<center>
<img SRC="../images/c/ag/d1-3.jpg"></center>
<a href="d1-4.html">goto>> page No.06.</a>
<br><br>
<a href="d1.html">Back</a></div>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/d1-4.ihtml
Index: d1-4.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<h1>Diagram Book Page- 06</h1>
<h2>Server Side Invokation Process/InitializeHandlers</h2>
<center>
<img SRC="../images/c/ag/d1-4.jpg"></center>
<a href="d1-6.html">goto>> page No.07.</a>
<br><br>
<a href="d1-3.html">Back</a></div>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/d1-5.ihtml
Index: d1-5.ihtml
===================================================================
<html>
<head>Diagram Book-Page 1.5</head>
<title>Server Side Invokation Process/Invoke Web Service</title>
<body>
<h2>Sequence Diagram:Server Side Invokation Process/GetResponseFlowHandlerChain</h2>
<center>
<img SRC="../images/c/ag/d1-5.jpg"></center>
<a href="d1-3.html">goto>> page No.04.</a>
<br><br>
<a href="server.html">Back</a>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/d1-6.ihtml
Index: d1-6.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book - Page 07</h1>
<h2>Sequence Diagram:Server Side Invokation Process/GetRequestHandlerChain</h2>
<center>
<img SRC="../images/c/ag/d1-6.jpg"></center>
<a href="d1-7.html">goto>> page No.8.</a>
<br><br>
<a href="d1-4.html">Back</a></div>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/d1-7.ihtml
Index: d1-7.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book-Page 08</h1>
<h2>Sequence Diagram:Server Side Invokation Process/PoolHandlerChain</h2>
<center>
<img SRC="../images/c/ag/d1-7.jpg"></center>
<a href="d1-8.html">goto>> page No.9.</a>
<br><br>
<a href="d1-5.html">Back</a>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/d1-8.ihtml
Index: d1-8.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book-Page 09</h1>
<h2>Sequence Diagram:Server Side Invokation Process/PoolWebService</h2>
<center>
<img SRC="../images/c/ag/d1-8.jpg"></center>
<a href="d1-9.html">goto>> page No.10</a>
<br><br>
<a href="d1-7.html">Back</a>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/d1-9.ihtml
Index: d1-9.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book-Page 10</h1>
<h2>Sequence Diagram:Server Side Invokation Process/SoapFaultCreation</h2>
<center>
<img SRC="../images/c/ag/d1-9.jpg"></center>
<a href="client.html">goto>> page No.11</a>
<br><br>
<a href="d1-8.html">Back</a>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/d1.ihtml
Index: d1.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book Page-04</h1>
<h2>Server Side Invokation Process/ServerAxisEngineInitialize</h2>
<center>
<img SRC="../images/c/ag/d1-2.jpg"></center>
<a href="d1-3.html">goto>> page No.05.</a>
<br><br>
<a href="d1.html">Back</a></div>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/deploy.ihtml
Index: deploy.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book-Page 17</h1>
<h2>Deployment Diagram:</h2>
<center>
<img SRC="../images/c/ag/d8.jpg"></center>
<br><br>
<a href="CommonMainCD.html">Back</a>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/EngineMainCD.ihtml
Index: EngineMainCD.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book-Page 15</h1>
<h2>Class Diagram:Engine/Main</h2>
<center>
<img SRC="../images/c/ag/d6.jpg"></center>
<a href="CommonMainCD.html">goto>> page No.16</a>
<br><br>
<a href="maincd.html">Back</a>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/h2i.bat
Index: h2i.bat
===================================================================
ren *.html *.ihtml
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/handler.ihtml
Index: handler.ihtml
===================================================================
<html>
<head>
<meta http-equiv="Content-Type" content="text/html">
<title>Handler Tutorial</title>
</head>
<body>
<h1>Handler Tutorial</h1>
<p><a href="#linux">For Linux </a> <br> <br>
<a href="#windows">For Windows </a><br>
<br>
</p>
<br>
<p><a name="#linux"></a> </p>
<h1>Linux</h1>
<p><a href="#introduction"> Introduction to Handlers </a> <br> <br>
<a href="#sample">Sample Handlers (building, running)</a> <br> <br>
<a href="#creating">Creating your own Handlers </a> <br> <br>
<a href="#API">API Notes for Handler writers</a> <br> <br> </p>
<p> <a name="#introduction"> </a> </p>
<p>Handlers are pluggable components in Axis C++. We have included a set of sample handlers for your reference. You could write your own handlers by following the instructions given for the sample Handlers. <br> <br>
<b>Note: If you are using Client side Handlers you need to enter the following entry to the [Axis_Folder]/axiscpp.conf configuration file. </b> <br> <br>
ClientWSDDFilePath:xxx <br> <br>
Here xxx should be the path to the �client.wsdd� file.
<br>
</p>
<p><a name="#sample"> </a> </p>
<p><b>Testing the sample Handlers </b> </p>
<br>
<p>We have included the following sample Handlers for your reference.<br> <br>
1) echoStringHeaderHandler (A server side handler sample)<br>
This sample handler will simply echo (i.e send back) the string which you send in the SOAP Header in the SOAP request. <br> <br>
2)testHandler (A client side handler sample) <br> <br>
This sample handler will simply add a SOAP Header to the generated SOAP request. <br> <br>
Please note that these are very primitive sample handlers and are presented here to give you an idea about writing your own Handlers. <br> </p>
<p>
<b>echoStringHeaderHandler</b> <br> <br>
<b>Building the Sample Handlers in RedHat linux</b> <br><br>
<b>Building echoStringHeaderHandler</b> (A server side handler sample) <br> <br>
The build files are available at <br> <br>
AXISCPP_HOME/samples/server/echoStringHeaderHandler.<br>
Change your current directory to this directory and then you could execute the following. <br><br>
make <br><br>
make install <br><br>
The handler so file will be created at $AXISCPP_DEPLOY/lib directory <br> <br>
<b>Configuring the Handler</b> <br> <br>
Now edit the AXISCPP_DEPLOY/etc/server.wsdd to include the handler for a particular service. <br> <br>
</p>
<p>
<service name="Calculator" provider="CPP:RPC" description="Simple Calculator Axis C++ Service "> <br>
<requestFlow name="CalculatorHandlers"><br>
<handler name="ESHHandler" type="AXIS_HOME/handlers/custom/echoStringHeaderHandler/libeshhandler.so"> <br>
</handler> <br>
</requestFlow> <br>
<responseFlow name="CalculatorHandlers"> <br>
<handler name="ESHHandler" type="AXISCPP_DEPLOY/lib/libeshhandler.so"> <br>
</handler> <br>
</responseFlow> <br>
<parameter name="allowedMethods" value="add sub mul div "/> <br>
<parameter name="className" value="Axis\webservices\Calculator.dll" /> <br>
</service> <br>
</p>
<p>
<b>Note:</b> Make sure you specify the correct path of the handler so in the server.wsdd file. Replace the AXISCPP_DEPLOY with the exact relative path which AXISCPP_DEPLOY points to. (eg: type="/usr/local/axiscpp_deploy/etc/libeshhandler.so ) <br> <br>
Now you are almost done to run your server side handler.<br>
Restart the Apache server and that's it. <br> <br>
<b>Running the Handler</b> <br> <br>
Since this Handler is configured to the Calculator web service in the above step, this Handler will be executed when a client send a SOAP request to the Calculator web service. <br><br>
<b>testHandler</b> <br> <br>
<b>Building the Sample Handlers in RedHat linux</b> <br><br>
<b>Building testHandler</b> (A client side handler sample) <br> <br>
The build files are available at AXISCPP_HOME/samples/client/testHandler. Change your current directory to this direcotory and then you could execute the following. <br><br>
make <br><br>
make install <br><br>
The handler so file will be created at $AXISCPP_DEPLOY/lib/. <br> <br>
<b>Configuring the Handler</b> <br> <br>
Now edit the AXISCPP_DEPLOY/etc/client.wsdd to include the handler for a particular service.
</p>
<p>
<service name="Calculator" provider="CPP:RPC" description="Calculator web service"> <br>
<requestFlow name="CalculatorHandlers"> <br>
<handler name="TestHandler" type="AXISCPP_DEPLOY/lib/libtest_client_handler.so"> <br>
</handler> <br>
</requestFlow> <br>
</service>
</p>
<p>
<b>Note:</b> Make sure you specify the correct path of the handler so in the client.wsdd file. Replace the AXISCPP_DEPLOY with the exact relative path which AXISCPP_DEPLOY points to. (eg: type="/usr/local/axiscpp_deploy/lib/libtest_client_handler.so) <br> <br>
Now you are almost done to run your client side handler. <br> <br>
<b>Note:</b> If you are using Client side Handlers you need to enter the <ClientWSDDFilePath> entry in the AXISCPP_DEPLOY/etc/axiscpp.conf configuration file. (See above) <br> <br>
<b>Running the Handler</b> <br> <br>
Since this Handler is configured to the Calculator web service in the above step, this Handler will be executed when you run the calculator web service client. (It is at AXISCPP_DEPLOY/bin/calculator )
</p>
<p><a name="#creating"> </a> </p>
<p><b>Handler Notes:</b> <br>
1) You can see the Handler behavior through the TCP Monitor. (TCP Monitor is a Axis Java tool) <br>
2) To get an idea of Handlers look at the Handler sample source files. <br>
a. echoStringHeaderHandler (AXISCPP_HOME/samples/server/echoStringHeaderHandler) <br>
b. testHandler (AXISCPP_HOME/samples/client/testHandler)
</p>
<p><a name="#API"> </a> </p>
<br>
<p><b>The Handler API and details for Handler writers</b> <br><br>
Now you have seen some sample Handlers so that you can explore more on Handlers. The following sections helps you for the same. <br> <br>
In order to get access to the DeSerializer the handler writer can use the following code block. <br> <br>
</p>
<p>
// ----- <br>
..... <br>
IHandlerSoapDeSerializer* pIHandlerSoapDeSerializer; <br>
pIMsg->getSoapDeSerializer(&pIHandlerSoapDeSerializer);<br>
..... <br>
-------// <br><br>
</p>
<p>
In order to get access to a incoming HeaderBlock the handler writer can use the following code block. <br><br>
// -----<br>
.....<br>
IHeaderBlock* pIHeaderBlock= pIHandlerSoapDeSerializer->getHeaderBlock("echoMeString", "http://soapinterop.org/echoheader/");<br>
.....<br>
-------//
</p>
<p>
In order to manipulate the above accessed HeaderBlock the handler writer can use the following code block. <br><br>
// -----<br>
.....<br>
if (pIHeaderBlock != NULL) {<br><br>
const BasicNode* pBasicNode= pIHeaderBlock->getFirstChild();<br><br>
const AxisChar* pachHeaderValue;<br><br>
if (pBasicNode != NULL)<br>
{<br>
if((pBasicNode->getNodeType()) == CHARACTER_NODE) {<br>
pachHeaderValue= pBasicNode->getValue();<br>
} else {<br>
pachHeaderValue = "This was not the expected value Ros";<br>
}<br>
} else <br>
{<br>
pachHeaderValue = "pBascNode is NULL";<br>
}<br><br>
AxisChar* pachTmpValue = (AxisChar*) malloc(strlen(pachHeaderValue) + 4); <br>
strcpy(pachTmpValue, pachHeaderValue);<br><br>
pachTemp = "EchoStringHeaderHandlerPr1.id"; <br>
pIMsg->setProperty(pachTemp, pachTmpValue);<br><br>
free(pachTmpValue); <br><br>
} else { <br><br>
//do some thing <br>
//AxisChar* pachTmpValue = "Default values since no reqeust SOAP header";<br>
//pachTemp = "EchoStringHeaderHandlerPr1.id";<br>
//pIMsg->setProperty(pachTemp, pachTmpValue);<br><br>
//free(pachTmpValue);<br>
}<br>
</p>
<p>
.....<br>
-------//
<br><br>
In order to get access to the incoming SOAP Body the handler writer can use the following code block. <br><br>
To get the body as a AxisChar* <br><br>
// -----<br><br>
.....<br>
IHandlerSoapDeSerializer* pIHandlerSoapDeSerializer;<br>
pIMsg->getSoapDeSerializer(&pIHandlerSoapDeSerializer);<br>
AxisChar* pSoapBody = pIHandlerSoapDeSerializer->getBodyAsChar(); <br>
.....<br>
-------// <br><br>
To get the body as a decoded base64 stream.<br>
// -----<br>
.....<br>
IHandlerSoapDeSerializer* pIHandlerSoapDeSerializer; <br>
pIMsg->getSoapDeSerializer(&pIHandlerSoapDeSerializer);<br>
xsd__base64Binary bb = pIHandlerSoapDeSerializer->getBodyAsBase64Binary();<br>
.....<br>
-------//
</p>
<p>
<b>Notes:</b><br>
Have a look at the following classes at the API docs to see all the available functions and their respective descriptions. (You can even look at the relevent .h/.hpp header files for the API comments) <br>
IhandlerSoapDeSerializer<br>
IHeaderBlock<br>
BasicNode<br>
</p>
<p>
The BasicNode API is similar (not exactly the same, but ..) to the DOM and is written as a tree traversing API. <br><br>
With the sample code samples provided above and with the API notes a developer will easily be able to write and play around his/her own Handlers. <br><br>
This tutorial will be updated frequently with the new additions and specially with your suggestions.<br><br>
</p>
<p><a name="#windows"></a>
<h1>Windows</h1> </p>
<p><a href="#introd"> Introduction to Handlers </a> <br> <br>
<a href="#sam">Sample Handlers (building, running)</a> <br> <br>
<a href="#create">Creating your own Handlers </a> <br> <br>
<a href="#APP">API Notes for Handler writers</a> <br> <br> </p>
<p> <a name="#introd"> </a> </p>
<p>Handlers are pluggable components in Axis C++. We have included a set of sample handlers for your reference. <br> <br>
You could write your own handlers by following the instructions given for the sample Handlers.<br> <br>
<b>Note: If you are using Client side Handlers you need to enter the following entry to the [Axis_Folder]/axiscpp.conf configuration file.</b> <br> <br>
ClientWSDDFilePath:Axis\conf\client.wsdd <br> <br>
After entering this entry to your [Axis_Folder]/axiscpp.conf configuration file will look like:<br> <br>
LogPath:Axis\logs\AxisLog.txt<br>
WSDDFilePath:Axis\conf\server.wsdd<br>
ClientWSDDFilePath:Axis\conf\client.wsdd<br> <br> </p>
<p><a name="#sam"> </a> </p>
<p>
<b>Testing the sample Handlers </b><br> <br>
We have included the following sample Handlers for your reference.<br> <br>
1) <b>echoStringHeaderHandler</b> (A server side handler sample) <br> <br>This sample handler will simply echo (i.e send back) the string which you send in the SOAP Header in the SOAP request. <br> <br>
2)<b>testHandler</b> (A client side handler sample)<br> <br>
This sample handler will simply add a SOAP Header to the generated SOAP request.<br>
Please note that these are very primitive sample handlers and are presented here to give you an idea about writing your own Handlers.<br> <br>
<b>echoStringHeaderHandler</b> <br> <br>
<b>Building the Sample Handlers in VC</b> <br>
</p>
<p>
<b>Building echoStringHeaderHandler</b> (A server side handler sample) <br> <br>
The VC dsw file (ServerHandlers.dsw) is available at Axis_Extract/vc/samples/server/ ServerHandlers.dsw.<br>
Open this file and build the project echoStringHeaderHandler. Once the build is successful you will find the DLL (echoStringHeaderHandler.dll) at Axis_Extract/bin. <br>
If you see this DLL at the above location you are done with the first step.<br> <br>
<b>Configuring the Handler</b> <br> <br>
Now edit the [Axis_Folder]/conf/server.wsdd to include the handler for a particular service.<br>
</p>
<p>
<service name="Calculator" provider="CPP:RPC" description="Simple Calculator Axis C++ Service "><br>
<requestFlow name="CalculatorHandlers"><br>
<handler name="ESHHandler" type="[Axis_Extract]/bin/echoStringHeaderHandler.dll"><br>
</handler><br>
</requestFlow><br>
<responseFlow name="CalculatorHandlers"><br>
<handler name="ESHHandler" type="[Axis_Extract]/bin/echoStringHeaderHandler.dll"><br>
</handler><br>
</responseFlow><br>
<parameter name="allowedMethods" value="add sub mul div "/><br>
<parameter name="className" value="Axis\webservices\Calculator.dll" /><br>
</service><br><br>
<b>Note:</b> Make sure you specify the correct path of the handler dll in the server.wsdd file. <br>
Now you are almost done to run your server side handler.<br>
Restart the Apache server.<br> <br>
</p><p>
<b>Running the Handler</b> <br> <br>
Since this Handler is configured to the Calculator web service in the above step, this Handler will be executed when a client send a SOAP request to the Calculator web service.<br> <br>
<b>testHandler</b> <br> <br>
<b>Building the Sample Handlers in VC</b> <br> <br>
<b>Building testHandler </b>(A client side handler sample)<br> <br>
The VC dsw file <b>(ClientHandlers.dsw)</b> is available at Axis_Extract/vc/samples/client/ClientHandlers.dsw.Open this file and build the project TestHandler. <br>
Once the build is successful you will find the DLL testHandler.dll) at Axis_Extract/bin. If you see this DLL at the above location you are done with the first step. <br> <br>
<b>Configuring the Handler</b> <br> <br>
Now edit the [Axis_Folder]/conf/client.wsdd to include the handler for a particular service. <br>
</p>
<p>
<service name="Calculator" provider="CPP:DOCUMENT" description="Calculator web service"><br>
<requestFlow name="CalculatorHandlers"><br>
<handler name="TestHandler" type="[Axis_Extract]/bin/testHandler.dll"><br>
</handler><br>
</requestFlow><br>
</service>
</p>
<p>
<b>Note:</b> Make sure you specify the correct path of the handler dll in the client.wsdd file. <br>
Now you are almost done to run your client side handler. <br> <br>
<b>Note: If you are using Client side Handlers you need to enter the ClientWSDDFilePath entry in the [Axis_Folder]/axiscpp.conf configuration file. (See above) <br> <br> <br>
<b>Running the Handler</b> <br> <br>
Since this Handler is configured to the Calculator web service in the above step, this Handler will be executed when you run the calculator web service client. (It is at [Axis_Extract]/bin/Calculator.exe) <br> <br> </p>
<p><a name="#create"> </a> </p>
<p>Handler Notes: <br> <br>
1) You can see the Handler behavior through the TCP Monitor. (TCP Monitor is a Axis Java tool) <br> <br>
2) To get an idea of Handlers look at the Handler sample source files. <br> <br>
a. echoStringHeaderHandler ([Axis_Extract]/samples/server/echoStringHeaderHandler) <br> <br>
b. testHandler ([Axis_Extract]/samples/client/testHandler) <br> <br>
</p>
<p>
<a name="#APP"> </a> </p>
<p><b>The Handler API and details for Handler writers</b> <br><br>
Now you have seen some sample Handlers so that you can explore more on Handlers. The following sections helps you for the same. <br><br>
In order to get access to the DeSerializer the handler writer can use the following code block.<br><br>
</p>
<p>
// -----<br>
.....<br>
IHandlerSoapDeSerializer* pIHandlerSoapDeSerializer; <br><br>
pIMsg->getSoapDeSerializer(&pIHandlerSoapDeSerializer);<br><br>
.....<br>
-------//<br><br>
In order to get access to a incoming HeaderBlock the handler writer can use the following code block.<br><br>
// -----<br>
.....<br>
IHeaderBlock* pIHeaderBlock= pIHandlerSoapDeSerializer->getHeaderBlock("echoMeString", "http://soapinterop.org/echoheader/");<br>
.....<br>
-------//<br>
</p>
<p>
In order to manipulate the above accessed HeaderBlock the handler writer can use the following code block.<br><br>
// -----<br>
.....<br>
if (pIHeaderBlock != NULL) {<br><br>
const BasicNode* pBasicNode= pIHeaderBlock->getFirstChild(); <br>
const AxisChar* pachHeaderValue; <br><br>
if (pBasicNode != NULL) <br>
{<br>
if((pBasicNode->getNodeType()) == CHARACTER_NODE) {<br>
pachHeaderValue= pBasicNode->getValue();<br>
} else {<br>
pachHeaderValue = "This was not the expected value Ros"; <br>
}<br>
} else<br>
{<br>
pachHeaderValue = "pBascNode is NULL";<br>
}<br><br>
AxisChar* pachTmpValue = (AxisChar*) malloc(strlen(pachHeaderValue) + 4); <br>
strcpy(pachTmpValue, pachHeaderValue); <br><br>
pachTemp = "EchoStringHeaderHandlerPr1.id"; <br>
pIMsg->setProperty(pachTemp, pachTmpValue); <br><br>
free(pachTmpValue); <br><br>
} else { <br>
//do some thing <br>
//AxisChar* pachTmpValue = "Default values since no reqeust SOAP header"; <br>
//pachTemp = "EchoStringHeaderHandlerPr1.id"; <br>
//pIMsg->setProperty(pachTemp, pachTmpValue); <br>
//free(pachTmpValue); <br>
} <br><br>
.... <br>
-------// <br>
</p>
<p>
In order to get access to the incoming SOAP Body the handler writer can use the following code block. <br><br>
To get the body as a AxisChar*<br>
// -----<br>
.....<br>
IHandlerSoapDeSerializer* pIHandlerSoapDeSerializer; <br>
pIMsg->getSoapDeSerializer(&pIHandlerSoapDeSerializer);<br>
AxisChar* pSoapBody = pIHandlerSoapDeSerializer->getBodyAsChar(); <br>
.....<br>
-------// <br><br>
To get the body as a decoded base64 stream.<br>
// -----<br>
.....<br>
IHandlerSoapDeSerializer* pIHandlerSoapDeSerializer;<br>
pIMsg->getSoapDeSerializer(&pIHandlerSoapDeSerializer);<br>
xsd__base64Binary bb = pIHandlerSoapDeSerializer->getBodyAsBase64Binary();<br>
.....<br>
-------//
</p>
<p>
<b>Note:</b> <br><br>
Have a look at the following classes at the API docs to see all the available functions and their respective descriptions. (You can even look at the relavent .h/.hpp header files for the API comments) <br>
1.IhandlerSoapDeSerializer<br>
2.IHeaderBlock <br>
3.BasicNode <br><br>
The BasicNode API is similar (not exactly the same, but ..) to the DOM and is written as a tree traversing API.<br><br>
With the sample code samples provided above and with the API notes a developer will easily be able to write and play around his/her own Handlers. <br><br>
This tutorial will be updated frequently with the new additions and specially with your suggestions.
</p>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/i2h.bat
Index: i2h.bat
===================================================================
ren *.ihtml *.html
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/maincd.ihtml
Index: maincd.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book-Page 14</h1>
<h2>Class Diagram:Logical View/Main</h2>
<center>
<img SRC="../images/c/ag/d4.jpg"></center>
<a href="EngineMainCD.html">goto>> page No.15</a>
<br><br>
<a href="soapE_AxisModule.html">Back</a>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/mem-management.ihtml
Index: mem-management.ihtml
===================================================================
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<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>
</head>
<body>
<center>
<h1>
<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>
<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.
<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>
<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
<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>
</nl>
<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> As C++ is an object oriented language, one would ideally like to leverage constructors and destructors for memory management. However, the Axis C++ engine uses structs in some cases (e.g. Arrays) and uses <i>malloc()</i> to allocate memory. Hence the C++ programmer would be forced to use <i>free()</i> at times. When using <i>malloc()</i> and <i>free()</i> constructors and destructors are not called. However, as the Axis C++ engine currently supports both C and C++, it is not simple to replace all <i>malloc()</i> with <i>new</i> or <i>free()</i> with <i>delete</i>. At the same time, there are some places where <i>new</i> and <i>delete</i> are being used. They too cannot be replaced with <i>malloc()</i> and <i>free()</i> overnight. This memory management complexity is the price paid for dual support of C and C++. Efforts are under way to clean up the memory management mix-ups and still support both C and C++. Currently the proposed solution is to make the Axis C++ engine pure C++ and use a wrapper mechanism to support C.
<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.
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/server.ihtml
Index: server.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book-Page 2</h1>
<h2>Sequence Diagram:Create Skeleton and Wrappers &<a href="client.html">Client Stubs</a>
</h2>
<center>
<img SRC="../images/c/ag/d1.jpg"></center>
<a href="d1-2.html">goto>> page No.03.</a>
<br><br>
<a href="usecase.html">Back</a>
</body></right>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/soapE_AxisModule.ihtml
Index: soapE_AxisModule.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book-Page 13</h1>
<h2>Sequence Diagram:Start SOAP Engine/AxisModuleInitialize</h2>
<center>
<img SRC="../images/c/ag/d3-1.jpg"></center>
<a href="maincd.html">goto>> page No.14</a>
<br><br>
<a href="soapEngine.html">Back</a>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/soapEngine.ihtml
Index: soapEngine.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1>Diagram Book-Page No.12</h1>
<h2>Sequence Diagram:Start SOAP Engine</h2>
<center>
<img SRC="../images/c/ag/d3.jpg"></center>
<a href="soapE_AxisModule.html">goto>> page No.13</a>
<br><br>
<a href="client.html">Back</a>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/usecase.ihtml
Index: usecase.ihtml
===================================================================
<html>
<head><title>Diagram Book</title></head>
<body>
<h1> Diagram Book Page-01</h1>
<h2>Use Case Diagram:Use Case View/Main</h2>
<p><img SRC="../images/c/ag/d9.jpg"></p>
<p><a href="server.html">goto >> page No.02.</a></p>
</body>
</html>
1.1 ws-axis/site/src4forrest-060/ja/src/documentation/content/xdocs/cpp/arch/WSDL2Ws.ihtml
Index: WSDL2Ws.ihtml
===================================================================
<html>
<head>
<title>WSDL2Ws Tool </title>
</head>
<body>
<h1>Axis C++ WSDL2Ws Tool</h1>
<HR size="1" noshade="noshade">
<p><strong>Contents</strong></p>
<p>
<a href="#intro">1 Introduction</a>
</p>
<p>
<a href="#codegen">1.1 Source Code Generation</a>
</p>
<p>
<a href="#proglang">1.2 Programming Languages</a>
</p>
<p>
<a href="#encode">1.3 Encoding Styles</a>
</p>
<p>
<a href="#svcstyle">1.4 Styles of Services</a>
</p>
<p>
<a href="#complext">1.5 Support for Complex Types </a>
</p>
<p>
<a href="#usage">2 Using the Tool</a>
</p>
<p>
<a href="#dependencies">2.1 Dependencies on Axis Java tool</a>
</p>
<p>
<a href="#building">2.2 Building the Tool</a>
</p>
<p>
<a href="#synopsis">2.3 Synopsis</a>
</p>
<p>
<a href="#classpath">2.4 Setting up CLASSPATH</a>
</p>
<p>
<a href="#runtool">2.5 Running the Tool</a>
</p>
<p>
<a href="#test">3 Architecture</a>
</p>
<p>
<a href="#test1">3.1 Outline</a>
</p>
<p>
<a href="#test2">3.2 Mediator WebServiceContext</a>
</p>
<p>
<a href="#test3">3.3 Generator</a>
</p>
<p>
<a href="#test4">3.4 Flow of Execution</a>
</p>
<p>
<a href="#test5">3.5 Sequence Diagram</a>
</p>
<p><a name="intro"></a></p>
<h1>1 Introduction</h1>
<p>The WSDL2Ws tool that comes with Axis C++ can be used to generate different types of wrapper classes / skeletons for the server side and wrapper classes / stubs for the client side for a given WSDL file. WSDL2Ws tool is written in Java and is based on the WSDL tools by Axis Java project.
<p><a name= "codegen"></a></p>
<h2>1.1 Source Code Generation</h2>
<p> WSDL2WS tool can be used for generating the following C/C++ source files for a given WSDL file : <p>
<ul>
<li>Server side skeletons and wrappers</li>
<li>Client side stubs and wrappers</li>
</ul>
<p>The generated Wrappers support the following functions : <p>
<ul>
<li>Method invocation</li>
<li>Serialization</li>
<li>Deserialization</li>
</ul>
<p><a name="proglang"></a></p>
<h2>1.2 Programming Languages </h2>
<p> The tool is capable of generating source code for both C++ and C</p>
<p><a name="encode"></a></p>
<h2>1.3 Encoding Styles</h2>
<p>The tool should be able to support SOAP 1.2 encoding style and extensible to support other encoding styles as well. However verifying the compliance with SOAP 1.1 / SOAP 1.2 and WS-I Basic Profile remains a TODO.
</p>
<p><a name="svcstyle"></a></p>
<h2>1.4 Styles of Services</h2>
<p>The tool is able to generate code for RPC (encoded) and Document Literal style WSDLs </p>
<p><a name="complext"></a></p>
<h2>1.5 Support for Complex Types</h2>
<p>The tool generates wrapper classes / structs / functions for complex types. The generated source include: </p>
<ul>
<li> Wrapper classes for complex types with data members and constructors/destructors</li>
<li> Helper functions for serializing/deserializing complex types</li>
<li> Wrapper structs to handle arrays of complex types</li>
</ul>
<p><a name="usage"></a></p>
<h1>2 Using the Tool</h1>
<p><a name="dependencies"></a></p>
<h2>2.1 Dependencies on Axis Java tool</h2>
<p>Apache Axis C++ uses WSDL processing tools from Axis Java project and extends those for C/C++ code generation. </p>
<p>The following jar files that comes with (or used by) Axis Java are required to run Axis C++ WSDL2Ws tool:</p>
<ul>
<li>axis.jar</li>
<li>wsdl4j.jar</li>
<li>commons-discovery.jar</li>
<li>commons-logging.jar</li>
<li>log4j-1.2.8.jar</li>
<li>jaxrpc.jar</li>
<li>saaj.jar</li>
</ul>
<p>"SchemaUtils" (SchemaUtils.java) and "ElementDecl" (ElementDecl.java) classes of Axis Java tools have been overridden by Axis C++ WSDL2Ws implementation.</p>
<p>Other than the two classes mentioned above, no other class from Axis Java WSDL tool implementation has been overridden or extended at present by Axis C++ WSDL2Ws tool; hence all other classes in Axis Java tool are used as they are.</p>
<p>Except for "SchemaUtils" and "ElementDecl" classes, the rest of the classes of Axis C++ WSDL2Ws are unique to Axis C++ and they use functionality form Axis Java jars.</p>
<p><a name="building"></a></p>
<h2>2.2 Building the Tool</h2>
<p>If you want to build the WSDL2Ws tool form source, there is an Apache Ant build script to help you.
Assuming that you have <a href="http://ant.apache.org/manual/install.html">installed Ant</a> properly, what you have to do is to set the CLASSPATH to include <a href="http://www.apache.org/dyn/closer.cgi/ws/axis/1_2beta/">Axis Java jar files</a> mentioned in the previous section and run ant command in $AXISCPP_HOME/src/wsdl folder. Once you build the tool the generated wsdl2ws.jar file would be placed in $AXISCPP_HOME/lib/axis/ folder.
</p>
<p><a name="synopsis"></a></p>
<h2>2.3 Synopsis</h2>
<p>
<strong>java WSDL2Ws [options] wsdl-file</strong>
</p>
<p><strong>Options</strong></p>
<pre>
-help, -h print a short help message<br>
-o(folder) target output folder - default is current folder<br>
-l(c++|c) target language (c++|c) - default is c++<br>
-s(server|client) generate server skeletons or client stubs? (serve|client) - default is server<br>
-w(wrapped|nonwrapped) wrapping style of the WSDL (wrapped|nonwrapped) - default is wrapped<br>
-verbose, -v be verbose<br>
-m(none|gnu) generate make files (none|gnu) - default is none<br>
</pre>
<p><a name="classpath"></a></p>
<h2>2.4 Setting up CLASSPATH</h2>
<p>Make sure that your CLASSPATH environment variable has all the jar files mentioned in section 2.1 above.
Then modify your CLASSPATH to include the wsdl2ws.jar file from Axis C++:
</p>
<p>On Linux: </p>
<pre>
CLASSPATH=$AXISCPP_HOME/lib/axis/wsdl2ws.jar:$CLASSPATH
export CLASSPATH
</pre>
<p>On Windows: </p>
<pre>
set CLASSPATH=%AXISCPP_HOME%\lib\axis\wsdl2ws.jar;%CLASSPATH%
</pre>
<p>Alternatively, you can use the -classpath option of java command to specify the CLASSPATH.</p>
<p><strong>NOTE: It is a MUST that that you have wsdl2ws.jar from Axis C++ appearing before all the jar files form Axis Java on the CLASSPATH.</strong> If not you will run into trouble when generating code. This is a known problem and happens because the two classes, "SchemaUtils" and "ElementDecl", of Axis C++ that overides Axis Java classes with the same name have identical package names to that of Axis Java classes.
</p>
<p><a name="runtool"></a></p>
<h2>2.5 Running the Tool</h2>
<p>You could run the tool as shown in the following example. Assuming you have not included wsdl2ws.jar in your class path:</p>
<pre>
java -classpath $AXISCPP_HOME/lib/axis/wsdl2ws.jar:$CLASSPATH org.apache.axis.wsdl.wsdl2ws.WSDL2Ws \
-obaseServerOut $AXISCPP_DEPLOY/wsdls/base.wsdl
</pre>
<p>
The above command will generate C++ server side skeleton and wrapper classes and place the generated source files in a folder named baseServerOut. You could have also used -sserver and -lc++ options to generate the same. To generate client side C++ code for the same WSDL file and place the generated code in baseClientOut folder, you could run:
</p>
<pre>
java -classpath $AXISCPP_HOME/lib/axis/wsdl2ws.jar:$CLASSPATH org.apache.axis.wsdl.wsdl2ws.WSDL2Ws \
-obaseClientOut -sclient -lc++ $AXISCPP_DEPLOY/wsdls/base.wsdl
</pre>
<p><a name="test"/></p>
<h1>3 Architecture</h1>
<p><a name="test1"/>
<h2>3.1 Outline</h2>
<p>The tool takes a top down approach. It starts with a WSDL document and generates all the classes (skeletons, wrapper classes for complex types and stubs) necessary to deploy (server side) and consume (client side) the web service. For more information about the generated classes please refer to the architecture documentation.</p>
<p> The following figure shows the high level architecture of the WSDL2Ws tool</p>
<align="left">
<img SRC="../images/c/ag/wsdl2ws.jpg" ></align></p>
<p><a name="test2"/>
<h2>3.2 Mediator WebServiceContext</h2>
<p>The WSDL file and the user options are processed by the WSDL2Ws class. Then WSDL2Ws creates an instance of WebServiceContext class (wscontext), which is the runtime representation of the processed data. This WebServiceContext instance selects the Generator to be used. The Generators extract the information from the WebServiceContext instance and creates the files. The WebServiceContext instance acts as a mediator and creates a loosely coupled system.</p>
<p>
<strong>WebServiceContext has the following components</strong>
</p>
<ol>
<li> ServiceInfo - information about service </li>
<li> WrapperInfo - information about wrapper options</li>
<li> TypeMap - information about custom types </li>
</ol>
<p><a name="test3"></a></p>
<h2>3.2 Generator
</h2>
<p>Generator generates a class based on the options passed by user. It contains a class called SourceWriter and the concrete implementation of the SourceWriter decides what the Generator generates. </p>
<p><a name="test4"></a></p>
<h2>3.4 flow of Execution</h2>
<p>
<ol>
<li>WSDL file and user options are processed by the WSDL2Ws and WebServiceContext object is created</li>
<li>WebServiceGenaratorFactory will create WebServiceGenerator based on the service style </li>
<li>Then the WebServiceGenarator will create the right set of Generators that will take care of generating C/C++ source files</li>
<li>Each Generator will invoke SourceWriter which is capable of writing the given type of file</li>
</ol>
</p>
<p><a name="test5"/>
<h2>3.5 Sequence Diagram
</h2>
<p><center>
<img SRC="../images/c/ag/sequence.jpg" ></center></p>
<HR size="1" noshade="noshade">
</body>
</html>