07.Filters and Interceptors - JohnyzHub/jax-rs GitHub Wiki

Filters are used to modify the properties of request and responses. They provide access to inbound and outbound messages for tasks such as authentication/logging, auditing, etc.

Filters can be divided into two categories into to in Jax-rs specification namely

1. Client-side Filters
2. Server-side filters

There are two filters those are applicable at client side.

1. ClientRequestFilter
   This filter is useful in filtering the outgoing request from the client. For the working example, refer MovieResourceClientRequestFilter.java
2. ClientResponseFilter
   This filter is useful in filtering the incoming response to the client. For the working example, refer MovieResourceClientResponseFilter.java

In order to activate the client side filters, these filters should be registered to the client.

There are three filters those are applicable at server side.

1. Pre matching ContainerRequestFilter
   This filter is useful in filtering the incoming request, before finding the matching resource for the request. This class should be annotated with @PreMatching.
   Notice that this filter gets executed if the base url(ie. localhost:8080/moviedirectory/rest) matches irrespective of the matching resource path (eg: directory).

2. Post matching ContainerRequestFilter
   This filter is useful in filtering the incoming request, after finding the matching resource for the request. All the server side filters are post matching by default. For example the authentication verification. Notice that this filter doesn't need special annotation such as @PreMatching in the previous one.

   For working example, refer MovieServiceRequestFilter.java

   There is one more vital difference between prematching and postmatching request filters. If the client sends the request with invalid url, the prematching filter still gets executed where as the postmatching filter doesn't. That means, the prematching filters gets executed always.

3. ContainerResponseFilter
   This filter is useful in filtering the outgoing response.
   For working example, refer MovieServiceResponseFilter.java

Interceptors are used to manipulate the requests and responses of rest call such as compressing/decompressing the outgoing responses and incoming requests. If using on client side, they should be registered to the client, the same the filters were registered.

1. ReaderInterceptor applicable to the requests
2. WriterInterceptor applicable to the responses
   For working example, Please refer MovieServiceInterceptor.java

Notice that the interceptors always get executed after the filters if exists.
Execution Order:

Jax-rs specification also provides the functionality to

• chain the filters (or) interceptors and setting the order of execution by using @Priority

  The priority is specified with an Integer or Priorities. Priority sorts the filters and interceptors in ascending order for the requests and in descending order for the responses
  

• Set the filters or interceptors applicable only for specific resources.

  • @NameBinding: In short, create a custom annotation and annotate it with @NameBinding. Place this custom annotation on the filter (or) interceptor and the rest resource (class or method level). While doing so, filter or interceptor classes do not need to be annotated with @Provider. Jax-rs container activates this functionality during runtime. This is an easy and clean way of applying filter/interceptor to a set of resources. One caveat is in order to verify all the resources a filter is applied to, needs a search in the whole workspace.
  • Dynamically Binding: In short, implement the interface DynamicFeature and override the method to register the filter or interceptor to the FeatureContext based on the ResourceInfo. Jax-rs container activates this functionality during application deployment. This is helpful if you would like to declare a set of resources at a single place to easily identify the filter/interceptor applied to them. One caveat is the class may get bloated with increase in number of resources.

Please refer below resources for more information regarding the jax-rs resource life cycle

• Filters and Interceptors by baeldung
• Understanding the JAX-RS resource life cycle section in the book Restful java web services