NAME

Servlet::Filter - filter interface

SYNOPSIS

  $filter->setFilterConfig($fconfig);

  # later

  $filter->doFilter($request, $response, $chain);

  my $config = $filter->getConfig();

DESCRIPTION

This is the interface for an object that performs filtering tasks on the request for a resource, the response, or both.

Filters perform filtering in the doFilter() method. Every filter has access to a Servlet::FilterConfig object from which it can obtain its initialization parameters and a reference to the Servlet::ServletContext which it can use, for example, to load resources needed for filtering tasks.

Filters are configured in the deployment descriptor of a web application.

Examples that have been identified for this design are:

Authentication Filters

Logging and Auditing Filters

Image conversion Filters

Data compression Filters

Encryption Filters

Tokenizing Filters

Filters that trigger resource access events

XSL/T Filters

MIME-type chain Filters

METHODS

doFilter($request, $response, $chain)

This method is called by the container each time a request/response pair is passed through the filter chain due to a client request for a resource at the end of the chain. The filter chain passed into this method allows the filter to passon the request and response to the next entity in the chain.

A typical implementation of this method would follow such a pattern:

1. Examine the request

2. Optionally wrap the request object with a custom implementation to filter content or headers for input filtering

3. Optionally wrap the response object with a custom implementation to filter content or headers for output filtering

4. 4 a)

   Either invoke the next entity in the chain by calling doFilter() on $chain,

5. 4 b)

   or block further filter processing by not passing the request/response pair down the chain

6. Directly set headers on the response after invocation of the next entity in the filter chain.

Parameters:

$request

the Servlet::ServletRequest object that contains the client's request

$response

the Servlet::ServletResponse object that contains the servlet's response

$chain

the Servlet::FilterChain through which the request and response are passed

Throws:

Servlet::ServletException

if an exception occurs while performing the filtering task

getFilterConfig()

Returns the Servlet::FilterConfig object for this filter

setFilterConfig($config)

Set the config object for this filter

Parameters:

$config

the Servlet::FilterConfig object for this filter

SEE ALSO

Servlet::FilterChain, Servlet::FilterConfig, Servlet::ServletException, Servlet::ServletRequest, Servlet::ServletResponse

AUTHOR

Brian Moseley, bcm@maz.org