Axis2 Execution Framework, Page 2
The concept of phase is completely new terminology to the Web service stack; it was introduced for targeting the dynamic ordering of handlers and to support phase rules. A phase can be defined in various ways:
- It can be considered a logical collection of handlers.
- It can be considered a specific time interval in the message execution.
- It can be considered a bucket into which one can put his handler.
As described later, a flow can be considered as a collection of phases. Even though it has been mentioned earlier that the Axis engine will call the invoke method of a handler, it is not totally correct. In fact, the engine really calls the invoke method of each phase in a given flow; then, phase will sequentially invoke all the handlers in it. Although one can extend the AbstractHandler handler and create a new handler but phase, so the phase implementation logic cannot be changed. Therefore, each and every phase in Axis works in a simpler way and the difference among those is handlers in side phases.
A phase is designed to support phase rules. As described later, there are rules such as phaseFirst and phaseLast, so in a handler there are reserved slots to hold both phase first and phase last handlers. The rest of the handlers will be kept in a different list. A phase can, therefore, be graphically represented as follows:
Phase invocation mainly consist of three steps:
- If the phase first handler is not null, it will be invoked first.
- Then rest of the handlers (except phase last handler) will be invoked.
- Finally, if the phase last handler is not null, it will be invoked.
Note: Handlers inside a phase can be ordered by using phase rules.
Type of Phases
In Axis2 there are two levels of phases:
- System pre-defined phase
- User-defined phase
System pre-defined phase
System pre-defined phases are the phases that are invoked irrespective of the service, and no one can change the order of these phases although they are defined in the Axis configuration (called server.xml or client.xml). If someone changes the order of these phases, the deployment will not be allowed to start Axis. The whole purpose of defining them in a configuration file is to tell the service or module developer the capability of using them in their development. The phases in their order corresponding to inflow can be represented as follows:
All these phases have some semantic meaning as well. The TrasnportIn phase consists of a handler that performs depending on the type of transport. As the name implies, the PreDispatch phase is the phase that always invokes (its handlers) before the dispatch has taken place. Handlers like WS-addressing will always be in this phase. The Dispatch phase is the phase that does the dispatching, simply by finding the corresponding service and the operation for the incoming message. Therefore, the Dispatch phase consists of dispatching handlers. PostDispatch is the phase that is invoked after Dispatch is been invoked.
Note: In Axis2, there are mainly two dispatch handlers, called RequestURIBasedDispatcher and AddressingBasedDispatcher.
There might be instances when service or module authors need to define a new phase; those phases are called user-defined phases. If someone wants to add a handler that should be invoked after the dispatching has taken place, in that case it is required to define a new phase. Another important thing is that phase rule has some limitations, as described later in the article. A combination of both phase rules and phase orders leads to build a more flexible and configurable handler chain.
Because there are four types of flows, for each flow phase orders are defined in the system configuration file; defining a new phase can be done by just adding a new phase element into the configuration file. Those phases can be referred by any handler. The default configuration file provided with Axis2 is as follows;
<phaseOrder type="inflow"> <!-- System pre defined phases --> <phase name="TransportIn"/> <phase name="PreDispatch"/> <phase name="Dispatch"/> <phase name="PostDispatch"/> <!-- System pre defined phases --> <!-- After Postdispatch phase module author or service author can add any phase he wants --> <phase name="userphase1"/> </phaseOrder> <phaseOrder type="outflow"> <!-- user can add his own phases to this area --> <phase name="userphase1"/> </phaseOrder> <phaseOrder type="INfaultflow"> <!-- user can add his own phases to this area --> <phase name="userphase1"/> </phaseOrder> <phaseOrder type="Outfaultflow"> <!-- user can add his own phases to this area --> <phase name="userphase1"/> </phaseOrder>
Note: Adding a new phase cannot be done at the run time. If you add a new phase element to the system configuration file, those changes won't be applied to the running system. For those changes to take place, it is necessary to restart the system.