JAX-RS executes the ContainerRequestFilter filter before invoking the wrapped target resource. JAX-RS executes ContainerResponseFilter after invoking the wrapped target resource.

The category of ContainerRequestFilter is divided into two more filter styles. A filter can be pre-matching or post-matching. The default is the post-matching. Pre-matching filters are designed to modify request attributes and header attributes before the JAX-RS runtime perform path pattern matching on the URI resource.

In order to designate a ContainerRequestFilter is a pre-matching filter, the class must be annotated with @javax.ws.js.container.PreMatching.

If we wanted to copy the HTTP Header parameter User Agent and shadow it for a processing pipeline, we could write a filter in the following way:

package je7hb.jaxrs.basic;
import javax.ws.rs.container.ContainerRequestContext;
import javax.ws.rs.container.ContainerRequestFilter;
import javax.ws.rs.container.PreMatching;
import javax.ws.rs.ext.Provider;
import java.io.IOException;

@Provider
@PreMatching
public class AddExtraUserAgentFilter implements ContainerRequestFilter {
  @Override
  public void filter(ContainerRequestContext context)
  throws IOException {
    String userAgent = context.getHeaderString("User-Agent");
    if ( userAgent != null ) {
      context.getHeaders().putSingle("X-User-Agent-Copy", userAgent );
    }
  }
}

The filter AddExtraUserAgentFilter is annotated as @javax.ws.js.ext.Provider. The class implements ContainerRequestFilter and the method filter(). We look up the header parameter by name from the supplied context. Since this agent usually is supplied by the client, we can make a copy of the parameter into a new header key and value pair called X-User-Agent-Copy.

If we wanted to, the flexibility of the JAX-RS API, allows us to change the User-Agent string. Since this filter is annotated with @PreMatching then the runtime will invoke this filter before proceeding with the URI path pattern matching phase and before the target resource is invoked.

Suppose we wanted to have a filter that automatically added an expiration time to the HTTP Response header for any JAX-RS Resource. We could write a container response filter like the following code:

package je7hb.jaxrs.basic;
import javax.ws.rs.container.*;
import javax.ws.rs.ext.Provider;
/* ... imports omitted */

@Provider
public class AutoExpirationDateFilter implements ContainerResponseFilter{
  private static SimpleDateFormat formatter =new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss Z");
  @Override
  public void filter(ContainerRequestContext reqCtx,ContainerResponseContext resCtx)
  throws IOException {
    if ( reqCtx.getMethod().equals("GET")) {
      Date oneHour = new Date(System.currentTimeMillis() + 60* 1000 );
      resCtx.getHeaders().add("Expires",formatter.format( oneHour));
    }
  }
}

In the class AutoExpirationDateFilter which implements the contract from ContainerResponseFilter, the filter() method accepts two context parameters and it is extremely useful to have access to both the request and response context objects.

We only add the expiration response header field for HTTP GET request, so in the method we can check this situation. With the response context, we add the expiration header with a properly formatted date and timestamp.

Writing JAX-RS filters for the client side is a one step filter, because there is no URI path pattern matching occurring. The developer has a choice of two filter types, namely, ClientRequestFilter and ClientResponseFilter . The JAX-RS filter will invoke ClientRequestFilter just before the HTTP request is sent to the remote URI resource. Similarly, after the remote URI resource processes the data and sends back a response, then the JAX-RS runtime invokes ClientResponseFilter instance.

We shall now inspect the code for a useful bit of kit in our toolkit. What happens if we have problem with some production code involving JAX-RS? Would it not be nice to debug to a standard console (and perhaps later to a logging facility) the requests going from the client to the remote URI resource and reading the server response? It would be nice to have a master client that we can travel around the business and validate the communication is functioning correctly between the client and server.

So the following is the basis of a debuggable logger for JAX-RS client, albeit incomplete:

package je7hb.jaxrs.basic;
import javax.ws.rs.client.*;
import javax.ws.rs.ext.Provider;
/* ... imports omitted */

@Provider
public class DebugClientLoggingFilter
implements ClientRequestFilter, ClientResponseFilter {

  @Override
  public void filter(ClientRequestContext reqCtx) 
  throws IOException {
    System.out.printf("**** DEBUG CLIENT REQUEST ****
");
    System.out.printf("uri: %s
", reqCtx.getUri());
    if ( reqCtx.getEntity() != null ) {
      System.out.printf("entity: %s
",
      reqCtx.getEntity().getClass().getName() + "@" +Integer.toHexString(System.identityHashCode( reqCtx.getEntity())));
    }
    System.out.printf("method: %s
", reqCtx.getMethod());
    System.out.printf("mediaType: %s
",reqCtx.getMediaType());
    System.out.printf("date: %s
", reqCtx.getDate());
    System.out.printf("language: %s
", reqCtx.getLanguage());
    for (String name: reqCtx.getHeaders().keySet()) {
      System.out.printf("header[%s] => %s
",name, reqCtx.getHeaderString(name) );
    }
    for (String name: reqCtx.getCookies().keySet()) {
      System.out.printf("cookie[%s] => %s
",name, reqCtx.getHeaderString(name) );
    }
    System.out.printf("**** END CLIENT REQUEST ****

");
  }
  // ... incoming filter method }

This class DebugClientLoggingFilter implements both the client request and response filters. As you can see the two different context objects ClientRequestContext and ClientResponseContext provide a wealth of information.

From the client, we are able to find out the request URI, the entity, the method, media type, language, headers, and cookies. Similarly, from the server we can debug the status, status code, response length, the date, headers, and cookies.

Once the remote endpoint has serviced the request, we expect a response, which can also be filtered. The following is the other incoming implementation filter method:

@Override
public void filter(ClientRequestContext reqCtx,ClientResponseContext resCtx) 
throws IOException {
  System.out.printf("**** DEBUG CLIENT RESPONSE ****
");
  System.out.printf("status: %s
", resCtx.getStatus());
  System.out.printf("status info: %s
", resCtx.getStatusInfo());
  System.out.printf("length: %s
", resCtx.getLength());
  System.out.printf("mediaType: %s
", resCtx.getMediaType());
  System.out.printf("date: %s
", resCtx.getDate());
  System.out.printf("language: %s
", resCtx.getLanguage());
  for (String name: resCtx.getHeaders().keySet()) {
    System.out.printf("header[%s] => %s
",name, resCtx.getHeaderString(name) );
  }
  for (String name: resCtx.getCookies().keySet()) {
    System.out.printf("cookie[%s] => %s
",name, resCtx.getHeaderString(name) );
  }
  System.out.printf("**** END CLIENT RESPONSE ****

");
}

We have access to the response header, content type, length, data, and also cookies. To find out more information, it is worth your while examining the API in detail for both ClientRequestContext and ClientResponseContext.

To configure the filter from the unit test, we set up the ClientBuilder in the following way:

@Test
public void shouldRetrieveBookList() throws Exception {
  WebTarget target = ClientBuilder.newClient()
  .register(new DebugClientLoggingFilter())
  .target("http://localhost:8080/mywebapp/rest/async/books");
  Future<Response> future = target.request().async().get();
    /* ... */
}

DebugClientLoggingFilter is registered on the builder object.

The following is a screenshot of the unit test in action:

If you are going to unit test the server response in an application, why would you not choose the JAX-RS client side library? It is a no brainer.

We shall move on to entity interceptors.

There is still one other way to configure binding to a resource. Whereas the @NameBinding annotation means the configuration is a static means for a dynamic or runtime application of behavior that we cannot use this feature. Luckily, JAX-RS 2.0 provides an additional interface javax.ws.js.container.DynamicInterface.

The dynamic interface is designed for the registration of post-matching providers during a JAX-RS application initialization at the time of deployment. There is one single interface to implement called configure() and it takes two arguments, namely javax.ws.js.container.ResourceInfo and javax.ws.js.core.FeatureContext.

Let us write a new configuration feature class AESCipherDynamicFeature, which supports dynamic binding. Following is the new code snippet:

@Provider
public class AESCipherDynamicFeature 
implements DynamicFeature 
@Override
public void configure(ResourceInfo resourceInfo,FeatureContext config ) {
  if ( SensitiveResource.class.isAssignableFrom(resourceInfo.getResourceClass() &&resourceInfo.getResourceMethod()
    .isAnnotationPresent(GET.class)) {
    config.register( 
      new AESCipherInterceptor() );
    }
  }
}

The class must be annotated with the @Provider in order to be successfully scanned by the JAX-RS runtime. Once the runtime discovers the new feature and it can see that the class is a type of DynamicFeature then the runtime invokes configure() method. We verify the resource that we want to protect is the target, and we also check the REST style resource method is the correct one to apply this interceptor. Is this resource method the HTTP GET request method? When these conditions are true, then we use the FeatureContext instance to configure and associate an instance of the interceptor with the resource.