/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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_PHASE_RULE_H
#define AXIS2_PHASE_RULE_H

/**
 * @defgroup axis2_phase_rule phase rule
 * @ingroup axis2_desc
 * phase rule encapsulates data and operations related to phase rules for a 
 * given handler. phase rule lives within a handler. 
 * phase rules of a handler specify the relative location of the 
 * handler within the phase to which it belongs, with respect to other handlers 
 * in the phase or first and last positions of the handler chain of the phase.
 * @{
 */

/**
 * @file axis2_phase_rule.h
 */

#include <axis2_defines.h>
#include <axutil_qname.h>
#include <axutil_param.h>

#ifdef __cplusplus
extern "C"
{
#endif

    /** Type name for struct axis2_phase_rule */
    typedef struct axis2_phase_rule axis2_phase_rule_t;

    /**
     * Gets the name of the handler before which the handler associated with 
     * this rule should be placed.
     * @param phase_rule pointer to phase rule
     * @param env pointer to environment struct
     * @return name of handler before which the handler should be placed
     */
    AXIS2_EXTERN const axis2_char_t *AXIS2_CALL
    axis2_phase_rule_get_before(const axis2_phase_rule_t *phase_rule,
        const axutil_env_t *env);

    /**
     * Sets the name of the handler before which the handler associated with 
     * this rule should be placed.
     * @param phase_rule pointer to phase rule
     * @param env pointer to environment struct
     * @param before name of handler before which the handler should be placed
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL
    axis2_phase_rule_set_before(axis2_phase_rule_t *phase_rule,
        const axutil_env_t *env,
        const axis2_char_t *before);

    /**
     * Gets the name of the handler after which the handler associated with 
     * this rule should be placed.
     * @param phase_rule pointer to phase rule
     * @param env pointer to environment struct
     * @return name of handler after which the handler should be placed
     */
    AXIS2_EXTERN const axis2_char_t *AXIS2_CALL
    axis2_phase_rule_get_after(const axis2_phase_rule_t *phase_rule,
        const axutil_env_t *env);

    /**
     * Sets the name of the handler after which the handler associated with 
     * this rule should be placed.
     * @param phase_rule pointer to phase rule
     * @param env pointer to environment struct
     * @param after name of handler after which the handler should be placed
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL
    axis2_phase_rule_set_after(axis2_phase_rule_t *phase_rule,
        const axutil_env_t *env,
        const axis2_char_t *after);

    /**
     * Gets name.
     * @param phase_rule pointer to phase rule
     * @param env pointer to environment struct
     * @return name string
     */
    AXIS2_EXTERN const axis2_char_t *AXIS2_CALL
    axis2_phase_rule_get_name(const axis2_phase_rule_t *phase_rule,
        const axutil_env_t *env);

    /**
     * Sets name.
     * @param phase_rule pointer to phase rule
     * @param env pointer to environment struct
     * @param name name string
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL
    axis2_phase_rule_set_name(axis2_phase_rule_t *phase_rule,
        const axutil_env_t *env,
        const axis2_char_t *name);

    /**
     * Checks if the handler is the first in phase. 
     * @param phase_rule pointer to phase rule
     * @param env pointer to environment struct
     * @return AXIS2_TRUE if the handler associated with this rule is the 
     * first in phase, else AXIS2_FALSE
     */
    AXIS2_EXTERN axis2_bool_t AXIS2_CALL
    axis2_phase_rule_is_first(const axis2_phase_rule_t *phase_rule,
        const axutil_env_t *env);

    /**
     * Sets handler to be the first in phase.
     * @param phase_rule pointer to phase rule
     * @param env pointer to environment struct
     * @param first AXIS2_TRUE if the handler associated with this rule is the 
     * first in phase, else AXIS2_FALSE
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL
    axis2_phase_rule_set_first(axis2_phase_rule_t *phase_rule,
        const axutil_env_t *env,
        axis2_bool_t first);

    /**
     * Checks if the handler is the last in phase. 
     * @param phase_rule pointer to phase rule
     * @param env pointer to environment struct
     * @return AXIS2_TRUE if the handler associated with this rule is the 
     * last in phase, else AXIS2_FALSE
     */
    AXIS2_EXTERN axis2_bool_t AXIS2_CALL
    axis2_phase_rule_is_last(const axis2_phase_rule_t *phase_rule,
        const axutil_env_t *env);

    /**
     * Sets handler to be the last in phase.
     * @param phase_rule pointer to phase rule
     * @param env pointer to environment struct
     * @param last AXIS2_TRUE if the handler associated with this rule is the 
     * last in phase, else AXIS2_FALSE
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL
    axis2_phase_rule_set_last(axis2_phase_rule_t *phase_rule,
        const axutil_env_t *env,
        axis2_bool_t last);

    /**
     * Frees phase rule.
     * @param phase_rule pointer to phase rule
     * @param env pointer to environment struct
     * @return void
     */
    AXIS2_EXTERN void AXIS2_CALL
    axis2_phase_rule_free(axis2_phase_rule_t *phase_rule,
        const axutil_env_t *env);

    /**
     * Clones phase rule.
     * @param phase_rule pointer to phase rule
     * @param env pointer to environment struct
     * @return pointer to newly cloned phase rule
     */
    AXIS2_EXTERN axis2_phase_rule_t *AXIS2_CALL
    axis2_phase_rule_clone(axis2_phase_rule_t *phase_rule,
        const axutil_env_t *env);

    /**
     * Creates a phase rule struct instance.
     * @param env pointer to environment struct
     * @param phase_name name of the phase rule 
     * @return pointer to newly created phase rule
     */
    AXIS2_EXTERN axis2_phase_rule_t *AXIS2_CALL
    axis2_phase_rule_create(const axutil_env_t *env,
        const axis2_char_t *name);

/** @} */

#ifdef __cplusplus
}
#endif

#endif    /* AXIS2_PHASE_RULE_H */