org.apache.myfaces.webapp.filter
Class ExtensionsFilter

java.lang.Object
  org.apache.myfaces.webapp.filter.ExtensionsFilter

All Implemented Interfaces:

javax.servlet.Filter

Direct Known Subclasses:

ExtensionsFilter

public class ExtensionsFilter
extends Object
implements javax.servlet.Filter

This filter provides a number of functions that many tomahawk components require.

In tomahawk versions up to and including 1.1.6, it is mandatory to define this filter in the application's web.xml in order to use some tomahawk components. In Tomahawk version 1.1.7, this filter is now optional; when defined it will be used as for earlier versions. When omitted, the same functionality is now automatically provided via classes TomahawkFacesContextFactory and ServeResourcePhaseListener.

Response Buffering

When the request is for a JSF page, and the configured "resource manager" requires response buffering then a response wrapper is created which buffers the entire output from the current request in memory.

Tomahawk provides at least three "resource managers":

• DefaultAddResources (the default) does require response buffering.
• NonBufferingAddResource does not require response buffering, but it renders javascript on body and offer support in portlets enviroments.
• StreamingAddResources does not, but only provides a subset of the features of DefaultAddResources and therefore does not work with all Tomahawk components.

Only one "resource manager" may be configured for a webapp. See class AddResourceFactory for further details on configuring this.

When DefaultAddResources is enabled (default behaviour), the resulting response buffering does cause some unnecessary memory and performance impact for pages where no component in the page actually registers a resource that needs to be inserted into the page - but whether a page does that or not cannot be known until after the page has been rendered. In the rare case where a request to a JSF page generates non-html output (eg a PDF is generated as a response to a submit of a jsf page), the data is unfortunately buffered. However it is not post-processed, because its http content-type header will not be "text/html" (see other documentation for this class).

Inserting Resources into HTML responses (DefaultAddResources)

After the response has been completely generated (and cached in memory), this filter checks the http content-type header. If it is not html or xhtml, then the data is simply send to the response stream without further processing. For html or xhtml responses, this filter causes the data to be post-processed to insert any "resources" registered via the AddResources framework. This allows jsf components (and other code if it wants) to register data that should be output into an HTML page, particularly into places like an html "head" section, even when the component occurs after that part of the response has been generated.

The default "resource manager" (DefaultAddResources) supports inserting resources into any part of the generated page. The alternate class StreamingAddResources does not; it does not buffer output and therefore can only insert resources for a jsf component into the page after the point at which that component is rendered. In particular, this means that components that use external javascript files will not work with that "resource manager" as [script href=...] only works in the head section of an html page.

Serving Resources from the Classpath

Exactly what text gets inserted into an HTML page via a "resource" (see above) is managed by the AddResources class, not this one. However often it is useful for jsf components to be able to refer to resources that are on the classpath, and in particular when the resource is in the same jar as the component code. Servlet engines do not support serving resources from the classpath. However the AddResources framework can be used to generate a special url prefix that this filter can be mapped to, allowing this to be done. In particular, many Tomahawk components use this to bundle their necessary resources within the tomahawk jarfile.

When a request to such a url is found by this filter, the actual resource is located and streamed back to the user (no buffering required). See the AddResource class documentation for further details.

Handling File Uploads

Sometimes an application needs to allow a user to send a file of data to the web application. The html page needs only to include an input tag with type=file; clicking on this will prompt the user for a file to send. The browser will then send an http request to the server which is marked as a "mime multipart request" with normal http post parameters in one mime part, and the file contents in another mime part.

This filter also handles such requests, using the Apache HttpClient library to save the file into a configurable local directory before allowing the normal processing for the url that the post request refers to. A number of configuration properties on this filter control maximum file upload sizes and various other useful settings. See the documentation for the init method for more details.

Avoiding Processing

When the ExtensionsFilter is enabled, and the DefaultAddResources implementation is used then there is no way to avoid having the response buffered in memory. However as long as the mime-type set for the response data is not text/html then the data will be written out without any modifications.

Version:

$Revision: 954965 $ $Date: 2010-06-15 11:58:31 -0500 (Tue, 15 Jun 2010) $

Author:

Sylvain Vieujot (latest modification by $Author: lu4242 $)

Field Summary

static String

DOFILTER_CALLED

Constructor Summary

ExtensionsFilter()

Method Summary

void	destroy() Destroy method for this filter
void	doFilter(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain chain)
void	init(javax.servlet.FilterConfig filterConfig) Init method for this filter.
boolean	isValidContentType(String contentType)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DOFILTER_CALLED

public static final String DOFILTER_CALLED

See Also:

Constant Field Values

Constructor Detail

ExtensionsFilter

public ExtensionsFilter()

Method Detail

init

public void init(javax.servlet.FilterConfig filterConfig)

Init method for this filter.

The following filter init parameters can be configured in the web.xml file for this filter:

• uploadMaxFileSize
• uploadThresholdSize
• uploadRepositoryPath
• uploadMaxSize
• cacheFileSizeErrors

All size parameters may have the suffix "g" (gigabytes), "m" (megabytes) or "k" (kilobytes).

uploadMaxFileSize

Sets the maximum allowable size for uploaded files.

If the user attempts to upload a file which is larger than this, then the data is transmitted from the browser to the server (this cannot be prevented with standard HTML functionality). However the file will not be saved in memory or on disk. An error message will be added to the standard JSF error messages, and the page re-rendered (as for a validation failure).

The default value is 100 Megabytes.

uploadThresholdSize

Sets the size threshold beyond which files are written directly to disk. Files which are smaller than this are simply held in memory. The default is 1 Megabyte.

uploadRepositoryPath

Sets the directory in which temporary files (ie caches for those uploaded files that are larger than uploadThresholdSize) are to be stored.

uploadMaxSize

Sets the maximum allowable size for the current request. If not set, its value is the value set on uploadMaxFileSize param.

cacheFileSizeErrors

Catch and swallow FileSizeLimitExceededExceptions in order to return as many usable items as possible.

Specified by:

init in interface javax.servlet.Filter

doFilter

public void doFilter(javax.servlet.ServletRequest request,
                     javax.servlet.ServletResponse response,
                     javax.servlet.FilterChain chain)
              throws IOException,
                     javax.servlet.ServletException

Specified by:

doFilter in interface javax.servlet.Filter

Throws:

IOException

javax.servlet.ServletException

isValidContentType

public boolean isValidContentType(String contentType)

destroy

public void destroy()

Destroy method for this filter

Specified by:

destroy in interface javax.servlet.Filter