javax.servlet.Filter

javax.servlet.Filter 接口

http://docs.oracle.com/javaee/6/api/javax/servlet/Filter.html

接口原型

public interface Filter {
public void init(FilterConfig filterConfig) throws ServletException;
public void doFilter(ServletRequest request, ServletResponse response,
FilterChain chain)
throws IOException, ServletException;
public void destroy();
}

Filter接口文档

英文文档

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, and 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:
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 Filter

Since:
Servlet 2.3

中文翻译

Filter 是一个在 资源请求（servlet或静态内容） 或 内容响应 中执行过滤任务的对象。

Filter 在 doFilter 方法内执行过滤。每一个 Filter 可以访问一个 FilterConfig 对象，
通过该对象，filter 可以获取到初始化参数和 ServletContext 引用，该引用可以用于加载过滤任务的所需的资源。

Filter 被配置在一个 Web 部署描述（文件）中。

已经确定可用于的设计例子如下：
身份认证 Filters
日志和审计 Filters
图像转换 Filters
数据压缩 Filters
加密 Filters
令牌化 Filters
触发资源访问事件的 Filters
XSL/T filters
Mime-type chain （mime类型链） Filter

Since:
Servlet 2.3

init 方法文档

英文文档

public void init(FilterConfig filterConfig) throws ServletException;

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 a ServletException
Does not return within a time period defined by the web container

Parameters:
filterConfig

Throws:
ServletException

中文翻译

此方法被容器调用，用于预示此 filter 正在被放入 service。

一旦 filter 初始化完，Servlet 容器会正确地调用此 init 方法。在被要求执行过滤任务前，次 init 方法必须执行完成。

出现以下情况时，Web 容器不会把此 filter 对象放入 service：
抛出 ServletException 时
在 Web 容器规定的一段时间周期内没有返回时

Parameters：
filterConfig

Throws:
ServletException

doFilter 方法注释

英文文档

public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException;

The doFilter method of the 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 FilterChain 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:

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. Either invoke the next entity in the chain using the FilterChain object (chain.doFilter()),
or not pass on the request/response pair to the next entity in the filter chain to block the request processing
5.Directly set headers on the response after invocation of the next entity in the filter chain.

Parameters:
request
response
chain
Throws:
IOException
ServletException

中文翻译

Filter 的 doFilter 方法由容器调用，每一次客户端请求资源时，都会有一对 request/response 被传递到 filter chain。
FilterChain 对象被传入此方法，允许 Fitler 把 request/response 传递给FilterChain里的下一个 filter。请求的资源会在 chain 执行完之后才被访问到。

此方法的标准实现将遵循以下模式：
1. 检查请求
2. 选择性地，为 input filtering 使用使用自定义的 filter content 或 headers 实现对请求进行转化。
3. 选择性地，为 output filtering 使用使用自定义的 filter content 或 headers 实现对响应进行转化。
4. 使用 FilterChain 对象的 chain.doFilter() 方法调用 filter chain 里的下一个filter， 或不再把一对 request/response 传给filter chain 里的下一个filter，阻止该请求处理。
5. 在调用 filter chain 里的下一个filter 之后，直接设置 response 的 headers。

Parameters:
request
response
chain
Throws:
IOException
ServletException

destroy 方法注释

英文文档

public void destroy();

Called by the web container to indicate to a filter that it is being taken out of service.

This method is only called once all threads within the filter's doFilter method have exited or after a timeout period has passed.
After the web container calls this method, it will not call the doFilter method again on this instance of the filter.

This method gives the filter an opportunity to clean up any resources that are being held (for example, memory, file handles, threads)
and make sure that any persistent state is synchronized with the filter's current state in memory.

中文翻译

此方法被容器调用，用于预示此 filter 正在被移出 service。

此方法仅会在所有在 doFilter 里的线程已退出或者一段时间周期之后被调用。
当 web 容器调用此方法之后，容器将不会再调用此 filter 实例的 doFilter 方法。

此方法给了 filter 一个机会去释放被自己占用的所有资源（例如：内存，文件句柄，线程等），
和去确保所有持久化的状态与当前内存中的状态同步。

总结

Filter 用于请求和响应流程中进行滤。

init 和 destroy 是 Filter 的生命周期方法，由 Servlet 容器调用。

一旦 filter 初始化完成，容器会调用 Filter 的 init 方法，预示 filter 正在被放入 service。

filter 被移出 service 时，容器会调用 Filter 的 destroy 方法。

Filter 及 FilterChain 会在请求的目标资源被访问之前调用。

doFilter 方法执行过滤逻辑。执行完过滤逻辑后，可以调用 chain.doFilter() 方法继续执行下一个 filter，也可不再调用，从而阻止请求处理。