A filter is an object that performs filtering tasks on either the request to a resource (a servlet or static content), or on the response from a resource, or both. More...

#include <filter.h>

Public Member Functions
virtual void	init ()
	A convenience method which can be overridden so that there's no need to call `init(filter_config)`. More...

virtual void	init (filter_config &cfg)
	Called by the web container to indicate to a filter that it is being placed into service. More...

virtual void	do_filter (http_request &request, http_response &response, filter_chain &chain)=0
	The `do_filter` method of the http_filter is called by the container each time a request/response pair is passed through the chain due to a client request for a resource at the end of the chain. More...

const filter_config &	get_filter_config () const
	Returns a `filter_config` object, which contains initialization and startup parameters for this filter. More...

const std::string &	get_filter_name () const
	Returns the name of this filter instance. More...

const std::map< std::string, std::string, std::less<> > &	get_init_parameters () const
	Returns the all of the filter's initialization parameters as an `tree_map` of `std::string` objects, or an empty `tree_map` if the servlet has no initialization parameters. More...

template<typename KeyType >
optional_ref< const std::string >	get_init_parameter (const KeyType &name) const
	Returns an optional `std::string` containing the value of the named initialization parameter, or `null` if the parameter does not exist. More...

Detailed Description

A filter is an object that performs filtering tasks on either the request to a resource (a servlet or static content), or on the response from a resource, or both.

Filters perform filtering in the doFilter method. Every Filter has access to a FilterConfig object from which it can obtain its initialization parameters, a reference to the 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
1) Authentication Filters
2) Logging and Auditing Filters
3) Image conversion Filters
4) Data compression Filters
5) Encryption Filters
6) Tokenizing Filters
7) Filters that trigger resource access events
8) XSL/T filters
9) Mime-type chain Filter

In order to make the filter available to mod_servlet a factory method should be provided and exported. The easiest way to do this is to use FILTER_EXPORT like this:

class my_filter : public servlet::http_filter
{
  ...
};
FILTER_EXPORT(myFilterFac, my_filter);

If the filter cannot be trivially created or requires special preparation before it is available to mod_servlet container than factory method should be coded manually:

class my_filter : public servlet::http_filter
{
  ...
};
extern "C" servlet::http_filter* myFilterFac()
{
    my_filter* filter = nullptr;
    // Create and prepare the filter instance
    return filter;
}

Member Function Documentation

virtual void servlet::http_filter::do_filter	(	http_request &	request,
		http_response &	response,
		filter_chain &	chain
	)

pure virtual

The do_filter method of the http_filter is called by the container each time a request/response pair is passed through the chain due to a client request for a resource at the end of the chain.

The filter_chain passed in to this method allows the Filter to pass on the request and response to the next entity in the chain.

A typical implementation of this method would follow the following pattern:-

Examine the request
Optionally wrap the request object with a custom implementation to filter content or headers for input filtering
Optionally wrap the response object with a custom implementation to filter content or headers for output filtering
a) Either invoke the next entity in the chain using the filter_chain object (chain.do_filter()),

b) or not pass on the request/response pair to the next entity in the filter chain to block the request processing
Directly set headers on the response after invocation of the next entity in the filter chain.

Parameters

request	The request to process
response	The response associated with the request
chain	Provides access to the next filter in the chain for this filter to pass the request and response to for further processing

const filter_config& servlet::http_filter::get_filter_config ( ) const

inline

Returns a filter_config object, which contains initialization and startup parameters for this filter.

The filter_config object returned is the one passed to the init method.

Method init is responsible for storing the filter_config object so that this method can return it.

Returns: the filter_config object that initializes this filter

See Also: init

const std::string& servlet::http_filter::get_filter_name ( ) const

inline

Returns the name of this filter instance.

The name may be provided via server administration, assigned in the web application deployment descriptor, or for an unregistered (and thus unnamed) filter instance it will be the filter's class name.

Returns: the name of the filter instance

template<typename KeyType >

optional_ref<const std::string> servlet::http_filter::get_init_parameter ( const KeyType & name ) const

inline

Returns an optional std::string containing the value of the named initialization parameter, or null if the parameter does not exist.

This method is supplied for convenience. It gets the value of the named parameter from the servlet's filter_config object.

Parameters

name	a `string` specifying the name of the initialization parameter

Returns: String an optional reference to std::string containing the value of the initialization parameter

See Also: servlet_config::get_init_parameter

const std::map<std::string, std::string, std::less<> >& servlet::http_filter::get_init_parameters ( ) const

inline

Returns the all of the filter's initialization parameters as an tree_map of std::string objects, or an empty tree_map if the servlet has no initialization parameters.

See filter_config::get_init_parameters.

This method is supplied for convenience. It gets the parameter names from the servlet's filter_config object.

Returns: a tree_map of std::string objects containing all of the filter's initialization parameters

See Also: filter_config::get_init_parameters

virtual void servlet::http_filter::init ( )

inlinevirtual

A convenience method which can be overridden so that there's no need to call init(filter_config).

Instead of overriding init(filter_config&), simply override this method and it will be called by init(filter_config config). The filter_config object can still be retrieved via get_filter_config.

See Also: init(filter_config&)

virtual void servlet::http_filter::init ( filter_config & cfg )

virtual

Called by the web container to indicate to a filter that it is being placed into service.

The servlet container calls the init method exactly once after instantiating the filter. The init method must complete successfully before the filter is asked to do any filtering work.

The web container cannot place the filter into service if the init method either:

Throws an exception
Does not return within a time period defined by the web container

Parameters

cfg	The configuration information associated with the filter instance being initialised

See Also: init

The documentation for this class was generated from the following file:

include/servlet/filter.h

Public Member Functions

Detailed Description

Member Function Documentation