In this article I will show you how to create a simple JavaServer Faces (JSF) Web application starting from zero with Eclipse. This simple example will be the start point to other articles that I want to publish in this blog. In this article we will not go deep inside JSF. We will only create a simple “Hello World” JSF application step by step.
The configuration used is explained here. As you see I am using Glassfish, but for this simple example you could use also other applications servers like Tomcat or JBoss. In this example I am not using Maven projects, although that it’s becoming the standard “de facto” for managing projects in the last years. But by now I am not going to use it.
So the objectives for this article will be:
- Create a simple Dynamic Web project with JSP capabilities.
- Add JSF capabilities
- Add Richfaces libraries
Step 3 is optional. My initial intention was to use richfaces and primefaces at the same time, but I think that there are some problems to use both of them because they both use different versions of the underlying jquery library. So, in this case I will choose, by now, to use only Richfaces as an extension of the defaul JSf libraries. In this article I assume that you have minimal knowledge of Eclipse.
Step 1. Create simple Dynamic Web Project with JSP capabilities.
Creating the project
These are the steps. Notice that we are doing basic configuration. Some of the screens that I will show you have interesting options to take full advantage of Eclipse and Java EE programming, but by now I will do only basic things. Some screens or steps may be different from you depending on your Eclipse / Glassfish configuration. In this link i talk about the configuration I am using
- Open Eclipse and choose option File → New → Other and choose Web → Dynamic Web Project from the list of options. In this case I prefer to not to use any other kind of project, although JBoss Tools offers some project templates that help us doing some part of configuration.
- Choose the project name and press Next. If you have a Glassfish server installed on Eclipse it will appear as a target runtime. If, not, in this link I talk about how to install a server in Eclipse
- Skip this screen because we will not change anything. Press Next.
- On the next screen we will specify the context root of our application and we choose also to generate explicitly the web.xml configuration file because we will need it later, at least for configuring JSF. The context root is the path following the site address where our application will be available. For example, if we have our application at http://www.myniceserver.com/myapp, the context root will be “myapp”. In this case I will use the root path (“/”). When finished press Next.
- Eclipse will create the skeleton for our Web project. In some cases, Eclipse will create a default “Hello World” JSP page called index.jsp inside your WebContent Folder. If Eclipse doesn’t create anyone you can create one manually. Right-click on your project and select New → JSP File. Call the file index.jsp and save it into WebContent folder inside your project.
- Your new JSP page may appear like this:
<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="ISO-8859-1"% > <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd" > <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>Insert title here</title> </head> <body> Hello world! </body> </html>
Testing this initial the project
The next thing we can do is to test if everything is working fine. Select your new project, right-click it and select Debug as … → Debug on Server and choose your Glassfish server. Depending on your Eclipse configuration it will open an internal or an external browser, poiting with your new JSP application: http://localhost:8080/
The important thing to remember here is that with following the steps shown until now, Eclipse creates the initial skeleton of your project, with a src folder where your java classes will exist, a WebContent folder where your html / jsp or xhtml pages will exist. And, very important, a web.xml file inside WebContent/WEB-INF folder with the initial configuration of your project. You can edit this file double-clicking on it. In this file there is a section called welcome-file-list showing different options for the first page that will appear when navigating to your root page (http://localhost:8080/). In this case we created a simple jsp page called index.jsp that appears on that welcome file list.
You can donwload the example for Step 1 clicking here
Step 2. Add JSF capabilities.
With step 1 we have created and run a Web project, but this project is not still a JSF project. We will add manually the JSF facet to the project, and with some extra steps we will convert our project into a full JSF application.
- Select your project. Right-click on it and go to option Properties on the context menu. Select Project Facets on your project properties window and check JavaServer Faces. Eclipse will ask you Further configurstion required. Click on the link to open next screen.
- Because we will add later Richfaces library we will disable Library configuration. Another reason to do this is that Glassfish comes with the reference implementation of JavaServer Faces, a library called Mojarra, and we don’t need to add it manually to our project. Additionally we will specify that all xhtml files will be processed by the JSF servlet class by default (javax.faces.webapp.FacesServlet) with URL mapping patterns.
Whith this step Eclispse generates a faces-config.xml file under WEB-INF folder. Also changes your web.xml configuration file to put there some minimal configuration to run JSF.
- Finally we will change our index.jsp initial page to a new index.xhtml page. First we delete the previously created index,jsp file and create a new xhtml file right-clicking on your project, selecting New → XHTML Page. Specify the name (index.xhtml) that will be saved directly on your WebContent folder. Click Next to continue. In this case We will use an xhtml Template. I don’t know if this feature (xhtml templates) comes with the standard Eclipse installation or with JBoss Tools, but I will use it to make the things easier. Select a Blank JSF Page and click Next.
- On the next screen choose at least the JSF core and JSF HTML tag libraries. When clicking Finish Eclipse will create a file called index.xhtml under your WebContent folder
- The created page will appear like this:
<!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" xmlns:f="http://java.sun.com/jsf/core" xmlns:ui="http://java.sun.com/jsf/facelets"> <h:head/> <body> Hello World! </body> </html>
- The last thing you have to do is tho specify this index.xhtml file as the default welcome file of your web site. You should edit WEB-INF/web.xml file, delete all entries inside <welcome-file-list> section and add only index.xhtml file. Now your project structure shoud appear like this:
Test again your project and you will have your first JSF project running! Remember that for every change in your Eclipse project you should republish it on Glassfish. You can do it clicking on publish button on your Servers view at Eclipse.
Here you can download a project example for this second step.
Step 3. Adding Richfaces manually to your project.
Nowadays there are several free JSF libraries available to the community that improve greatly the user expierence when running JSF Web applications. The most popular are Primefaces and Richfaces. Primefaces is a very good library, specially for begginers, with great visual widgets and easy to use. But the one that we are using by now at work is Richfaces. Richfaces is, maybe, a little more difficult to configure manually and to use, but I like the way that this project is moving, people at JBoss community is doing good work and I think that this library will have a bright future if they continue in this way.
Configuring your project to use Richfaces
You can download the latest stable version of Richfaces at this link. Richfaces jars are inside artifacts\framework and artifacts\ui folders of the downloaded zip file.
Configuring Richfaces manually is not so easy as all we would. In this example I will use the latest version (4.2.3.Final) So here are the steps to do it. First, you can read this article where explains a basic configuration for your project. But in this article there are some missing information and is not updated with the latest release of Richfaces and it’s dependencies. After some research I found versions that, at least, are not giving me deployement errors. The library needed to use Richfaces, then, are:
So, to use Richfaces in your projecte download all the previous jar files and put them on your WEB-INF/lib path. Doing this all these libraries will be automatically on your classpath.
Another option to configure your project, is to use Maven to resolve automatically library dependecies if you know how to use it, but, as I explained initially I will not use it here. Following this link is a forum page where explains how to do it with Maven.
Testing your Richfaces project
Our last step will be to test our project. You can do it changing our index.xhtml file created previously to something like this:
<!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" xmlns:f="http://java.sun.com/jsf/core" xmlns:ui="http://java.sun.com/jsf/facelets" xmlns:rich="http://richfaces.org/rich" > <h:head/> <h:body> Hello World! <h:form> <h:outputText value="Calendar:" /> <rich:calendar/> </h:form> </h:body> </html>
Republish and reload again your web page. It will appear a screen like this:
Congratulations! You have your first JSF application running !!
You can download the full example clicking here