javax.ws.rs.container

## Interface ContainerRequestFilter

-     public interface ContainerRequestFilter

  An extension interface implemented by container request filters.

  By default, i.e. if no `name binding` is applied to the filter implementation class, the filter instance is applied globally, however only after the incoming request has been matched to a particular resource by JAX-RS runtime. If there is a `@NameBinding` annotation applied to the filter, the filter will also be executed at the post-match request extension point, but only in case the matched `resource or sub-resource method` is bound to the same name-binding annotation.

  In case the filter should be applied at the pre-match extension point, i.e. before any request matching has been performed by JAX-RS runtime, the filter MUST be annotated with a `@PreMatching` annotation.

  Use a pre-match request filter to update the input to the JAX-RS matching algorithm, e.g., the HTTP method, Accept header, return cached responses etc. Otherwise, the use of a request filter invoked at the post-match request extension point (after a successful resource method matching) is recommended.

  Filters implementing this interface must be annotated with `@Provider` to be discovered by the JAX-RS runtime. Container request filter instances may also be discovered and bound `dynamically` to particular resource methods.

  Since:
    2.0
  Author:
    Marek Potociar, Santiago Pericas-Geertsen
  See Also:
    `PreMatching`, `ContainerResponseFilter`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `filter(ContainerRequestContext requestContext)` Filter method called before a request has been dispatched to a resource.

- - ### Method Detail

    - #### filter

          void filter(ContainerRequestContext requestContext)
                      throws IOException

      Filter method called before a request has been dispatched to a resource.

      Filters in the filter chain are ordered according to their `javax.annotation.Priority` class-level annotation value. If a request filter produces a response by calling `ContainerRequestContext.abortWith(javax.ws.rs.core.Response)` method, the execution of the (either pre-match or post-match) request filter chain is stopped and the response is passed to the corresponding response filter chain (either pre-match or post-match). For example, a pre-match caching filter may produce a response in this way, which would effectively skip any post-match request filters as well as post-match response filters. Note however that a responses produced in this manner would still be processed by the pre-match response filter chain.

      Parameters:
        `requestContext` - request context.
      Throws:
        `IOException` - if an I/O exception occurs.
      See Also:
        `PreMatching`

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.