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-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:
  1. PreMatchContainerRequest filter
  2. ContainerRequest filter
  3. ReadInterceptor
  4. ContainerResponse filter
  5. WriteInterceptor
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-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:
  1. ClientRequest filter
  2. WriteInterceptor
  3. ClientResponse filter
  4. ReadInterceptor

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: