Chapter 56. The Interceptor APIs

download PDF


Interceptors implement the PhaseInterceptor interface which extends the base Interceptor interface. This interface defines a number of methods used by the Apache CXF’s runtime to control interceptor execution and are not appropriate for application developers to implement. To simplify interceptor development, Apache CXF provides a number of abstract interceptor implementations that can be extended.


All of the interceptors in Apache CXF implement the base Interceptor interface shown in Example 56.1, “Base interceptor interface”.

Example 56.1. Base interceptor interface

package org.apache.cxf.interceptor;

public interface Interceptor<T extends Message>

  void handleMessage(T message) throws Fault;

  void handleFault(T message);


The Interceptor interface defines the two methods that a developer needs to implement for a custom interceptor:

The handleMessage() method does most of the work in an interceptor. It is called on each interceptor in a message chain and receives the contents of the message being processed. Developers implement the message processing logic of the interceptor in this method. For detailed information about implementing the handleMessage() method, see Section 58.2, “Processing messages”.
The handleFault() method is called on an interceptor when normal message processing has been interrupted. The runtime calls the handleFault() method of each invoked interceptor in reverse order as it unwinds an interceptor chain. For detailed information about implementing the handleFault() method, see Section 58.3, “Unwinding after an error”.

Most interceptors do not directly implement the Interceptor interface. Instead, they implement the PhaseInterceptor interface shown in Example 56.2, “The phase interceptor interface”. The PhaseInterceptor interface adds four methods that allow an interceptor the participate in interceptor chains.

Example 56.2. The phase interceptor interface

package org.apache.cxf.phase;

public interface PhaseInterceptor<T extends Message> extends Interceptor<T>

    Set<String> getAfter();

    Set<String> getBefore();

    String getId();

    String getPhase();


Abstract interceptor class

Instead of directly implementing the PhaseInterceptor interface, developers should extend the AbstractPhaseInterceptor class. This abstract class provides implementations for the phase management methods of the PhaseInterceptor interface. The AbstractPhaseInterceptor class also provides a default implementation of the handleFault() method.

Developers need to provide an implementation of the handleMessage() method. They can also provide a different implementation for the handleFault() method. The developer-provided implementations can manipulate the message data using the methods provided by the generic org.apache.cxf.message.Message interface.

For applications that work with SOAP messages, Apache CXF provides an AbstractSoapInterceptor class. Extending this class provides the handleMessage() method and the handleFault() method with access to the message data as an org.apache.cxf.binding.soap.SoapMessage object. SoapMessage objects have methods for retrieving the SOAP headers, the SOAP envelope, and other SOAP metadata from the message.

Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.