How to Use WSO2 WSF/C, XMPP Transport

Introduction

You will learn how to compile WSO2 WSF/C to use XMPP transport as a communication protocol, and how to consume Web services using the XMPP transport. You will also receive some background knowledge regarding the WSO2 WSF/C Web services engine.

Users who have deployed services with WSO2 WSF/C will be more comfortable with this tutorial.

Applies To

WSF/C	1.0.0
Environment	Linux - Debian Etch/Lenny, Ubuntu, Fedora

Background
Compiling
- Installing iksemel
- Installing WSO2 WSF/C with XMPP
Getting the Services Up and Running
- Configuring XMPP transport sender
- Configuring the Service
Invoking the WSF/C Client with XMPP
Summary
Resources

Background

Quoting from the Wikipedia [1],"Extensible Messaging and Presence Protocol (XMPP) is an open, XML-inspired protocol for near-real-time, extensible instant messaging (IM) and presence information (a.k.a. buddy lists). It is the core protocol of the Jabber Instant Messaging and Presence technology. The protocol is built to be extensible and other features such as Voice over IP and file transfer signaling have been added."

There is a lot of interest towards the XMPP transport. WSF/C is the Web Services Framework implemented in C. Furthermore, WSF/C has the most number of WS-* specs implemented. Implementing XMPP transport for WSF/C expands the usages of WSF/C into new territories.

Compiling

Installing iksemel

The WSF/C XMPP transport is implemented using the iksemel library. Before working with the XMPP transport, you have to install it on your system. Download [2] the sources for iksemel library.

For Debian and Ubuntu systems, type the following command: apt-get install libiksemel3
If Binaries are not available, you need to download [2] it and install.

Installing WSO2 WSF/C with XMPP

It is important to note that, by default, XMPP is disabled in WSF/C. Therefore it is not shipped with the WSF/C binary distribution. If anyone is interested, they need to get the WSF/C sources required to compile the source enabling XMPP. After downloading WSO2 WSF/C [3], you can build the enabling XMPP.

tar xvfz wso2-wsf-c-src-1.0.1.tar.gz
cd wso2-wsf-c-src-1.0.1
./configure --with-xmpp=[path to iksemel header files] .. [other configuration options]
make
make install

After installing, make sure that libaxis2_xmpp_sender.so and libaxis2_xmpp_receiver.so is available in the deployment directory.

Note: WSF/C XMPP transport has been compiled and tested only in the Unix/Linux environment.

For Microsoft Windows systems, it hasn't been compiled and tested yet.

Getting the Services Up and Running

After installing WSO2 WSF/C, you have to edit the axis2.xml file in oder to make the XMPP transport available to the WSF/C engine. The axis2.xml file can be found in the WSF/C repository

Configuring the XMPP transport sender

Add the following entry below axis2_http_sender in axis2.xml

<transportSender name="xmpp" class="axis2_xmpp_sender">
    <parameter name="PROTOCOL" locked="false">XMPP</parameter>
 </transportSender>

transportSender:
The Axis2/C engine uses this property when selecting the transport sender. Here the "name" attribute represents the transport sender name and the class ascribes to the transport sender library.
parameter:
Defines a parameter named PROTOCOL which specifies the availability of the XMPP transport to the Axis2/C engine.

In order to get the service up and running, you need to have a Jabber ID associated with the Jabber server. There are plenty of Public Jabber servers that you can get using a Jabber client. Getting a Jabber ID is not within the scope of this article. If you are interested, please refer to the Jabber User Guide [4].

For this tutorial, I'm using a xyecho@xmpp.ws jabber account for the echo service.

I'm going to deploy and consume the "echo" sample, which is shipped with WSF/C through the XMPP transport.

Configuring the Service

Add the following lines to the services.xml of the echo service.

<parameter name="xmpp_id" locked="xsd:false"> xyecho@xmpp.ws </parameter>
<parameter name="xmpp_password" locked="xsd:false">123</parameter>

xmpp_id:
XMPP ID that we use for getting the service up. This ID should be associated with the Jabber server. You can use the public servers available to obtain an ID.
xmpp_password:
Password associated with the above xmpp_id Both xmpp_id and xmpp_password require to be authenticated by the Jabber (XMPP) server.

Now we are about to get the echo service up and running using the XMPP transport. In the deploy directory, (where you installed WSF/C, basically this is the repository directory) under bin directory make sure the axis2_xmpp_server executable file is available. You can use the SASL [5] protocol to authenticate it with the Public server.

With SASL

cd wso2-wsfc-installed-directory
cd bin
./axis2_xmpp_server -s

Without SASL

You can get the service up without SASL authentication by not using the -s option.

cd wso2-wsfc-installed-directory
cd bin
./axis2_xmpp_server

Invoking the WSF/C Client with XMPP

When invoking a client using the XMPP transport, you need to provide some additional information. While using the XMPP transport, svc_client should posses a Jabber ID. Moreover, svc_client should be authenticated by the server and should come online prior to any communication. There are two methods available to the client to communicate with a server. Namely, the Statical method (using axis2.xml) and the Programmatic method using the WSF service client.

Using a configuration file (Using axis2.xml)

To give the Jabber ID and the password associated with that jabber library, we use axis2.xml in the repository. Add the following line to the client axis2.xml

<parameter name="XMPP" JID="xyxmpp@xmpp.ws/Home" PASSWORD="123" SASL="true"/>

Options
- name="XMPP"
  This is the name of the parameter. When the client is executed, it gets the details from this name.
- JID="xyxmpp@xmpp.ws"
  Before invoking the client, the client should be authenticated by the server and should come online. Therefore, we need to have a Jabber ID for the client. For this tutorial, I'm using the xyxmpp@xmpp.ws JabberID.
- PASSWORD="123"
  Password of the above Jabber ID. It needs to be authenticated by the server.
- SASL="true"/"false"
  Specify whether the client should use the SASL authentication or not. It is recommended to use SASL authentication. Furthermore, it is supported by most public servers.
Programmatically, using the service client

You might have a requirement of using the client programmatically rather than statically. In that case we should specify the above mentioned parameters to the service client.

...

...

axutil_property_t *xmpp_jid = NULL;

axutil_property_t *xmpp_password = NULL;

axutil_property_t *xmpp_sasl = NULL;

...

...

xmpp_jid = axutil_property_create (env);

axutil_property_set_value (xmpp_jid, env, (void *)axutil_strdup (env, "xyxmpp@xmpp.ws/Home"));

axis2_options_set_property (options, env, "XMPP_JID", (void *)xmpp_jid);

xmpp_password = axutil_property_create (env);

axutil_property_set_value (xmpp_password, env, (void *)axutil_strdup (env, "123"));

axis2_options_set_property (options, env, "XMPP_PASSWORD", (void *)xmpp_password);

xmpp_sasl = axutil_property_create (env);

axutil_property_set_value (xmpp_sasl, env, (void *)axutil_strdup (env, "true"));

axis2_options_set_property (options, env, "XMPP_SASL", (void *)xmpp_sasl);

axis2_svc_client_set_options(svc_client, env, options);

NOTE:
Source codes for this sample can be found at the WSF/C source repository. Under xmpp transport, there is a directory named "samples", you can find the relevant source and configuration files there. If you wish to refer them online, please refer to the resources section.

Service URI

Irrespective of the way that you going to use the client, you need to specify the service URL in the client.

const axis2_char_t *address = NULL;
    axis2_endpoint_ref_t* endpoint_ref = NULL;
         ...
         ...
    address = "xmpp://xyecho@xmpp.ws/WSF/services/echo";
    endpoint_ref = axis2_endpoint_ref_create(env, address); 
         ...

If we closely identify the parts of the address, there are certain parameters you should note.

address = "xmpp://xyecho@xmpp.ws/axis2/services/echo";

xmpp://

This is known as a scheme. Generally this is identified by the transport element. When we are using XMPP transport, it is specified as xmpp://

xyecho@xmpp.ws

Normally, this is the server address or IP. However in XMPP transport, we give the Jabber client ID. If you observe the above procedures closely, you may note that our service is up and running as a Jabber Client instance. That is why we are using JID as the server address. As I already mentioned, I'm using the xyecho@xmpp.ws account to get my service up and running.