Abstract
Interceptors are organized into phases. The phase in which an interceptor runs determines what portions of the message data it can access. An interceptor can determine its location in relationship to the other interceptors in the same phase. An interceptors phase and its location within the phase are specified in the class' constructor.
When developing a custom interceptor the first thing to consider is where in the message processing chain the interceptor belongs. The developer can control an interceptor's position in the message processing chain in two ways:
Specifying the interceptor's phase
Specifying constraints on the location of the interceptor within the phase
Typically the code specifying an interceptor's location is placed in the interceptor's constructor. This makes it possible for the runtime to instantiate the interceptor and put in the proper place without any explicit action in the application level code.
Interceptors are organized into phases. An interceptor's phase determines when in the message processing sequence it is called. Developers specify an interceptor's phase its constructor. Phases are specified using constant values provided by the framework.
Phases are a logical collection of interceptors. As shown in Figure 3.1, “Phase”, the interceptors within a phase are called sequentially.
The phases are linked together in an ordered list to form an interceptor chain. The phases provide define logical steps in the
message processing procedure. For example, a group interceptors in the RECEIVE
phase of an inbound
interceptor chain processes transport level details using the raw message data picked up from the wire.
There is, however, no enforcement of what can be done in any of the phases. It is recommended that interceptors within a phase adhere to tasks that are in the spirit of the phase.
The complete list of phases defined by FUSE Services Framework can be found in Appendix A.
FUSE Services Framework provides the org.apache.cxf.Phase
class to use for specifying a phase. The class is
a collection of constants. Each phase defined by FUSE Services Framework has a corresponding constant in the Phase
class. For example the RECEIVE
phase is specified by the value Phase.RECEIVE
.
An interceptor's phase is set in the interceptor's constructor. The AbstractPhaseInterceptor
class
defines three constructors for instantiating an interceptor:
public AbstractPhaseInterceptor(String phase)
—sets the phase of the interceptor to the
specified phase and automatically sets the interceptor's id to the interceptor's class name.
This constructor will satisfy most use cases.
public AbstractPhaseInterceptor(String id, String phase)
—sets the interceptor's id to
the string passed in as the first parameter and the interceptor's phase to the second string.
public AbstractPhaseInterceptor(String phase, boolean uniqueId)
—specifies if the
interceptor should use a unique, system generated id. If the uniqueId
parameter is
true
the interceptor's id will be calculated by the system. If the uniqueId
parameter is
true
the interceptor's id is set to the interceptor's class name.
The recommended way to set a custom interceptor's phase is to pass the phase to the
AbstractPhaseInterceptor
constructor using the super()
method as
shown in Example 3.1, “Setting an Interceptor's Phase”.
Example 3.1. Setting an Interceptor's Phase
import org.apache.cxf.message.Message;
import org.apache.cxf.phase.AbstractPhaseInterceptor;
import org.apache.cxf.phase.Phase;
public class StreamInterceptor extends AbstractPhaseInterceptor<Message>
{
public StreamInterceptor()
{
super(Phase.PRE_STREAM);
}
}
The StreamInterceptor
interceptor shown in
Example 3.1, “Setting an Interceptor's Phase” is placed into the PRE_STREAM
phase.