JSF Welcome File Gotcha

When using web.xml’s welcome file capability to specify your application home page, make sure your editor (hint: Eclipse Web Tools?) doesn’t put in a leading slash.

Right:

<welcome-file-list>
<welcome-file>homePage.jsf</welcome-file>
</welcome-file-list>

Wrong:

<welcome-file-list>
<welcome-file>/homePage.jsf</welcome-file>
</welcome-file-list>

The leading slash in the second example will trip up JSF such that when you submit a form on the home page, it will simply reload the home page on the first click, and then do the action and navigate to a new page only on the second click. If you look closely in the URL, you’ll see a // in the path that causes the problem. Welcome files work in any directory (thus, no slash is needed), but Eclipse WTP appears to add a preceding slash when using the file chooser.

Note: if you’re using Tomcat and specify a welcome file with a jsf extension as shown, you’ll also need to create a dummy file with that extension in addition to the real JSP or .xhtml (facelets) view template to satisfy Tomcat’s welcome file existence check. I create a .jsf file with a single line:

<%// Dummy file to trick Tomcat into supporting welcome-file-list –%>