Apache Axis2/C User's Guide

Introduction

Welcome to Axis2/C, the Apache Axis2 implementation in C. This User's Guide will help you understand what Axis2/C has to offer and how to get started with it.

What is Axis2/C?

Axis2/C is an effort to implement the Axis2 architecture in C programming language. For more information on the architecture C Specific Architectural Notes are also available.

After months of continued discussion and coding in this direction, Axis2/C now delivers the following key features:

  • Speed - Axis2/C uses its own XML object model and StAX (Streaming API for XML) parsing to achieve significant speed. In addition to that, Axis2/C is inherently benefited by the speed of its implementation language, namely C, compared to Java implementation.

  • Low memory foot print- Axis2 architecture was designed ground-up keeping in mind the low memory foot print. Axis2/C strives to achieve the same with a well designed memory management strategy.

  • AXIOM/C- Axis2/C comes with its own light-weight object model for XML, AXIOM/C which is the C implementation of AXIOM.

  • MEP Support - Supports Message Exchange Patterns (MEPs)

  • Flexibility - Axis2/C architecture gives the developer complete freedom to insert extensions into the engine (using modules and handlers) for custom SOAP header processing.

  • Transport Framework - We have a clean and simple abstraction for integrating and using transports, and the core of the engine is completely transport-independent.

  • Composition and Extensibility - Modules and phases improve support for composability and extensibility. Modules support composability and are able to add support for new WS-* specifications in a simple and clean manner. They are however, not hot deployable as they change the overall behavior of the system.

Axis2/C team is working hard to continuously improve the implementation. Please note that this is an open-source effort. If you feel you have some time to spare, please get involved and lend us a hand! The Axis2/C developer community welcomes your participation and contributions.

Let us know what you think! Please send your feedback on Axis2/C to "axis-c-user@ws.apache.org" and please remember to prefix the subject of the mail with [Axis2].

The following sections will guide on how to write Web service clients and services.

Web Services Using Axis2/C

Before starting, please make sure that you have installed Axis2/C correctly and whether you can run the axis2_http_server located in AXIS2C_HOME/bin (See Installation Guide for details).

Writing Web Services Using Axis2/C

Creating Web Service (Echo service)

First let's see how we can write a simple Web Service (echo service) using Axis2/C's primary interfaces and how to deploy it. For this purpose we will create a Web Service with one operation as follows.

axiom_node_t* axis2_echo_echo(axiom_node_t *echo_node){}

You can have a peek at the complete source code for this example echo service located in the "AXIS2C_HOME/samples/server/echo" directory.

How to write the Web Service?

Writing a new Web Service with Axis2/C involves four steps. Let's take echo service as our example.

  1. Write a echo_skeleton.c file which implements the API given in axis2_svc_skeleton.h header file.

  2. Write the service implementation source file (in this case echo.c service) which implements the actual business logic.
  3. Write a services.xml file to explain the Web service.
  4. Create a folder with the service name under AXIS2C_HOME/services and put the compiled service ( .dll or .so file) for the Web service and services.xml file into that folder.

Step1 :Write the echo_skeleton.c file implementing the axis2_svc_skeleton.h

axis2_svc_skeleton.h header file has the axis2_svc_skeleton_ops_t operations struct which defines four function pointers to be implemented and assigned by a service skeleton.

They are:

int (AXIS2_CALL * init) (axis2_svc_skeleton_t *svc_skeleton,
 const axis2_env_t *env);

axiom_node_t * (AXIS2_CALL* invoke)(axis2_svc_skeleton_t *svc_skeli, 
 const axis2_env_t *env, axiom_node_t *node);

axiom_node_t *(AXIS2_CALL* on_fault)(axis2_svc_skeleton_t *svc_skeli,
 const axis2_env_t *env, axiom_node_t *node);

int (AXIS2_CALL *free)(axis2_svc_skeleton_t *svc_skeli, 
 const axis2_env_t *env);

Let's implement the above functions for echo service.

/*Initializetheservice*/

intAXIS2_CALL

echo_init(axis2_svc_skeleton_t*svc_skeleton,

const axis2_env_t*env)

{

svc_skeleton->func_array=axis2_array_list_create(env,0);

/*Addtheimplementedoperationnamesoftheserviceto

*thearraylistoffunctions

*/


AXIS2_ARRAY_LIST_ADD(svc_skeleton->func_array,env,"echoString");

/*Anyinitializationstuffofechoserviceshouldgohere*/

returnAXIS2_SUCCESS;

}



/*

*Thismethodinvokestherightservicemethod

*/


axiom_node_t*AXIS2_CALL

echo_invoke(axis2_svc_skeleton_t*svc_skeleton,

const axis2_env_t*env,

axiom_node_t*node)

{

/*Invokethebusinesslogic.

*Dependingonthefunctionnameinvokethecorrectimplmethod.

*Wehaveonlyechointhissample,henceinvokeechomethod.

*Toseehowtodealwithmultipleimplmethods,havealookatthe

*mathsample.

*/


returnaxis2_echo_echo(env,node);

}



/*Onfault,handlethefault*/

axiom_node_t*AXIS2_CALL

echo_on_fault(axis2_svc_skeleton_t*svc_skeli,

const axis2_env_t*env,axiom_node_t*node)

{

/*Herewearejustsettingasimpleerrormessageinsideanelement

*called'EchoServiceError'

*/


axiom_node_t*error_node=NULL;

axiom_node_t*text_node=NULL;

axiom_element_t*error_ele=NULL;

error_ele=axiom_element_create(env,node,"EchoServiceError",NULL,

&error_node);

AXIOM_ELEMENT_SET_TEXT(error_ele,env,"Echoservicefailed",

text_node);

returnerror_node;

}



/*Freetheresourcesused*/

intAXIS2_CALL

echo_free(axis2_svc_skeleton_t*svc_skeleton,

const axis2_env_t*env)

{

/*Freethefunctionarray*/

if(svc_skeleton->func_array)

{

AXIS2_ARRAY_LIST_FREE(svc_skeleton->func_array,env);

svc_skeleton->func_array=NULL;

}



/*Freethefunctionarray*/

if(svc_skeleton->ops)

{

AXIS2_FREE(env->allocator,svc_skeleton->ops);

svc_skeleton->ops=NULL;

}



/*Freetheserviceskeleton*/

if(svc_skeleton)

{

AXIS2_FREE(env->allocator,svc_skeleton);

svc_skeleton=NULL;

}



returnAXIS2_SUCCESS;

}

Now we can write the create function of the echo_service_skeleton as follows:

/*Createfunction*/

axis2_svc_skeleton_t*

axis2_echo_create(const axis2_env_t*env)

{

axis2_svc_skeleton_t*svc_skeleton=NULL;

/*Allocatememoryforthestructs*/

svc_skeleton=AXIS2_MALLOC(env->allocator,

sizeof(axis2_svc_skeleton_t));



svc_skeleton->ops=AXIS2_MALLOC(

env->allocator,sizeof(axis2_svc_skeleton_ops_t));



/*Assignfunctionpointers*/

svc_skeleton->ops->free=echo_free;

svc_skeleton->ops->init=echo_init;

svc_skeleton->ops->invoke=echo_invoke;

svc_skeleton->ops->on_fault=echo_on_fault;



returnsvc_skeleton;

}

In addition to the above functions, every service must have the following two functions with exactly the same function signature as in xxx_skeleton.c file.

AXIS2_EXPORTint

axis2_get_instance(axis2_svc_skeleton_t**inst,

const axis2_env_t*env)

{

*inst=axis2_echo_create(env);

if(!(*inst))

{

returnAXIS2_FAILURE;

}

returnAXIS2_SUCCESS;

}



AXIS2_EXPORTint

axis2_remove_instance(axis2_svc_skeleton_t*inst,

const axis2_env_t*env)

{

axis2_status_tstatus=AXIS2_FAILURE;

if(inst)

{

status=AXIS2_SVC_SKELETON_FREE(inst,env);

}

returnstatus;

}

Axis2/C engine can load the service dll. However, it needs to know which method to call. Since C does not have reflection, we need to have some dll exposing functions known to Axis2/C engine. axis2_get_instance and axis2_remove_instance are the two functions that need to be exposed from a service dll (or any other dll of Axis2/C engine). Axis2/C engine calls axis2_get_instance method, which creates a new service instance, and casts the return pointer to axis2_svc_skeleton interface. Then, the interface methods can be called by Axis2/C engine.

Step2 : Now we can write the echo service in a file echo.c

axiom_node_t*

axis2_echo_echo(const axis2_env_t*env,axiom_node_t*node)

{

axiom_node_t*text_parent_node=NULL;

axiom_node_t*text_node=NULL;

axiom_node_t*ret_node=NULL;



AXIS2_ENV_CHECK(env,NULL);



/*Expectedrequestformatis:-

*<ns1:echoStringxmlns:ns1="http://localhost:9090/axis2/services/echo">

*<text>echo5</text>

*</ns1:echoString>

*/


if(!node)/*'echoString'node*/

{

AXIS2_ERROR_SET(env->error,AXIS2_ERROR_SVC_SKEL_INPUT_OM_NODE_NULL,AXIS2_FAILURE);

printf("EchoclientERROR:inputparameterNULL\n");

returnNULL;

}



text_parent_node=AXIOM_NODE_GET_FIRST_CHILD(node,env);

if(!text_parent_node)/*'text'node*/

{

AXIS2_ERROR_SET(env->error,AXIS2_ERROR_SVC_SKEL_INVALID_XML_FORMAT_IN_REQUEST,AXIS2_FAILURE);

printf("EchoclientERROR:invalidXMLinrequest\n");

returnNULL;

}



text_node=AXIOM_NODE_GET_FIRST_CHILD(text_parent_node,env);

if(!text_node)/*actualtexttoecho*/

{

AXIS2_ERROR_SET(env->error,AXIS2_ERROR_SVC_SKEL_INVALID_XML_FORMAT_IN_REQUEST,AXIS2_FAILURE);

printf("EchoclientERROR:invalidXMLinrequest\n");

returnNULL;

}



if(AXIOM_NODE_GET_NODE_TYPE(text_node,env)==AXIOM_TEXT)

{

axiom_text_t*text=(axiom_text_t*)AXIOM_NODE_GET_DATA_ELEMENT(text_node,env);

if(text&&AXIOM_TEXT_GET_VALUE(text,env))

{

axis2_char_t*text_str=AXIOM_TEXT_GET_VALUE(text,env);

printf("Echoingtextvalue%s\n",text_str);

ret_node=build_om_programatically(env,text_str);

}

}

else

{

AXIS2_ERROR_SET(env->error,AXIS2_ERROR_SVC_SKEL_INVALID_XML_FORMAT_IN_REQUEST,AXIS2_FAILURE);

printf("EchoclientERROR:invalidXMLinrequest\n");

returnNULL;

}



returnret_node;

}



/*Buildstheresponsecontent*/

axiom_node_t*

build_om_programatically(const axis2_env_t*env,axis2_char_t*text)

{

axiom_node_t*echo_om_node=NULL;

axiom_element_t*echo_om_ele=NULL;

axiom_node_t*text_om_node=NULL;

axiom_element_t*text_om_ele=NULL;

axiom_namespace_t*ns1=NULL;



ns1=axiom_namespace_create(env,"http://localhost:9090/axis2/services/echo","ns1");



echo_om_ele=axiom_element_create(env,NULL,"echoString",ns1,&echo_om_node);



text_om_ele=axiom_element_create(env,echo_om_node,"text",NULL,&text_om_node);



AXIOM_ELEMENT_SET_TEXT(text_om_ele,env,text,text_om_node);



returnecho_om_node;

}

Step3 :Write the services.xml file

Axis2/C uses "services.xml" file to keep configurations of a Web service. Each Web service deployed in Axis2/C needs a "services.xml" file containing the configurations. Note that services.xml has the same semantics as Axis2 Java's services.xml file. Only difference is that instead of giving package qualified class name, we use the dll name for class attributes.

"services.xml" for echo will be as follows:

<service name="echo">

<parameter name="ServiceClass" locked="xsd:false">echo</parameter>

<description>

This is a echo service

</description>



<operation name="echoString">

<parameter name="wsamapping">

http://localhost:9090/axis2/services/echo/echoString

</parameter>

</operation>

</service>

Name of the service will be the name of the folder with the shared library and services.xml. In this example we will have a folder named "echo" in which we have the echo.dll (or libecho.so on Linux platform) and services.xml file.

You can write a services.xml file to include a group of services instead of a single service. This makes management and deployment of a set of related services very easy. At runtime you can share information between these services within a single interaction using the axis2_svc_grp_ctx (Service Group Context ). If you hope to use this functionality, the services.xml file should have following format:

<serviceGroup>

<service name="Service1">

<!-- details for Service1 -->

</service>

<service name="Service2">

<!-- details for Service2 -->

</service>

<module ref="ModuleName" />

<parameter name="serviceGroupParam1" locked="false">value 1</parameter>

</serviceGroup>

Note : Name of the service is a compulsory attribute

Step4 :Create the Web service folder in services folder of the repository.

In Axis2/C , it is required to create a folder with the corresponding service/service group name which will contain the shared library (compiled service) and the services.xml file which describes the Web service. So for this example, we will have to create a folder named "echo", which contains the services.xml file and echo dll.

Step5 :Archive Based Deployment Model

Axis2 uses ".aar" (Axis Archive) file as the deployment package for the Web services. Therefore, for echo service we will use "echo.aar". Note that the name of the service will be the name of the archive file. To create "echo.aar" user can create a zip file containing echo.so and services.xml and rename the zip extension to aar. Then Axis2 understands it as a service archive.

Writing Web Services Skeleton Using Code Generator

WSDL2C tool

Axis2/Java WSDL2C tool supports generation of Axis2/C stub and skeleton. Axis2/Java SVN revision 414253 and later versions provide this facility. A basic guide for the tool can be found here.

We will run the tool with the following parameters and generate the skeleton and other required files to support ADB (Axis Data Binding). In order to run the tool, set all the .jar library files in the Axis2/Java to the classpath. To generate code with no data binding support, just replace -d adb -u with -d none

java org.apache.axis2.wsdl.WSDL2C -uri interoptestdoclitparameters.wsdl -ss -sd -d adb -u 


If you need an XML in/out programming model, you can just ignore the data binding support by setting the following parameters.

java org.apache.axis2.wsdl.WSDL2C -uri interoptestdoclitparameters.wsdl -ss -sd -d none

The WSDL interoptestdoclitparameters.wsdl can be found in <axis2_src_dir>/test/resources directory. This is used to generate stub and skeleton code throughout this User's Guide.

Implement the Business Logic

Locate the skeleton source file from the generated files: "axis2_WSDLInteropTestDocLitService.c". You can go through the rest of the guide to add the business logic to the following operations in the WSDL.

  • echoString - Operation that echoes a String value.
  • echoStringArray - Operation that accepts a string array as the input and echoes them back.
  • echoStruct - Operation that accepts a Struct as the input and echoes them back.

Complete skeleton source file for the above operations can be found under <axis2_src_dir>/samples/codegen/server/interop_doc2 directory with the name "axis2_WSDLInteropTestDocLitService.c".

echoString

If you generate the code with data binding support, you will find the following code segment in the "axis2_WSDLInteropTestDocLitService.c". Fill the business logic inside this function as shown below:

axis2_echoStringResponse_t*
axis2_WSDLInteropTestDocLitService_echoString
 (const axis2_env_t* env ,axis2_echoString_t* param6 )
{
 /* Todo fill this with the necessary business logic *}


Once the business logic is filled, it will be as follows. The code is simple and the inline comments provide explanation.

axis2_echoStringResponse_t*
axis2_WSDLInteropTestDocLitService_echoString
 (const axis2_env_t* env ,axis2_echoString_t* param6 )
{
 axis2_echoString_t* echo_in = param6;
 axis2_echoStringResponse_t* echo_out = NULL;

 char* echo_string = NULL;
 
 /* retrieve the string input */
 echo_string = AXIS2_ECHOSTRING_GET_PARAM0 ( echo_in, env );

 /* create the response and set the output string */
 echo_out = axis2_echoStringResponse_create ( env );
 AXIS2_ECHOSTRUCTRESPONSE_SET_RETURN ( echo_out, env, echo_string );

 return echo_out;
}

echoStringArray

axis2_echoStringArrayResponse_t*
axis2_WSDLInteropTestDocLitService_echoStringArray
 (const axis2_env_t* env ,axis2_echoStringArray_t* param2 )

{
 axis2_echoStringArray_t* echo_in = param2;
 axis2_echoStringArrayResponse_t* echo_out = NULL;
 axis2_ArrayOfstring_literal_t* array_in = NULL;
 axis2_ArrayOfstring_literal_t* array_out = NULL;
 char ** string_array = NULL;
 int string_array_length = 0;
 
 /* retrieve the array from input*/
 array_in = AXIS2_ECHOSTRINGARRAY_GET_PARAM0( echo_in, env);
 /* retrieve the string_array and array length */
 string_array =
 AXIS2_ARRAYOFSTRING_LITERAL_GET_STRING 
 (array_in, env,&string_array_length );
 
 /* create the output array and set the string array and length */
 array_out = axis2_ArrayOfstring_literal_create ( env );
 AXIS2_ARRAYOFSTRING_LITERAL_SET_STRING(
 array_out, env, string_array, string_array_length );
 
 /* create the response and set the output*/
 echo_out = axis2_echoStringArrayResponse_create ( env );
 AXIS2_ECHOSTRINGARRAYRESPONSE_SET_RETURN ( echo_out, env , array_out
 );
 
 return echo_out;

echoStruct

axis2_echoStructResponse_t*
axis2_WSDLInteropTestDocLitService_echoStruct
 (const axis2_env_t* env ,axis2_echoStruct_t* param4 )

{
 axis2_echoStruct_t* echo_in = param4;
 axis2_echoStructResponse_t* echo_out = NULL;
 axis2_SOAPStruct_t* struct_in = NULL;
 axis2_SOAPStruct_t* struct_out = NULL;
 
 float float_val = 0;
 int int_val = 0;
 char* string_val = NULL;
 
 /* retrieve the structure from input */
 struct_in = AXIS2_ECHOSTRUCT_GET_PARAM0( echo_in, env);

 /* retrieve each value from the structure */ 
 float_val = AXIS2_SOAPSTRUCT_GET_VARFLOAT ( struct_in, env);
 int_val = AXIS2_SOAPSTRUCT_GET_VARINT ( struct_in, env);
 string_val = AXIS2_SOAPSTRUCT_GET_VARSTRING ( struct_in, env);
 
 /* create the output structure and set values */
 struct_out = axis2_SOAPStruct_create( env );
 AXIS2_SOAPSTRUCT_SET_VARFLOAT ( struct_out, env, float_val );
 AXIS2_SOAPSTRUCT_SET_VARINT ( struct_out, env, int_val );
 AXIS2_SOAPSTRUCT_SET_VARSTRING ( struct_out, env, string_val );
 
 /* create the response and set the output structure*/
 echo_out = axis2_echoStructResponse_create ( env );
 AXIS2_ECHOSTRUCTRESPONSE_SET_RETURN ( echo_out, env, struct_out );
 
 return echo_out;

services.xml

Axis2 uses "services.xml" to hold the configurations for a particular Web service deployed in the Axis2 engine. When we generate the skeleton using the WSDL2Java tool, it will generate the required services.xml for this Web service as well. This is essential to deploy the service. Please refer to the 'Write the services.xml' section in this guide to learn more about services.xml.

Deploy the Web Service

We simply put our service folder or the ".aar" file to the services directory. You need restart the server for the engine to pick this service.

Web Service Clients Using Axis2/C

Now let's see how we can write a Web service client to consume a Web service.

Web services can be used to provide wide range of functionality to the users ranging from simple, less time consuming operations such as "getStockQuote" to time consuming business services. When we utilize (invoke using client applications) these Web services, we cannot use some simple generic invocation paradigm that suits all the timing complexities involved in the service operations. For example, if we use a single transport channel (such as HTTP) to invoke a Web service with an IN-OUT operation which takes a long time to complete, then most of the time we may end up with "connection time outs". On the other hand, if there are simultaneous service invocations thatwe need to perform from a single client application, then the use of a "blocking" client API will degrade the performance of the client application. Similarly, there are various other consequences such as One-Way transports that come into play when we need them. Let's try to analyze some common service invocation paradigms.

Many Web service engines provide the users with a Blocking and Non-Blocking client APIs.

  • Blocking API -Once the service invocation is called, the client application hangs and only gets control back when the operation completes, after which client receives a response or a fault. This is the simplest way of invoking Web services and it also suits many business situations.

  • Non-Blocking API- This is a callback or polling based API. Hence, once a service invocation is called, the client application immediately gets the control back and the response is retrieved using the callback object provided. This approach provides the client application with the flexibility to invoke several Web services simultaneously without blocking the operation that has already been invoked.

Both these mechanisms work in the API level. Let's name theasynchronous behavior that we can get using the Non-Blocking API as API Level Asynchrony.

Both these mechanisms use single transport connection to send the request and to receive the response. They severely lack the capability of using two transport connections for the request and the response (either One-Way of Two-Way). So both these mechanisms fail to address the problem of long running transactions (the transport connection may time-out before the operation completes). A possible solution would be to use two separate transport connections for request and response. The asynchronous behavior that we gain using this solution can be called Transport Level Asynchrony.

By combining API Level Asynchrony & Transport Level Asynchrony we can obtain four different invocation patterns for Web services as shown in the following table.

API (Blocking/Non-Blocking)Dual Transports (Yes/No)Description
BlockingNoSimplest and the familiar invocation pattern
Non-BlockingNoUsing callbacks or polling
BlockingYesThis is useful when the service operation is IN-OUT in nature but the transport used is One-Way (e.g. SMTP)
Non-BlockingYesThis can be used to gain the maximum asynchronous behavior. No blocking in the API level and also in the transport level

Axis2/C provides the user with all these possibilities to invoke Web services.

Below we describe how to write Web Services Clients using Axis2/C.

Writing Web Service Clients Using Axis2's Primary APIs

echo_blocking Client

Axis2/C provides the user with several invocation patterns for Web Services, ranging from pure blocking single channel invocations to a non-blocking dual channel invocation. Let's first see how we can write a client to invoke "echo" operation of "echo" service using the simplest blocking invocation. The client code you need to write is as follows.

 /* Create EPR with given address */
endpoint_ref = axis2_endpoint_ref_create(env, address);
/* Setup options */
options = axis2_options_create(env);
AXIS2_OPTIONS_SET_TO(options, env, endpoint_ref);
/* Set the deploy folder */
client_home = AXIS2_GETENV("AXIS2C_HOME");
if (!client_home)
client_home = "../../deploy";
/* Create service client */
svc_client = axis2_svc_client_create(env, client_home);
    if (!svc_client)
    {
       printf("Error creating service client\n");
       AXIS2_LOG_ERROR(env->log, AXIS2_LOG_SI, "Stub invoke FAILED:
        Error code: 
%	d :: %s", env->error->error_number,
        AXIS2_ERROR_GET_MESSAGE(env->error));
    }
/* Set service client options */
AXIS2_SVC_CLIENT_SET_OPTIONS(svc_client, env, options); /* Build the
SOAP request message payload using OM API.*/
payload = build_om_payload_for_echo_svc(env);
/* Send request */
ret_node = AXIS2_SVC_CLIENT_SEND_RECEIVE(svc_client, env, payload);
/* Print result */
    if(ret_node)
    {
       axis2_char_t *om_str = NULL;
       om_str = AXIOM_NODE_TO_STRING(ret_node, env);
       if (om_str)
          printf("\nReceived OM : %s\n", om_str);
       printf("\necho client invoke SUCCESSFUL!\n");
    }      
    else
    {
       AXIS2_LOG_ERROR(env->log, AXIS2_LOG_SI, "Stub invoke FAILED: Error code:"
" %d :: %s", env->error->error_number,
       AXIS2_ERROR_GET_MESSAGE(env->error));
       printf("echo client invoke FAILED!\n");
}

The comments in the above code explains the code. In simple terms, these are the steps:

  1. Set up the options to be used in the invocation.
  2. Create the service client.
  3. Set the options to service client.
  4. Build the XML payload to be sent out using AXIOM.
  5. Send payload and receive result XML as OM.
  6. Consume result.

Options can be used to define the invocation parameters such as target endpoint, soap version, addressing parameters, etc. When creating service client, the deployment folder has to be passed as a parameter. It is from the deploy folder, the configuration is picked up, using the axis2.xml file. The send_receive function of the service client sends the XML given as a payload to the server side and returns the result received. Basically this is the XML in/out model. Once the result is received, the user can consume the result in whichever the way(s) he wishes.

echo_non_blocking Client

In the echo_blocking client once the "send_receive" function is called, the client is blocked till the operation is completed. This behavior is not desirable when there are many Web service invocations to be done in a single client application or within a GUI. A solution would be to use a non-blocking API to invoke Web services. Axis2/C provides a callback based non-blocking API for users.

A sample client for this can be found under "<axis2c_home>/samples/user_guide/clients" with the name echo_non_blocking.c. The changes that user may have to do with respect to the "echo_blocking" client in order to make it non-blocking, would be as follows:

AXIS2_SVC_CLIENT_SEND_RECEIVE_NON_BLOCKING(svc_client, env, payload, callback);

Unlike "send_receive", "send_receive_non_blocking" accepts a callback struct in addition to payload. Axis2/C client API provides a callback struct with the following associated functions:

axis2_status_t (AXIS2_CALL *
on_complete)(
 struct axis2_callback *callback,
 const axis2_env_t *env);

axis2_status_t (AXIS2_CALL *
on_error)(
 struct axis2_callback *callback,
 const axis2_env_t *env,
 int exception);

axis2_bool_t (AXIS2_CALL *
get_complete)(
 struct axis2_callback *callback,
 const axis2_env_t *env);

The user is expected to implement the "on_complete " and "on_error " functions and set them on the callback using the "set_on_complete" and "set_on_error" API calls. In the sample, ''on complete'' is implemented by "echo_callback_on_complete" function and is set on the callback struct created as shown below:

AXIS2_CALLBACK_SET_ON_COMPLETE(callback, echo_callback_on_complete);

Axis2/C engine calls the "on_complete" method once the Web service response is received by the Axis2/C client API (that is service_client). This will eliminate the blocking nature of the Web service invocations and provide the user with the flexibility to use non-blocking API for Web service clients.

Please have a look at the echo_non_blocking.c file located at "<axis2c_home>/samples/user_guide/client" for more details.

echo_non_blocking_dual Client

The solution provided by the non-blocking API has one limitation when it comes to Web service invocations,it takes a long time to complete. The limitation is due to the use of a single transport connection to invoke the Web service and to retrieve the response. In other words, client API provides a non blocking invocation mechanism for the users, but the request and the response comes in a single transport (Two-Way transport) connection (like HTTP). Long running Web service invocations or Web service invocations using One-Way transports (like SMTP) cannot be utilized by simply using a non blocking invocation.

The trivial solution is to use separate transport connections (either One-Way or Two-Way) for the request and response. The next problem that needs to be solved is the correlation (correlating the request and the response). WS-Addressing provides a neat solution to this using <wsa:MessageID> and <wsa:RelatesTo> headers. Axis2/C provides support for addressing based correlation mechanism and a compliant client API to invoke Web services with two transport connections.

Users can select between blocking or non-blocking APIs for the Web service clients with two transport connections. By simply using a boolean flag, the same API can be used to invoke Web services (IN-OUT operations) using two separate transport connections. All you have to do is to set "use_separate_listener" to true in options:

AXIS2_OPTIONS_SET_USE_SEPERATE_LISTENER(options, env, AXIS2_TRUE);

In addition to setting the use_separate_listener to true, to use dual transports one has to"engage" the addressing module.

Engaging Addressing on Server Side

To engage the addressing module simply add a module reference for addressing in the "axis2.xml" configuration file. This can be done by adding the following line to "axis2.xml" file in the deployment folder.

 <module ref="addressing"/>

Note: Once you modify the "axis2.xml" file you have to restart the server. You also have to have the addressing module installed in the modules folder of the deployment folder. This is done by default when you make the installation.

Engaging Addressing on Client Side

There are two ways of doing this:

  1. Engage addressing globally. This can be done by following the same steps as done in the case of the server side; add module reference to axis2.xml and have the module installed in the modules folder of the deploy folder.
  2. Engage the module on service client using the service_client API.
    AXIS2_SVC_CLIENT_ENGAGE_MODULE(svc_client, env, AXIS2_MODULE_ADDRESSING);

Once addressing is engaged, echo_non_blocking_dual client would work perfectly. Note that by default, Axis2/C comes with addressing enabled globally.

echo_blocking_dual Client

This is again a Two-Way transport request/response client, but this time, we use a Blocking API in the client code. Sample code for this can be found in the "<axis2c_home>/samples/user_guide/clients/" directory and the explanation is similar to the echo_non_blocking_dual client, except that here we do not use a callback object to handle response. This is an extremely useful mechanism when the service invocation is IN-OUT in nature and the transports are One-Way (e.g. SMTP). For the sample client we use two HTTP connections for request and response.

Writing Web Service Clients using Code Generation with Data Binding Support

Axis2 code generator provides the data binding support for Web service client generation as well. You can generate the required stubs from a given WSDL with the other supporting files. Use the following parameters to generate the Axis2/C stub code with data binding support. You should have Axis2/Java source SVN revision 414253 or later to generate Axis2/C code.

java WSDL2C -uri interoptestdoclitparameters.wsdl -d adb -u

In order to ignore the data binding support (to use XML in/out model), just use the following parameters.

java WSDL2C -uri interoptestdoclitparameters.wsdl -d none

The following section demonstrates how to use the generated code using the wsdl file "interoptestdoclitparameters.wsdl" to implement the client business logic.

Client for echoString operation

#include "axis2_WSDLInteropTestDocLitService_stub.h"
/*
 * demonstrates how to execute the service using databinding */
void invoke_service_using_databinding ( axis2_stub_t* stub, 
                                    const axis2_env_t* env );
int main(int argc, char** argv)
{
/* variables to keep the environment */
 axis2_env_t* env = NULL;
 axis2_char_t* client_home = NULL;
 axis2_char_t* endpoint_uri =NULL;
 axis2_stub_t* stub= NULL;
 /* endpoint uri: if it is NULL endpoint will be picked from the WSDL */ 
 endpoint_uri =
 "http://localhost:9090/axis2/services/WSDLInteropTestDocLitService";
 env = axis2_env_create_all( "codegen_utest_blocking.log", 
 AXIS2_LOG_LEVEL_TRACE);
 /* Set up deploy folder.*/
 client_home = AXIS2_GETENV("AXIS2C_HOME");
 if (!client_home)
 client_home = "../../../deploy";
 /* create the stub using generated code */
 stub = axis2_WSDLInteropTestDocLitService_stub_create( env,
 client_home , endpoint_uri); 
 /* calls the service*/
 invoke_service_using_databinding ( stub, env );
 return 0;
} 

void invoke_service_using_databinding ( axis2_stub_t* stub,
 const axis2_env_t* env )
 {
 /* variables used by databinding */
 axis2_echoString_t* echo_in = NULL;
 axis2_echoStringResponse_t* echo_out = NULL;
 /* variables to store data */
 char* echo_str = "hello";
 char* return_echo_str = NULL;
 /* create the input params using databinding */
 echo_in = axis2_echoString_create( env );
 AXIS2_ECHOSTRING_SET_PARAM0( echo_in, env, echo_str );
 /* invoke the web service method*/
 echo_out = axis2_echoString( stub, env, echo_in );
 /* return the output params using databinding */
 return_echo_str = AXIS2_ECHOSTRUCTRESPONSE_GET_RETURN( echo_out, env
 );
 /* print the result */
 printf ( "returned string %s\n", return_echo_str );
} 

Client for echoStringArray operation

You can change the invoke_service_using_databinding function to invoke the echoStringArray operation as follows.

void invoke_service_using_databinding ( axis2_stub_t* stub, const
axis2_env_t* env )
 {
 /* variables used by databinding */
 axis2_echoStringArray_t* echo_in = NULL;
 axis2_echoStringArrayResponse_t* echo_out = NULL;
 axis2_ArrayOfstring_literal_t* array_in = NULL;
 axis2_ArrayOfstring_literal_t* array_out = NULL;
  /* variables to store data */
 char *string_array[]= { "test","this","array" };
 int array_length = 3;
  char **string_return_string_array = NULL;
 int return_array_length = 0;
 int i = 0;
 
  /*create the input array and set the string array and length*/
 array_in = axis2_ArrayOfstring_literal_create (env );
 AXIS2_ARRAYOFSTRING_LITERAL_SET_STRING( array_in, env,
 string_array, array_length );

 /* create the request and set the inputs */
 echo_in = axis2_echoStringArray_create ( env );
 AXIS2_ECHOSTRINGARRAY_SET_PARAM0( echo_in, env, array_in );

 /* invoke the web service method*/
 echo_out = axis2_echoStringArray( stub, env, echo_in );

 /* return the output params using databinding */
 array_out = AXIS2_ECHOSTRINGARRAYRESPONSE_GET_RETURN( echo_out, env
 ); 
 
 /* retrieve the string array values and length */
 string_return_string_array = AXIS2_ARRAYOFSTRING_LITERAL_GET_STRING
 ( array_out, env, &return_array_length );

 /* print the output */
 for ( i = 0; i < return_array_length ; i ++ )
  {
    printf("value%d: %s \n", i, string_return_string_array[i] );
  }
 

Client for echoStruct operation

void invoke_service_using_databinding ( axis2_stub_t* stub,
 const axis2_env_t* env )
 {
 /* variables used by databinding */
 axis2_echoStruct_t* echo_in = NULL;
 axis2_echoStructResponse_t* echo_out = NULL;
 axis2_SOAPStruct_t* struct_in = NULL;
 axis2_SOAPStruct_t* struct_out = NULL;


 /* variables to store data */
 float float_val = 11;
 int int_val = 10;
 char* string_val = "hello struct";
 int ret_int_val = 0;
 float ret_float_val = 0;
 char* ret_string_val = "";
 
 /* create the struct and set input values*/
 struct_in = axis2_SOAPStruct_create( env );
 AXIS2_SOAPSTRUCT_SET_VARFLOAT ( struct_in, env, float_val );
 AXIS2_SOAPSTRUCT_SET_VARINT ( struct_in, env, int_val );
 AXIS2_SOAPSTRUCT_SET_VARSTRING ( struct_in, env, string_val );

 /* create the request and set the struct */
 echo_in = axis2_echoStruct_create( env );
 AXIS2_ECHOSTRUCT_SET_PARAM0( echo_in, env, struct_in );
 /* invoke the web service method */
 echo_out = axis2_echoStruct( stub, env, echo_in );

 /* retrieve the structure from response */
 struct_out = AXIS2_ECHOSTRUCTRESPONSE_GET_RETURN( echo_out, env );

 /* retrieve each value from the structure */
 ret_float_val = AXIS2_SOAPSTRUCT_GET_VARFLOAT ( struct_out, env );
 ret_int_val = AXIS2_SOAPSTRUCT_GET_VARINT ( struct_out, env );
 ret_string_val = AXIS2_SOAPSTRUCT_GET_VARSTRING ( struct_out, env );

 /* print the values */
 printf ( "returned values \n");
 printf (" float %f\n", ret_float_val );
 printf (" int %d \n", ret_int_val );
 printf (" string %s \n", ret_string_val);
 }
 

Providing Security using Rampart/C

Rampart/C is the security module for Axis2/C, which supports UsernameToken based authentication and Timestamps as per WS-Security specification. In this User's Guide we will explain how to use Rampart inside Axis2/C.

Engaging rampart module

  • Step 1: Copy rampart directory created in AXIS2C_HOME/deploy/rampart to AXIS2C_HOME/deploy/modules
    cp $AXIS2C_HOME/deploy/rampart/rampart $AXIS2C_HOME/deploy/modules
  • Step 2:Add following line to the axis2.xml under axisconfig. This will engage the rampart module.
    <module ref="rampart"/>
  • Step 3:Then add the following to axis2.xml file to specify In/Out flow parameters. You may find a sample axis2.xml file in rampart/samples/client/echo/data/

    <parameter name="OutflowSecurity"><action>

    <items>UsernameToken Timestamp</items>

    <user>Gajaba</user>

    <passwordType>passwordDigest</passwordType>

    <passwordCallbackClass>/home/gajaba/axis2/c/deploy/rampart/samples/callback/libpwcb.so</passwordCallbackClass>

    <timeToLive>360</timeToLive>

    </action>

    </parameter>

    <parameter name="InflowSecurity">

    <action>

    <items>UsernameToken Timestamp</items>

    <passwordCallbackClass>/home/gajaba/axis2/c/deploy/rampart/samples/callback/libpwcb.so</passwordCallbackClass>

    </action>

    </parameter>

Note: You must replace the value of passwordCallbackClass parameter to suit your settings.

Now everything is setup to try out the sample. Start axis2 server and run the sample under rampart/samples/client/echo. If everything works fine a security header should be added to the outgoing SOAP message.

<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">

<wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">

<wsse:Username>Gajaba</wsse:Username>

<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">WNPznBN3PeLypKYXlwV7w9zJZ9o=</wsse:Password>

<wsse:Nonce>ICAgICAgIDEwNDY0NDk1Mg==</wsse:Nonce>

<wsu:Created>2006-08-28T11:52:27Z</wsu:Created>

</wsse:UsernameToken>

<wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">

<wsu:Created>2006-08-28T11:52:27Z</wsu:Created>

<wsu:Expires>2006-08-28T11:58:27Z</wsu:Expires>

</wsu:Timestamp>

</wsse:Security>

Note: For the above sample we have used the same axis2.xml file for both server and the client. But in the real world this is not possible. In such a situation you can specify a client home as an argument.

./echo [endpoint_url] [path to your client_home]

Semantics of Parameters Specified in axis2.xml

ParameterSemantic
itemsSpecify the tokens to be used for the credential exchange. In the above example we used both UsernameTokens and Timestamps
userThe username of the UsernameToken
passwordTypeThe way password is delivered. This can be either passwordText or the passwordDigest. The former delivers password in plainText whilst the latter delivers the hashed value of the password. Default is passwordText
passwordCallbackClassThe module that provides the password for a particular user
timeToLiveThe validity period of the TimestampToken after issuing. The time is in seconds. In the above example, it's 6 minutes. If not specified, the default is 5 minutes

Writing Your Own Password Callback Module

The Rampart module is not dependent on the way that passwords are stored. For example, you may have passwords in a flat file or in a secured database. What ever the way, Rampart expects a password callback module to retrieve passwords for a given username. The sample coming under "<axis2c_home>rampart/samples/callback" is a simple one containing a few hard-coded passwords. It assigns a function to the function pointer.

rcb->ops->callback_password = get_sample_password;

callback_password is a function pointer to any function which has the following signature.

*
your_function(rampart_callback_t *rcb,
              const axis2_env_t *env, const axis2_char_t *username)

your_function should return the password as axis2_char_t* per the username specified, if any. Inside your function, you may write your code to supply stored passwords.

Then the path to the callback module needs to be specified in axis2.xml under passwordCallbackClass. [The word Class, instead of Module is only for compatibility with java implementation]

Adding Security Parameters Dynamically

Outflow parameters specified in the axis2.xml can be added dynamically in the client level. This can be done as shown in the following sample code.

 un_property = axis2_property_create(env);
AXIS2_PROPERTY_SET_VALUE(un_property, env, "Gajaba");
AXIS2_OPTIONS_SET_PROPERTY(options, env, RAMPART_ACTION_USER, un_property);

The above code will set the username parameter dynamically. All the values specified in the axis2.xml will be overridden by the dynamic settings.