Tuesday, May 15, 2012

Decorating Error Pages with SiteMesh 2.4.x

I've encountered a problem when decorating error pages with SiteMesh 2.4.2. I thought that others may benefit from the fix that we've done. So, I'm explaining it here.

When using Jetty 7.x, and the following web.xml configuration, SiteMesh does not correctly decorate the HTTP 404 error page.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    version="2.5">

    <!-- Sitemesh filter -->
    <filter>
        <filter-name>sitemeshFilter</filter-name>
        <filter-class>com.opensymphony.sitemesh.webapp.SiteMeshFilter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>sitemeshFilter</filter-name>
        <url-pattern>/*</url-pattern>
        <dispatcher>REQUEST</dispatcher>
        <dispatcher>FORWARD</dispatcher>
        <dispatcher>ERROR</dispatcher>
    </filter-mapping>

    <error-page>
        <error-code>404</error-code>
        <location>/WEB-INF/pages/not-found.jsp</location>
    </error-page>

</web-app>

I'm not sure if this problem occurs in Tomcat 6.x. From my tests, when a URL to a non-existent page is used (e.g. http://localhost/…/xxx), a 404 page is expected. This should be decorated by SiteMesh. But it's not.

After further investigation, when the SiteMesh filter configuration is limited to *.jsp (see below, line 12), all non-existing URLs that do not match *.jsp do get decorated. So, xxx does get decorated (as expected). But xxx.jsp does not! This inconsistency led to some work-arounds that included using "flash"-scoped variables and a HttpServletResponse#sendRedirect() call to redirect to the 404 page.

<?xml version="1.0" encoding="UTF-8"?>
<web-app ...>

    <!-- Sitemesh filter -->
    <filter>
        <filter-name>sitemeshFilter</filter-name>
        <filter-class>com.opensymphony.sitemesh.webapp.SiteMeshFilter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>sitemeshFilter</filter-name>
        <url-pattern>*.jsp</url-pattern>
        <dispatcher>REQUEST</dispatcher>
        <dispatcher>FORWARD</dispatcher>
        <dispatcher>ERROR</dispatcher>
    </filter-mapping>

    <error-page>
        <error-code>404</error-code>
        <location>/WEB-INF/pages/not-found.jsp</location>
    </error-page>

</web-app>

This led me to look further into SiteMesh 2.4.2 code. After adding some debugging statements, I can see that the wrapped response was not used by Jetty in its HttpServletResponse#sendError() implementation. Thus, there was no content in SiteMesh's PageResponseWrapper. It was written directly to the original response, and not the wrapped response. So, in SiteMesh's point of view, there was no content to be decorated. But there is!

Given this finding, I looked for work-arounds. The result was some minor modification to the SiteMeshFilter and the following web.xml configuration.

<?xml version="1.0" encoding="UTF-8"?>
<web-app ...>

    <!-- Sitemesh filter -->
    <filter>
        <filter-name>sitemeshFilter</filter-name>
        <filter-class>com.opensymphony.sitemesh.webapp.SiteMeshFilter</filter-class>
    </filter>
    <filter>
        <filter-name>errorSitemeshFilter</filter-name>
        <filter-class>com.opensymphony.sitemesh.webapp.SiteMeshFilter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>errorSitemeshFilter</filter-name>
        <url-pattern>/*</url-pattern>
        <dispatcher>ERROR</dispatcher>
    </filter-mapping>
    <filter-mapping>
        <filter-name>sitemeshFilter</filter-name>
        <url-pattern>*.jsp</url-pattern>
        <dispatcher>REQUEST</dispatcher>
        <dispatcher>FORWARD</dispatcher>
    </filter-mapping>

    <error-page>
        <error-code>404</error-code>
        <location>/WEB-INF/pages/not-found.jsp</location>
    </error-page>

</web-app>

The changes to the SiteMeshFilter allowed multiple instances of the filter to co-exist and act separately. One instance handles ERROR pages (due to sendError() calls). The other instance handles non-error pages. I used the filter's name to differentiate the two instances. When a non-existent URL is encountered, the filter that handles ERROR pages decorates properly. When a non-existent URL that matches *.jsp is encountered, the "sitemeshFilter" gets to filter it. But since it is not existent, the servlet container ends up calling sendError(404). As expected, the "sitemeshFilter" could not handle this properly. The good thing is, we have another "errorSitemeshFilter" that handles this.

public class SiteMeshFilter implements Filter {

    private FilterConfig filterConfig;
    private ContainerTweaks containerTweaks;
    private static final String ALREADY_APPLIED_KEY = "com.opensymphony.sitemesh.APPLIED_ONCE";
    private String alreadyAppliedKey;

    public void init(FilterConfig filterConfig) {
        this.filterConfig = filterConfig;
        alreadyAppliedKey = ALREADY_APPLIED_KEY + "-" + this.filterConfig.getFilterName();
        containerTweaks = new ContainerTweaks();
    }

    public void destroy() {
        filterConfig = null;
        containerTweaks = null;
    }

    /**
     * Main method of the Filter.
     *
     * Checks if the Filter has been applied this request. If not, parses the page
     * and applies {@link com.opensymphony.module.sitemesh.Decorator} (if found).
     */
    public void doFilter(ServletRequest rq, ServletResponse rs, FilterChain chain)
            throws IOException, ServletException {

        HttpServletRequest request = (HttpServletRequest) rq;
        HttpServletResponse response = (HttpServletResponse) rs;
        ServletContext servletContext = filterConfig.getServletContext();

        // no changes
        . . .

        try {

            Content content = obtainContent(contentProcessor, webAppContext, request, response, chain);

            if (content == null) {
                return;
            }

            Decorator decorator = decoratorSelector.selectDecorator(content, webAppContext);
            decorator.render(content, webAppContext);

        } catch (IllegalStateException e) {
            // Some containers (such as WebLogic) throw an IllegalStateException when an error page is served.
            // It may be ok to ignore this. However, for safety it is propegated if possible.
            if (!containerTweaks.shouldIgnoreIllegalStateExceptionOnErrorPage()) {
                throw e;
            }
        } catch (RuntimeException e) {
            if (containerTweaks.shouldLogUnhandledExceptions()) {
                // Some containers (such as Tomcat 4) swallow RuntimeExceptions in filters.
                servletContext.log("Unhandled exception occurred whilst decorating page", e);
            }
            throw e;
        } catch (ServletException e) {
            request.removeAttribute(alreadyAppliedKey);
            throw e;
        }

    }

    // no changes
    . . .

    private boolean filterAlreadyAppliedForRequest(HttpServletRequest request) {
        if (request.getAttribute(alreadyAppliedKey) == Boolean.TRUE) {
            return true;
        } else {
            request.setAttribute(alreadyAppliedKey, Boolean.TRUE);
            return false;
        }
    }

}

This should work for error pages other than 404.

That's all. I hope this helps. Let me know if it works for you.

UPDATE: This is related to http://jira.opensymphony.com/browse/SIM-168.

UPDATE (2013 July): Thanks to Jeremy for pointing out the use of alreadyAppliedKey instead of ALREADY_APPLIED_KEY in the doFilter() method.

2 comments:

  1. Is there a reason why you didn't change request.setAttribute(alreadyAppliedKey, null); to request.setAttribute(ALREADY_APPLIED_KEY, null); in the doFilter method? I would have assumed that the attribute name would be the same everywhere in this class.

    ReplyDelete
    Replies
    1. Thanks for pointing that out Jeremy. I forgot to point that out in the code. Let me update the post.

      Delete