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.
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.
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).
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.
Writing a new Web Service with Axis2/C involves four steps. Let's take echo service as our example.
Write a echo_skeleton.c file which implements the API given in axis2_svc_skeleton.h header file.
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.
/* Initialize the service */
int AXIS2_CALL
echo_init(axis2_svc_skeleton_t *svc_skeleton,
const axis2_env_t *env)
{
svc_skeleton->func_array = axis2_array_list_create(env, 0);
/* Add the implemented operation names of the service to
* the array list of functions
*/
AXIS2_ARRAY_LIST_ADD(svc_skeleton->func_array, env, "echoString");
/* Any initialization stuff of echo service should go here */
return AXIS2_SUCCESS;
}
/*
* This method invokes the right service method
*/
axiom_node_t* AXIS2_CALL
echo_invoke(axis2_svc_skeleton_t *svc_skeleton,
const axis2_env_t *env,
axiom_node_t *node)
{
/* Invoke the business logic.
* Depending on the function name invoke the correct impl method.
* We have only echo in this sample, hence invoke echo method.
* To see how to deal with multiple impl methods, have a look at the
* math sample.
*/
return axis2_echo_echo(env, node);
}
/* On fault, handle the fault */
axiom_node_t* AXIS2_CALL
echo_on_fault(axis2_svc_skeleton_t *svc_skeli,
const axis2_env_t *env, axiom_node_t *node)
{
/* Here we are just setting a simple error message inside an element
* 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, "Echo service failed ",
text_node);
return error_node;
}
/* Free the resources used */
int AXIS2_CALL
echo_free(axis2_svc_skeleton_t *svc_skeleton,
const axis2_env_t *env)
{
/* Free the function array */
if(svc_skeleton->func_array)
{
AXIS2_ARRAY_LIST_FREE(svc_skeleton->func_array, env);
svc_skeleton->func_array = NULL;
}
/* Free the function array */
if(svc_skeleton->ops)
{
AXIS2_FREE(env->allocator, svc_skeleton->ops);
svc_skeleton->ops = NULL;
}
/* Free the service skeleton */
if(svc_skeleton)
{
AXIS2_FREE(env->allocator, svc_skeleton);
svc_skeleton = NULL;
}
return AXIS2_SUCCESS;
}
Now we can write the create function of the
echo_service_skeleton as follows:
/*Create function */
axis2_svc_skeleton_t *
axis2_echo_create(const axis2_env_t *env)
{
axis2_svc_skeleton_t *svc_skeleton = NULL;
/* Allocate memory for the structs */
svc_skeleton = AXIS2_MALLOC(env->allocator,
sizeof(axis2_svc_skeleton_t));
svc_skeleton->ops = AXIS2_MALLOC(
env->allocator, sizeof(axis2_svc_skeleton_ops_t));
/* Assign function pointers */
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;
return svc_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_EXPORT int
axis2_get_instance(axis2_svc_skeleton_t **inst,
const axis2_env_t *env)
{
*inst = axis2_echo_create(env);
if(!(*inst))
{
return AXIS2_FAILURE;
}
return AXIS2_SUCCESS;
}
AXIS2_EXPORT int
axis2_remove_instance(axis2_svc_skeleton_t *inst,
const axis2_env_t *env)
{
axis2_status_t status = AXIS2_FAILURE;
if (inst)
{
status = AXIS2_SVC_SKELETON_FREE(inst, env);
}
return status;
}
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.
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);
/* Expected request format is :-
* <ns1:echoString xmlns: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("Echo client ERROR: input parameter NULL\n");
return NULL;
}
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("Echo client ERROR: invalid XML in request\n");
return NULL;
}
text_node = AXIOM_NODE_GET_FIRST_CHILD(text_parent_node, env);
if (!text_node) /* actual text to echo */
{
AXIS2_ERROR_SET(env->error, AXIS2_ERROR_SVC_SKEL_INVALID_XML_FORMAT_IN_REQUEST, AXIS2_FAILURE);
printf("Echo client ERROR: invalid XML in request\n");
return NULL;
}
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("Echoing text value %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("Echo client ERROR: invalid XML in request\n");
return NULL;
}
return ret_node;
}
/* Builds the response content */
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);
return echo_om_node;
}
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
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.
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.
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.
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.
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".
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;
}
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;
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;
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.
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.
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 that we 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.
Both these mechanisms work in the API level. Let's name the asynchronous 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 |
| Blocking | No | Simplest and the familiar invocation pattern |
| Non-Blocking | No | Using callbacks or polling |
| Blocking | Yes | This is useful when the service operation is IN-OUT in nature but the transport used is One-Way (e.g. SMTP) |
| Non-Blocking | Yes | This 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.
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:
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.
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.
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.
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.
There are two ways of doing this:
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.
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.
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.
#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 );
}
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] );
}
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);
}
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.
cp $AXIS2C_HOME/deploy/rampart/rampart $AXIS2C_HOME/deploy/modules
<module ref="rampart"/>
<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]
| Parameter | Semantic |
| items | Specify the tokens to be used for the credential exchange. In the above example we used both UsernameTokens and Timestamps |
| user | The username of the UsernameToken |
| passwordType | The 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 |
| passwordCallbackClass | The module that provides the password for a particular user |
| timeToLive | The 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 |
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]
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.