Axis2/C Handler Configurations Using Parameters

Each flow is made up of phases. These phases can be seen in the axis2.xml file. For the in-flow, there are four pre-defined phases. For the out-flow, there is only one pre-defined phase. You can define your own phases as well. Each of these phases is a collection of handlers. A handler is the smallest unit of execution in Axis2/C. When Axis2/C receives a message, it sends it through every phase, and every phase sends the message through every handler that has registered with the phase.

You can extend the functionality of Axis2/C by using handlers. Handlers are not standalone components. A user-defined handler should be a part of a module to register with Axis2/C. So a module acts as a placeholder for handlers. A single module can contain many handlers.

A module has a configuration file called module.xml describing the configuration of its handlers. It specifies the handlers it has and where to insert them. Every handler configuration can have its own parameter list specifying the handler specific configurations.

Here is a module.xml file with handler specific configurations. There are two handlers registered by this module. They are DiscoveryInHandler and DiscoveryDuplicateInHandler. Both handlers are inserted to the user-defined phase called Discovery. The second handler has handler specific parameters. You can see that under the handler element, there are only a few parameter elements. Parameters is the standard way of introducing configurations to the Axis2/C configuration files. A parameter consists of a name and a value.  

<module name="discovery" class="discovery">
    <inflow>
        <handler name="DiscoveryInHandler" class="discovery">
            <order phase="Discovery"/>
        </handler>
        <handler name="DiscoveryDuplicateInHandler" class="discovery">
            <order phase="Discovery" phaseLast="true"/>
            <parameter name="algo">DiscoveryDuplicateAlgoCount</parameter>
            <parameter name="count">1000</parameter>
            <parameter name="time">10</parameter>
        </handler>
    </inflow>
    <operation name="Probe">
        <parameter name="wsamapping">https://schemas.xmlsoap.org/ws/2004/10/discovery/Probe</parameter>
    </operation>
    <operation name="Resolve">
        <parameter name="wsamapping">https://schemas.xmlsoap.org/ws/2004/10/discovery/Resolve</parameter>
    </operation>
</module>

Now let’s see how to access these handler specific parameters from the code. A handler has two standard methods. They are handler Create method and handler Invoke method. Handler create method only has access to the environment. So we cannot access the configuration from the create method.

Handler invoke method has access to all the necessary information. Let’s see how we can access this configuration from the handler invoke method. Here is an implementation of a handler invoke method.

axis2_status_t AXIS2_CALL
discovery_duplicate_in_handler_invoke(
    struct axis2_handler *handler,
    const axutil_env_t *env,
    struct axis2_msg_ctx *msg_ctx)
{
    axis2_handler_desc_t *handler_desc = NULL;
    axutil_param_t *param = NULL;
    axis2_char_t *temp = NULL;
    
    /* get the handler description. This holds the configuration info */
    handler_desc = axis2_handler_get_handler_desc(handler, env);
    /* access the parameter algo */
    param = axis2_handler_desc_get_param(handler_desc, env, “algo”);
    if (param)
    {
        temp = (axis2_char_t *)axutil_param_get_value(param, env);
        /* now we know the value */
    }
    /* access the parameter count */
    param = axis2_handler_desc_get_param(handler_desc, env, “count”);
    if (param)
    {
        temp = (axis2_char_t *)axutil_param_get_value(param, env);
        /* now we know the value */
    }
}

Axis2_handler_desc_t is the structure containing the information about the handler. We can get this from the axis2_handler_t object which is passed to the invoke method. After getting the axis2_handler_desc_t, it is pretty straight forward to access the parameters.

 Author

Supun Kamburugamuva, Software Engineer, WSO2.Inc, supun AT wso2 DOT com