Este contenido no está disponible en el idioma seleccionado.
Chapter 55. 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 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
Message processing in Apache CXF
When a Apache CXF developed consumer invokes a remote service the following message processing sequence is started:
- The Apache CXF runtime creates an outbound interceptor chain to process the request.
- If the invocation starts a two-way message exchange, the runtime creates an inbound interceptor chain and a fault processing interceptor chain.
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.
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.
- The request is dispatched to the appropriate service provider.
When the response is received, it is passed sequentially through the inbound interceptor chain.
NoteIf the response is an error message, it is passed into the fault processing interceptor chain.
- If any of the interceptors on the inbound chain create an error condition, the chain is unwound.
- 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:
- The Apache CXF runtime creates an inbound interceptor chain to process the request message.
- 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.
- The request is passed sequentially through the inbound interceptor chain.
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.
- When the request reaches the end of the inbound interceptor chain, it is passed to the service implementation.
When the response is ready it is passed sequentially through the outbound interceptor chain.
NoteIf the response is an exception, it is passed through the fault processing interceptor chain.
- If any of the interceptors on the outbound chain create an error condition, the chain is unwound and a fault message is dispatched.
- 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:
Chapter 56, The Interceptor APIs
Apache CXF provides a number of abstract interceptors to make it easier to develop custom interceptors.
Section 57.2, “Specifying an interceptor’s phase”
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.
Section 57.3, “Constraining an interceptors placement in a phase”
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.
- Section 58.2, “Processing messages”
Section 58.3, “Unwinding after an error”
If an error occurs in the active interceptor chain after the interceptor has executed, its fault processing logic is invoked.
- Chapter 59, Configuring Endpoints to Use Interceptors
