Adventures in JSF 2.0: Hello World Tutorial using Maven 2, JSF 2, Facelets 2, and Weld

By Steven Boscarine in Information Technology| People Who Make Software| Uncategorized

17 Oct 2009

In the first of many posts regarding the recently finalized JSF 2.0, I will be showing you what you need to do to write a simple Hello World Application. Instead of traditional JSF backing beans, this application will use Weld, an open-source implementation of JSR-299: Contexts and Dependency Injection for the Java EE platform. JSR-299 will be part of the upcoming JEE 6 specification.

Prerequisites:

Install Sun’s JDK 6, the latest version of Maven (presently 2.2.1), and the IDE of your choice. I use Eclipse, but GEdit or notepad would work just fine. For this demo, I’ll be using Jetty, so you won’t need to install a container of any sort.

Getting Started:

Create Empty Project

Our first step is to create an ordinary empty WAR project in Maven using the

archetype:generate

command in the directory of your choice.

cd ~/workspace #this can obviously be anywhere.
mvn archetype:generate -DinteractiveMode=n -DarchetypeArtifactId=maven-archetype-webapp -Dversion=0.0.1-SNAPSHOT -DgroupId=org.bogus -DartifactId=jsf2_tutorial

Unfortunately, the default Maven archetype falls short of what we need, so we need to make a few extra directories. We need a java directory and the test java and resources directory. I’ve also added the commands that an eclipse user would use to generate an importable eclipse project. Netbeans and IntellJ users can simply import the pom.xml.

#create a few extra directories for the project.
mkdir jsf2_tutorial/src/test jsf2_tutorial/src/test/java jsf2_tutorial/src/test/resources jsf2_tutorial/src/main/java
cd jsf2_tutorial
#if you're using *NIX, you can create empty files with this command.
mkdir src/main/java/org/ src/main/java/org/bogus/ #need to create package first.
touch pom.xml src/main/webapp/WEB-INF/web.xml src/main/webapp/WEB-INF/beans.xml src/main/java/org/bogus/HelloWorld.java src/main/webapp/index.xhtml src/test/resources/jetty-env.xml

Overview

I was very impressed that a simple Hello World project can be created with as little as five artifacts.

/pom.xml
/src/main/webapp/WEB-INF/web.xml
/src/main/webapp/WEB-INF/beans.xml
/src/main/java/org/bogus/HelloWorld.java
/src/main/webapp/index.xhtml
/src/test/resources/jetty-env.xml (for Jetty users).

Writing the actual Code

pom.xml

The first step is to the pom.xml file. Afterwards it can be easily imported into any modern IDE.

<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/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>org.bogus</groupId>
	<artifactId>helloworld</artifactId>
	<packaging>war</packaging>
	<version>0.0.1-SNAPSHOT</version>
	<name>JSF 2.0 Tutorial</name>
	<repositories>
		<!-- As of October 2009, a few of the weld dependencies were not yet on the main maven repo.  We can add JBoss repo as it is updated more frequently.  -->
		<repository>
			<id>repository.jboss.org</id>
			<name>JBoss Repository</name>
			<url>http://repository.jboss.org/maven2</url>
			<releases>
				<enabled>true</enabled>
			</releases>
			<snapshots>
				<enabled>false</enabled>
			</snapshots>
		</repository>
	</repositories>
	<dependencies>
		<!-- Common -->
		<dependency>
			<groupId>javax.enterprise</groupId>
			<artifactId>cdi-api</artifactId>
			<scope>provided</scope>
			<version>1.0-CR1</version>
		</dependency>
 
		<dependency>
			<groupId>javax.annotation</groupId>
			<artifactId>jsr250-api</artifactId>
			<version>1.0</version>
		</dependency>
 
		<dependency>
			<groupId>javax.faces</groupId>
			<artifactId>jsf-api</artifactId>
			<version>2.0.0-RC</version>
		</dependency>
 
		<!-- Jetty-specific scopes and artifacts -->
		<dependency>
			<groupId>javax.faces</groupId>
			<artifactId>jsf-impl</artifactId>
			<scope>runtime</scope>
			<version>2.0.0-RC</version>
		</dependency>
 
		<dependency>
			<groupId>javax.servlet</groupId>
			<artifactId>jstl</artifactId>
			<version>1.2</version>
			<scope>runtime</scope>
		</dependency>
 
		<dependency>
			<groupId>org.jboss.weld.servlet</groupId>
			<artifactId>weld-servlet</artifactId>
			<version>1.0.0-CR1</version>
			<scope>runtime</scope>
		</dependency>
 
		<dependency>
			<groupId>org.glassfish.web</groupId>
			<artifactId>el-impl</artifactId>
			<version>2.1.2-b04</version>
			<scope>runtime</scope>
			<exclusions>
				<exclusion>
					<groupId>javax.el</groupId>
					<artifactId>el-api</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
	</dependencies>
	<build>
		<finalName>jsf2</finalName>
		<plugins>
			<!-- Compiler plugin enforces Java 1.6 -->
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<configuration>
					<source>1.6</source>
					<target>1.6</target>
				</configuration>
			</plugin>
 
			<!-- Eclipse plugin enforces download of source and JavaDoc jars -->
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-eclipse-plugin</artifactId>
				<configuration>
					<wtpversion>2.0</wtpversion>
					<downloadSources>true</downloadSources>
					<downloadJavadocs>true</downloadJavadocs>
				</configuration>
			</plugin>
			<!-- Embedded Jetty (jetty:run) -->
			<plugin>
				<groupId>org.mortbay.jetty</groupId>
				<artifactId>maven-jetty-plugin</artifactId>
				<configuration>
					<!-- force friendly name instead of artifact name + version -->
					<contextPath>${build.finalName}</contextPath>
					<!-- Where the BeanManager is constructed.  This is where we'll later declare datasource. -->
					<jettyEnvXml>${basedir}/src/test/resources/jetty-env.xml</jettyEnvXml>
					<!-- This parameter will auto-deploy modified classes...my personal favorite Jetty feature. -->
					<scanIntervalSeconds>3</scanIntervalSeconds>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

Now that your pom is complete, you can import it into the IDE of your choice. Eclipse requires users to either install m2eclipse or run:

mvn eclipse:eclipse

Boilerplate

web.xml

Since JSF 1.2, the web.xml page got a lot smaller. This is where convention over configuration pays off. Also, faces-config.xml is now optional!

<?xml version="1.0" encoding="UTF-8"?>
<web-app 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-app_2_5.xsd" version="2.5">
	<!-- Standard JSF 2.0 Configuration Paramters. -->
	<!-- No Joke!!...This is all you need now! -->
	<context-param>
		<param-name>javax.faces.DEFAULT_SUFFIX</param-name>
		<param-value>.xhtml</param-value>
	</context-param>
	<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>*.jsf</url-pattern>
	</servlet-mapping>
 
	<!-- Weld Jetty Configuration parameters -->
	<listener>
		<listener-class>org.jboss.weld.environment.servlet.Listener</listener-class>
	</listener>
	<resource-env-ref>
		<description>Object factory for the CDI Bean Manager</description>
		<resource-env-ref-name>BeanManager</resource-env-ref-name>
		<resource-env-ref-type>javax.enterprise.inject.spi.BeanManager</resource-env-ref-type>
	</resource-env-ref>
</web-app>

beans.xml

In order to indicate to weld to initialize dependency injection, you’ll need to create an empty file named beans.xml. The mere presence of this file in your WEB-INF folder tells the container that your WEB-INF/classes folder is a bean deployment archive.

Application-Specific Code

HelloWorld.java

To confirm that Weld (A.K.A. JSR 299 or WebBeans) Dependency Injection works, we’re going to write an incredibly simple bean. In contrast to Spring, you don’t need to declare the package or bean. Simply adding the @Named annotations and declaring a scope is all that is needed to have your bean registered with the dependency injection container and visible to your facelets view pages.

package org.bogus;
 
import java.io.Serializable;
 
import javax.enterprise.context.SessionScoped;
import javax.inject.Named;
 
@Named //assigns this bean the name of "helloWorld"...its "de-caplitalized" class name
@SessionScoped  //creates one bean for each user session.
public class HelloWorld implements Serializable {
	private final String text = "Hello World!";
 
	public String getText() {
		return text;
	}
 
	private static final long serialVersionUID = 1L;
}

index.xhtml

Now we want to actually view the bean we created. Below is an incredibly simple xhtml/facelets page.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:h="http://java.sun.com/jsf/html">
<h:head>
	<title>JSF Demo</title>
</h:head>
<h:body>
	<h1>Does Weld Work?</h1>
	<!-- Your bean can be easily accessed via Expression Language -->
	<p>My weld-injected bean says: #{helloWorld.text}</p>
</h:body>
</html>

jetty-env.xml

Since we’re not using a full JEE container, we need to configure Jetty to prepare the BeanManager.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN"
   "http://jetty.mortbay.org/configure.dtd">
<Configure id="webAppCtx" class="org.mortbay.jetty.webapp.WebAppContext">
	<New id="appManager" class="org.mortbay.jetty.plus.naming.Resource">
		<Arg>
			<Ref id="webAppCtx" />
		</Arg>
		<Arg>BeanManager</Arg>
		<Arg>
			<New class="javax.naming.Reference">
				<Arg>javax.enterprise.inject.spi.BeanManager</Arg>
				<Arg>org.jboss.weld.resources.ManagerObjectFactory</Arg>
				<Arg />
			</New>
		</Arg>
	</New>
</Configure>

Start up Jetty

Jetty is an embedded servlet container that can be easily launched from Maven. Since we added that small snippet to the pom, we can simply type:

mvn war:inplace jetty:run

…and maven will download Jetty and run it with the configuration file we passed.

Test Your Application

Simply load http://localhost:8080/jsf/index.jsf

firefox http://localhost:8080/jsf/index.jsf

Screenshot of your application
If you see the hello world text, everything has worked. Now that you’ve confirmed your configuration is setup correctly, you can explore the more interesting features of Weld and JSF 2, which I’ll be covering in future posts.

Download the Code

The source code to this tutorial is available via subversion here

UPDATE: Tomcat Users

With the addition of a context.xml, this example runs perfectly on Tomcat.
Please see this article for details.

However, your statement is only correct in existing applications spring-enabled applications where your package has been previously registered. Also, Spring doesn’t really handle scoping. Spring IOC handles singleton and non-singleton (the equivalent of @Request). You have to use WebFlow to get Conversation or Session scoping.

As far as JBoss propaganda or being misinformed. I am actually a Spring 2.5 user migrating towards CDI. Weld is just an implementation of JSR 299, part of JEE 6. I’m not sure of the reason why, but Spring didn’t feel like contributing to the JSR, so it is led by Gavin King of JBoss. You could easily use the Apache implementation of CDI (OpenWebBeans) if you had issues with JBoss.

The difference between CDI and Spring 2.5 is that by adding an empty beans.xml file, you’re ready to start using CDI. To write the same tutorial in Spring, I would have to:

1. Create a Spring config.
2. Register EACH package in the config.
3. Modify your web.xml to initialize the Spring listener.
4. Modify your face-config.

In the end, you still couldn’t declare a bean as @ConversationScoped through Spring.

CDI is not a revolutionary improvement over Spring IOC so much as it’s an evolutionary improvement. I personally still like Spring and would not be so enamored with CDI if Spring had decent, first-class integration with JSF. SpringSource added JSF integration as a afterthought with WebFlow and it is very cumbersome to use for anything other than long multi-page flows.

If you use JSF, CDI is a huge improvement over Spring. If you don’t, then it’ll do a few things slightly better, but probably isn’t worth gutting your entire infrastructure out for if you’re already invested in a non-JSF-webframework.

The specifications and implementation of the various components of JEE6 are just now getting finalized. They have excellent APIs and potential. Once greater integration and testing documentation is out in the wild, I think you’ll find JEE6 to be a compelling alternative to whatever you’re using now.

Thanks again for reading and responding,
Steven

Alberto Gori

November 21st, 2009 at 6:42 am

You can run the example using command

mvn clean package jetty:run-war

just putting the jetty-evn.xml file into the webapp/WEB-INF folder.

Tai

November 23rd, 2009 at 1:58 am

Hi,

I have a problem with setting up this example under Windows. I am not familiar with Maven but I get stuck with the command:
touch pom.xml src/main/webapp/WEB-INF/web.xml src/main/webapp/WEB-INF/beans.xml src/main/java/org/bogus/HelloWorld.java src/main/webapp/index.xhtml src/test/resources/jetty-env.xml

The touch command and I figured out that it is part of a mvn plugin. I have also tried calling “mvn touch …” but I only get this a “BUILD FAILURE” with:
Invalid task ‘touch’: you must specify a valid lifecycle phase, or a goal in the format plugin:goal or pluginGroupId:pluginArtifactId:pluginVersion:goal

Can anybody Help?

Thanks in advance,
Tai
P.S.: using mkdir under windows you have to replace “/” with “\”

November 23rd, 2009 at 10:02 am

Hello Tai,
You are correct. Those commands are for *NIX. You can install cygwin if you really want to run them, however, there’s an easier way to accomplish the same goals.

Touch in *NIX simply creates an empty file. I added that command to reduce the chances of someone forgetting to create a file or putting it in the wrong directory. For example one user had issues because he forgot to create the empty beans.xml file. The touch command is designed to avoid that.

Simply create the folders and files in the Overview section in Windows explorer or eclipse and move on to writing the actual code.

If you want to work on your Maven skills and skip the manual steps, there’s an even easier way. I’ve been working with the kind folks at JBoss to create maven archetype that creates all the files you need to get started.

The instructions are here: http://www.seamframework.org/Documentation/WeldQuickstartForMavenUsers Once these archetypes get published to the maven repo (hopefully soon), this entire tutorial becomes 2 maven commands. For now, you have to check out the code and build it.

Finally, I included my original source in the “Download the Code” section if you want to just have a working project to play with.

Thanks for commenting and checking out Weld.

In the last month, I have been working with the Weld team to try to make CDI and Weld as accessible and easy to use as possible to new users. Hopefully, in a month or 2, users in your situation will find it CDI and JSF 2.0 incredibly easy to get started with.

Martin

December 6th, 2009 at 12:19 pm

As Murat Can ALPAY, I get nothing. But I noticed the following in the log output:
Dec 6, 2009 5:55:56 PM org.jboss.weld.environment.servlet.Listener contextInitialized
INFO: JSR-299 injection will not be available in Servlets, Filters etc. This facility is only available in Tomcat
Dec 6, 2009 5:55:56 PM org.jboss.interceptor.model.InterceptionTypeRegistry

Creating the war file and deploying to Tomcat works fine though.

Regards,

Ashley Westwell

January 8th, 2010 at 7:08 am

Hey

I tried your example and it works fine, thanks for the quick start. However if I try to update the JSF 2 dependencies to latest version the injection stops working!

Here is what I changed the JSF dependancies to in the pom.xml

From

javax.faces
jsf-impl
runtime
2.0.0-RC

javax.servlet
jstl
1.2
runtime

javax.faces
jsf-api
2.0.2-FCS

javax.faces
jsf-impl
runtime
2.0.2-FCS

January 8th, 2010 at 7:09 am

Type above

Should be

January 8th, 2010 at 9:22 am

Hello Ashley,
I apologize, but much as changed since that post was written. When that post was written, there were no weld archetypes. Since then, I got a chance to work with the JBoss team to create archetypes to automate the entire procedure.

Please try this procedure instead: http://www.seamframework.org/Documentation/WeldQuickstartForMavenUsers

I’ll update that post to reflect the fact that nearly the entire tutorial has been reduced to a few command lines. The JBoss team is actively working with the community to make adopting Java EE features as easy as possible with projects like the archetype project.

Bee

February 21st, 2010 at 7:30 am

Thanks for the great tutorial. I wonder if it can be run in tomcat 5.5.x. I mean if JSF 2.0 and Weld can be run on tomcat 5.5.x.
I did manage to get it up and render the page. however, the el expression, both ${helloWord.text} and #{helloWorld.text}, are not evaluated.

Also this tutorial uses JSF RI from Sun, can you show me how to use it with MyFaces?

Thanks in advance

February 22nd, 2010 at 12:30 am

I manage to get it running on tomcat 5.5.x. Thanks.

Bee: I manage to get it running on tomcat 5.5.x. Thanks. [...]

Bee: Thanks for the great tutorial. I wonder if it can be run in tomcat 5.5.x. I mean if JSF 2.0 and Weld [...]

Aruna: hi Steven, Thanks for this great tutorial. I'm new to all this stuff maven, jsf, tomcat etc. I lo [...]

Steven Boscarine: Hello Ashley, I apologize, but much as changed since that post was written. When that post was writ [...]

Ashley Westwell: Type above javax.servlet jstl 1.2 runtime Should be javax.faces jsf-impl runtime 2. [...]

info.rmatics

Adventures in JSF 2.0: Hello World Tutorial using Maven 2, JSF 2, Facelets 2, and Weld

Prerequisites:

Getting Started:

Create Empty Project

Overview

Writing the actual Code

pom.xml

Boilerplate

web.xml

beans.xml

Application-Specific Code

HelloWorld.java

index.xhtml

jetty-env.xml

Start up Jetty

Test Your Application

Download the Code

UPDATE: Tomcat Users

Further Reading

21 Responses to Adventures in JSF 2.0: Hello World Tutorial using Maven 2, JSF 2, Facelets 2, and Weld

Comment Form

About this blog

Categories

Archives

Topics

Health IT Blogs & Sites

Healthcare Policy

Informatics and HIT Research

Meta