Handler and Phase in Apache Axis2

Cart | Your Account | Trade | Sitemap

Visit Packt's Article Network, for all the latest quality, relevant and free content.
See More

The fundamental goal of any given Simple Object Access Protocol (SOAP) processing framework is to deliver an incoming SOAP message to the target application. However, if we consider today's Web Services or any other application, just delivering the message to the application is not sufficient. We need to provide quality of service, such as reliability and security. To provide these features, most SOAP processing frameworks have the concept of pipes, where, any incoming or outgoing message goes through the pipe, and the pipe gets divided into smaller pieces. Each piece is known as an interceptor. "Handler" is the Apache terminology for "message interceptor". In this article by Deepal Jayasinghe, we will see how to write a simple handler, what is a Phase, different types of Phase, and invalid Phase rules.

Handler

In any messaging system, the interceptor has its factual meaning in the context of messaging, where it intercepts the flow of messaging and does whatever task it is assigned to do. In fact, an interceptor is the smallest execution unit in a messaging system, and an Axis2 handler is also an interceptor.

Handlers in Axis are stateless, that is, they do not keep their pass execution states in the memory. A handler can be considered as a logic invoker with the input for the logic evaluation taken from the MessageContext. A Handler has both read and write access permissions to MessageContext (MC) or to an incoming SOAP message.

We can consider MessageContext as a property bag that keeps incoming or outgoing messages (maybe both) and other required parameters. It may also include properties to carry the message through the execution chain. On the other hand, we can access the whole system including the system runtime, global parameters, and property service operations via the MC.

In most cases, a handler only touches the header block part of the SOAP message, which will either read a header (or headers), add a header(s), or remove a header(s). (This does not mean that the handler cannot touch the SOAP body, nor does it mean that it is not going to touch the SOAP body.) During reading, if a header is targeted to a handler and is not executing properly (the message might be faulty), then it should throw an exception, and the next driver in the chain (in Axis2, it is the Axis engine) would take the necessary action. A typical SOAP message with few headers is shown in the figure given below:

Any handler in Axis2 has the capability to pause the message execution, which means that the handler can terminate the message flow if it cannot continue. Reliable messaging (RM) is a good example or use case for that scenario, when it needs to pause the flow depending on some of the preconditions and the postconditions as well and it works on a message sequence. If a service invocation consists of more than one message, and if the second message comes before the first one, then the RM handler will stop (or rather pause) the execution of the message invocation corresponding to the second message until it gets the first one. And when it gets, the first message is invoked, and thereafter it invokes or resumes the second message.

Writing a Simple Handler

Just learning the concepts will not help us in remembering what we have discussed. For that, we need to write a handler and see how it works. Writing a handler in Axis2 is very simple. If you want to write a handler, you either have to extend the AbstractHandler class or implement the Handler interface.

A simple handler that extends the AbstractHandler class will appear as follows:

public class SimpleHandler extends AbstractHandler
{
	public SimpleHandler()
	{
	}
public InvocationResponse invoke(MessageContext msgContext)
					throws AxisFault {
	//Write the processing logic here
	// DO something
	return InvocationResponse.CONTINUE;
	}
}

Note the return value of the invoke method. We can have the following three values as the return value of the invoke method:

Continue: The handler thinks that the message is ready to go forward.
Suspend: The handler thinks that the message cannot be sent forward since some conditions are not satisfied; so the execution is suspended.
Abort: The handler thinks that there is something wrong with the message, and cannot therefore allow the message to go forward.

In most cases, handlers will return InvocationResponse.CONTINUE as the return value.

When a message is received by the Axis engine, it calls the invoke method of each of the handlers by passing the argument to the corresponding MessageContext. As a result of this, we can implement all the processing logic inside that method. A handler author has full access to the SOAP message, and also has the required properties to process the message via the MessageContext. In addition, if the handler is not satisfied with the invocation of some precondition, the invocation can be paused as we have discussed earlier (Suspend).

If some handler suspends the execution, then it is its responsibility to store the message context, and to forward the message when the conditions are satisfied. For example, the RM handler performs in a similar manner.

Phase

The concept of phase is introduced by Axis2, mainly to support the dynamic ordering of handlers. A phase can be defined in a number of 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 to put a handler.
One can consider a phase as a handler too.

A flow or an execution chain can be considered as a collection of phases. Even though it was mentioned earlier that an Axis engine calls the invoke method of a handler, that is not totally correct. In fact, what the engine really does is call the invoke method of each phase in a given flow, and then the phase will sequentially invoke all the handlers in it (refer to the following figure). As we know, we can extend AbstractHandler and create a new handler; in the same way one can extend the Phase class and then create a new phase. But remember that we need not always extend the Phase class to create a new phase. We can do it by just adding an entry into axis2.xml (All the configuration that requires starting axis2 is obtained from axis2.xml). A phase has two important methods—precondition checking and postcondition checking. Therefore, if we are writing a custom phase, we need to consider the methods that have been mentioned. However, writing a phase is not a common case; you need to know how to write a handler.

This article has been extracted from: Quickstart Apache Axis2

A practical guide to creating quality web services

Complete practical guide to Apache Axis 2
Using Apache Axis2 to create secure, reliable web services quickly
Write Axis2 modules to enhance web services’ security, reliability, robustness and transaction support

For more information, please visit:
http://www.PacktPub.com/creating-web-services-with-apache-axis-2/book

A phase is designed to support different phase rules. These rules include phaseFirst as well as phaseLast. In a phase, there are reserved slots to hold both phaseFirst handlers and phaseLast handlers. The rest of the handlers are in a different list. A phase can, therefore, be graphically represented as follows:

Once the engine calls the invoke method of the phase, it has the following execution sequence:

First, check whether the precondition is satisfied.
Then check whether the phaseFirst handler is there. If it is present, then it will be invoked.
Next, the rest of the handlers will be invoked, except for the phaseLast handler.
If the phaseLast handler is there, then it will be invoked.
Finally, it will check whether the postcondition is satisfied so as to forward the message.

Types of Phases

There are two types of phases defined in axis2.xml. There are no differences between the ways the logic is implemented. However, the location of the phase in the execution chain differs. The two types of phases are:

Global phase
Operation phase

Global Phase

A global phase is a phase that is invoked irrespective of the service. In simple terms, whenever a message comes into the system, it will go through the global phase. The whole idea of defining a global phase and an operation phase in axis2.xml is to provide an easy path for module authors.

If we consider the default axis2.xml file which is present in our download directory, we will observe that it has a set of global as well as operation phases. The splitting point of the global phase and operation phase is the Dispatch phase. All the phases up to and including Dispatch phase are considered global phases, whereas the rest are considered operation phases.

The phase section of the default axis2.xml file is given below. It is a bit complicated. But all you need to do is focus on the keyword 'phase'.

<phaseOrder type="InFlow">
   <!-- System predefined phases -->
    <phase name="Transport">
      <handler name="RequestURIBasedDispatcher"
               class="org.apache.axis2.engine.RequestURIBasedDispatcher">
          <order phase="Transport"/>
      </handler>
      <handler name="SOAPActionBasedDispatcher"
               class="org.apache.axis2.engine.SOAPActionBasedDispatcher">
          <order phase="Transport"/>
      </handler>
</phase>
<phase name="Security"/>
<phase name="PreDispatch"/>
<phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase">
      <handler name="RequestURIBasedDispatcher"
               class="org.apache.axis2.engine.RequestURIBasedDispatcher"/>
      <handler name="SOAPActionBasedDispatcher"
               class="org.apache.axis2.engine.SOAPActionBasedDispatcher"/>
      <handler name="AddressingBasedDispatcher"
               class="org.apache.axis2.engine.AddressingBasedDispatcher"/>
      <handler name="RequestURIOperationDispatcher"
               class="org.apache.axis2.engine.RequestURIOperationDispatcher"/>
      <handler name="SOAPMessageBodyBasedDispatcher"
               class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher"/>
      <handler name="HTTPLocationBasedDispatcher"
               class="org.apache.axis2.engine.HTTPLocationBasedDispatcher"/>
</phase>
    <!-- System predefined phases -->
    <!-- After Postdispatch phase module author or service
         author can add any phase he or she wants -->
   <phase name="OperationInPhase"/>
   <phase name="soapmonitorPhase"/>
</phaseOrder>

In the previous code, 'Transport', 'Security', 'PreDispatch', and 'Dispatch' are the global phases while 'OperationInPhase' and 'soapmonitorPhase' are the operation-specific phases.

All the global phases have semantic meanings from their names as well. Transport phase consists of a handler, which performs the tasks that are dependent on the type of transport. In the Security phase, WS-Security implementation will include their handlers. As the name implies, PreDispatch phase is the phase consisting of a set of handlers that performs the work needed for dispatching. Handlers such as WS-Addressing, are always included in this phase. Dispatch phase is the phase that does the dispatching by simply finding the corresponding service as well as the operation for the incoming message. As a result, it is evident that Dispatch phase consists of dispatching handlers.

Operation Phase

For instance, suppose that we have a handler, that we do not have to run for every message coming to the system, rather we need to run that for a selected set of operations. This is where the operation phase comes into the picture.

Phase Rules

The main idea of the phase rule is to correctly locate a handler, relative to the one that is inside a phase, either at deployment time or at run time. In Axis1, we did not have the concept of phases or phase rules. What it had was a global configuration file wherein we defined our handlers. But it had a number of limitations such as loosing the dynamic nature of the handler chain. One aspect of phase rule is addressing the issues of dynamic execution chain-building capability.

Characterizing a phase rule can be based on one or more of the following properties:

Phase name: Name of the phase where the handler must be placed.
Phase first (phaseFirst): First handler of the phase.
Phase Last (phaseLast): Last handler of the phase.
Before (before): should be positioned before a given handler.
After (after): should be positioned after a given handler.
Before and after: should be placed between two given handlers.

Phase Name

"Phase" is a compulsory attribute for any phase rule, which specifies the phase in which the handler must fit. For validity, the name of the phase should be either in the global phase, or in the operational phase, and should be defined in axis2.xml.

phaseFirst

If we want a handler to be invoked as the first handler in a given phase, irrespective of the other handlers in the phase, then we need to set the phaseFirst attribute to "true". A handler, which has phaseFirst as the only phase rule, is shown below:

    <handler name="simple_Handler " class="org.apache.axis.handlers.SimpleHandler ">
        <order phase="userphase1" phaseFirst="true"/>
    </handler>

phaseLast

If we want a handler to run last in a given phase irrespective of the other handlers, then the phaseLast attribute should be set to "true". Refer to the following code:

    <handler name="simple_Handler" class="org.apache.axis.handlers.SimpleHandler ">
       <order phase="userphase1" phaseLast="true"/>
    </handler>

If there is a phase rule with both phaseFirst and phaseLast attributes set to true, then that phase cannot have any other handlers. As a result, the phase has only one handler.

before

There may be situations where a handler should always run before some other handler, irrespective of its exact location. A real-time use case for this can be a security handler, which needs to run before the RM handler. Refer to the following code to understand the logic. Here, the value of the 'before' attribute is the name of the handler before which this handler must run.

    <handler name="simple_Handler2 " class="org.apache.axis.handlers.SimpleHandler2 ">
       <order phase="userphase1" before=" simple_Handler "/>
    </handler>

Axis2 phase rule processing logic is implemented in such a way that if the handler referred to by the attribute 'before' is not available in the phase but only at the time the rule is being processed, then it just ignores the rule and the handler is placed immediately after the phaseFirst handler. (If it is available, it places the handler somewhere in the phase.)

after

As before, if a handler always runs after some other handler, then the phase rule can be written using the attribute 'after', and the value of 'after' attribute is the name of the handler after which this handler must run.

    <handler name="simple_Handler3 " class="org.apache.axis.handlers.SimpleHandler3 ">
       <order phase="userphase1" after=" simple_Handler2"/>
    </handler>

This article has been extracted from: Quickstart Apache Axis2

A practical guide to creating quality web services

Complete practical guide to Apache Axis 2
Using Apache Axis2 to create secure, reliable web services quickly
Write Axis2 modules to enhance web services’ security, reliability, robustness and transaction support

For more information, please visit:
http://www.PacktPub.com/creating-web-services-with-apache-axis-2/book

Invalid Phase Rules

The validity of a phase rule is an important factor in Axis2. There can be many ways to get the same handler order by using different kinds of phase rules. But when writing a phase rule, it is required to check whether the rule is a valid rule. There are many ways in which a phase rule can become an invalid rule. Some of them are:

If there is a phase rule for a handler with either the phaseFirst or the phaseLast attribute set to true, then it can have neither 'before' nor 'after' appearing in the phase rule. If they do, then the rule is invalid.
If there is a phase rule for a handler with both phaseFirst and phaseLast set to true, then that particular phase cannot have more than one handler. If someone tries to write a phase rule that inserts a handler into the same phase, then the second phase rule is invalid.
There cannot be two handlers in one phase with their phaseFirst attribute set to true.
There cannot be two handlers in one phase with their phaseLast attribute set to true.
If the rule is such that the attribute 'before' refers to a phaseFirst handler, then the rule is invalid.
If the rule is such that the attribute 'after' refers to a phaseLast handler, then the rule is invalid.

<handler name="simple_HandlerError " class="org.apache.axis.
                                  handlers.SimpleHandlerError ">
    <order phase="userphase1" before=" simple_Handler"
           phaseFirst="true"/>
</handler>

Phase rules are defined on a per-handler basis, and any handler in the system must fit into a phase in the system.

Flow

Flow is simply a collection of phases. The order of phases inside a flow is defined in axis2.xml. Since phase is a logical collection (which is in fact a virtual concept), a flow can be assumed to be the execution chain (collection of handlers).

The following are the four types of flows in Axis2:

InFlow
OutFlow
InFaultFlow
OutFaultFlow

InFlow: When a message comes in (request message), it has to go via the InFlow. This in turn invokes all the handlers in the InFlow. InFlow is somewhat different from OutFlow. The Inflow consist of two parts. The first part starts from the Transport Receiver, and ends at Dispatcher (up to and including Dispatch phase). The second part will be there only if the corresponding service and operations are found at the end of Dispatch phase. Therefore, the second part of the flow is the InFlow of the corresponding operation for the incoming message. So the InFlow consists of global as well as operation parts.

InFaultFlow: This flow is invoked if the incoming request is faulty (request with HTTP status code 500).

OutFlow: When a message is moving out from the server (say a response), the OutFlow is invoked. As a result, the outgoing message is always bound to an operation, and there is nothing similar to dispatching in the out path.

OutFaultFlow: If something goes wrong in the out path, then the OutFaultFlow is invoked.

Summary

In this article, we gave an introduction to handlers and saw how to implement a simple handler. This was followed by the description of phase and its types. Axis2 is good enough to provide flexible Web Service interaction and this flexibility is achieved using the concept of phases and phase rules.

About the Author

Deepal Jayasinghe is a Technical Lead at WSO2 Inc., an open-source software development company that creates middleware platforms for Web Services. He joined WSO2, Inc. in August, 2005. He has more than 3 years of experience with SOA and Web Services in addition to being a contributing member of the Apache Axis2 project since its inception. He is a key architect and a developer of Apache Axis2 Web Service project and has led a number of releases. In addition to Axis2, he has made major contributions to Apache Synapse, Apache Axiom, and Apache XMLSchema projects. Deepal has written more than 30 technical magazine articles, research papers and has delivered speeches in various SOA and Web Services conferences. He is a Apache Web Services PMC member, an Apache committer, and an Apache Member. His expertise lay mainly in distributed computing, fault-tolerant systems and Web Services related technologies. He has B.Sc. in Engineering from the University of Moratuwa, Sri Lanka and and will be starting graduate studies at Georgia Institute of Technology in fall, 2008.

Quickstart Apache Axis2