Apache CXF Interceptors

webservicesInterceptors are the fundamental processing unit which is native in Apache CXF. Basically they are Java classes that intercept your message to provide or apply certain core services to it. In this tutorial we will show how to use them and how to create some custom ones.

Apache CXF provides many built-in Interceptors that provide core services to the message that is being exchanged between consumer and service endpoint. These interceptors do the work of marshalling and unmarshalling, manipulating message headers, performing authorization checks, validating the message data, and so on.
You can also create your own Interceptors which are able to process incoming and outgoing messages. However before that, you need to learn how Interceptors work:

Interceptors are invoked in chain and organized in phases. When a CXF client invokes a CXF server, there is an outgoing interceptor chain for the client and an incoming chain for the server. When the server sends the response back to the client, there is an outgoing chain for the server and an incoming one for the client. Additionally, in the case of SOAPFaults, a CXF web service will create a separate outbound error handling chain and the client will create an inbound error handling chain.

apache cxf interceptors

Writing an interceptor is relatively simple. Your interceptor needs to extend from either the AbstractPhaseInterceptor or one of its many subclasses such as AbstractSoapInterceptor.

public class MyPhaseInterceptor extends AbstractPhaseInterceptor {
  public MyPhasedInterceptor() {
    super(Phase.INVOKE); // Put this interceptor in this phase
  }
  public void handleMessage(Message msg) throws Fault {
     // process the message
  }
}

The most important thing you should notice is the constructor: it defines the phase name for your interceptor. When you specify the phase, your interceptor is ordered according to the phase in the chain.

Most of the time you will want to extend from sub-classes of AbstractPhaseInterceptor. For example, using the SoapHeaderInterceptor you can access more specific information such as the SOAP Header.  

For example the following Interceptor scans through the SOAP header:

package com.sample.ws;;


import java.util.List;

import org.apache.cxf.binding.soap.SoapMessage;
import org.apache.cxf.binding.soap.interceptor.AbstractSoapInterceptor;

import org.apache.cxf.headers.Header;
import org.apache.cxf.interceptor.Fault;
import org.apache.cxf.phase.Phase;


public class BasicAuthAuthorizationInterceptor extends
AbstractSoapInterceptor {

 public BasicAuthAuthorizationInterceptor() {
 super(Phase.INVOKE);
 }
 public void handleMessage(SoapMessage message) throws Fault {
 
   List <Header> list = message.getHeaders();
     for (Header header : list) {
       System.out.println(header.getName() + " = " + header.toString());
     }
 }
}

You can also add information to the SOAP header using the message.getHeaders().add(header) method of the SoapMessage class.

package com.sample.ws;


import java.util.List;

import org.apache.cxf.binding.soap.SoapMessage;
import org.apache.cxf.binding.soap.interceptor.AbstractSoapInterceptor;

import org.apache.cxf.headers.Header;
import org.apache.cxf.interceptor.Fault;
import org.apache.cxf.phase.Phase;


public class BasicAuthAuthorizationInterceptor extends
AbstractSoapInterceptor {

 public BasicAuthAuthorizationInterceptor() {
 super(Phase.INVOKE);
 }
 public void handleMessage(SoapMessage message) throws Fault {
 
 // . . . . . . . .
 DocumentBuilder builder = null;
 try {
 builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
 } catch (ParserConfigurationException e) {
 e.printStackTrace();
 }
 Document doc = builder.newDocument();

 Element eSecure = doc.createElement("Secured");

 Element eUser = doc.createElement("user");
 eUser.setTextContent("myuser");

 Element ePassword = doc.createElement("password");
 ePassword.setTextContent("password");

 eSecure.appendChild(elementUser);
 eSecure.appendChild(elementPassword);
 // Create Header object
 QName qnameCredentials = new QName("Secured");
 Header header = new Header(qnameCredentials,
 eSecure);
 message.getHeaders().add(header);
 }
}    

In this example we have just added this header:

<soap:Header>
  <Secured>
    <user>myuser</user>
    <password>password</password>
  </Secured>
</soap:Header>

Here’s a custom Interceptor that extends AbstractLoggingInterceptor, providing a log of the SOAP Message which can be printed or stored somewhere if necessary:

package com.sample;

import java.io.InputStream;

import java.util.logging.Level;
import java.util.logging.Logger;


import org.apache.cxf.common.logging.LogUtils;
import org.apache.cxf.helpers.IOUtils;
import org.apache.cxf.interceptor.AbstractLoggingInterceptor;
import org.apache.cxf.interceptor.Fault;
import org.apache.cxf.interceptor.LoggingMessage;
import org.apache.cxf.io.CachedOutputStream;
import org.apache.cxf.message.Message;
import org.apache.cxf.phase.Phase;

/**
 * A simple logging handler which outputs the bytes of the message to the
 * Logger.
 */

public class LogInterceptor extends AbstractLoggingInterceptor {
  private static final Logger LOG = LogUtils.getLogger(LogInterceptor.class);
 
  public LogInterceptor() {
   super(Phase.RECEIVE);
  }
 
  public void handleMessage(Message message) throws Fault {
 
   if (writer != null || getLogger().isLoggable(Level.INFO)) {
     logging(message);
   }
  }

  protected void logging(Message message) throws Fault {
 
   if (message.containsKey(LoggingMessage.ID_KEY)) {
     return;
   }
  String id = (String)message.getExchange().get(LoggingMessage.ID_KEY);
   if (id == null) {
     id = LoggingMessage.nextId();
     message.getExchange().put(LoggingMessage.ID_KEY, id);
   }
   message.put(LoggingMessage.ID_KEY, id);
   final LoggingMessage buffer = new LoggingMessage("Inbound Message\n----------------------------", id);

   Integer responseCode = (Integer)message.get(Message.RESPONSE_CODE);
   if (responseCode != null) {
    buffer.getResponseCode().append(responseCode);
   }

   String encoding = (String)message.get(Message.ENCODING);

   if (encoding != null) {
     buffer.getEncoding().append(encoding);
   }
   String httpMethod = (String)message.get(Message.HTTP_REQUEST_METHOD);
   if (httpMethod != null) {
     buffer.getHttpMethod().append(httpMethod);
   }
   String ct = (String)message.get(Message.CONTENT_TYPE);
   if (ct != null) {
     buffer.getContentType().append(ct);
   }
   Object headers = message.get(Message.PROTOCOL_HEADERS);

   if (headers != null) {
     buffer.getHeader().append(headers);
   }
   String uri = (String)message.get(Message.REQUEST_URL);
   if (uri != null) {
     buffer.getAddress().append(uri);
     String query = (String)message.get(Message.QUERY_STRING);
     if (query != null) {
     buffer.getAddress().append("?").append(query);
   }
  }
 
   InputStream is = message.getContent(InputStream.class);
   if (is != null) {
     CachedOutputStream bos = new CachedOutputStream();
     try {
     IOUtils.copy(is, bos);

     bos.flush();
     is.close();

     message.setContent(InputStream.class, bos.getInputStream());
 
     writePayload(buffer.getPayload(), bos, encoding, ct);
 
     bos.close();
   } catch (Exception e) { throw new Fault(e); }
  }
   System.out.println("============= SOAP Message ==============");
   System.out.println(buffer.toString());
  }

 @Override
  protected Logger getLogger() {
   return LOG;
  }
}

There are two ways to apply CXF Interceptors in your applications:

1) The recommended approach is to configure them in the jaxws-endpoint-config.xml descriptor of your application or, if you want to set them for all endpoints, in your webservices sibsystem

2) The legacy approach is to use CXF annotations in your code. This can be applied for older WildFly versions (versions 8-10)

Let’s start from the first approach. You can include the jaxws-endpoint-config.xml descriptor in the WEB_INF folder of your application. Within this file, you will specify a list of interceptor class names for the “cxf.interceptors.in” and “cxf.interceptors.out”. Example:

<?xml version="1.0" encoding="UTF-8"?>
<jaxws-config xmlns="urn:jboss:jbossws-jaxws-config:4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:javaee="http://java.sun.com/xml/ns/javaee"
  xsi:schemaLocation="urn:jboss:jbossws-jaxws-config:4.0 schema/jbossws-jaxws-config_4_0.xsd">
  <endpoint-config>
    <config-name>SampleWSConfig</config-name>
    <property>
      <property-name>cxf.interceptors.in</property-name>
      <property-value>com.sample.DemoRequestInterceptor</property-value>
    </property>
    <property>
      <property-name>cxf.interceptors.out</property-name>
      <property-value>com.sample.DemoResponseInterceptor</property-value>
    </property>
  </endpoint-config>
</jaxws-config>

As an alternative, you can set the same properties in the webservices subsystem of your WildFly configuration:

  <subsystem xmlns="urn:jboss:domain:webservices:2.0">
            <wsdl-host>${jboss.bind.address:127.0.0.1}</wsdl-host>
            <endpoint-config name="Standard-Endpoint-Config">
                <property name="cxf.interceptors.in" value="com.sample.DemoRequestInterceptor"/>
            </endpoint-config>

Using CXF Annotations in your Web services (deprecated)

Interceptors can be added either via configuration, via annotations or even programmatically. The simplest of all is maybe using annoations. The following example uses two custom interceptors Test1Interceptor which is bound to the Server Incoming Chain and Test2Interceptor which is bound to the Outgoing Chain:

@org.apache.cxf.interceptor.InInterceptors (interceptors = {"com.example.Test1Interceptor" })
@org.apache.cxf.interceptor.OutInterceptors (interceptors = {"com.example.Test2Interceptor" })
})
@WebService(
public class SayHiImpl  implements SayHi {
   public long sayHi(long arg) {
     return arg;
   }
 
}

and here’s how you can configure these interceptors using cxf.xml configuration file:

<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:cxf="http://cxf.apache.org/core"
 xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd">

 <bean id="MyInterceptor1" class="com.example.Test1Interceptor"/>
 <bean id="MyInterceptor2" class="com.example.Test2Interceptor"/>
 

 <cxf:bus>
   <cxf:inInterceptors>
     <ref bean="MyInterceptor1"/>
   </cxf:inInterceptors>
   <cxf:outInterceptors>
     <ref bean="MyInterceptor2"/>
   </cxf:outInterceptors>
 </cxf:bus>
</beans>

Adding Fault Interceptors to your Web services

In the case of SOAPFaults, a CXF web service will create a separate outbound error handling chain and the client will create an inbound error handling chain. By default, the last interceptor in the outbound fault chain is Soap11FaultOutInterceptor which  automatically appends the details of the SOAPFault into the response. This might now be always desirable as we might want to display a custom error message.

In order to do that you need simply to add a custom OutFaultInterceptors which modifies the details of the SOAPFault. There are many places that we could do this, for example you could do that before the final interceptor (Soap11FaultOutInterceptor) is called.

public class CustomFaultInterceptor extends AbstractSoapInterceptor {

   public CustomFaultInterceptor() {
     super(Phase.MARSHAL);
   }

   public void handleMessage(SoapMessage message) throws Fault {
     Fault fault = (Fault) message.getContent(Exception.class);
     fault.setDetail(createDetailSomehow());
   }

 
}

And here’s how you can bind this Interceptor to your Web service using annotations:

@org.apache.cxf.interceptor.OutFaultInterceptors (interceptors = {"com.sample.CustomFaultInterceptor" })
@WebService(
public class SayHiImpl  implements SayHi {
    public long sayHi(long arg) {
      return arg;
    }
 
}
Found the article helpful? if so please follow us on Socials