Chapter 59. JAX-RS 2.0 Filters and Interceptors
Abstract
JAX-RS 2.0 defines standard APIs and semantics for installing filters and interceptors in the processing pipeline for REST invocations. Filters and interceptors are typically used to provide such capabilities as logging, authentication, authorization, message compression, message encryption, and so on.
59.1. Introduction to JAX-RS Filters and Interceptors
Overview
This section provides an overview of the processing pipeline for JAX-RS filters and interceptors, highlighting the extension points where it is possible to install a filter chain or an interceptor chain.
Filters
A JAX-RS 2.0 filter is a type of plug-in that gives a developer access to all of the JAX-RS messages passing through a CXF client or server. A filter is suitable for processing the metadata associated with a message: HTTP headers, query parameters, media type, and other metadata. Filters have the capability to abort a message invocation (useful for security plug-ins, for example).
If you like, you can install multiple filters at each extension point, in which case the filters are executed in a chain (the order of execution is undefined, however, unless you specify a priority value for each installed filter).
Interceptors
A JAX-RS 2.0 interceptor is a type of plug-in that gives a developer access to a message body as it is being read or written. Interceptors are wrapped around either the
MessageBodyReader.readFrom method invocation (for reader interceptors) or the MessageBodyWriter.writeTo method invocation (for writer interceptors).
If you like, you can install multiple interceptors at each extension point, in which case the interceptors are executed in a chain (the order of execution is undefined, however, unless you specify a priority value for each installed interceptor).
Server processing pipeline
Figure 59.1, “Server-Side Filter and Interceptor Extension Points” shows an outline of the processing pipeline for JAX-RS filters and interceptors installed on the server side.
Figure 59.1. Server-Side Filter and Interceptor Extension Points
Server extension points
In the server processing pipeline, you can add a filter (or interceptor) at any of the following extension points:
PreMatchContainerRequestfilterContainerRequestfilterReadInterceptorContainerResponsefilterWriteInterceptor
Note that the
PreMatchContainerRequest extension point is reached before resource matching has occurred, so some of the context metadata will not be available at this point.
Client processing pipeline
Figure 59.2, “Client-Side Filter and Interceptor Extension Points” shows an outline of the processing pipeline for JAX-RS filters and interceptors installed on the client side.
Figure 59.2. Client-Side Filter and Interceptor Extension Points
Client extension points
In the client processing pipeline, you can add a filter (or interceptor) at any of the following extension points:
ClientRequestfilterWriteInterceptorClientResponsefilterReadInterceptor
Filter and interceptor order
If you install multiple filters or interceptors at the same extension point, the execution order of the filters depends on the priority assigned to them (using the
@Priority annotation in the Java source). A priority is represented as an integer value. In general, a filter with a higher priority number is placed closer to the resource method invocation on the server side; while a filter with a lower priority number is placed closer to the client invocation. In other words, the filters and interceptors acting on a request message are executed in ascending order of priority number; while the filters and interceptors acting on a response message are executed in descending order of priority number.
Filter classes
The following Java interfaces can be implemented in order to create custom REST message filters:
Interceptor classes
The following Java interfaces can be implemented in order to create custom REST message interceptors:
