/*
* Copyright 2004,2005 The Apache Software Foundation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*      http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

#ifndef AXIS2_DISP_H
#define AXIS2_DISP_H

/**
 * @defgroup axis2_disp dispatcher
 * @ingroup axis2_engine
 * dispatcher is responsible for finding the service and operation for a given
 * invocation. A Web service request would contain information that help 
 * locate the service and the operation serving the request. This information
 * could be in various formats, and hence the mechanism to find the requested
 * service and operation based on the available information could too vary.
 * Hence there can be various types on dispatches involved in a dispatching 
 * phase of the engine, that implements the API given in this header.
 * @{
 */

/**
 * @file axis2_disp.h
 */

#include <axis2_defines.h>
#include <axis2_qname.h>
#include <axis2_handler.h>
#include <axis2_svc.h>

#ifdef __cplusplus
extern "C"
{
#endif

    /** Type name for struct axis2_disp */
    typedef struct axis2_disp axis2_disp_t;
    /** Type name for struct axis2_disp_ops */
    typedef struct axis2_disp_ops axis2_disp_ops_t;

    /**
     * dispatcher ops struct.
     * Encapsulator struct for operations of axis2_dispatcher.
     */
     struct axis2_disp_ops
    {
        /**
         * Gets the base struct which is of type handler.
         * @param disp pointer to dispatcher
         * @param env pointer to environment struct
         * @return pointer to base handler struct. Returns a reference, not a 
         * cloned copy
         */
        axis2_handler_t *(AXIS2_CALL *
                get_base)(
                    const axis2_disp_t *disp,
                    const axis2_env_t *env);

        /**
         * Gets the qname of the dispatcher.
         * @param disp pointer to dispatcher
         * @param env pointer to environment struct
         * @return pointer to qname. Returns a reference, not a 
         * cloned copy
         */
        axis2_qname_t *(AXIS2_CALL *
                get_qname)(
                    const axis2_disp_t *disp,
                    const axis2_env_t *env);

        /**
         * Sets the qname of the dispatcher.
         * @param disp pointer to dispatcher
         * @param env pointer to environment struct
         * @param qname pointer to qname, dispatcher assumes ownership of the 
         * qname struct
         * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
         */
        axis2_status_t (AXIS2_CALL *
                set_qname)(
                    axis2_disp_t *disp,
                    const axis2_env_t *env, 
                    axis2_qname_t *qname);

        /**
         * Frees dispatcher struct.
         * @param disp pointer to dispatcher
         * @param env pointer to environment struct
         * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE                    
         */
        axis2_status_t (AXIS2_CALL *
                free)(
                    axis2_disp_t *disp,
                    const axis2_env_t *env);
        /**
         * Finds the service that corresponds to the given message context. 
         * The various dispatcher implementations that inherit from dispatcher 
         * struct should implement this find_svc method and assign the 
         * respective function pointers to point to this method. 
         * @param msg_ctx pointer to message context 
         * @param env pointer to environment struct
         * @return pointer to service that should be servicing the request
         */
        axis2_svc_t *(AXIS2_CALL *
                find_svc)(
                    axis2_msg_ctx_t *msg_ctx,
                    const axis2_env_t *env);
        /**
         * Finds the operation that corresponds to the given message context
         * and service. The various dispatcher implementations that inherit from 
         * dispatcher struct should implement this find_op method and assign the 
         * respective function pointers to point to this method. 
         * Finds the op
         * @param msg_ctx pointer to message context
         * @param env pointer to environment struct
         * @param svc pointer to service, usually this is found through find_svc
         * method
         * @return pointer to operation that the request is targeted to
         */
        axis2_op_t *(AXIS2_CALL *
                find_op)(
                    axis2_msg_ctx_t *msg_ctx,
                    const axis2_env_t *env,
                    const axis2_svc_t *svc);

    };

    /**
     * dispatcher struct.
     */
    struct axis2_disp
    {
        /** operations of dispatcher struct */
        axis2_disp_ops_t *ops;
    };


    /**
     * Creates a dispatcher struct instance.
     * @param env pointer to environment struct
     * @param qname pointer to QName. QName is cloned by create method.
     * @return pointer to newly created dispatcher
     */
    AXIS2_EXTERN axis2_disp_t *AXIS2_CALL 
    axis2_disp_create(
        const axis2_env_t *env, 
        const axis2_qname_t *qname);

    /**
     * Invokes the dispatcher.
     * @param handler pointer to handler that is the base of the dispatcher 
     * to be invoked
     * @param env pointer to environment struct
     * @param msg_ctx pointer to message context
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    axis2_status_t AXIS2_CALL 
    axis2_disp_invoke(
        axis2_handler_t *handler,
        const axis2_env_t *env,
        axis2_msg_ctx_t *msg_ctx);

    /**
     * Creates a WS-Addressing based dispatcher.
     * @param env pointer to environment struct
     * @return pointer to the newly created dispatcher with find_svc and find_op
     * methods implemented based on WS-Addressing
     */
    axis2_disp_t *AXIS2_CALL 
    axis2_addr_disp_create(
        const axis2_env_t *env);

    /**
     * Creates a request URI based dispatcher.
     * @param env pointer to environment struct
     * @return pointer to the newly created dispatcher with find_svc and find_op
     * methods implemented based on request URI processing.
     */
    axis2_disp_t *AXIS2_CALL 
    axis2_req_uri_disp_create(
        const axis2_env_t *env);

    /**
     * Creates a SOAP body based dispatcher.
     * @param env pointer to environment struct
     * @return pointer to the newly created dispatcher with find_svc and find_op
     * methods implemented based on SOAP body processing.
     */
    axis2_disp_t *AXIS2_CALL 
    axiom_soap_body_disp_create(
        const axis2_env_t *env);

    /**
     * Creates a SOAP action based dispatcher.
     * @param env pointer to environment struct
     * @return pointer to the newly created dispatcher with find_svc and find_op
     * methods implemented based on SOAP action processing
     */
    axis2_disp_t *AXIS2_CALL 
    axiom_soap_action_disp_create(
        const axis2_env_t *env);


/** Gets the base handler. 
    @sa axis2_disp_ops#get_base */
#define AXIS2_DISP_GET_BASE(disp, env) \
        ((disp)->ops->get_base(disp, env))

/** Gets QName.
    @sa axis2_disp_ops#get_qname */
#define AXIS2_DISP_GET_QNAME(disp, env) \
        ((disp)->ops->get_qname(disp, env))

/** Sets QName.
    @sa axis2_disp_ops#set_qname */
#define AXIS2_DISP_SET_QNAME(disp, env, name) \
        ((disp)->ops->set_qname(disp, env, name))

/** Frees dispatcher.
    @sa axis2_disp_ops#free */
#define AXIS2_DISP_FREE(disp, env) \
        ((disp)->ops->free(disp, env))

/** Finds service that should service the request.
    @sa axis2_disp_ops#find_svc */
#define AXIS2_DISP_FIND_SVC(msg_ctx, env) \
        ((msg_ctx)->ops->find_svc(msg_ctx, env))

/** Finds the operation in the give service that the request is targeted to.
    @sa axis2_disp_ops#find_op */
#define AXIS2_DISP_FIND_OP(msg_ctx, env, svc) \
        ((msg_ctx)->ops->find_op(msg_ctx, env, svc))

/** @} */

#ifdef __cplusplus
}
#endif

#endif    /* AXIS2_DISP_H */