Filter (Java EE 5)

Java EE API

previous page next page

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.servlet Interface Filter

public interface Filter

过滤器是执行过滤任务的对象，这些任务是针对对某一资源（servlet 或静态内容）的请求或来自某一资源的响应执行的，抑或同时针对这两者执行。

Filter 用 doFilter 方法执行过滤。每个 Filter 都有对 FilterConfig 对象的访问权，可从该对象获得其初始化参数以及对它可以使用的 ServletContext 的引用，以便为过滤任务加载所需的资源。

Filter 是在 Web 应用程序的部署描述符中配置的。

已经标识用于此设计的示例是
1) 验证过滤器
2) 日志记录和审计过滤器
3) 图像转换过滤器
4) 数据压缩过滤器
5) 加密过滤器
6) 标记过滤器
7) 触发资源访问事件的过滤器
8) XSL/T 过滤器
9) Mime 类型链过滤器

since

Servlet 2.3

英文文档：

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

Since:: Servlet 2.3

Method Summary
`void`	`destroy()` Called by the web container to indicate to a filter that it is being taken out of service.
`void`	`doFilter(ServletRequest request, ServletResponse response, FilterChain chain)` 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.
`void`	`init(FilterConfig filterConfig)` Called by the web container to indicate to a filter that it is being placed into service.

Method Detail

public void init(FilterConfig filterConfig) throws ServletException
由 Web 容器调用，指示将放入服务中的过滤器。servlet 容器只在实例化过滤器之后调用一次 init 方法。在要求过滤器做任何过滤工作之前，init 方法必须成功完成。

如果 init 方法
1.抛出 ServletException
2.没有在 Web 容器定义的时间段内返回，则 Web 容器无法将过滤器放入服务中。

英文文档：
init

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

Throws:: ServletException

public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws java.io.IOException, ServletException
每次由于对链末尾的某个资源的客户端请求而通过链传递请求/响应对时，容器都会调用 Filter 的 `doFilter` 方法。传入此方法的 FilterChain 允许 Filter 将请求和响应传递到链中的下一个实体。
此方法的典型实现遵循以下模式：-
1. 检查请求
2. 有选择地将带有自定义实现的请求对象包装到用于输入过滤的过滤器内容或头中
3. 有选择地将带有自定义实现的响应对象包装到用于输出过滤的过滤器内容或头中
4. a) 既可以使用 FilterChain 对象 (`chain.doFilter()`) 调用链中的下一个实体，
4. b) 也可以不将请求/响应对传递给过滤器链中的下一个实体，从而阻塞请求处理
5. 在调用过滤器链中的下一个实体之后直接设置响应上的头。

英文文档：
doFilter

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. a) Either invoke the next entity in the chain using the FilterChain object (chain.doFilter()),
4. b) 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.

Throws:: IOException; ServletException

public void destroy()
由 Web 容器调用，指示将从服务中取出的过滤器。此方法仅在过滤器的 doFilter 方法中的所有线程都已退出之后调用一次，或者在过了超时期之后调用。在调用此方法之后，Web 容器不会再对此过滤器实例调用 doFilter 方法。

此方法为过滤器提供了一个清除持有的所有资源（比如内存、文件句柄和线程）的机会，并确保任何持久状态都与内存中该过滤器的当前状态保持同步。

英文文档：
destroy

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.