Chapter 55. Interceptors in the Apache CXF Runtime

A large part of what Apache CXF does entails processing messages. When a consumer makes a invocation on a remote service the runtime needs to marshal the data into a message the service can consume and place it on the wire. The service provider must unmarshal the message, execute its business logic, and marshal the response into the appropriate message format. The consumer must then unmarshal the response message, correlate it to the proper request, and pass it back to the consumer’s application code. In addition to the basic marshaling and unmarshaling, the Apache CXF runtime may do a number of other things with the message data. For example, if WS-RM is activated, the runtime must process the message chunks and acknowledgement messages before marshaling and unmarshaling the message. If security is activated, the runtime must validate the message’s credentials as part of the message processing sequence.

Figure 55.1, “Apache CXF interceptor chains” shows the basic path that a request message takes when it is received by a service provider.

Figure 55.1. Apache CXF interceptor chains

When a Apache CXF developed consumer invokes a remote service the following message processing sequence is started:

When a Apache CXF developed service provider receives a request from a consumer, a similar process takes place:

All of the message processing in the Apache CXF runtime is done by interceptors. Interceptors are POJOs that have access to the message data before it is passed to the application layer. They can do a number of things including: transforming the message, stripping headers off of the message, or validating the message data. For example, an interceptor could read the security headers off of a message, validate the credentials against an external security service, and decide if message processing can continue.

The message data available to an interceptor is determined by several factors:

Interceptors are organized into phases. A phase is a logical grouping of interceptors with common functionality. Each phase is responsible for a specific type of message processing. For example, interceptors that process the marshaled Java objects that are passed to the application layer would all occur in the same phase.

Phases are aggregated into interceptor chains. An interceptor chain is a list of interceptor phases that are ordered based on whether messages are inbound or outbound.

Each endpoint created using Apache CXF has three interceptor chains:

Interceptor chains are primarily constructed based on the choose of binding and transport used by the endpoint. Adding other runtime features, such as security or logging, also add interceptors to the chains. Developers can also add custom interceptors to a chain using configuration.

Developing an interceptor, regardless of its functionality, always follows the same basic procedure: