|
|
| |
Filters
The following sections provide information about using filters in a Web Application:
Overview of Filters
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 m odify the response and request objects or execute other tasks.
Filters are an advanced J2EE 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.
Note: Filters are a new feature in the Java servlet specification, version 2.3 from Sun Microsystems. Version 2.3 is a proposed final draft of the servlet specification. If you are planning to use filters in your application, note that the specification has not been finalized and could change in the future.
The Servlet 2.3 specification is part of the J2EE 1.3 specification. To use J2EE 1.3 features, please see WebLogic Server 6.1 with J2EE 1.2 and J2EE 1.3 Functionality.
WebLogic Server 6.1 with J2EE 1.2 and J2EE 1.3 Functionality
BEA WebLogic Server 6.1 is the first e-commerce transaction platform to implement advanced J2EE 1.3 features. To comply with the rules governing J2EE, BEA Systems provides two separate downloads: one with J2EE 1.3 features enabled, and one that is limited to J2EE 1.2 features only. Both downloads offer the same container and differ only in the APIs that are available.
WebLogic Server 6.1 with J2EE 1.2 Plus Additional J2EE 1.3 Features
With this download, WebLogic Server defaults to running with J2EE 1.3 features enabled. These features include EJB 2.0, JSP 1.2, Servlet 2.3, and J2EE Connector Architecture 1.0. When you run WebLogic Server 6.1 with J2EE 1.3 features enabled, J2EE 1.2 applications are still fully supported. The J2EE 1.3 feature implementations use non-final versions of the appropriate API specifications. Therefore, application code developed for BEA WebLogic Server 6.1 that uses the new features of J2EE 1.3 may be incompatible with the J2EE 1.3 platform supported in future releases of BEA WebLogic Server.
WebLogic Server 6.1 with J2EE 1.2 Certification
With this download, WebLogic Server defaults to running with J2EE 1.3 features disabled and is fully compliant with the J2EE 1.2 specification and regulations.
How Filters Work
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.
Uses for Filters
Filters can be useful for the following functions:
Configuring Filters
You configure filters as part of a Web Application, using the application's web.xml deployment descriptor. In the deployment descriptor, you declare the filter and then map the filter to a URL pattern or to a specific servlet in the Web Application. You can declare any number of filters.
Configuring a Filter
To configure a filter:
<filter> <icon> <small-icon>MySmallIcon.gif</small-icon> <large-icon>MyLargeIcon.gif</large-icon> </icon> <filter-name>myFilter1</filter-name> <display-name>filter 1</display-name> <description>This is my filter</description> <filter-class>examples.myFilterClass</filter-class> </filter>
The icon, description, and display-name elements are optional.
<filter> <icon> <small-icon>MySmallIcon.gif</small-icon> <large-icon>MyLargeIcon.gif</large-icon> </icon> <filter-name>myFilter1</filter-name> <display-name>filter 1</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 parameters using the FilterConfig.getInitParameter() or FilterConfig.getInitParameters() methods.
<filter-mapping> <filter-name>myFilter</filter-name> <url-pattern>/myPattern/*</url-pattern> </filter-mapping>
<filter-mapping> <filter-name>myFilter</filter-name> <servlet-hame>myServlet</servlet-name> </filter-napping>
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:
In your filter class, use the FilterChain.doFilter() method to invoke the next item in the chain.
Writing a Filter
To write a filter class, implement the javax.servlet.Filter interface. You must implement the following methods of this interface:
Several other methods are available on the FilterConfig object for accessing the name of the filter, the ServletContext and the filter's initialization parameters. For more information see the J2EE javadocs from Sun Microsystems for javax.servlet.FilterConfig.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.
Example of a Filter Class
The following code example demonstrates the basic structure of a Filter class.
Listing 7-1 Filter Class Example
import javax.servlet.*; public class Filter1Impl implements Filter { private FilterConfig filterConfig; public void doFilter(ServletRequest req, ServletResponse res, FilterChain fc) throws java.io.IOException, javax.servlet.ServletException { // Execute a task such as logging. //... fc.doFilter(req,res); // invoke next item in the chain -- // either another filter or the // originally requested resource. } public FilterConfig getFilterConfig() { // Execute tasks return filterConfig; } public void setFilterConfig(FilterConfig cfg) { // Execute tasks filterConfig = cfg; } }
Filtering the Servlet Response Object
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 the J2EE javadocs from Sun Microsystems for javax.servlet.http.HttpServletResponseWrapper and javax.servlet.http.HttpServletRequestWrapper. .
Additional Resources
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|