Package com.sun.jersey.api.container.filter

Provides common server-side filters.

There are two types of filter that may be registered with Jersey:

1. Container filters, which are filters that are registered to filter the request before the request is matched and dispatched to a root resource class, and filters that are registered to filter the response after the response has returned from a resource method.
2. Resource filters, which are filters that are registered to filter requests and responses specific to resource methods, sub-resource methods and sub-resource locators.

A request will be filtered by container filters before the request is filtered by resource filters. A response will be filtered by resource filters before the response is filtered by container filters.

Container filters are registered as properties of the ResourceConfig. Container request filters, of the class ContainerRequestFilter, are registered using the property ResourceConfig.PROPERTY_CONTAINER_REQUEST_FILTERS. Container response filters, of the class ContainerResponseFilter, are registered using the property ResourceConfig.PROPERTY_CONTAINER_RESPONSE_FILTERS.

For example, to log requests and responses when an application is deployed as a Servlet or Filter a LoggingFilter can be registered using the following initialization parameters:

     <init-param>
         <param-name>com.sun.jersey.spi.container.ContainerRequestFilters</param-name>
         <param-value>com.sun.jersey.api.container.filter.LoggingFilter</param-value>
     </init-param>
     <init-param>
         <param-name>com.sun.jersey.spi.container.ContainerResponseFilters</param-name>
         <param-value>com.sun.jersey.api.container.filter.LoggingFilter</param-value>
     </init-param>
 

Note that two or more request or response filters may be registered as a ';' separated list of fully qualified class names.

Resource filters are registered using two mechanisms:

1. As resource filter factories. Resource filter factories, of the class ResourceFilterFactory, are registered using the property ResourceConfig.PROPERTY_RESOURCE_FILTER_FACTORIES.
2. As resource filters, of the class ResourceFilter, declared using the annotation ResourceFilters, which may occur on a resource class, resource method, sub-resource method or sub-resource locator.

A request will be filtered by filters produced by resource filter factories before a request is filtered by resource filters declared by annotation. A response will be filtered by resource filters declared by annotation before the response is filtered by filters produced by resource filter factories.

For example, to support RolesAllowed on resource classes when an application is deployed as a Servlet or Filter a RolesAllowedResourceFilterFactory can be registered using the following initialization parameter:

     <init-param>
         <param-name>com.sun.jersey.spi.container.ResourceFilters</param-name>
         <param-value>com.sun.jersey.api.container.filter.RolesAllowedResourceFilterFactory</param-value>
     </init-param>
 

Note that two or more resource filter factories may be registered as a ';' separated list of fully qualified class names.

The use of resource filter factories allow the application of filters to any method of a resource class that conforms to a certain pattern as defined by a resource filter factory implementation. For example, the support for the annotation ResourceFilters is implemented as a resource filter factory, that is registered after all user-registered resource filter factories.

If an exception is thrown by a request filter (registered using any mechanism) then:

1. the request processing is terminated;
2. the exception is mapped to a response; and
3. the response is filtered by the response filters.

If an exception is thrown by a response filter (registered using any mechanism) then:

1. the response processing is terminated;
2. the exception is mapped to a response; and
3. the response is returned to the client.