What is the Extensions Filter for?

Some MyFaces components do more than include some HTML in the pages. They may need additional support scripts, style sheets, images, ...
Those resources are included in the MyFaces' jar file and the Extensions Filter adds the code and URL needed to provide those resources to the generated HTML.

Some other components, like the file upload component (t:inputFileUpload), need to parse Multipart requests.
The extensions filter handles this as well.

Why is this useful?

This design has several benefits :

1. It provides a clean separation between MyFaces' components and your webapp.
2. You don't have to include additional MyFaces' components-related code or resources in your pages or webapp.
3. It provides flexibility so that the MyFaces' team can upgrade the components while keeping transparent backward compatibility.
4. It makes it possible for complex components to use many support resources without any burden on the page developer.
5. It loads only the resources useful for the rendered components.
6. It handles the MyFaces' resources caching.

How does it work?

When a component needs a resource, it calls one of the org.apache.myfaces.component.html.util.AddResource methods (for example AddResource.addJavaScriptToHeader(InputHtmlRenderer.class, "sarissa.js", context); ).
The AddResource methods add an attribute to the request so that the filter is notified to include the given javascript, stylesheet, or resource link in the generated HTML for your JSF page.
The URL for an embedded resource begins with /faces/myFacesExtensionResource so that it can be intercepted by the filter when the client needs to load the resource.
When the clients fetches the resource, the filter also decodes the URL, and serves the proper resource from the MyFaces' jar.

How do I configure it?

In your web.xml, map this filter to the path used for the JSF pages (most likely *.jsf) so the filter can update resource links on your JSF pages, and also map the filter to the /faces/myFacesExtensionResource/* path so it can serve page-independent resources like images, javascript files, and stylesheets. Here's one example of configuring the extensions filter:

<filter>
	<filter-name>MyFacesExtensionsFilter</filter-name>
	<filter-class>org.apache.myfaces.webapp.filter.ExtensionsFilter</filter-class>
    <init-param>
        <param-name>uploadMaxFileSize</param-name>
        <param-value>20m</param-value>
        <description>Set the size limit for uploaded files.
            Format: 10 - 10 bytes
                    10k - 10 KB
                    10m - 10 MB
                    1g - 1 GB
        </description>
    </init-param>
</filter>

<!-- extension mapping for adding <script/>, <link/>, and other resource tags to JSF-pages  -->
<filter-mapping>
    <filter-name>MyFacesExtensionsFilter</filter-name>
    <!-- servlet-name must match the name of your javax.faces.webapp.FacesServlet entry -->
    <servlet-name>Faces Servlet</servlet-name>
</filter-mapping>

<!-- extension mapping for serving page-independent resources (javascript, stylesheets, images, etc.)  -->
<filter-mapping>
    <filter-name>MyFacesExtensionsFilter</filter-name>
    <url-pattern>/faces/myFacesExtensionResource/*</url-pattern>
</filter-mapping>
	

Alternate mapping using a url-pattern instead of a servlet-name (you still need the /faces/myFacesExtensionResource/* mapping as well):

<!-- extension mapping for adding <script/>, <link/>, and other resource tags to JSF-pages  -->
<filter-mapping>
    <filter-name>MyFacesExtensionsFilter</filter-name>
    <url-pattern>*.jsf</url-pattern>
</filter-mapping>
	

What configuration settings are available?

See the javadoc for class ExtensionsFilter for information on the full set of configuration options for this filter.

Under what circumstances am I *required* to use the extensions filter?

If you just use standard JSF component, but don't use any MyFaces' extended component (beginning with t:), then you don't need the Extensions Filter.
However, if you use some of the MyFaces' extended components like t:inputFileUpload, t:inputHtml, t:inputCalendar, ... then you most likely need to have this filter configured in your webapp.

Does this impact performance?

The filter hasn't any significant impact the response time.
However, as the filter has to cache the whole response in memory before writing it out to the client, it slightly increases the memory usage.