Two Ways for Partial Facelets Adoption

Summary

This article explains two ways to use JSP-based JSF and Facelets-based JSF in the same project, one of which is well known while the other is less known and is worth writing about.

Motivation and Prefix Mapping Technique

Say, you have hundreds of JSP-based JSF files and you want to switch to Facelets. Some people say it is fairly easy to manually conver them and it would take a day or two, but you don't want to risk. So you need to use JSP and Facelets in the same JSF project. A well known way to do this is to use prefix mapping technique as described here. With this technique, *.xhtml files will use Facelets while *.jsp files will use JSP. A drawback is that you must use prefix mapping, thus URLs will have to change. It is a pain in some cases, when your pages have many incoming links, for example.

Suffix Mapping Technique

Fortunately, there is another way that use suffix mapping. With this technique, URLs don't have to change for your old JSP-based JSF. This could be done with some sacrifice: Facelets-based JSF files must have jsp extention instead of xhtml. To distinguish JSP and Facelets, name Facelets files *_.jsp for example. Then all *_.jsp files will use Facelets while the other *.jsp files will use JSP. In some cases, this is an easier way to adopt Facelets partially. To use this technique, you just configure your web.xml as below:

---

web.xml

<web-app>
    <!-- Default suffix for jsf files -->
    <context-param>
        <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
        <param-value>.jsp</param-value>
    </context-param>

    <!--
    Only jsf files with _.jsp suffix are processed with Facelets.
    Other .jsp files are processed as JSP-based JSF.
    -->
    <context-param>
        <param-name>facelets.VIEW_MAPPINGS</param-name>
        <param-value>*_.jsp</param-value>
    </context-param>

    <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
    </servlet>

    <!-- Url with .jsf suffix are passed to facesServlet -->
    <servlet-mapping>
        <servlet-name>facesServlet</servlet-name>
        <url-pattern>*.jsf</url-pattern>
    </servlet-mapping>
</web-app>

URL with .jsf extention are handled by FacesServlet. A suffix ".jsp" is used to determine the JSF view file, as specified by javax.faces.DEFAULT_SUFFIX param. If the view file ends with "_.jsp" then Facelets processes the view file, otherwise the view processing is deligated to the default JSP engine.