Handler and Phase in Apache Axis2

darkpoon

　　


转自 http://www.packtpub.com/article/handler-and-phase-in-apache-axis


 

Handler
and Phase in Apache Axis2

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:

http://www.packtpub.com/files/images/aa2-article-1.bmp

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 intoaxis2.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

http://images.packtpub.com/images/114x140/1847192866.png

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

http://www.packtpub.com/files/images/aa2-article-2.png

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:

http://www.packtpub.com/files/images/aa2-article-3.bmp

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

http://images.packtpub.com/images/114x140/1847192866.png

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.

http://www.packtpub.com/files/images/aa2-article-4.bmp

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.