This chapter describes how to use Java classes known as filters in WebLogic Web applications.
This chapter includes the following sections:
A filter is a Java class that is invoked in response to a request for a resource in a Web application. Resources include Java servlets, JavaServer pages (JSP), and static resources such as HTML pages or images. A filter intercepts the request and can examine and modify the response and request objects or execute other tasks.
Filters are an advanced Java EE feature primarily intended for situations where the developer cannot change the coding of an existing resource and needs to modify the behavior of that resource. Generally, it is more efficient to modify the code to change the behavior of the resource itself rather than using filters to modify the resource. In some situations, using filters can add unnecessary complexity to an application and degrade performance.
You define filters in the context of a Web application. A filter intercepts a request for a specific named resource or a group of resources (based on a URL pattern) and executes the code in the filter. For each resource or group of resources, you can specify a single filter or multiple filters that are invoked in a specific order, called a chain.
When a filter intercepts a request, it has access to the javax.servlet.ServletRequest
and javax.servlet.ServletResponse
objects that provide access to the HTTP request and response, and a javax.servlet.FilterChain
object. The FilterChain
object contains a list of filters that can be invoked sequentially. When a filter has completed its work, the filter can either call the next filter in the chain, block the request, throw an exception, or invoke the originally requested resource.
After the original resource is invoked, control is passed back to the filter at the bottom of the list in the chain. This filter can then examine and modify the response headers and data, block the request, throw an exception, or invoke the next filter up from the bottom of the chain. This process continues in reverse order up through the chain of filters.
Note:
The filter can modify the headers only if the response has not already been committed.Filters can be useful for the following functions:
Implementing a logging function
Implementing user-written security functionality
Debugging
Encryption
Data compression
Modifying the response sent to the client. (However, post processing the response can degrade the performance of your application.)
To write a filter class, implement the javax.servlet.Filter
interface (see http://docs.oracle.com/javaee/7/api/javax/servlet/Filter.html
). You must implement the following methods of this interface:
init()
destroy()
doFilter()
You use the doFilter()
method to examine and modify the request and response objects, perform other tasks such as logging, invoke the next filter in the chain, or block further processing.
Several other methods are available on the FilterConfig
object for accessing the name of the filter, the ServletContext
and the filter's initialization attributes. For more information see the Java EE javadocs for javax.servlet.FilterConfig
at http://docs.oracle.com/javaee/7/api/javax/servlet/FilterConfig.html
.
To access the next item in the chain (either another filter or the original resource, if that is the next item in the chain), call the FilterChain.doFilter()
method.
You configure filters as part of a Web application, using the application's web.xml
deployment descriptor. In the deployment descriptor, you specify the filter and then map the filter to a URL pattern or to a specific servlet in the Web application. You can specify any number of filters.
To configure a filter:
Open the web.xml
deployment descriptor in a text editor or use the WebLogic Server Administration Console. For more information, see Web Application Developer Tools. The web.xml
file is located in the WEB-INF
directory of your Web application.
Add a filter declaration. The filter
element declares a filter, defines a name for the filter, and specifies the Java class that executes the filter. The filter
element must directly follow the context-param
element and directly precede the listener
and servlet
elements. For example:
<context-param>Param</context-param> <filter> <icon> <small-icon>MySmallIcon.gif</small-icon> <large-icon>MyLargeIcon.gif</large-icon> </icon> <filter-name>myFilter</filter-name> <display-name>My Filter</display-name> <description>This is my filter</description> <filter-class>examples.myFilterClass</filter-class> </filter> <listener>Listener</listener> <servlet>Servlet</servlet>
The icon
, description
, and display-name
elements are optional.
Specify one or more initialization attributes inside a filter
element. For example:
<filter> <icon> <small-icon>MySmallIcon.gif</small-icon> <large-icon>MyLargeIcon.gif</large-icon> </icon> <filter-name>myFilter</filter-name> <display-name>My Filter</display-name> <description>This is my filter</description> <filter-class>examples.myFilterClass</filter-class> <init-param> <param-name>myInitParam</param-name> <param-value>myInitParamValue</param-value> </init-param> </filter>
Your Filter
class can read the initialization attributes using the FilterConfig.getInitParameter()
or FilterConfig.getInitParameters()
methods.
Add filter mappings. The filter-mapping
element specifies which filter to execute based on a URL pattern or servlet name. The filter-mapping
element must immediately follow the filter
element(s).
To create a filter mapping using a URL pattern, specify the name of the filter and a URL pattern. URL pattern matching is performed according to the rules specified in the Servlet 3.1 specification at http://jcp.org/en/jsr/detail?id=340
. For example, the following filter-mapping
maps myFilter
to requests that contain /myPattern/
.
<filter-mapping> <filter-name>myFilter</filter-name> <url-pattern>/myPattern/*</url-pattern> </filter-mapping>
To create a filter mapping for a specific servlet, map the filter to the name of a servlet that is registered in the Web application. For example, the following code maps the myFilter
filter to a servlet called myServlet
:
<filter-mapping> <filter-name>myFilter</filter-name> <servlet-hame>myServlet</servlet-name> </filter-mapping>
To create a chain of filters, specify multiple filter mappings. For more information, see Configuring a Chain of Filters.
WebLogic Server creates a chain of filters by creating a list of all the filter mappings that match an incoming HTTP request. The ordering of the list is determined by the following sequence:
Filters where the filter-mapping
element contains a url-pattern
that matches the request are added to the chain in the order they appear in the web.xml
deployment descriptor.
Filters where the filter-mapping
element contains a servlet-name
that matches the request are added to the chain after the filters that match a URL pattern.
The last item in the chain is always the originally requested resource.
In your filter class, use the FilterChain.doFilter()
method to invoke the next item in the chain.
You can use filters to post-process the output of a servlet by appending data to the output generated by the servlet. However, in order to capture the output of the servlet, you must create a wrapper for the response. (You cannot use the original response object, because the output buffer of the servlet is automatically flushed and sent to the client when the servlet completes executing and before control is returned to the last filter in the chain.) When you create such a wrapper, WebLogic Server must manipulate an additional copy of the output in memory, which can degrade performance.
For more information on wrapping the response or request objects, see javax.servlet.http.HttpServletResponseWrapper
and javax.servlet.http.HttpServletRequestWrapper
at http://docs.oracle.com/javaee/7/api/javax/servlet/http/package-summary.html
.
Servlet 3.1 specification at http://jcp.org/en/jsr/detail?id=340
Java EE 7 API Reference (Javadocs) at http://docs.oracle.com/javaee/7/api/index.html
The Java EE tutorial at http://docs.oracle.com/javaee/7/tutorial/index.html