Chapter 59. Configuring Endpoints to Use Interceptors

There are a number of runtime objects that host interceptor chains. These include:

A developer can attach their own interceptors to any of these objects. The most common objects to attach interceptors are the bus and the individual endpoints. Choosing the correct object requires understanding how these runtime objects are combined to make an endpoint. As per the design, each cxf related bundle has its own cxf bus. Hence, if the interceptors are configured in the bus and the service at the same Blueprint context is imported or created into another bundle, the interceptor won’t be processed. Instead you can configure the interceptors directly into the JAXWS client or endpoint in the imported service.

Attaching interceptors to either the endpoint or the proxy is the most fine grained way to place an interceptor. Any interceptors attached directly to an endpoint or a proxy only effect the specific endpoint or proxy. This is a good place to attach interceptors that are specific to a particular incarnation of a service. For example, if a developer wants to expose one instance of a service that converts units from metric to imperial they could attach the interceptors directly to one endpoint.

Using the Spring configuration to attach interceptors to the factories used to create an endpoint or a proxy has the same effect as attaching the interceptors directly to the endpoint or proxy. However, when interceptors are attached to a factory programmatically the interceptors attached to the factory are propagated to every endpoint or proxy created by the factory.

Attaching interceptors to the binding allows the developer to specify a set of interceptors that are applied to all endpoints that use the binding. For example, if a developer wants to force all endpoints that use the raw XML binding to include a special ID element, they could attach the interceptor responsible for adding the element to the XML binding.

The most general place to attach interceptors is the bus. When interceptors are attached to the bus, the interceptors are propagated to all of the endpoints managed by that bus. Attaching interceptors to the bus is useful in applications that create multiple endpoints that share a similar set of interceptors.

Because an endpoint’s final set of interceptor chains is an amalgamation of the interceptor chains contributed by the listed objects, several of the listed object can be combined in a single endpoint’s configuration. For example, if an application spawned multiple endpoints that all required an interceptor that checked for a validation token, that interceptor would be attached to the application’s bus. If one of those endpoints also required an interceptor that converted Euros into dollars, the conversion interceptor would be attached directly to the specific endpoint.

The easiest way to attach interceptors to an endpoint is using the configuration file. Each interceptor to be attached to an endpoint is configured using a standard Spring bean. The interceptor’s bean can then be added to the proper interceptor chain using Apache CXF configuration elements.

Each runtime component that has an associated interceptor chain is configurable using specialized Spring elements. Each of the component’s elements have a standard set of children for specifying their interceptor chains. There is one child for each interceptor chain associated with the component. The children list the beans for the interceptors to be added to the chain.

Table 59.1, “Interceptor chain configuration elements” describes the four configuration elements for attaching interceptors to a runtime component.

All of the interceptor chain configuration elements take a list child element. The list element has one child for each of the interceptors being attached to the chain. Interceptors can be specified using either a bean element directly configuring the interceptor or a ref element that refers to a bean element that configures the interceptor.

Example 59.1, “Attaching interceptors to the bus” shows configuration for attaching interceptors to a bus' inbound interceptor chain.

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:cxf="http://cxf.apache.org/core"
       xmlns:http="http://cxf.apache.org/transports/http/configuration"
       xsi:schemaLocation="
       http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd
       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">
  ...
  <bean id="GZIPStream" class="demo.stream.interceptor.StreamInterceptor"/>

  <cxf:bus>
    *<cxf:inInterceptors>
      <list>
        <ref bean="GZIPStream"/>
      </list>
    </cxf:inInterceptors>*
  </cxf:bus>
</beans>

Example 59.2, “Attaching interceptors to a JAX-WS service provider” shows configuration for attaching an interceptor to a JAX-WS service’s outbound interceptor chain.

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

  <jaxws:endpoint ...>
    *<jaxws:outInterceptors>
      <list>
        <bean id="GZIPStream" class="demo.stream.interceptor.StreamInterceptor" />
      </list>
    </jaxws:outInterceptors>*
  </jaxws:endpoint>
</beans>

For more information about configuring endpoints using the Spring configuration see Part IV, “Configuring Web Service Endpoints”.