2009/07/28
28 Jul, 2009

Dummy's Guide to Writing Web Services Clients with WSO2 WSF/C++

  • Senaka Fernando
  • - WSO2

Introduction

WSO2 Web Services Framework for C++[1] is an extension to WSO2 Web Services Framework for C[2]. WSO2 WSF/C++ makes the popular open source, enterprise-grade Web Services Framework (WSF) library available to those familiar with the C++ syntax and programming style, and is used for consuming and producing web services. Without WSO2 WSF/C, C++ developers had to create their own extensions to port a library into native C++ format. WSO2 WSF/C++ provides a perfect solution to this requirement. Among the major benefits of WSF/C++ are:

  • Open source - $0 licensing cost
  • Includes everything in WSF/C, with a more friendly API now available in C++
  • Provides a comprehensive coverage of most WS-* specifications enabling the development of enterprise-ready applications
  • Easy to extend and integrate
  • Includes a number of examples making it easier to learn

WSO2 WSF/C++ is released under the popular Apache license, Version 2.0, and provides a C++ alternative to most WS-* projects at the Apache Software Foundation. For instance, using WSO2 WSF/C++, you can use Apache Axiom in C++ instead of C. This means that you can now work with objects implemented using classes in C++, instead of in C.  Future versions of WSO2 WSF/C++ will bring the complete WS-* support and most tools found in WSO2 WSF/C, which will provide reliability, security, policy and eventing support  - all as a part of a single package, with a C++ based API. WSO2 WSF/C++ is designed to inter-operate with Microsoft .Net, WSO2 Web Services Application Server, WSO2 Web Services Framework for C, PHP, Ruby, Perl, JavaScript and more (see a complete list at [3]), and also many other J2EE based implementations in the very manner WSO2 WSF/C does.

WSO2 WSF/C++ can be readily integrated with any C++ application and is available for both Windows-based and Unix-based platforms, making cross-platform development easy. The Apache 2.0 license makes it possible to use WSO2 WSF/C++ within most of your projects without having to bother with complex licensing issues.

Applies To

WSO2 WSF/C++ 2.0.0
Environment all supported

Contents

  1. Introduction
  2. What's New
  3. Setting up WSO2 WSF/C++
    1. Windows
    2. Unix
  4. Running Your First Web Service Client with WSO2 WSF/C++
  5. Creating Your First Web Service Client with WSO2 WSF/C++
  6. Advanced Features
  7. Conclusion

What's New

The core of WSO2 WSF/C++ extends WSO2 WSF/C, and therefore provides a C++ alternative to Apache Axis2/C. The unique nature of the WSO2 WSF/C++ architecture provides a C++ version of each core component; these components are loosely coupled together, rather than providing a total API that covers the entire WSO2 WSF/C library. Therefore, you may use WSO2 WSF/C++ as an extension to Apache Axiom/C without needing the remainder of the API.  If you require a full API, it is possible to create your own. The way WSO2 WSF/C++ is organized is shown in the diagram below:

Not implicit in this diagram is the abstraction of the environment-related aspects in WSO2 WSF/C++, which are different from WSO2 WSF/C. The developers do not need to bother with handling the underlying environment and passing references of the Axis2 Environment to each and every object. Also, overloaded methods are provided, giving you a convenient range of new options and a better organized API.

WSO2 WSF/C++ have also added detailed exception-handling mechanisms which have been carefully implemented to suit both Unix- and Windows-based environments in the very same manner. The library also comes with the public vs. private API concept in its Windows-based version, meaning that you are exposed to only the API you require through a well-defined interface of exports. Axis Faults are now not limited to simple messages as in Apache Axis2/C and WSO2 WSF/C, but presented as exception objects making solution development much easier.

The Service Client API is tailored to include most of the common client-side requirements as a part of single object while encapsulating resources into independent objects such as Options. This helps the Web service developer not worry about handling multiple objects in order to get the job done, and also makes complex dependency issues easier to organize.

Setting up WSO2 WSF/C++

WSO2 WSF/C++ comes in a range of distributions tailored to suit various requirements and especially various operating systems. Depending on your requirement and your operating system it is recommended that you select the distribution package that best suits you. In order to make the process much easier to understand I have separately explained the process for Windows-based and Unix-based systems.

Windows

This section is intended for developers and users who wish to use WSO2 WSF/C++ on a Microsoft Windows-based system. If you are on a Unix-based system, skip to section 3.2. To begin, you need to install a list of dependent libraries. Please note that you may not need to install all libraries mentioned below, depending on your current system configuration. You are advised to contact your system administrator for further information. If you want to use to the binary distribution click here.

Mandatory

Optional

To install WSO2 WSF/C++ on your system, follow the procedure below:

  1. Extract the source zip package to a folder.
  2. If you want to install WSO2 WSF/C++ in a location other than the default, wso2-wsf-cpp-bin-x.x.x-win32, set WSFCPP_HOME environment variable pointing to the location where you want to install WSO2 WSF/C++.
    > set WSFCPP_HOME='your_desired_path_to_wsf_c++_installation'
  3. Then go to the folder where you extracted the source.
    > cd your_path_to_wsf_c++_source
  4. Edit the Configuration (configure.in) found in the folder where you extracted the source.

    The configure.in file contains the user specific configuration parameters. Please have a look at this file and set the settings to match your system's settings. Settings for Apache Axis2/C are mandatory. Settings for Apache Rampart/C and Apache Sandesha2/C are optional and needs to be set only if you want to build those. The comments in the configure.in file explain each setting, please have a look at the comments to get an understanding on what each setting means.

  5. Run build.bat batch file found in the folder where you extracted the source.
    > build.bat

    Note: You may need to set the PATH environment variable to vcvars32.bat if Windows complains that it cannot find this batch file when running the build.bat file

  6. You need to add the path to lib directory to the PATH variable (%WSFCPP_HOME%\lib)
    > set PATH=%PATH%;%WSFCPP_HOME%\lib

To run the Server, follow the steps below.

  1. Go to where you installed WSO2 WSF/C++. Start simple axis server on port 9090 by running the following commands
    > cd "%WSFCPP_HOME%\bin"
    > axis2_http_server.exe
  2. If the server fails to start, you may need to set the WSFCPP_HOME environment variable, pointing to the deploy folder (C:\wsfcpp)
    > set WSFCPP_HOME='C:\wsfcpp'
  3. You also may need to add the path to lib directory to the PATH variable (%WSFCPP_HOME%\lib)
    > set PATH=%PATH%;%WSFCPP_HOME%\lib

Unix

This section is intended for developers and users who wish to use WSO2 WSF/C++ on a Unix-based system. If you are on a Microsoft Windows-based system, see section 3.1. To start with, you need to install a list of dependent libraries. Please note that you may not need to install all the libraries mentioned below depending on your current system software configuration. You are advised to contact your system administrator for further information.

Mandatory

  • pkg-config tool is required (most Linux systems have this by default)

 

Optional

To install WSO2 WSF/C++ on your system, follow the procedure below.

  1. Extract the source tar package to a folder.
  2. Set WSFCPP_HOME environment variable pointing to the location where you want to install WSO2 WSF/C++.
    $ WSFCPP_HOME='/your_desired_path_to_wsf_c++_installation'
    $ export WSFCPP_HOME
  3. Then go to the folder where you extracted the source.
    $ cd /your_path_to_wsf_c++_source
  4. Build the source using the following command sequence in the directory where you have extracted the source
    $ ./configure --prefix=${WSFCPP_HOME}
    $ make
    $ make install
    $ make samples

To run the Server, follow the steps below.

  1. Go to where you installed WSO2 WSF/C++. Start simple axis server on port 9090 by running the following commands
    $ cd ${WSFCPP_HOME}/bin
    $ ./axis2_http_server
  2. If you run into shared library problems, try setting the LD_LIBRARY_PATH
    $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${WSFCPP_HOME}/lib

For more information refer the latest installation guide at [4].

Running Your First Web Service Client with WSO2 WSF/C++

Like WSO2 WSF/C, there are many samples that are available as a part of the distribution. In the Binary distribution, you can find several samples in the WSFCPP_HOME/samples/bin/ folder. The most basic of these samples, the echo client, is found inside the samples folder. To run the echo client simply run the executable:

> echo.exe

You should receive an output on the console indicating the success of the operation. For source distributions, you are required to build the samples (which is an automated step in the build process, unless you explicitly exclude it).

Creating Your First Web Service Client with WSO2 WSF/C++

Creating a Web service Client is relatively easy with WSO2 WSF/C++ when compared to WSO2 WSF/C and other similar libraries. Creating a client similar to the echo client is just as easy as running the client.

#include <ServiceClient.h>
#include <OMElement.h>
#include <iostream>
#include <AxisFault.h>
#include <Environment.h>
using namespace std;
using namespace wso2wsf;

int main(int argc, char *argv[])
{
    Environment::initialize("echo.log", AXIS2_LOG_LEVEL_TRACE);
    ServiceClient * sc;

    sc = new ServiceClient("https://localhost:9090/axis2/services/echo");
    sc->engageModule(AXIS2_MODULE_ADDRESSING);
    OMNamespace * ns = new OMNamespace("http://ws.apache.org/axis2/services/echo", "ns1");
    OMElement * payload = new OMElement(NULL,"echoString", ns);
    OMElement * child = new OMElement(payload,"text", NULL);
    child->setText("Hello World!");
    try
    {
        OMElement * response = sc->request(payload, "http://ws.apache.org/axis2/c/samples/echoString");
    }
    catch (AxisFault & e) { }
    delete payload;
    delete sc;
}

To start with, we require several includes. You may or may not use the namespaces, but using them makes your life easy. The wso2wsf namespace is used by various classes found in WSO2 WSF/C++. The initial includes and namespace block are shown below:

#include <ServiceClient.h>
#include <OMElement.h>
#include <iostream>
#include <AxisFault.h>
#include <Environment.h>
using namespace std;
using namespace wso2wsf;

Next, we create the SOAP client by passing the location of the service as a parameter. There are various other constructors available for this purpose, and you may refer to the complete API documentation for more information. The Environment is initialized as the first step. This step will setup the environment and other related infrastructure components. In this example, we also engage the WS-Addressing module to the Service Client. You may also engage other standard and/or custom modules in the very same manner. More information is found in the complete API documentation. The code shown below demonstrates this:

Environment::initialize("echo.log", AXIS2_LOG_LEVEL_TRACE);
ServiceClient * sc;

sc = new ServiceClient("https://localhost:9090/axis2/services/echo");
sc->engageModule(AXIS2_MODULE_ADDRESSING);

The payload is constructed in the next four steps, which needs no further explanation. More information on how to use the C++ API to Axiom is found as a part of the WSO2 WSF/C++ documentation. The next step will generate a request using the constructed payload and obtain the response sent. An exception will be thrown, should there be any error in the process.

OMElement * response = sc->request(payload, "http://ws.apache.org/axis2/c/samples/echoString");

Some freeing of resources is the final step. As in C, you need to make sure that you free the memory you allocate. However, an exception is that, if you free a parent node in an Axiom Tree, the child nodes, attributes and associated namespaces will automatically be freed. Creating your own custom client involves customizing the steps mentioned above. You may also be interested in using the Service Client Options object to provide more configuration details. The examples bundled with the distributions show how this can be achieved.

Advanced Features

WSO2 WSF/C++ also supports several advanced features such as asynchronous operations using callbacks. All what you need to do is write an implementation of the ICallback interface, as shown below:

class EchoCallback: public ICallback
{
public:
    WSF_CALL EchoCallback() { }

    void WSF_CALL onComplete(OMElement* message)
    {
        doTaskA();
    }

    void WSF_CALL onFault(OMElement* message)
    {
        doTaskB();
    }

    WSF_CALL ~EchoCallback() { }
};

A few additional samples on how to use SOAP version 1.1, and how to use a security policy can be found as a part of the distributions, as well as several clients written for real-world Web services such as Yahoo, Google and Flickr search services.

Conclusion

WSO2 WSF/C++ provides everything from the WSO2 WSF/C library in a user-friendly 100% C++ API. The library saves you from all the trouble from having to collect various bits and pieces together to build a solution for creating and consuming Web services. This tutorial provides a basic introduction and step-by-step instructions for creating your very first Web service client with WSO2 WSF/C++. This work builds upon the Dummy's Guide to WSO2 WSF/C by Malinda Kaushalye Kapuruge[5]. For more information, you are advised to use the mailing lists, and the User Forum.

References

[1] WSO2 Web Services Framework for C++
[2] WSO2 Web Services Framework for C
[3] WSO2 Web Services Framework Implementations
[4] WSO2 Web Services Framework for C++ - Documentation
[5]

Dummy's Guide to WSO2 WSF/C

Author

Senaka L. Fernando, Software Engineer, WSO2 Inc., senaka at wso2 dot com

 

About Author

  • Senaka Fernando