Axis C++ User's Guide

Table of Contents

• Introduction

• Consuming Web Services with Axis

• Publishing Web Services with Axis

• XML <-> C++ Data Mapping in Axis

• Using WSDL with Axis

  •  ?WSDL: Obtaining WSDL for deployed services

  •  WSDL2C++: Building stubs, skeletons, and data

  •  C++2WSDL: Building WSDL from C++

• Published Interfaces

• Newbie Tips: Finding Your Way Around

• Appendix : Using TCPMon

• Appendix : Using SOAP Monitor

• Glossary

Introduction

Welcome to Axis C++, a c++ implementation of SOAP !

What is SOAP?

SOAP is an XML-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, SOAP 1.1, is fast growing in popularity and usage. The W3C's XML Protocol working group 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.

SOAP is widely viewed as the backbone to a new generation of cross-platform cross-language distributed computing applications, termed Web Services.

What is Axis c++?

Axis is essentially a SOAP engine. The more complete version of axis is written in java.This version is written in c++ and will continue to be developed.

Axis c++ includes

• an apache module that can be plugged in to the apache webserver on linux,

• A set of sample web service classes and their handwritten wrapper classes.

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.

Let us know what you think!

Please send feedback about the package to "axis-user@xml.apache.org".

What's in Axis c++ at this moment?

Axis c++ includes the following features:

• Partial SOAP 1.1 compliant engine

• Support for all basic types

• Automatic serialization/deserialization of Java Beans, including customizable mapping of fields to XML elements/attributes

• Provider for RPC and based SOAP services

Consuming Web Services with Axis C++

Publishing Web Services with Axis C++

This chapter explains how to deploy the sample web services included with Axis C++.

Hopefully by now you have installed Axis C++.

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.
 

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
<axiscpp_home>.

sample webservice modules are included in <axiscpp_home>/src/server/samples/

in this folder you will find two subfolders called webservice and webservicewrapper and
service.wsdd file written by the service provider for his service.

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).

Using WCG

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.

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.

Unwrap the WCG tool downloaded, into a working folder of your choice. Hereafter I name this folder as <work>.

Unzip wcg.zip

>cd <work>/wcg

>dir

 Directory of E:\Axiswcg

07/25/2003 08:32p <DIR> .
07/25/2003 08:32p <DIR> ..
07/24/2003 09:09p <DIR> common
07/25/2003 08:21p 249,856 wcg.exe

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.

Now run the wcg.exe with the following options.

In linux

<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>

In windows

<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>

-L<path to your service lib> and -l<your service lib name> option tells wcg where your service library is.

-I<include file path> option let you include additional header files. You can have multiple include paths.

-o<generated so/dll name> will specify the name you want for your generated so/dll without extension.

After executing this command you will find MyService.so (MyService.dll in windows) created in the current folder where you ran the wcg.exe.

Copy this so/dll into where apache will be serching for deployed services.

 Guidelines to follow in order to use WCG tool

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 axis-dev@ws.apache.org

• axis includes should be included as from standard include directories using '<' and '>'(not “.....”)

• All user types should derive from IAccessBean interface and inside the class predefined macro ACCESSBEAN_SERIALIZABLE should be declared.(See example)

• Basic data types shoud be passed and returned by value or by reference(using &)

• User data types shoud be passed and returned by pointers (using *).

• No variable qualifiers should be used such as const, static, volatile etc.

• No function qualifiers should be used such as const, static etc. except virtual.

• Should not use extern keyword.

• Defining macros is OK but using macros is not allowed.

• No global or static variables outside classes.

• Only integer default values are allowed for method parameters.

• No initialization lists for constructors.

• Member variables of basic types should be value types.

• Member variables of user types should be pointer types. Also constructors should allocate memory for these members and destructors should delete them.

• Namespace directives are allowed but no namespace declarations.

• Scope resolution operator(::) is not allowed anywhere.

• No enumerations allowed.

• No inline functions allowed.

• No type defs allowed.

• No operator overloading allowed.

• Using template keyword is not allowed. But using STL is OK.

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/.

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

make clean
make

You will find the corresponding handler generated in <axiscpp_home>axis/handlers directory.
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/.

Happy Axis!!!


 

XML <-> C++ Data Mapping in Axis C++

How your  C++ types map to SOAP/XML types

Standard mappings from WSDL to C++

Using WSDL with Axis

Published Axis Interfaces

Newbie Tips: Finding Your Way Around

Appendix : Using the Axis TCP Monitor (tcpmon)

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 http://ws.apache.org/axis/ and get Axis java, to obtain tcpmon.

The "tcpmon" utility can be found in the org.apache.axis.utils package. To run it from the command line:

% java org.apache.axis.utils.tcpmon [listenPort targetHost targetPort]

Without any of the optional arguments, you will get a gui which looks like this:

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:

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.

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.