Basic JSF 2.0 Maven Configuration (with Eclipse and Tomcat 7.0)

I’ve decided to learn JSF 2 to upgrade my knowledge of JSF. I would have searched for a JSF 2 Maven archetype but I wanted to learn how to configure it myself so here’s a basic hello world application (I’m assuming that you have a basic knowledge of Maven, if not please go here).

pom.xml

Let’s start with the pom.xml...

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.sample</groupId>
    <artifactId>jsf</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>war</packaging>
    <name>jsf-sample</name>
    
	<repositories>
		<repository>
			<id>jboss</id>
			<name>JBoss Repository for Maven</name>
			<url>https://repository.jboss.org/nexus/content/groups/public/</url>
		</repository>
		<repository>
			<id>central</id>
			<name>Maven Repository Switchboard</name>
			<url>http://repo1.maven.org/maven2</url>
		</repository>
		<repository>
			<id>maven2-repository.java.net</id>
			<name>Java.net Repository for Maven</name>
			<url>http://download.java.net/maven/2/</url>
		</repository>
	</repositories>

    <dependencies>
    	<dependency>
			<groupId>javax</groupId>
			<artifactId>javaee-web-api</artifactId>
			<version>6.0</version>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>com.sun.faces</groupId>
			<artifactId>jsf-api</artifactId>
			<version>${jsf.version}</version>
		</dependency>
		<dependency>
			<groupId>com.sun.faces</groupId>
			<artifactId>jsf-impl</artifactId>
			<version>${jsf.version}</version>
		</dependency>
    </dependencies>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.3.2</version>
                <configuration>
                    <source>1.6</source>
                    <target>1.6</target>
                </configuration>
            </plugin>
            <plugin>
              	<groupId>org.apache.maven.plugins</groupId>
             	<artifactId>maven-war-plugin</artifactId>
              	<version>2.1.1</version>
              	<configuration>
                  	<failOnMissingWebXml>false</failOnMissingWebXml>
                  	<contextRoot>/jsf</contextRoot>
              	</configuration>
          	</plugin>
            <plugin>
          	 	<groupId>org.apache.maven.plugins</groupId>
              	<artifactId>maven-eclipse-plugin</artifactId>
              	<version>2.8</version>
              	<configuration>
                  	<wtpmanifest>true</wtpmanifest>
		          	<wtpversion>2.0</wtpversion>
		          	<manifest>${basedir}/src/main/resources/META-INF/MANIFEST.MF</manifest>
              	</configuration>
	        </plugin>
        </plugins>
    </build>
    
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <jsf.version>2.1.2</jsf.version>
    </properties>
</project>

If you're using a web server such as Tomcat 6.0 or above you will need to have jsf-api and jsf-impl. I've decided to use the jars in the public JBoss repository because the ones in the central Maven repo will produce an error during server start-up:
java.lang.ClassFormatError: Absent Code attribute in method that is not native or abstract in class file javax/faces/FacesException

You can use any Java EE 6 server instead but that is not part of this post because there maybe additional configurations such as ear pom configuration which I haven't tried yet.

web.xml

Next, we need to configure the web.xml file to direct *.xhtml requests to the FacesServlet.

<?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">
  <!-- Minimum requirement for JSF 2 is a servlet 2.5 declaration -->
  <!-- Map FacesServlet -->
  <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>*.xhtml</url-pattern>
  </servlet-mapping>
  <!-- For better error messages during development -->
  <context-param>
    <param-name>javax.faces.PROJECT_STAGE</param-name>
    <param-value>Development</param-value>
  </context-param>
 
  <welcome-file-list>
    <welcome-file>index.jsp</welcome-file>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.xhtml</welcome-file>
  </welcome-file-list>
</web-app>

Mapping *.xhtml to FacesServlet will allow us to use JSF tags in our xhtml files.

faces-config.xml

At the minimum we need to have an empty faces-config.xml in WEB-INF.

<?xml version="1.0"?>
<faces-config xmlns="http://java.sun.com/xml/ns/javaee" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd"
   version="2.0">
  <!-- Empty but needed -->
</faces-config>

Test

To test the configuration I created a basic index.xhtml file which uses some JSF tags (with the h prefix) in src/main/webapp.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" 
	  xmlns:h="http://java.sun.com/jsf/html">
<h:head>
	<title>JSF | Index</title>
</h:head>
<h:body>
	<h1>Hello World!</h1>
</h:body>	
</html>

Just run the mvn clean eclipse:clean eclipse:eclipse install, import in Eclipse, create a server, add the project, run the server and go to index.xhtml.

I hope this helped you. Cheers!