55.2. Specifying an interceptor's phase
Overview
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.
Phase
Phases are a logical collection of interceptors. As shown in Figure 55.1, “An interceptor phase”, the interceptors within a phase are called sequentially.
Figure 55.1. An interceptor phase
The phases are linked together in an ordered list to form an interceptor chain and provide defined logical steps in the message processing procedure. For example, a group of 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 Apache CXF can be found in Appendix F, Apache CXF Message Processing Phases.
Specifying a phase
Apache CXF provides the
org.apache.cxf.Phase class to use for specifying a phase. The class is a collection of constants. Each phase defined by Apache CXF has a corresponding constant in the Phase class. For example, the RECEIVE phase is specified by the value Phase.RECEIVE.
Setting the phase
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.TipThis 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 theuniqueIdparameter istrue, the interceptor's id will be calculated by the system. If theuniqueIdparameter isfalsethe 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 55.1, “Setting an interceptor's phase”.
Example 55.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 55.1, “Setting an interceptor's phase” is placed into the PRE_STREAM phase.
