Servlet::Filter - filter interface

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
- SEE ALSO
- AUTHOR

# 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. a)
     Either invoke the next entity in the chain by calling `doFilter()` on $chain,

  5. 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

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

# AUTHOR

Brian Moseley, bcm@maz.org