LibraryLink ToToggle FramesPrintFeedback

Chapter 1. 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 1.1 shows the basic path that a request message takes when it is received by a service provider.


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:

  • the interceptor's chain

  • the interceptor's phase

  • the other interceptors that occur earlier in the chain

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:

  • a chain for inbound messages

  • a chain for outbound messages

  • a chain for error messages

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:

  1. Determine which abstract interceptor class to extend.

    Apache CXF provides a number of abstract interceptors to make it easier to develop custom interceptors.

  2. Determine the phase in which the interceptor will run.

    Interceptors require certain parts of a message to be available and require the data to be in a certain format. The contents of the message and the format of the data is partially determined by an interceptor's phase.

  3. Determine if there are any other interceptors that must be executed either before or after the interceptor.

    In general, the ordering of interceptors within a phase is not important. However, in certain situations it may be important to ensure that an interceptor is executed before, or after, other interceptors in the same phase.

  4. Implement the interceptor's message processing logic.

  5. Implement the interceptor's fault processing logic.

    If an error occurs in the active interceptor chain after the interceptor has executed, its fault processing logic is invoked.

  6. Attach the interceptor to one of the endpoint's interceptor chains.