# phases
[engine]

## Files
file | axis2_phase.h
## Defines
#define | AXIS2_PHASE_BOTH_BEFORE_AFTER 0
#define | AXIS2_PHASE_BEFORE 1
#define | AXIS2_PHASE_AFTER 2
#define | AXIS2_PHASE_ANYWHERE 3
## Typedefs
typedef struct axis2_phase | axis2_phase_t
## Functions
AXIS2_EXTERN axis2_status_t | axis2_phase_add_handler_at (axis2_phase_t *phase, const axutil_env_t *env, const int index, axis2_handler_t *handler)
AXIS2_EXTERN axis2_status_t | axis2_phase_add_handler (axis2_phase_t *phase, const axutil_env_t *env, axis2_handler_t *handler)
AXIS2_EXTERN axis2_status_t | axis2_phase_remove_handler (axis2_phase_t *phase, const axutil_env_t *env, axis2_handler_t *handler)
AXIS2_EXTERN axis2_status_t | axis2_phase_invoke (axis2_phase_t *phase, const axutil_env_t *env, struct axis2_msg_ctx *msg_ctx)
AXIS2_EXTERN const axis2_char_t * | axis2_phase_get_name (const axis2_phase_t *phase, const axutil_env_t *env)
AXIS2_EXTERN int | axis2_phase_get_handler_count (const axis2_phase_t *phase, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_phase_set_first_handler (axis2_phase_t *phase, const axutil_env_t *env, axis2_handler_t *handler)
AXIS2_EXTERN axis2_status_t | axis2_phase_set_last_handler (axis2_phase_t *phase, const axutil_env_t *env, axis2_handler_t *handler)
AXIS2_EXTERN axis2_status_t | axis2_phase_add_handler_desc (axis2_phase_t *phase, const axutil_env_t *env, axis2_handler_desc_t *handler_desc)
AXIS2_EXTERN axis2_status_t | axis2_phase_remove_handler_desc (axis2_phase_t *phase, const axutil_env_t *env, axis2_handler_desc_t *handler_desc)
AXIS2_EXTERN axis2_status_t | axis2_phase_insert_before (axis2_phase_t *phase, const axutil_env_t *env, axis2_handler_t *handler)
AXIS2_EXTERN axis2_status_t | axis2_phase_insert_after (axis2_phase_t *phase, const axutil_env_t *env, axis2_handler_t *handler)
AXIS2_EXTERN axis2_status_t | axis2_phase_insert_before_and_after (axis2_phase_t *phase, const axutil_env_t *env, axis2_handler_t *handler)
AXIS2_EXTERN axis2_status_t | axis2_phase_insert_handler_desc (axis2_phase_t *phase, const axutil_env_t *env, axis2_handler_desc_t *handler_desc)
AXIS2_EXTERN axutil_array_list_t * | axis2_phase_get_all_handlers (const axis2_phase_t *phase, const axutil_env_t *env)
AXIS2_EXTERN axis2_status_t | axis2_phase_invoke_start_from_handler (axis2_phase_t *phase, const axutil_env_t *env, const int paused_handler_index, struct axis2_msg_ctx *msg_ctx)
AXIS2_EXTERN void | axis2_phase_free (axis2_phase_t *phase, const axutil_env_t *env)
AXIS2_EXTERN axis2_phase_t * | axis2_phase_create (const axutil_env_t *env, const axis2_char_t *phase_name)
AXIS2_EXTERN axis2_status_t | axis2_phase_increment_ref (axis2_phase_t *phase, const axutil_env_t *env)

## Detailed Description

phase is a logical unit of execution in the Axis2 engine's execution flows. A phase encapsulates one or more handlers in a given sequence to be invoked. The sequencing of handlers within a phase are often defined by module configuration which specifies where in the phase's handler chain a given handler should be placed. Calling invoke on phase triggers invoke on the handlers stored within the phase in the sequence they are ordered.

## Define Documentation

#define AXIS2_PHASE_AFTER 2

A given handler's location within the list of handlers is after another given handler.

#define AXIS2_PHASE_ANYWHERE 3

A given handler's location within the list of handlers could be anywhere in the list.

#define AXIS2_PHASE_BEFORE 1

A given handler's location within the list of handlers is before another given handler.

#define AXIS2_PHASE_BOTH_BEFORE_AFTER 0

A given handler's location within the list of handlers is before a particular handler and after another particular handler.

## Typedef Documentation

typedef struct axis2_phase axis2_phase_t

Type name for axis2_phase

## Function Documentation

AXIS2_EXTERN axis2_status_t axis2_phase_add_handler | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env,
|  | axis2_handler_t * | handler |
| ) |  |  |

Adds the given handler to the end of the handler list.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct
  | handler | pointer to handler, phase does not assume the ownership of the handler

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_phase_add_handler_at | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env,
|  | const int | index,
|  | axis2_handler_t * | handler |
| ) |  |  |

Adds given handler to the specified position in the handler array list.

Parameters:

  | phase | pointer to phase struct
  | env | pointer to environment struct
  | index | index
  | handler | pointer to handler, phase does not assume the ownership of the handler

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_phase_add_handler_desc | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env,
|  | axis2_handler_desc_t * | handler_desc |
| ) |  |  |

Adds handler within the handler description to the list of handlers in the phase.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct
  | handler_desc | pointer to handler description, phase does not assume the ownership of neither the handler description not the handler within the handler description

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_phase_t* axis2_phase_create | ( | const axutil_env_t * | env,
|  | const axis2_char_t * | phase_name |
| ) |  |  |

creates phase struct instance.

Parameters:

  | env | pointer to environment struct
  | phase_name | name of the phase to be created

Returns:
  pointer to newly created phase

AXIS2_EXTERN void axis2_phase_free | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env |
| ) |  |  |

Frees phase struct.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct

Returns:
  void

AXIS2_EXTERN axutil_array_list_t* axis2_phase_get_all_handlers | ( | const axis2_phase_t * | phase,
|  | const axutil_env_t * | env |
| ) |  |  |

Gets all the handlers in the phase.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct

Returns:
  pointer to array list containing the list of handlers

AXIS2_EXTERN int axis2_phase_get_handler_count | ( | const axis2_phase_t * | phase,
|  | const axutil_env_t * | env |
| ) |  |  |

Gets handler count in the handler list.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct

Returns:
  the number of handlers in the handler list

AXIS2_EXTERN const axis2_char_t* axis2_phase_get_name | ( | const axis2_phase_t * | phase,
|  | const axutil_env_t * | env |
| ) |  |  |

Gets phase name.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct

Returns:
  returns name of phase

AXIS2_EXTERN axis2_status_t axis2_phase_insert_after | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env,
|  | axis2_handler_t * | handler |
| ) |  |  |

Inserts the handler into handler list of the phase based on the phase rules associated with the handler. This function takes into account the after rules of the handler. After rules specify the location of a current handler in the handler list, after which the given handler is to be placed.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct
  | handler | pointer to handler, phase does not assume the ownership of the handler

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_phase_insert_before | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env,
|  | axis2_handler_t * | handler |
| ) |  |  |

Inserts the handler into handler list of the phase based on the phase rules associated with the handler. This function takes into account the before rules of the handler. Before rules specify the location of a current handler in the handler list, before which the given handler is to be placed.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct
  | handler | pointer to handler, phase does not assume the ownership of the handler

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_phase_insert_before_and_after | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env,
|  | axis2_handler_t * | handler |
| ) |  |  |

Inserts the handler into handler list of the phase based on both before and after phase rules associated with the handler. This method assume that both the before and after cannot be the same handler . That condition is not checked by this function. It should be checked before calling this function

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct
  | handler | pointer to handler, phase does not assume the ownership of the handler

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_phase_insert_handler_desc | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env,
|  | axis2_handler_desc_t * | handler_desc |
| ) |  |  |

Inserts the handler to the correct location in the handler list of the phase. Location is evaluated based on the phase rules.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct
  | handler_desc | pointer to handler description, phase does not assume the ownership of neither the handler description not the handler within the handler description

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_phase_invoke | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env,
|  | struct axis2_msg_ctx * | msg_ctx |
| ) |  |  |

Invokes the phase. This function will in turn call invoke method of each handler in the handler list, in sequence, starting from the beginning of the list to the end of the list.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct
  | msg_ctx | pointer to message context

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_phase_invoke_start_from_handler | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env,
|  | const int | paused_handler_index,
|  | struct axis2_msg_ctx * | msg_ctx |
| ) |  |  |

Invokes handlers starting from the given handler index.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct
  | paused_handler_index | index of the handler to start the invocation from
  | msg_ctx | pointer to message context

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_phase_remove_handler | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env,
|  | axis2_handler_t * | handler |
| ) |  |  |

Remove the given handler from the handler list.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct
  | handler | pointer to handler, phase does not assume the ownership of the handler

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_phase_remove_handler_desc | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env,
|  | axis2_handler_desc_t * | handler_desc |
| ) |  |  |

Remove handler within the handler description from the list of handlers in the phase.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct
  | handler_desc | pointer to handler description, phase does not assume the ownership of neither the handler description not the handler within the handler description

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_phase_set_first_handler | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env,
|  | axis2_handler_t * | handler |
| ) |  |  |

Sets the first handler in the handler list.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct
  | handler | pointer to handler, phase does not assume the ownership of the handler

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE

AXIS2_EXTERN axis2_status_t axis2_phase_set_last_handler | ( | axis2_phase_t * | phase,
|  | const axutil_env_t * | env,
|  | axis2_handler_t * | handler |
| ) |  |  |

Sets the last handler in the handler list.

Parameters:

  | phase | pointer to phase
  | env | pointer to environment struct
  | handler | pointer to handler, phase does not assume the ownership of the handler

Returns:
  AXIS2_SUCCESS on success, else AXIS2_FAILURE