Prepare Eclipse for Facelet work

Update Helios to include the JavaServer Faces (JSF) Project. I'm not certain you have to do this; I'm still researching. It doesn't seem to make any difference in my observation. At least it doesn't hurt.

1. Help -> Install New Software
2. Type "Helios" into Work with:
3. Select "Helios - http://download.eclipse.org/releases/helios"
4. Type "jsf" into the text filter field (the empty one just below the Work with: field; don't press Enter, but wait
5. Web, XML, and Java EE Development should appear; check JavaServer Faces (JSF) Project
6. Click Next and Finish the installation

The set-up

Facelets JAR

jsf-facelets-1.1.14.jar

The definitive JAR list

Just as for my RichFaces JSF work, I ended up with a definitive set of libraries to work with. This is a good thing. My set is almost identical to the original one. In fact, I lost the JSTL libraries (they're unnecessary) and gained a Facelets library. From my working WAR file:

Apache Commons
	commons-beanutils-1.8.3.jar
	commons-codec-1.4.jar
	commons-collections-3.2.1.jar
	commons-digester-2.1.jar
	commons-discovery-0.4.jar
	commons-logging-1.1.1.jar
JSTL 1.2
	jstl-api-1.2.jar
	jstl-impl-1.2.jar
Facelets
	jsf-facelets-1.1.15.B1.jar
MyFaces 2.0.4
	myfaces-api-2.0.4.jar
	myfaces-impl-2.0.4.jar
RichFaces 3.3.3
	richfaces-api-3.3.3.Final.jar
	richfaces-impl-3.3.3.Final.jar
	richfaces-ui-3.3.3.Final.jar

web.xml additions

web.xml is the deployment descriptor in use by many server containers such as Tomcat, GlassFish, JBoss, etc.

The IBM article also says to add these lines to web.xml. There are no actual JSF files in the sample application, however, the web.xml wiring does make use of this. I would add the others in grey here, though I think I only needed the explicit path ("/faces/*"), the first one to match.

<servlet>
   <servlet-name>Faces Servlet</servlet-name>
   <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
   <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
   <servlet-name>Faces Servlet</servlet-name>
   <url-pattern>/faces/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
   <servlet-name>Faces Servlet</servlet-name>
   <url-pattern>*.jsf</url-pattern>
</servlet-mapping>
<servlet-mapping>
   <servlet-name>Faces Servlet</servlet-name>
   <url-pattern>*.xhtml</url-pattern>
</servlet-mapping>
<servlet-mapping>
   <servlet-name>Faces Servlet</servlet-name>
   <url-pattern>*.faces</url-pattern>
</servlet-mapping>

Servlet mappings

Servlets are registered with the container; this is done via web.xml.

When a servlet is defined, it's given a name and a supplying class. In this case, what comes out of javax.faces.webapp.FacesServlet is given the name Faces Servlet, which is used as the name in all servlet mapping references.

You can name the servlet anything you want, but unless every significant (read: consumed) occurrence of it is identical to what you used for <servlet><servlet-name>name</servlet-name> ... </servlet>, Tomcat will fail to start up or, at least, execution will fail.

A servlet mapping specifies the web container for which the servlet should be invoked for a URI given by the client. It maps (the end of) URI patterns to servlets. In this way, when there's a request from a client to the container, the latter decides which (if there is more than one) application will handle the request. Of course, the pattern given could fail to match any pattern and no servlet will be passed the request. When this happens, an HTTP Status 404 is issued.

Mapping order

The first successful match fires and no further attempt is made. So, it follows that a strict order must be made that will allow this.

In web.xml above, the *.jsf, *.xhmtl and *.faces are unnecessary for running guessnumber.xhtml.

Parameters

The following addition DOES make sense, and I expected it:

<context-param>
   <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
   <param-value>.xhtml</param-value>
</context-param>

There is yet more. You'll need all the <filter ... /> statements learned about in the other, RichFaces article, plus the SKIN context parameter. What's new, however, in pursing a Facelet, is the VIEW_HANDLE context parameter:

<context-param>
  <param-name>org.ajax4jsf.VIEW_HANDLERS</param-name>
  <param-value>com.sun.facelets.FaceletViewHandler</param-value>
</context-param>

Sample project

I'm going to take some direction from the IBM article project, however, I'm not going to re-create it. Once you've finished reading this article, feel free to download their WAR and play with it. You'll find a link to do this near the end of the article.

My purpose here is to do just enough to show the structure of a Facelets application and some Facelet-specific technology, so really, all I'm borrowing from that article is confirmation that my JAR set is accurate and how to do xHTML files.

Creating the project

Application resources

A resource is anything that the application requires for display, including images, JavaScripts, cascading stylesheets, component libraries, etc. Typically, they are gathered into a standard location. In the xHTML sources, you're used to seeing

<h:graphicImage value="#{resource['images:java_duke.gif']}" />

In Eclipse, this puts the image above on the path project-name/WebContent/META-INF/resources/images/java_duke.gif. The resource identifier is images. So, as general rules, ...

1. A resource packaged in the web application root must be in a subdirectory of a resources directory at the web application root: resources/resource-identifier. This refers to resources stored in the Eclipse project directly under WebContent.
2. A resource packaged in the web application's classpath must be in a subdirectory of the META-INF/resources directory within a web application: META-INF/resources/resource-identifier. This refers to resources stored in the Eclipse project under WebContent/META-INF or under Java Resources: src down on the classpath (in a package, etc.).

Remember that Eclipse does the deployment and some of this will work "mysteriously" in that context. It's the finished deployment and not the Eclipse project structure on disk that is described here.

This means that you must study Eclipse deployment in order to know where to keep resources in the project.

Also, (and this must be made to agree with what's being said above), resource identifiers are unique strings that conform to the format:

[locale-prefix/][library-name/][library-version/]resource-name[/resource-version]

Launch the application

Because I often use port 8080 (the default Tomcat port) for other projects, I change this in Eclipse and have changed it here. To change this port number, simply double-click the Tomcat server in the Eclipse Server view (tab), then find the port numbers on the page that comes up for editing (all three or so port numbers), then save the document.

Appendices

Eclipse project layout

Here is the project in Eclipse, with most of the important files and subdirectories visible.

Apache Tomcat deployment (layout)

Here's what the Tomcat deployment done by Eclipse looks like. This is the path workspace/.metadata/.plugins/org.eclipse.wst.server.core/tmp0/wtpwebapps.

RichFaceletsTutorial/
|-- footer.xhtml
|-- guessnumber.xhtml
|-- header.xhtml
|-- META-INF
|   `-- MANIFEST.MF
|-- numberresponse.xhtml
|-- resources
|   `-- images
|       `-- java_duke.gif
|-- templateClient.xhtml
|-- template.xhtml
|-- test.jsp
`-- WEB-INF
    |-- classes
    |   `-- com
    |       `-- etretatlogiciels
    |           `-- facelets
    |               |-- HelloBean.class
    |               `-- UserNumberBean.class
    |-- faces-config.xml
    |-- lib
    |   |-- commons-beanutils-1.8.3.jar
    |   |-- commons-codec-1.4.jar
    |   |-- commons-collections-3.2.1.jar
    |   |-- commons-digester-2.1.jar
    |   |-- commons-discovery-0.4.jar
    |   |-- commons-logging-1.1.1.jar
    |   |-- jsf-facelets-1.1.15.B1.jar
    |   |-- myfaces-api-2.0.4.jar
    |   |-- myfaces-impl-2.0.4.jar
    |   |-- richfaces-api-3.3.3.Final.jar
    |   |-- richfaces-impl-3.3.3.Final.jar
    |   `-- richfaces-ui-3.3.3.Final.jar
    `-- web.xml

9 directories, 25 files

Tag libraries

Tag libraries supported by Facelets include those below. This table is augmented from one I found on a Sun (Oracle) site.

Facelets Templating Tags

I got this convenient list of templating-relevant tags from a Sun (Oracle) site.

Compositing tags

Appendix: Useful links

Appendix: Whence JAR downloads

Here's where I've found downloads for all or most of the JARs in this article.