| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> |
| <HTML> |
| <HEAD> |
| <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8"> |
| <TITLE>Axis User</TITLE> |
| <META NAME="GENERATOR" CONTENT="Microsoft FrontPage 5.0"> |
| <META NAME="CREATED" CONTENT="20030725;12341600"> |
| <META NAME="CHANGED" CONTENT="20030725;16060000"> |
| <META NAME="ProgId" CONTENT="FrontPage.Editor.Document"> |
| <META HTTP-EQUIV="Content-Language" CONTENT="en-us"> |
| <STYLE> |
| <!-- |
| TD P { margin-left: 0.98cm; color: #000000; font-family: "Verdana", "Arial", "Helvetica", sans-serif } |
| H1 { color: #000000 } |
| P { margin-left: 0.98cm; color: #000000; font-family: "Verdana", "Arial", "Helvetica", sans-serif } |
| H3 { color: #000000 } |
| H2 { color: #000000; text-decoration: underline } |
| H4 { margin-left: 0.98cm; color: #000000 } |
| PRE { margin-left: 0.98cm; color: #000000 } |
| --> |
| </STYLE> |
| </HEAD> |
| <BODY LANG="en-US"> |
| <H1 ALIGN=CENTER><IMG SRC="images/axis.jpg" NAME="Graphic1" ALIGN=BOTTOM WIDTH=176 HEIGHT=96 BORDER=0></H1> |
| <H1>Axis C++ User's Guide</H1> |
| <H3>Table of Contents</H3> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0cm"><A HREF="#Introduction">Introduction</A> |
| </P> |
| <LI><P STYLE="margin-bottom: 0cm"><A HREF="#ConsumingServices">Consuming |
| Web Services with Axis</A> |
| </P> |
| <LI><P STYLE="margin-bottom: 0cm"><A HREF="#PublishingServices">Publishing |
| Web Services with Axis</A> |
| </P> |
| <LI><P STYLE="margin-bottom: 0cm"><A HREF="#DataMapping">XML <-> |
| C++ Data Mapping in Axis</A> |
| </P> |
| <LI><P STYLE="margin-bottom: 0cm"><A HREF="#WSDL">Using WSDL with |
| Axis</A> |
| </P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0cm"> <A HREF="#WSDL: Obtaining WSDL for deployed services">?WSDL: |
| Obtaining WSDL for deployed services</A> |
| </P> |
| <LI><P STYLE="margin-bottom: 0cm"> <A HREF="#WSDL2Java: Building stubs, skeletons, and data">WSDL2C++: |
| Building stubs, skeletons, and data</A> |
| </P> |
| <LI><P STYLE="margin-bottom: 0cm"> <A HREF="#Java2WSDL: Building WSDL from Java">C++2WSDL: |
| Building WSDL from C++</A> |
| </P> |
| </UL> |
| <LI><P STYLE="margin-bottom: 0cm"><A HREF="#published interfaces">Published |
| Interfaces</A> |
| </P> |
| <LI><P STYLE="margin-bottom: 0cm"><A HREF="#newbie">Newbie Tips: |
| Finding Your Way Around</A> |
| </P> |
| <LI><P STYLE="margin-bottom: 0cm"><A HREF="#tcpmon">Appendix : Using |
| TCPMon</A> |
| </P> |
| <LI><P STYLE="margin-bottom: 0cm"><A HREF="#soapmon">Appendix : |
| Using SOAP Monitor</A> |
| </P> |
| <LI><P><A HREF="#Glossary">Glossary</A> |
| </P> |
| </UL> |
| <H2><A NAME="Introduction"></A>Introduction</H2> |
| <P>Welcome to Axis C++, a c++ implementation of SOAP ! |
| </P> |
| <H3>What is SOAP?</H3> |
| <P>SOAP is an XML<I>-</I>based communication protocol and encoding |
| format for inter-application communication. Originally conceived by |
| Microsoft and Userland software, it has evolved through several |
| generations and the current spec, <A HREF="http://w3.org/TR/soap">SOAP |
| 1.1</A>, is fast growing in popularity and usage. The W3C's <A HREF="http://www.w3.org/2000/xp/Group/">XML |
| Protocol working group</A> is in the process of turning SOAP into a |
| true open standard, and as of this writing has released a working |
| draft of SOAP 1.2, which cleans up some of the more confusing areas |
| of the 1.1 spec. |
| </P> |
| <P>SOAP is widely viewed as the backbone to a new generation of |
| cross-platform cross-language distributed computing applications, |
| termed Web Services. |
| </P> |
| <H3>What is Axis c++?</H3> |
| <P>Axis is essentially a <I>SOAP engine</I>. The more complete |
| version of axis is written in java.This version is written in c++ and |
| will continue to be developed. |
| </P> |
| <P>Axis c++ includes</P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0cm">an apache module that can be |
| plugged in to the apache webserver on linux, |
| </P> |
| <LI><P>A set of sample web service classes and their handwritten |
| wrapper classes. |
| </P> |
| </UL> |
| <P>We hope you enjoy using Axis c++. Please note that this is an |
| open-source effort - if you feel the code could use some new features |
| or fixes, please get involved and lend a hand! The Axis developer |
| community welcomes your participation. |
| </P> |
| <H4><B>Let us know what you think!</B></H4> |
| <P>Please send feedback about the package to |
| "<A HREF="mailto:axis-user@xml.apache.org">axis-user@xml.apache.org</A>". |
| </P> |
| <H3>What's in Axis c++ at this moment?</H3> |
| <P>Axis c++ includes the following features: |
| </P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0cm">Partial SOAP 1.1 compliant engine |
| </P> |
| <LI><P STYLE="margin-bottom: 0cm">Support for all basic types |
| </P> |
| <LI><P STYLE="margin-bottom: 0cm">Automatic |
| serialization/deserialization of Java Beans, including customizable |
| mapping of fields to XML elements/attributes |
| </P> |
| <LI><P>Provider for RPC and based SOAP services |
| </P> |
| </UL> |
| <H2><A NAME="ConsumingServices"></A>Consuming Web Services with Axis |
| C++</H2> |
| <H2><A NAME="PublishingServices"></A>Publishing Web Services with |
| Axis C++</H2> |
| <P>This chapter explains how to deploy the sample web services |
| included with Axis C++.</P> |
| <P>Hopefully by now you have installed Axis C++.<BR><BR>If you |
| haven't already done so download the binary version of Axis C++ and |
| follow the instructions in the integration-guide to install it.<BR> </P> |
| <P>From here onwards the folder in which Axis C++ is installed by |
| being extracted from the Axis C++ installation package will be |
| referred to as <BR><axiscpp_home>.<BR><BR>sample webservice |
| modules are included in <axiscpp_home>/src/server/samples/<BR><BR>in |
| this folder you will find two subfolders called webservice and |
| webservicewrapper and <BR>service.wsdd file written by the service |
| provider for his service.</P> |
| <P>In the webservice folder, the header files and cpp files written |
| in c++, for each of the webservice can be found. In the |
| webservicewrapper folder the corresponding the wrapper classes for |
| each of the webservices can be found. The wrapper classes are supposed to be |
| generated by a tool called WCG (Wrapper Class |
| Generator). |
| </P> |
| <P><U>Using WCG</U> |
| </P> |
| <P>Suppose you have a C++ web service to be deployed called SimpleService. And |
| the SimpleService.h and SimpleService.cpp are the source files. And SimpleService.cpp contains the implementation for |
| the intended service. SimpeService.h contains only the declarations of the class. You need only this SimpleService.h to generate |
| your wrapper classes. </P> |
| <P>So you compile the sources and create a static library SimpleService.lib (or |
| SimpleService.a in Linux) first using the compiler. Now wcg can create the |
| service DLL for you with SimpleService.h and SimpleService.lib.</P> |
| <P>Unwrap the WCG tool downloaded, into a working |
| folder of your choice. Hereafter I name this folder as <work>.</P> |
| <P>Unzip wcg.zip</P> |
| <P>>cd <work>/wcg</P> |
| <P>>dir</P> |
| <P> Directory of E:\Axiswcg<br> |
| <br> |
| 07/25/2003 08:32p <DIR> .<br> |
| 07/25/2003 08:32p <DIR> ..<br> |
| 07/24/2003 09:09p <DIR> common<br> |
| 07/25/2003 08:21p 249,856 wcg.exe</P> |
| <P>This will contain the tool itself (wcg.exe) and the Axis common include |
| files that are needed by the WCG to make the service DLL. </P> |
| <P>Now run the wcg.exe with the following options.</P> |
| <P>In linux</P> |
| <P><work>/wcg>wcg -L<path to directory where the SimpleService.a is> -ISimpleService.lib -oMyService |
| -I. -I<path to directory where the SimpeWebService.h is></P> |
| <P>In windows</P> |
| <P><work>/wcg>wcg /L<path to directory where the SimpleService.a is> /ISimpleService.lib |
| /oMyService /I. /I<path to directory where the SimpeWebService.h is></P> |
| <P> -L<path to your service lib> and -l<your service lib name> |
| option tells wcg where your service library is.</P> |
| <P>-I<include file path> option let you include additional |
| header files. You can have multiple include paths.</P> |
| <P>-o<generated so/dll name> will specify the name you want for |
| your generated so/dll without extension.</P> |
| <P>After executing this command you will find MyService.so (MyService.dll |
| in windows) created in the current folder where you ran the wcg.exe.</P> |
| <P><BR>Copy this so/dll into where apache will be serching for |
| deployed services.</P> |
| <P> <BR> <U>Guidelines to follow in order to use WCG tool</U></P> |
| <UL> |
| <P>Web service header files should follow following guidelines in |
| order to use wrapper class generater tool. Most of the limitations |
| imposed here are due to the fact that wrapper class is still young |
| and evolving. Please feel free to report any other limitations you |
| come across when using the WCG tool to <A HREF="mailto:axis-dev@ws.apache.org?subject=[AxisC++] Reporting limitations in WCG tool">axis-dev@ws.apache.org</A></P> |
| <LI><P>axis includes should be included as from standard include |
| directories using '<' and '>'(not “.....”)</P> |
| <LI><P>All user types should derive from IAccessBean interface and |
| inside the class predefined macro ACCESSBEAN_SERIALIZABLE should be |
| declared.(See example)</P> |
| <LI><P>Basic data types shoud be passed and returned by value or by |
| reference(using &)</P> |
| <LI><P>User data types shoud be passed and returned by pointers |
| (using *).</P> |
| <LI><P>No variable qualifiers should be used such as const, static, |
| volatile etc.</P> |
| <LI><P>No function qualifiers should be used such as const, static |
| etc. except virtual.</P> |
| <LI><P>Should not use extern keyword.</P> |
| <LI><P>Defining macros is OK but using macros is not allowed.</P> |
| <LI><P>No global or static variables outside classes.</P> |
| <LI><P>Only integer default values are allowed for method |
| parameters.</P> |
| <LI><P>No initialization lists for constructors.</P> |
| <LI><P>Member variables of basic types should be value types.</P> |
| <LI><P>Member variables of user types should be pointer types. Also |
| constructors should allocate memory for these members and |
| destructors should delete them.</P> |
| <LI><P>Namespace directives are allowed but no namespace |
| declarations. |
| </P> |
| <LI><P>Scope resolution operator(::) is not allowed anywhere.</P> |
| <LI><P>No enumerations allowed.</P> |
| <LI><P>No inline functions allowed.</P> |
| <LI><P>No type defs allowed.</P> |
| <LI><P>No operator overloading allowed.</P> |
| <LI><P>Using template keyword is not allowed. But using STL is OK.</P> |
| </UL> |
| <P>Restart apache web server and test the web service using the java |
| webservice client. For infromation on how to use the java web service |
| client refer to the Axis java user guide which can be found at |
| http://ws.apache.org/axis/.<BR><BR>If you want to test handlers go |
| into the <axiscpp_home>/src/servcer/handlers folder where |
| example handlers are included. Change to a particular example |
| directory of your choice and type the following</P> |
| <P>make clean<BR>make</P> |
| <P>You will find the corresponding handler generated in |
| <axiscpp_home>axis/handlers directory.<BR>Restart the apache |
| web server and test your handler using the web service client in Axis |
| java.For infromation on how to use the java web service client refer |
| to the Axis java user guide which can be found at |
| http://ws.apache.org/axis/.<BR><BR>Happy Axis!!!<BR><BR><BR> </P> |
| <P> </P> |
| <H2><A NAME="DataMapping"></A>XML <-> C++ Data Mapping in Axis |
| C++</H2> |
| <H3>How your C++ types map to SOAP/XML types</H3> |
| <H4>Standard mappings from WSDL to C++</H4> |
| <TABLE CELLPADDING=2 CELLSPACING=2> |
| <TR> |
| <TD> |
| <P>xsd:base64Binary |
| </P> |
| </TD> |
| <TD> |
| <P>Not implemented yet</P> |
| </TD> |
| </TR> |
| <TR> |
| <TD> |
| <P>xsd:boolean |
| </P> |
| </TD> |
| <TD> |
| <P>int</P> |
| </TD> |
| </TR> |
| <TR> |
| <TD> |
| <P>xsd:byte |
| </P> |
| </TD> |
| <TD> |
| <P>unsigned char</P> |
| </TD> |
| </TR> |
| <TR> |
| <TD> |
| <P>xsd:dateTime |
| </P> |
| </TD> |
| <TD> |
| <P>Not implemented yet</P> |
| </TD> |
| </TR> |
| <TR> |
| <TD> |
| <P>xsd:decimal |
| </P> |
| </TD> |
| <TD> |
| <P>Not implemented yet</P> |
| </TD> |
| </TR> |
| <TR> |
| <TD> |
| <P>xsd:double |
| </P> |
| </TD> |
| <TD> |
| <P><TT>double</TT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD> |
| <P>xsd:float |
| </P> |
| </TD> |
| <TD> |
| <P><TT>float</TT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD> |
| <P>xsd:hexBinary |
| </P> |
| </TD> |
| <TD> |
| <P>Not implemented yet</P> |
| </TD> |
| </TR> |
| <TR> |
| <TD> |
| <P>xsd:int</P> |
| </TD> |
| <TD> |
| <P><TT>int</TT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD> |
| <P>xsd:integer</P> |
| </TD> |
| <TD> |
| <P>int</P> |
| </TD> |
| </TR> |
| <TR> |
| <TD> |
| <P>xsd:long |
| </P> |
| </TD> |
| <TD> |
| <P><TT>long</TT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD> |
| <P>xsd:QName |
| </P> |
| </TD> |
| <TD> |
| <P>Not implemented yet</P> |
| </TD> |
| </TR> |
| <TR> |
| <TD> |
| <P>xsd:short |
| </P> |
| </TD> |
| <TD> |
| <P><TT>short</TT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD> |
| <P>xsd:string</P> |
| </TD> |
| <TD> |
| <P>stl::string</P> |
| </TD> |
| </TR> |
| </TABLE> |
| <H2><A NAME="WSDL"></A>Using WSDL with Axis</H2> |
| <H2><A NAME="published interfaces"></A>Published Axis Interfaces</H2> |
| <H2><A NAME="newbie"></A>Newbie Tips: Finding Your Way Around</H2> |
| <H2><A NAME="tcpmon"></A>Appendix : Using the Axis TCP Monitor |
| (tcpmon)</H2> |
| <P>This section describe a java tool that is included with Axis java |
| that can be used to view what goes on the wire when a soap |
| transaction is taking place. Please visit <A HREF="http://ws.apache.org/axis/">http://ws.apache.org/axis/</A> |
| and get Axis java, to obtain tcpmon.</P> |
| <P>The "tcpmon" utility can be found in the |
| org.apache.axis.utils package. To run it from the command line: |
| </P> |
| <PRE STYLE="margin-left: 1.96cm; margin-bottom: 0.5cm"><FONT COLOR="#000000">% java org.apache.axis.utils.tcpmon [listenPort targetHost targetPort]</FONT></PRE><P> |
| Without any of the optional arguments, you will get a gui which looks |
| like this: |
| </P> |
| <P ALIGN=CENTER><IMG SRC="images/tcpmon1.jpg" NAME="Graphic2" ALIGN=BOTTOM WIDTH=599 HEIGHT=599 BORDER=0></P> |
| <P>To use the program, you should select a local port which tcpmon |
| will monitor for incoming connections, a target host where it will |
| forward such connections, and the port number on the target machine |
| which should be "tunneled" to. Then click "add". |
| You should then notice another tab appearing in the window for your |
| new tunneled connection. Looking at that panel, you'll see something |
| like this: |
| </P> |
| <P ALIGN=CENTER><IMG SRC="images/tcpmon2.jpg" NAME="Graphic3" ALIGN=BOTTOM WIDTH=599 HEIGHT=600 BORDER=0></P> |
| <P>Now each time a SOAP connection is made to the local port, you |
| will see the request appear in the "Request" panel, and the |
| response from the server in the "Response" panel. Tcpmon |
| keeps a log of all request/response pairs, and allows you to view any |
| particular pair by selecting an entry in the top panel. You may also |
| remove selected entries, or all of them, or choose to save to a file |
| for later viewing. |
| </P> |
| <P>The "resend" button will resend the request you are |
| currently viewing, and record a new response. This is particularly |
| handy in that you can edit the XML in the request window before |
| resending - so you can use this as a great tool for testing the |
| effects of different XML on SOAP servers. Note that you may need to |
| change the content-length HTTP header value before resending an |
| edited request. |
| </P> |
| </BODY> |
| </HTML> |
