Dummy's Guide to WSO2 WSF/C

Submitted on January 8, 2008 - 21:29. Story :

Tutorials

Level :

Introductory

Project :

WSF > C

This tutorial from Malinda Kaushalye Kapuruge, is for an absolute beginner, sniffing around wanting to try WSO2 Web Services Framework for C. It contains basic information on the WSF/C framework and a detailed description on installation, executing samples and using different tools.

Applies To

WSO2 WSF/C	1.2.0
Environment	Linux - Debian, Ubuntu, Fedora, Windows

What is WSO2 WSF/C?
WSO2 WSF/C and Apache projects
Setting WSF/C in your machine
Important directories
How to run the server
How to run a client
Spying the wire content
WSO2 WSF/C with httpd
Conclusion

What is WSO2 WSF/C?

The Web Services Framework for C (WSF/C) is an open source library written to provide and consume Web services in C programming language. The framework is released under the Apache license 2.0. This means it comes with a $0 cost and liberty to redistribute. It also integrates a few Apache projects. Using Apache Axis2/C as the Web services engine, it has also consists of Apache Rampart/C, Apache Sandesha2/C and Apache Savan/C. Armed with all of the above projects, WSF/C provides Web services security, reliability and eventing support with only a single download. It is inter-operable with Microsoft .Net, WSO2 Web Services Application Server and other J2EE implementations. Moreover, WSF/C is the base framework for other Web service frameworks like WSF/PHP and WSF/Ruby. Since the framework is written in C, you may easily integrate it with your preferred scripting language as well.

WSO2 WSF/C and Apache Projects

Apache Axis2/C - Provides the Web services engine, to deploy Web services and an easy to use client API to consume Web services. Additionally, it includes built-in support for MTOM, WS-Addressing and WS-Policy.
Apache Rampart/C - Provides message level security for Web services exchanged with simple configurations. This includes SOAP message encryption, signature and many other mechanisms to ensure secure delivery of a message. Apache Rampart/C is based on WS-Security* specifications.
Apache Sandesha2/C - Provides message reliability implementing the WS-ReliableMessaging specification. By configuring Sandesha2/C, you can guarantee complete message delivery to the desired party.
Apache Savan/C - Provides WS-Eventing for Web services deployed. This is designed in a general publisher and subscriber architecture.

Setting up WSF/C in Your Machine

WSO2 WSF/C comes with different packages. You may download the binary distribution or the source distribution. Also check which operating system you are in. There are different packages for UNIX and Win32. Download the appropriate version. For this tutorial, we will use the WSF/C v 1.2.0 released in January 2008.

Prerequisites:

In order to follow this tutorial, the following packages must also be installed in your system:

Libxml2 - http://www.xmlsoft.org/
libiconv - http://www.gnu.org/software/libiconv/
zlib - http://www.zlib.net/
Microsoft VSExpress2005 edition and Platform SDK (If Win32)
OpenSSL - http://www.openssl.org/ (For Web services security samples)
Either SQLite - http://www.sqlite.org/ or MySQL - http://www.mysql.org/ - (Required for WS-ReliableMessaging with Apache Sandesha2/C)

UNIX

Following steps will install WSF/C in your UNIX box:

Extract the source package to any directory. Let's say /home/bob/wsfc
Set the WSFC_HOME environment variable use following commands:
1. % WSFC_HOME='/home/bob/wsf/c/deploy' (You are free to choose any location)
2. % Export WSFC_HOME
  
  To make sure that it's done, use % echo $WSFC_HOME. This should give you the path you configured in the earlier step.
Now go back to the directory where you extracted the source package and build the source
1. % ./configure --prefix=${WSFC_HOME}
2. % make
3. % make install
4. % make samples

WIN32

Following steps will install WSO2 WSF/C in your Windows machine from the source:

Extract the source package to any directory. Let's say C:\wsfc-src
Open the configure.in file

This is where you specify the directories or values for different parameters. Names of these parameter settings are self explanatory. For example, the openssl binaries are specified as follows:

OPENSSL_BIN_DIR= C:\OpenSSL

Please edit the file giving correct configuration parameters.
Open a DOS command shell. Go to the source directory

%cd C:\wsfc-src
Run build.bat file

%build.bat

If you get a build error, please check settings in the configure.in file.
Now see that there is a directory called wsfc-bin created under C:\wsfc-src. Copy this directory to any place where you'd like your WSFC_HOME to be. Let's say we copy and rename it to C:\wsfc
Export following environment variables:

% set WSFC_HOME=C:\wsfc

% set PATH=%PATH%;%WSFC_HOME%\lib

Important Directories

If everything goes well, go to the directory in which you have WSF/C installed. In our example, this is /home/bob/wsf/c/deploy if you are in UNIX, or, C:\wsfc\ in Win32. Peek into the WSFC_HOME directory and you will see there are different directories for sample clients, services, libraries, logs etc.

bin = Contains the binaries. This includes the binary for the simple Apache Axis2/C server(axis2_http_server), the web service client binary(wsclient), tools and binaries for samples.
lib = All the libraries that are needed will be copied to here.
logs = The place for log files. The Axi2/C engine will create a log called axis2.log.
include = Contains header files. These header files are from different projects that are bundled with WSF/C. i.e. Apache Axis2/C, Apache Rampart/C, Apache Sandesha2/C, Apache Savan/C
modules = Modules are a way to extend the SOAP message processing model in the Axis2 architecture. You may create your own modules and drop here. The pre-packaged modules contains the implementations of WS-* specifications.
services = The services you need to deploy should be dropped here. There are few sample services shipped with WSF/C that's worth looking at.
docs = Contains documentation for WSO2 WSF/C. This include a comprehensive and detailed installation guide and manuals for each and every module.
samples = Contains samples. Note that these samples are spread over many areas. It varies from a simple echo client/server to more complex samples demonstrating secured and reliable messaging scenarios. Please read the respective README files to know how to run them.

How to Run the Server?

Starting the simple Axis server is quite easy. A successful start is sort of an assuarance for a successful installation. Go to the WSFC_HOME/bin directory to start the server as outlined below:

%axis2_http_server.exe
Started Simple Axis2 HTTP Server ...

If you see the above line, it means the server start is successful. Alternatively, you may specify the port in which the server must be started. Here, we will start the server in port 8080.(default is port 9090)

%axis2_http_server.exe -p8080
Started Simple Axis2 HTTP Server ...

Note: To see other command line options, use the command

%axis2_http_server.exe -h

If you did not see that pretty line that says "Started Simple Axis2 HTTP Server ...", it means you are in a bit of trouble! Please open up the log file at WSFC_HOME/log/axis2.log. This log file will contain the error that describes exactly what the problem is. For example, if you have accidentally deleted the WSFC_HOME/axis2.xml file, which is the configuration file for Axis2/C engine, then you might get an error as:

[date/time] [error] dep_engine.c(304) Configuration file cannot be found.

So you know the reason. Sometimes though, the error may not be as straightforward as it was before. There can be hundreds of reasons for the server to not start up. You might end up pulling your hair trying to figure out what exactly the cause is. In that case, you can ask for support from the WSF/C mailing list. It's advisable to attach the log file in such querying for easy troubleshooting.

How to Run a Client?

Note that there are about 20 odd sample clients available with the WSF/C package. Go to WSFC_HOME/bin/samples.

First, we will try to run a simple echo client.

%echo.exe

If you get the line "echo client invoke SUCCESSFUL!", then you have invoked the echo service located at WSFC_HOME/services/echo, successfully. If not, please look at the log files created at WSFC_HOME/logs. But do you have any idea what is going on behind the scenes? How can we guarantee that there is a SOAP message exchanged between the client and the server? Don't you like to see the wire content and discover different parts of a SOAP message?

Spying on the Wire Content

For this, you have to use a tool like TCPMonitor. For your convenience, WSO2 WSF/C has it packed in for you. It's located in WSFC_HOME/bin/tools. Go to the directory and start the tool by typing:

%tcpmon.exe

Now, by default, the tool listens to the port 9090 and redirects messages to port 8080 on localhost(i.e. to the same machine). Note: You may change these default settings using few command line arguments as:

Usage : tcpmon.exe [-lp LISTEN_PORT] [-tp TARGET_PORT] [-th TARGET_HOST] [-f LOG_FILE]

Since we are redirecting our messages to port 8080, this time we have to start the server listening to that port:

%axis2_http_server.exe -p8080

Alright. Now we are ready to sniff the wire content. As illustrated in an earlier section, go to the WSFC_HOME/bin/samples and run the echo client. This time let us use the echo client with WS-Addressing support for a change:

%echo_blocking_addr.exe

Now you see that your service invokation is successful and should feel that the world is now newer and better place to live! So please open the tcpmon_traffic.log inside WSFC_HOME/bin/tools using a text editor like Notepad, gedit or vi to see the wire content. You should see something like this:

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
SENDING DATA..
/* sending time = 10:58:13*/
---------------------
POST /axis2/services/echo HTTP/1.1

User-Agent: Axis2/C

Content-Length: 512

Content-Type: application/soap+xml;charset=UTF-8

Host: localhost:9090
 <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"> <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"> <wsa:To>http://localhost:9090/axis2/services/echo</wsa:To> <wsa:Action>http://ws.apache.org/axis2/c/samples/echoString</wsa:Action> <wsa:MessageID>02973ea8-bb4f-1dc1-2693-000000000000</wsa:MessageID> </soapenv:Header> <soapenv:Body> <ns1:echoString xmlns:ns1="http://ws.apache.org/axis2/services/echo"> <text>Hello World!</text> </ns1:echoString> </soapenv:Body> </soapenv:Envelope>  = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = RETRIEVING DATA.. /* retrieving time = 10:58:13*/ /* time throughput = 0 sec(s)*/ --------------------- HTTP/1.1 200 OK  Content-Type: application/soap+xml;charset=UTF-8  Content-Length: 672  <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"> <soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"> <wsa:Action>http://ws.apache.org/axis2/c/samples/echoString</wsa:Action> <wsa:From> <wsa:Address>http://localhost:9090/axis2/services/echo</wsa:Address> </wsa:From> <wsa:MessageID>02983114-bb4f-1dc1-3856-000000000000</wsa:MessageID> <wsa:RelatesTo wsa:RelationshipType="http://www.w3.org/2005/08/addressing/reply">02973ea8-bb4f-1dc1-2693-000000000000</wsa:RelatesTo> </soapenv:Header> <soapenv:Body> <ns1:echoString xmlns:ns1="http://ws.apache.org/axis2/c/samples"> <text>Hello World!</text> </ns1:echoString> </soapenv:Body> </soapenv:Envelope>

The SOAP envelope in the first portion of the file means the request and the last SOAP envelope means the response from the server.

WSO2 WSF/C with httpd

In the production environment, it might be necessary to use a better Web server than the simple Axis2/C server, that is shipped with the framework. So let's see how to use WSF/C with Apache httpd in Linux environment.

First, download and install Apache2 server. Please follow the instructions given in the INSTALL file.

Then download WSF/C and configure with the following option

%./configure --with-apache2=/path/to/apache2 --prefix=...
%make
%make install

Once you complete installation, it will create a libmod_axis2.so inside WSFC_HOME/lib. Copy this file to apache2/modules directory. Now, open the httpd.conf file inside conf directory. Add following entries to the file. These will be your configurations to the axis2/c Web services engine.

LoadModule axis2_module modules/libmod_axis2.so
    Axis2RepoPath /your/path/to/wsf/c/home
    Axis2LogFile /tmp/apache_axis2.log
    Axis2LogLevel debug
    Axis2MaxLogFileSize 32
    <Location /axis2>
        SetHandler axis2_module
    </Location>

With that, you are done. Start the server by typing:

%./httpd -k start

If the default port (i.e. 80) is in use, try another such as port 8080. You can change the port in the conf/httpd.conf file

Listen 8080

Open a browser and enter the following address as the url:

http://localhost:8080/axis2/services

If all goes well, this should show the deployed services. Usually, these are samples that comes with WSF/C.

Conclusion

WSO2 WSF/C is a library written in C programming language to consume and deploy Web services. It eradicates all the trouble of having to download multiple project files and having to integrate them. From the tutorial, we discovered steps to running samples and viewing the wire content starting from downloading the distributions . You may use this tutorial as a starting point to discover the many features packed with WSO2 WSF/C. Please subscribe to the WSF-C user list to receive updates and details on the framework.