SupportConsoleDevelopersStart a trialContact

Chapter 53. Interceptors in the Apache CXF Runtime

Abstract

Most of the functionality in the Apache CXF runtime is implemented by interceptors. Every endpoint created by the Apache CXF runtime has three potential interceptor chains for processing messages. The interceptors in the these chains are responsible for transforming messages between the raw data transported across the wire and the Java objects handled by the endpoint's implementation code. The interceptors are organized into phases to ensure that processing happens on the proper order.

Overview

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 53.1, “Apache CXF interceptor chains” shows the basic path that a request message takes when it is received by a service provider.

Figure 53.1. Apache CXF interceptor chains

depiction of an endpoint with in and out interceptor chains

Message processing in Apache CXF

When a Apache CXF developed consumer invokes a remote service the following message processing sequence is started:
  1. The Apache CXF runtime creates an outbound interceptor chain to process the request.
  2. If the invocation starts a two-way message exchange, the runtime creates an inbound interceptor chain and a fault processing interceptor chain.
  3. The request message is passed sequentially through the outbound interceptor chain.
    Each interceptor in the chain performs some processing on the message. For example, the Apache CXF supplied SOAP interceptors package the message in a SOAP envelope.
  4. If any of the interceptors on the outbound chain create an error condition the chain is unwound and control is returned to the application level code.
    An interceptor chain is unwound by calling the fault processing method on all of the previously invoked interceptors.
  5. The request is dispatched to the appropriate service provider.
  6. When the response is received, it is passed sequentially through the inbound interceptor chain.
    Note
    If the response is an error message, it is passed into the fault processing interceptor chain.
  7. If any of the interceptors on the inbound chain create an error condition, the chain is unwound.
  8. When the message reaches the end of the inbound interceptor chain, it is passed back to the application code.
When a Apache CXF developed service provider receives a request from a consumer, a similar process takes place:
  1. The Apache CXF runtime creates an inbound interceptor chain to process the request message.
  2. If the request is part of a two-way message exchange, the runtime also creates an outbound interceptor chain and a fault processing interceptor chain.
  3. The request is passed sequentially through the inbound interceptor chain.
  4. If any of the interceptors on the inbound chain create an error condition, the chain is unwound and a fault is dispatched to the consumer.
    An interceptor chain is unwound by calling the fault processing method on all of the previously invoked interceptors.
  5. When the request reaches the end of the inbound interceptor chain, it is passed to the service implementation.
  6. When the response is ready it is passed sequentially through the outbound interceptor chain.
    Note
    If the response is an exception, it is passed through the fault processing interceptor chain.
  7. If any of the interceptors on the outbound chain create an error condition, the chain is unwound and a fault message is dispatched.
  8. Once the request reaches the end of the outbound chain, it is dispatched to the consumer.

Interceptors

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

Phases

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.

Interceptor chains

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 interceptors

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.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.