| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <head> |
| <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <link rel="stylesheet" href="../../skin/tigris.css" type="text/css"> |
| <link rel="stylesheet" href="../../skin/mysite.css" type="text/css"> |
| <link rel="stylesheet" href="../../skin/site.css" type="text/css"> |
| <link media="print" rel="stylesheet" href="../../skin/print.css" type="text/css"> |
| <title>Handler Tutorial</title> |
| </head> |
| <body bgcolor="white" class="composite"> |
| <div id="banner"> |
| <table width="100%" cellpadding="8" cellspacing="0" summary="banner" border="0"> |
| <tbody> |
| <tr> |
| <td align="left"> |
| <div class="groupLogo"> |
| <a href="http://ws.apache.org/"><img border="0" class="logoImage" alt="The Apache WebServices Project" src="../../images/project-logo.jpg"></a> |
| </div> |
| </td><td align="right"> |
| <div class="projectLogo"> |
| <a href="http://ws.apache.org/axis/"><img border="0" class="logoImage" alt="The Apache Axis Project" src="../../images/axis.jpg"></a> |
| </div> |
| </td><td valign="top" rowspan="2" align="right" class="search"> |
| <form target="_blank" action="http://www.google.com/search" method="get"> |
| <table summary="search" border="0" cellspacing="0" cellpadding="0"> |
| <tr> |
| <td bgcolor="#a5b6c6" colspan="3"><img height="10" width="1" alt="" src="../../skin/images/spacer.gif" class="spacer"></td> |
| </tr> |
| <tr> |
| <td colspan="3"><img height="8" width="1" alt="" src="../../skin/images/spacer.gif" class="spacer"></td> |
| </tr> |
| <tr> |
| <td><img height="1" width="1" alt="" src="../../skin/images/spacer.gif" class="spacer"></td><td nowrap="nowrap"><input value="ws.apache.org" name="sitesearch" type="hidden"><input size="10" name="q" id="query" type="text"><img height="1" width="5" alt="" src="../../skin/images/spacer.gif" class="spacer"><input name="Search" value="GO" type="submit"> |
| <br> |
| Search WS</td><td><img height="1" width="1" alt="" src="../../skin/images/spacer.gif" class="spacer"></td> |
| </tr> |
| <tr> |
| <td colspan="3"><img height="7" width="1" alt="" src="../../skin/images/spacer.gif" class="spacer"></td> |
| </tr> |
| <tr> |
| <td class="bottom-left-thick"></td><td bgcolor="#a5b6c6"><img height="1" width="1" alt="" src="../../skin/images/spacer.gif" class="spacer"></td><td class="bottom-right-thick"></td> |
| </tr> |
| </table> |
| </form> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <table width="100%" cellpadding="0" cellspacing="0" border="0" summary="nav" id="breadcrumbs"> |
| <tbody> |
| <tr class="status"> |
| <td><a href="http://www.apache.org/">Apache</a> | <a href="http://ws.apache.org/">WS</a><a href=""></a></td><td id="tabs"> |
| <div class="tab"> |
| <span class="selectedTab"><a class="base-selected" href="../../index.html">WebServices-Axis</a></span> |
| </div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <table id="main" width="100%" cellpadding="8" cellspacing="0" summary="" border="0"> |
| <tbody> |
| <tr valign="top"> |
| <td id="leftcol"> |
| <div id="navcolumn"> |
| <div class="menuBar"> |
| <div class="menu"> |
| <span class="menuLabel">Axis</span> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/index.html">Introduction</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/news.html">News</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://wiki.apache.org/ws/FrontPage/Axis">FAQ/Wiki</a> |
| </div> |
| |
| <div class="menu"> |
| <span class="menuLabel">Get Involved</span> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/overview.html">Overview</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/cvs.html">CVS Repository</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/mail.html">Mailing Lists</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/ref.html">Reference Library</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/bugs.html">Bugs</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/howtobuild.html">HowToBuildSite</a> |
| </div> |
| |
| </div> |
| |
| <div class="menu"> |
| <span class="menuLabel">Axis (Java)</span> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/java/index.html">Documentation</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/java/install.html">Installation</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/java/user-guide.html">User's Guide</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/java/developers-guide.html">Developer's Guide</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/java/integration-guide.html">Integration Guide</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/java/architecture-guide.html">Architecture Guide</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/java/reference.html">Reference Guide</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/java/reading.html">Reading Guide</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/java/requirements.html">Requirements</a> |
| </div> |
| |
| </div> |
| |
| <div class="menu"> |
| <span class="menuLabel">Axis (C++)</span> |
| |
| <div class="menuItem"> |
| <a href="../../cpp/index.html">Home</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="../../cpp/documentation.html">Documentation</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="../../cpp/download.html">Download</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://wiki.apache.org/ws/FrontPage/AxisCPP">Wiki Pages</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="../../cpp/who.html">Who we are</a> |
| </div> |
| |
| </div> |
| |
| <div class="menu"> |
| <span class="menuLabel">Downloads</span> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/releases.html">Releases</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/interim.html">Interim Drops</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://cvs.apache.org/viewcvs/ws-axis/">Source Code</a> |
| </div> |
| |
| </div> |
| |
| <div class="menu"> |
| <span class="menuLabel">Translation</span> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/ja/index.html">Japanese</a> |
| </div> |
| |
| </div> |
| |
| <div class="menu"> |
| <span class="menuLabel">Related Projects</span> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/wsif/">WSIF</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://cvs.apache.org/viewcvs/*checkout*/ws-wsil/java/README.htm">WSIL</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://www-124.ibm.com/developerworks/projects/wsdl4j/">WSDL4J</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://www.uddi4j.org/">UDDI4J</a> |
| </div> |
| |
| </div> |
| |
| <div class="menu"> |
| <span class="menuLabel">Misc</span> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/who.html">Who We Are</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/contact.html">Contact</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/legal.html">Legal</a> |
| </div> |
| |
| <div class="menuItem"> |
| <a href="http://ws.apache.org/axis/docs.html">Notes/Docs</a> |
| </div> |
| |
| </div> |
| |
| |
| </div> |
| </div> |
| </div> |
| </td><td> |
| <div id="bodycol"> |
| <div class="app"> |
| <div align="center"> |
| <h1>Handler Tutorial</h1> |
| </div> |
| <div class="h3"> |
| <div class="h3"> |
| <h3>Contents</h3> |
| </div> |
| <ul> |
| <li> |
| <a href="#Introduction">Introduction to Handlers</a> |
| </li> |
| <li> |
| <a href="#Samples">Handler Samples</a> |
| </li> |
| <li> |
| <a href="#ServerHandlerSample">Server sample handler</a> |
| </li> |
| <li> |
| <a href="#ClientHandlerSample">Client sample handler</a> |
| </li> |
| <li> |
| <a href="#HandlerAPIs">Handler API's</a><a href="#ClientHandlerSample"></a> |
| </li> |
| </ul> |
| <div class="h3"> |
| <h3>Introduction to Handlers</h3> |
| </div> |
| <p> |
| <a name="Introduction"></a>Handlers are pluggable components in Axis C++. Handlers are pieces of code that you write to intercept the message either on the client or service side. We have included a set of sample handlers for your reference.<br> You can write your own handlers by following the instructions given for the sample Handlers. At the end of this section we have also added some more detailed API information.</p> |
| <div class="h3"> |
| <h3>Handler samples</h3> |
| </div> |
| <p> |
| <a name="Samples"></a>We have included the following sample Handlers for your reference.</p> |
| <ol> |
| <li> |
| <a href="#ServerHandlerSample">echoStringHeaderHandler</a> (A server side handler sample) This sample handler will simply echo (i.e send back) the string which you send in the SOAP Header in the SOAP request.</li> |
| <li> |
| <a href="#ClientHandlerSample">testHandler</a> (A client side handler sample) This sample handler will simply add a SOAP Header to the generated SOAP request.</li> |
| </ol> |
| <br> |
| <br> |
| <div class="h3"> |
| <h3>echoStringHeaderHandler (A server side handler sample)</h3> |
| </div> |
| <p> |
| <a name="ServerHandlerSample"></a> |
| </p> |
| <div class="h4"> |
| <h4>Building the echoStringHeaderHandler</h4> |
| </div> |
| <div class="h2"> |
| <h2>Linux</h2> |
| </div> |
| <p>The build files are available at:</p> |
| <pre class="code"><Axis install directory>/samples/server/echoStringHeaderHandler</pre> |
| <p>Change your current directory to this directory and then execute the following...</p> |
| <ul> |
| <li>make</li> |
| <li>make install</li> |
| </ul> |
| <p>The handler <strong>libeshhandler.so</strong> file will be created at</p> |
| <pre class="code"><Axis install directory>/lib directory</pre> |
| <div class="h2"> |
| <h2>Windows</h2> |
| </div> |
| <p>The VC dsw file (ServerHandlers.dsw) is available at</p> |
| <pre class="code"><Axis Install directory>/vc/samples/server/ServerHandlers.dsw.</pre> |
| <p>Open this file and build the project <strong>echoStringHeaderHandler</strong>. Once the build is successful you will find the DLL ( <strong>echoStringHeaderHandler.dll</strong>) at:</p> |
| <pre class="code"><Axis install directory>/bin</pre> |
| <div class="h4"> |
| <h4>Configuring the echoStringHeader Handler</h4> |
| </div> |
| <p>Edit the server.wsdd file <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 same handler being deployed on both the incoming and outgoing message.</p> |
| <pre><service name="Calculator" provider="CPP:RPC" description="Simple Calculator Axis C++ Service"> |
| <strong><requestFlow name="CalculatorHandlers"> |
| <handler name="ESHHandler" type="<Axis installation directory>/handlers/custom/echoStringHeaderHandler/libeshhandler.so"> |
| </handler> |
| </requestFlow> |
| <responseFlow name="CalculatorHandlers"> |
| <handler name="ESHHandler" type="<Axis installation directory>/handlers/custom/echoStringHeaderHandler/libeshhandler.so"> |
| </handler> |
| </responseFlow></strong> |
| <parameter name="allowedMethods" value="add sub mul div"/> |
| <parameter name="className" value="<Axis installation directory>/webservices/libcalculator.so" /> |
| </service></pre> |
| <strong>Note:</strong> |
| <br> |
| <br> |
| <br> |
| <br> |
| <br> |
| <div class="h4"> |
| <h4>Running the echoStringHeader Handler</h4> |
| </div> |
| <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 client</a> you created earlier.</p> |
| <br> |
| <br> |
| <br> |
| <br> |
| <div class="h3"> |
| <h3>testHandler (A client side handler sample)</h3> |
| </div> |
| <p> |
| <a name="ClientHandlerSample"></a> |
| </p> |
| <div class="h4"> |
| <h4>Building the testHandler</h4> |
| </div> |
| <p>The build files are available at <strong><Axis installation directory>/samples/client/testHandler</strong>. Change your current directory to this directory and then you can execute the following.</p> |
| <div class="h2"> |
| <h2>Linux</h2> |
| </div> |
| <ul> |
| <li>make</li> |
| <li>make install</li> |
| </ul> |
| <p>The handler so file will be created at</p> |
| <pre class="code"><Axis installation directory>/lib/</pre> |
| <div class="h2"> |
| <h2>Windows</h2> |
| </div> |
| <p>The VC dsw file (ClientHandlers.dsw) is available at:</p> |
| <pre class="code"><Axis Installation directory>/vc/samples/client/ClientHandlers.dsw</pre> |
| <p>Open this file and build the project TestHandler.</p> |
| <p>Once the build is successful you will find the DLL (<strong>testHandler.dll</strong>) at:</p> |
| <pre class="code"><Axis Installation directory>/bin</pre> |
| <p>If you see this DLL at the above location you are done with the first step.</p> |
| <div class="h4"> |
| <h4>Configuring the testHandler</h4> |
| </div> |
| <p>Now edit the <strong><Axis installation directory>/etc/client.wsdd</strong> to include the handler for a particular service.</p> |
| <p>In this example we will continue to use the Calculator service. The sample wsdd file outlined below shows a linux directory system - for other operating systems please use the correct path symbols.<br> |
| <strong>Note:</strong> Up until this point you did not need a client wsdd file the client only requires a wsdd file when it has handlers.</p> |
| <pre> |
| <strong><service name="Calculator" provider="CPP:RPC" description="Calculator web service"> |
| <requestFlow name="CalculatorHandlers"> |
| <handler name="TestHandler" type="<Axis Installation directory>/lib/libtest_client_handler.so"> |
| </handler> |
| </requestFlow> |
| </service></strong> |
| </pre> |
| <p>Now you are almost ready to run your client side handler.<br> |
| <br> |
| <strong>Note:</strong> If you are using Client side Handlers you need to enter the <strong>ClientWSDDFilePath</strong> entry in your <a href="../install-guide.html#Installing_Client">axiscpp.conf</a> configuration file.<br> |
| </p> |
| <br> |
| <br> |
| <div class="h4"> |
| <h4>Running the testHandler</h4> |
| </div> |
| <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 web service client</a>..</p> |
| <div class="h3"> |
| <h3>The Handler API's</h3> |
| </div> |
| <p> |
| <a name="HandlerAPIs"></a>Now you have seen some sample Handlers you can explore more on Handlers. The following sections should help you understand that API's available to you in your handler code.<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-&gtgetBodyAsBase64Binary();<br> .....<br> -------//</p> |
| <p> |
| <strong>Notes:</strong> |
| <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> |
| </p> |
| <br> |
| <br> |
| <div id="pdf" align="right"> |
| <a href="handler.pdf"><img alt="PDF" src="../../skin/images/pdfdoc.gif" class="skin"><br> |
| PDF</a> |
| </div> |
| </div> |
| </div> |
| </div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <div id="footer"> |
| <table summary="footer" cellspacing="0" cellpadding="4" width="100%" border="0"> |
| <tbody> |
| <tr> |
| <td colspan="2"> |
| <div align="center"> |
| <div class="copyright"> |
| Copyright © 2000-2005 The Apache Software Foundation. All rights reserved. |
| </div> |
| </div> |
| </td> |
| </tr> |
| <tr> |
| <td align="left"></td><td align="right"> |
| <div align="right"> |
| <div class="credit"></div> |
| </div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </body> |
| </html> |
