Using RIFE to Serve 404, 403, etc. Responses - RIFE

Problem Statement

Issue: I've configured my web.xml error-page declarations ("404 Page Not Found", "403 ...", etc) to specify a RIFE url, but the RIFE pages aren't being served. Is it possible to serve RIFE pages for these situations?

Answer: Yes, if you have a container which supports the Servlet 2.4 spec (such as Tomcat 5.0+ or Jetty 5.0+).

Don't forget about site fallbacks

The information that's presented here is to handle HTTP status and error messages with RIFE instead of relying on the default behavior of your servlet container. However, if you simply want to display an element when a user accesses a URL that's not registered in a site, then you can do that easily by adding a fallbackid declaration:

<site fallbackid="Fallback">
    <element id="Fallback" ... />
    ...
</site>

The fallbackid can be any local element ID.

Explanation

(I think...) An external request (such as from a browser) enters a servlet container and is passed to a dispatcher. This dispatcher checks to see if the requests match any of the filter mappings or servlet mappings. If so, then the request is passed to (or handled by) the respective filters and servlets. If no match occurs, then the request becomes in internal request which is handled by a different dispatcher. This is also the situation with jsp:forward and jsp:include directives – they are not handled by the external request dispatcher. Unfortunately, pre-Servlet 2.4 there was no way to indicate that filters or servlets should also map on the internal dispatchers, so non-maps on external requests could only be mapped to certain types of documents, mainly actual files on the filesystem such as html or jsp files.

As of Servlet 2.4, it is now possible to tell each the various dispatchers to do the mapping. The 4 types of dispatchers are "REQUEST", "ERROR", "FORWARD", and "INCLUDE". If no dispatchers are specified, then "REQUEST" is assumed. However, if you specify "ERROR", make sure you also specify "REQUEST" so that the servlets and filters still map on the incoming requests.

Steps

0. Create your RIFE pages
1. Make sure you have a container that supports Servlet 2.4
2. Add <dispatcher>ERROR</dispatcher> to your filter-mapping for RIFE in WEB-INF/web.xml
3. Add your error-page declarations which point to your RIFE pages in WEB-INF/web.xml
4. Go get a (root) beer.

Create your RIFE pages

Two RIFE elements are defined here. The ids PAGE403 or PAGE404 are normal RIFE ids; there is nothing special about these names. There is also nothing special about the urls ("/403" and "/404").

A snippet from a RIFE participant sites file:

...
     <element id="PAGE403" extends="rife/template/print.xml" url="/403">
		<property name="name">403</property>
     </element>
     <element id="PAGE404" extends="rife/template/print.xml" url="/404">
		<property name="name">404</property>
     </element>
...

Modified WEB-INF/web.xml:

Note the dispatcher elements in the filter-mapping elements as well as the normal error-page elements mapping the error codes to a location. The locations here ("/404" and "/403") are urls for the pages defined in your RIFE participant sites file.

<?xml version="1.0" encoding="ISO-8859-1" ?>

<!-- Note: The xsi:schemeLocation has a space after ".../j2ee", and
"http://java...." is on the same line!   It's just wrapping here. -->

<web-app  xmlns="http://java.sun.com/xml/ns/j2ee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
	version="2.4"
>
	<filter>
		<filter-name>RIFE</filter-name>
		<filter-class>
			com.uwyn.rife.servlet.RifeFilter
		</filter-class>
		<init-param>
			<param-name>rep.path</param-name>
			<param-value>rep/participants.xml</param-value>
		</init-param>
	</filter>

	<filter-mapping>
	    <filter-name>RIFE</filter-name>
	    <url-pattern>/*</url-pattern>

	    <!-- The important part -->
	    <dispatcher>REQUEST</dispatcher>
	    <dispatcher>ERROR</dispatcher>

	</filter-mapping>

    <error-page>
       <error-code>403</error-code>
       <location>/403</location>
    </error-page>

    <error-page>
       <error-code>404</error-code>
       <location>/404</location>
    </error-page>
</web-app>

Other Notes

If you'd like to use a jsp (or other servlet) to include or forward
requests to RIFE, you can add 'dispatcher' elements for INCLUDE and FORWARD.

Requirements

A Servlet 2.4 compatible container (Tomcat 5.0+ and Jetty 5.0+ both implement Servlet 2.4)
403 and 404 here are just RIFE templates with names '403.html' and '404.html'
Shouldn't be required, but FWIW, I'm using rife-1.3.1-jdk14.jar and JDK1.5.

Testing

This document was written based on a system using:

Tomcat 5.0+
Jetty 5.1.4+
rife-1.3.1-jdk14.jar
JDK 1.5

References

Servlet 2.4 Specification (Final Release): "Filtering -> SRV 6.2.5 Filters and Requests"
http://jcp.org/aboutJava/communityprocess/final/jsr154/index.html

Jetty releases with what specs are implemented version:
http://jetty.mortbay.org/jetty/download.html

Tomcat releases with what specs are implemented by each version:
http://tomcat.apache.org/whichversion.html