Page History

...

Interceptors are used with both CXF clients and CXF servers. 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.

...

Several different components inside CXF may provide interceptors to an InterceptorChain. These implement the InterceptorProvider interface:

Code Block

	java
	java


public interface InterceptorProvider {

    List<Interceptor> getInInterceptors();

    List<Interceptor> getOutInterceptors();

    List<Interceptor> getOutFaultInterceptors();

    List<Interceptor> getInFaultInterceptors();
}

To add an interceptor to an interceptor chain, you'll want to add it to one of the Interceptor Providers.

Code Block

	java
	java


MyInterceptor interceptor = new MyInterceptor();
provider.getInInterceptors().add(interceptor);

...

The CXF distribution is shipped with a demo called configuration_interceptor which shows how to develop a user interceptor and configure the interceptor into its interceptor chain.

...

Writing an interceptor is relatively simple. Your interceptor needs to extend from either the AbstractPhaseInterceptor or one of its many subclasses such as AbstractSoapInterceptor. Extending from AbstractPhaseInterceptor allows your interceptor to access the methods of the Message interface. For example, AttachmentInInterceptor is used in CXF to turn a multipart/related message into a series of attachments. It looks like below:

Code Block

	java
	java


import java.io.IOException;

import org.apache.cxf.attachment.AttachmentDeserializer;
import org.apache.cxf.message.Message;
import org.apache.cxf.phase.AbstractPhaseInterceptor;
import org.apache.cxf.phase.Phase;

public class AttachmentInInterceptor extends AbstractPhaseInterceptor<Message> {
    public AttachmentInInterceptor() {
        super(Phase.RECEIVE);
    }

    public void handleMessage(Message message) {
        String contentType = (String) message.get(Message.CONTENT_TYPE);
        if (contentType != null && contentType.toLowerCase().indexOf("multipart/related") != -1) {
            AttachmentDeserializer ad = new AttachmentDeserializer(message);
            try {
                ad.initializeAttachments();
            } catch (IOException e) {
                throw new Fault(e);
            }
        }
    }

    public void handleFault(Message messageParam) {
    }
}

Extending from sub-classes of AbstractPhaseInterceptor allows your interceptor to access more specific information than those in the Message interface. One of the sub-classes of AbstractPhaseInterceptor is AbstractSoapInterceptor. Extending from this class allows your interceptor to access the SOAP header and version information of the SoapMessage class. For example, SoapActionInInterceptor is used in CXF to parse the SOAP action, as a simplified version of it shows below:

Code Block

	java
	java


import java.util.Collection;
import java.util.List;
import java.util.Map;

import org.apache.cxf.binding.soap.Soap11;
import org.apache.cxf.binding.soap.Soap12;
import org.apache.cxf.binding.soap.SoapMessage;
import org.apache.cxf.binding.soap.model.SoapOperationInfo;
import org.apache.cxf.endpoint.Endpoint;
import org.apache.cxf.helpers.CastUtils;
import org.apache.cxf.interceptor.Fault;
import org.apache.cxf.message.Exchange;
import org.apache.cxf.message.Message;
import org.apache.cxf.phase.Phase;
import org.apache.cxf.service.model.BindingOperationInfo;
import org.apache.cxf.service.model.OperationInfo;

public class SoapActionInInterceptor extends AbstractSoapInterceptor {

    public SoapActionInInterceptor() {
        super(Phase.READ);
        addAfter(ReadHeadersInterceptor.class.getName());
        addAfter(EndpointSelectionInterceptor.class.getName());
    }

    public void handleMessage(SoapMessage message) throws Fault {
        if (message.getVersion() instanceof Soap11) {
            Map<String, List<String>> headers = CastUtils.cast((Map)message.get(Message.PROTOCOL_HEADERS));
            if (headers != null) {
                List<String> sa = headers.get("SOAPAction");
                if (sa != null && sa.size() > 0) {
                    String action = sa.get(0);
                    if (action.startsWith("\"")) {
                        action = action.substring(1, action.length() - 1);
                    }
                    getAndSetOperation(message, action);
                }
            }
        } else if (message.getVersion() instanceof Soap12) {
          ...........
        }
    }

    private void getAndSetOperation(SoapMessage message, String action) {
        if ("".equals(action)) {
            return;
        }

        Exchange ex = message.getExchange();
        Endpoint ep = ex.get(Endpoint.class);

        BindingOperationInfo bindingOp = null;

        Collection<BindingOperationInfo> bops = ep.getBinding().getBindingInfo().getOperations();
        for (BindingOperationInfo boi : bops) {
            SoapOperationInfo soi = (SoapOperationInfo) boi.getExtensor(SoapOperationInfo.class);
            if (soi != null && soi.getAction().equals(action)) {
                if (bindingOp != null) {
                    //more than one op with the same action, will need to parse normally
                    return;
                }
                bindingOp = boi;
            }
        }
        if (bindingOp != null) {
            ex.put(BindingOperationInfo.class, bindingOp);
            ex.put(OperationInfo.class, bindingOp.getOperationInfo());
        }
    }

}

Note that you will need to specify the phase that the interceptor will be included in. This is done in the interceptor's constructor:

Code Block

	java
	java


public class MyInterceptor extends AbstractSoapInterceptor {
  public MyInterceptor() {
    super(Phase.USER_PROTOCOL);
  }
  ...
}

You can also express that you would like the interceptor to run before/after certain other interceptors defined in the same phase:

Code Block

	java
	java


public class MyInterceptor extends AbstractSoapInterceptor {
  public MyInterceptor() {
    super(Phase.USER_PROTOCOL);

    // MyInterceptor needs to run after SomeOtherInterceptor
    getAfter().add(SomeOtherInterceptor.class.getName());

    // MyInterceptor needs to run before YetAnotherInterceptor
    getBefore().add(YetAnotherInterceptor.class.getName());
  }
  ...
}

...

To add this to your server, you'll want to get access to the Server object (see here for more info):

Code Block

	java
	java


import org.apache.cxf.endpoint.Server;
import org.apache.cxf.frontend.ServerFactoryBean;
...

MyInterceptor myInterceptor = new MyInterceptor();

Server server = serverFactoryBean.create();
server.getEndpoint().getInInterceptor().add(myInterceptor);

On the Client side the process is very similar:

Code Block

	java
	java


import org.apache.cxf.endpoint.Client;
import org.apache.cxf.frontend.ClientProxy;
...

MyInterceptor myInterceptor = new MyInterceptor();
FooService client = ... ; // created from ClientProxyFactoryBean or generated JAX-WS client

//You could also call clientProxyFactroyBean.getInInterceptor().add(myInterceptor) to add the interceptor

Client cxfClient = ClientProxy.getClient(client);
cxfClient.getInInterceptors().add(myInterceptor);

// then you can call the service
client.doSomething();

You can also use annotation to add the interceptors from the SEI or service class. When CXF create the server or client, CXF will add the interceptor according with the annotation.

Code Block

	java
	java


@org.apache.cxf.interceptor.InInterceptors (interceptors = {"com.example.Test1Interceptor" })
@org.apache.cxf.interceptor.InFaultInterceptors (interceptors = {"com.example.Test2Interceptor" })
@org.apache.cxf.interceptor.OutInterceptors (interceptors = {"com.example.Test1Interceptor" })
@org.apache.cxf.interceptor.InFaultInterceptors (interceptors = {"com.example.Test2Interceptor","com.example.Test3Intercetpor" })
@WebService(endpointInterface = "org.apache.cxf.javascript.fortest.SimpleDocLitBare",
            targetNamespace = "uri:org.apache.cxf.javascript.fortest")
public class SayHiImplementation implements SayHi {
   public long sayHi(long arg) {
       return arg;
   }
   ...
}

...

Adding MyInterceptor to the bus:

Code Block

	xml
	xml


<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="MyInterceptor" class="demo.interceptor.MyInterceptor"/>

    <!-- We are adding the interceptors to the bus as we will have only one endpoint/service/bus. -->

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

...

Adding MyInterceptor to your client:

Code Block

	xml
	xml


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

    <http:conduit name="{http://apache.org/hello_world_soap_http}SoapPort9001.http-conduit">
      <http:client DecoupledEndpoint="http://localhost:9990/decoupled_endpoint"/>
    </http:conduit>

    <bean id="MyInterceptor" class="demo.interceptor.MyInterceptor"/>

    <!-- We are adding the interceptors to the bus as we will have only one endpoint/service/bus. -->

    <bean id="cxf" class="org.apache.cxf.bus.CXFBusImpl">
        <property name="inInterceptors">
            <ref bean="MyInterceptor"/>
        </property>
        <property name="outInterceptors">
            <ref bean="MyInterceptor"/>
        </property>
    </bean>
</beans>

...

In CXF, all the functionality of processing messages is done via interceptors. Thus, when debugging a message flow, you will come across a bunch of interceptors in the chain. Here is a list of some of the common interceptors and the functionality they provide. The source code for these interceptors (latest trunk version) can be viewed with this Fisheye queryis available on github.

Default JAX-WS Incoming interceptor chain (Server):

AttachmentInInterceptor Parse the mime headers for mime boundaries, finds the "root" part and resets the input stream to it, and stores the other parts in a collection of Attachments
StaxInInterceptor Creates an XMLStreamReader from the transport InputStream on the Message
ReadHeadersInterceptor Parses the SOAP headers and stores them on the Message
SoapActionInInterceptor Parses "soapaction" header and looks up the operation if a unique operation can be found for that action.
MustUnderstandInterceptor Checks the MustUnderstand headers, its applicability and process it, if required
SOAPHandlerInterceptor SOAP Handler as per JAX-WS
LogicalHandlerInInterceptor Logical Handler as per JAX-WS
CheckFaultInterceptor Checks for fault, if present aborts interceptor chain and invokes fault handler chain
URIMappingInterceptor (for CXF versions <= 2.x) Can handle HTTP GET, extracts operation info and sets the same in the Message
DocLiteralnInterceptor Examines the first element in the SOAP body to determine the appropriate Operation (if soapAction did not find one) and calls the Databinding to read in the data.
SoapHeaderInterceptor Perform databinding of the SOAP headers for headers that are mapped to parameters
WrapperClassInInterceptor For wrapped doc/lit, the DocLiteralInInterceptor probably read in a single JAXB bean. This interceptor pulls the individual parts out of that bean to construct the Object[] needed to invoke the service.
SwAInInterceptor For Soap w/ Attachments, finds the appropriate attachments and assigns them to the correct spot in the parameter list.
HolderInInterceptor For OUT and IN/OUT parameters, JAX-WS needs to create Holder objects. This interceptor creates the Holders and puts them in the parameter list.
ServiceInvokerInInterceptor Actually invokes the service.

...

Child pages

Versions Compared

Old Version 29

New Version Current

Key

Default JAX-WS Incoming interceptor chain (Server):