JSF 2.0 tutorial with Eclipse and Glassfish

Fast menu
Introduction
Preparing
Download and install Java SE 6 JDK
Download and install Java EE 6 Web Profile SDK
Download and install Eclipse Helios 3.6 SR1
Run and configure Eclipse
Integrate Glassfish in Eclipse
Prepare JSF web project in Eclipse
Create JSF hello world in Eclipse - The model
Create JSF hello world in Eclipse - The controller
Create JSF hello world in Eclipse - The view
Run JSF web project in Glassfish
Extra! Finetuning validation
And now?

Introduction

In this tutorial you will learn how to setup a JSF 2.0 (Mojarra) playground with Eclipse 3.6 SR1 (Helios) and Oracle Application Server v3 (Glassfish).

There are also another IDE's available next to Eclipse, e.g. Oracle Netbeans, IntelliJ IDEA, etcetera. The choice for Eclipse is made because it's highly configureable, customizeable, has lots of helpful wizards and .. it's free! True, it may eat memory and it may sometimes crash. Just make sure that your environment has enough RAM memory for Java EE development. I recommend at least 2GB of free RAM of which 1GB is reserved to Eclipse. Also at least a dual/quad core CPU around 2GHz is recommended to be able to work fluently. Also make sure that you install trusted Eclipse plugins the right and clean way, because the well-known Eclipse-instability is almost always caused by bad plugins.

There are also another application servers available next to Oracle Glassfish, e.g. JBoss Application Server, Apache Tomcat, etcetera. The choice for Glassfish is made because it ships as being a full fledged Java EE 6 application server already with JSF builtin and offers builtin support for lot of other handy Java EE aspects like JPA for database connectivity, EJB for business services, JSR303 for bean validation, CDI for dependency injection, etcetera. Also, in combination with the current Eclipse plugin, it allows for extremely fast development. Not only Glassfish starts up relatively quick, but it is able to hotdeploy code changes in a subsecond. It's certainly an improvement as compared to its predecesor, Glassfish v2. In the 3-year old JSF 1.2 tutorial, Apache Tomcat was been used. One of the reasons to prefer Tomcat over Glassfish v2 was the lack of a good Eclipse plugin for Glassfish back then in 2008.

Back to top

Preparing

Create a working directory where you install and store all related files. In this tutorial we'll use C:\Java as working directory. If you want to store it somewhere else, then you'll have to replace every occurence of "C:\Java" throughout the tutorial by the desired directory.

Back to top

Download and install Java SE 6 JDK

The Java SE 6 JDK contains both the runtime (JRE, java.exe) and the compiler (JDK, javac.exe) for the standard Java API.

You can skip this part if you already have downloaded/installed Java SE 6 JDK.

1. Surf to the Java SE 6 download page.


2. You'll see four big buttons next to each other, press the leftmost one, which says just 'Java'.


3. Accept the License Agreement and choose the right file for your platform. For Windows x64 for example you will get the file jdk-6u23-windows-x64.exe (naming may differ per version), save it to disk.
   


4. Install the JDK and JRE in C:\Java\jdk1.6.0_23 and C:\Java\jre1.6.0_23 respectively (or in their default paths, if you want).
   
   
   
   

Back to top

Download and install Java EE 6 Web Profile SDK

The Java EE 6 covers the enterprise Java API. This is basically an abstract API for which Glassfish is one of the concrete implementations. Actually, Glassfish is the reference implementation. The Java EE 6 Web Profile is a specified part of the huge Java EE 6 API which includes the minimum necessary API's required for Java web development: the Servlet 3.0 API, JSF 2.0 API, JPA 2.0 API and EJB 3.1 Lite. Note that Apache Tomcat 7.0 only includes Servlet 3.0 API.

You can also consider to pick the standard (full) profile. It's only too heavy-weight since it contains API components which are (possibly) not of your interest like EJB (full), JAX-WS, JAXB, JMS, JACC, JAX-RPC, JAXR, etcetera. It causes Glassfish to start slower as compared to the lightweight web profile, sometimes very noticeably slower. The web profile starts in only a few seconds. You can find an overview of differences halfway the download page of the Glassfish development site.

You can skip this part if you already have downloaded/installed Glassfish, even though you did it by their development site.

1. Surf to the Java EE 6 download page.


2. You'll see four big buttons next to each other, press the rightmost one, which says 'Java EE 6 Web Profile SDK'.


3. Choose Platform/Language, accept the License Agreement and press the Continue button.
   
   
   
   


4. In the section 'Available Files', click at the link below 'Java EE 6 Web Profile SDK Update 1', you will get the file java_ee_sdk-6u1-web-windows.exe (naming may differ per version), save it to disk.
   
   
   
   
   


5. Install Glassfish in C:\Java\glassfishv3 and walk through the remnant of the wizard. Just with default settings is fine. You may possibly get a firewall warning whenever you go to the next step after setting the ports (the installer is just testing them). Just let the firewall allow access. Don't forget to remember the admin username and password for the case that you've changed them!
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   

Note that you may possibly get the error 'This application needs version 1.6 or higher of the Java 2 Runtime Environment.' when executing the installer. In this case, your best bet is to try reinstalling the JRE (not the JDK!) which you can download from java.com. In the latest Java 1.6 releases, there's apparently a little difference in how the JDK/JRE installers configures the necessary registry keys and DLL's in Windows. Just reinstall JRE from java.com in the same folder. During auto-uninstalling the original JRE, you'll possibly get warnings that msvcr71.dll is missing, just ignore it and go ahead (it's may namely be exactly that file which was broken in the original JRE install!).

Back to top

Download and install Eclipse Helios 3.6 SR1

The Eclipse IDE is available in several tastes. As we're going to develop Java EE web applications, we need the Java EE variant. It contains among others the invaluable WTP (Web Tools Platform) which eases the development of Java EE web applications. The currently latest version is Eclipse Helios 3.6 SR1.

1. Surf to the Eclipse download page.


2. Click at the Eclipse IDE for Java EE Developers link.


3. On the right hand menu, pick the platform version.


4. Click the default mirror or pick a mirror and you will get the file eclipse-jee-helios-SR1-win32-x86_64.zip (naming may differ per version), save it to disk.


5. Extract the zip and move the child directory \eclipse to C:\Java\eclipse.

Back to top

Run and configure Eclipse

After starting Eclipse for the first time, we would like to finetune Eclipse a bit so that we don't after all end in trouble and/or annoyances. Eclipse has enormously a lot of settings of which some default values should after all not have been the default values. Here I'll describe only the most useful/important ones.

1. Run C:\Java\eclipse\eclipse.exe. You will be asked to select a workspace. Point it to C:\Java\workspace.
   
   
   
   
   


2. On the welcome screen, click at the icon with the curved arrow at the right top: Go to the workbench.
   
   
   
   
   
   
   


3. In the top menu, go to Window » Preferences. This is the preferences dialogue.


4. You want world domination, so enter 'encoding' in the 'type filter text' input field on the left top. On every section, change the encoding from default (often cp1252 or ISO 8859-1) to UTF-8.
   
   
   
   


5. In the Preferences dialogue, clear if necessary first the entered filter text, then go to General » Editors » Text Editors » Spelling and disable it. Really. It will save you from a big annoyment, because it also unnecessarily spellchecks XML documents like web.xml, faces-config.xml and on.
   
   
   
   
   
   


6. In the Preferences dialogue, go to Web » JavaServer Faces Tools » Validation and in the section Type Assignment Problems set Method expression signature incompatibility to Warning or Ignore if you want to allow JSF action methods return void. I also recommend to set the Unary operation number (and boolean) coercion problems in the section Type Coercion Problems to Warning or Ignore, because it would unnecessarily give an error when you're using for example UIComponent#getValue() -which has Object type outcome- in EL but you treated it as number or boolean.
   
   
   
   
   
   
   
   
   


7. In the Preferences dialogue, go to Web » HTML Files » Editor » Templates and click New. Enter name New Facelet Page, select context New HTML, enter description Creates a new Facelet page, copypaste the following snippet in the pattern field and click OK:
   

    html>
    lang="en"
       xmlns="http://www.w3.org/1999/xhtml"
       xmlns:f="http://java.sun.com/jsf/core"
       xmlns:h="http://java.sun.com/jsf/html"
       xmlns:ui="http://java.sun.com/jsf/facelets">
       
           
       
       
           ${cursor}
       
   
   

   
   
   
   
   
   
   


8. Here are some more screenshots of how I configured some other preferences (Text Editors, HTML Editor and Errors/Warnings), you may find it useful as well (indent using spaces, set line width and print margin, finetune errors/warnings, etc):
   
   
   
   
   
   
   
   
   
   


9. Click OK to close the Preferences dialogue.

Back to top

Integrate Glassfish in Eclipse

We need to familarize Eclipse with any installed application servers so that Eclipse can seamlessly link their libraries in the build path (read: the compiletime classpath) of the project. This is mandatory in order to be able to import classes from the Java EE API in your project (you know, the applications server is namely the concrete Java EE implementation).

1. At the bottom box click at the Servers tab to open the servers view. Rightclick at the box and choose New » Server. In the wizard, click the link 'Download additional server adapters'. Wait until it has finished gathering all available adapters. Finally choose 'Oracle Glassfish Server Tools' from the list and click Next. Accept the license terms and click Finish. In the end you need to restart Eclipse, do it.
   
   
   
   
   
   
   
   
   


2. After restarting and going to workbench, open the servers view once again to add a new server. In the wizard, select GlassFish » GlassFish Server Open Source Edition 3 (Java EE 6) and click Next. In the next page, click at Browse, point to C:\Java\glassfishv3\glassfish and click Next. In the next page, change if necessary the admin ID (username) and password, which is the same as the ones specified during Glassfish installation. Finally click Finish. Now Glassfish is integrated in Eclipse.
   
   
   
   
   
   
   
   
   


3. Doubleclick the Glassfish server entry in the Servers tab, you'll get the server configuration. You can there if necessary change the admin name/password and configure the degree of publishing (hotdeploying). You may possibly get a firewall warning when you open the server configuration for the first time, just let it allow access. Glassfish is able to publish extremely fast on just a Ctrl+S. In the Publishing section, set Automatically publish when resources change and set the interval to 0.
   
   
   
   
   
   


4. Rightclick the Glassfish server entry in the Servers tab and choose Start. You can also start it by clicking at the green arrow at the toolbar of the box. Again, you may possibly get a firewall warning here as well, just let it allow access (this should be the last time now ;) ). Once it is started, go to http://localhost:8080 (where 8080 is the HTTP port as in Glassfish config). You should get the default Glassfish home page. Also checkout the admin console on http://localhost:4848 (where 4848 is the admin port as in Glassfish config).
   
   
   
   
   
   
   
   
   
   If you get a timeout or kind of an unknown host error message, then doublecheck it is started properly and you're using the right port number. In Eclipse you can find the Glassfish logs at the Console tab of the bottom dialogue box (you can doubleclick the tab to maximize it and bring it back). Glassfish actually shows two consoles, one of the JVM and one of the server.log logfile. The last one is of your interest. Click the blue monitor icon on the right top to switch between consoles.
   
   
   
   
   
   
   


5. You can stop the server by rightclicking at the Glassfish server entry in the Servers tab and choose Stop. You can also stop it by clicking at the red square at the toolbar of the box.

Back to top

Prepare JSF web project in Eclipse

Now we can finally create a JSF web project in Eclipse.

1. At the left box open the Project Explorer tab if not already opened. Rightclick at the box and choose New » Dynamic Web Project. In the wizard, give it the Project name Playground, verify if Target Runtime is set to 'GlassFish Server Open Source Edition 3 (Java EE 6)' and Dynamic Web Module version is set to '3.0' (this is actually the Servlet API version). Under Configuration select 'JavaServer Faces v2.0 project' and click Next.
   
   
   
   
   


2. In the next page, you can configure the source folder and build folder (there where compiled classes will end up in). Just keep it default and click Next.
   
   
   
   
   


3. In the next page, you may change the module settings to your taste. Personally I like to have URL's always in lowercase, so I change the default Context Root from Playground to playground. Also, check the checkbox Generate web.xml deployment descriptor to have Eclipse auto-generate the web.xml. Click Next.
   
   
   
   


4. In the next page, you need to define JSF Capabilities. At JSF Implementation Library, select 'Disable Library Configuration'. Glassfish already ships with JSF 2.0 builtin, so we don't need to specify anything. At URL Mapping Patterns, select the default /faces/* and click Remove to remove it. Prefix patterns end up to be less maintainable. Better use postfix patterns like *.jsf or even *.xhtml (unless you have XHTML files which you'd like not to have JSF's FacesServlet to kick in). We'll pick *.xhtml here, a major advantage is that this is an easy way to avoid that the enduser can see the JSF source code whenever s/he (accidently) opens the page with *.xhtml in the URL while the FacesServlet is mapped on *.jsf.
   
   Click Add... to add a new pattern with the value *.xhtml. Finally click Finish.
   
   
   
   


5. After creation of the web project, you should get a directory structure similar to the screenshot below.
   
   
   
   


6. Due to a combination of constraints in the HTTP/HTML/EL specifications, empty HTML input fields are by default treated as empty String. The average (Java) web developer usually dislikes this (so do I). We can instruct JSF to interpret them as null. Open WebContent/WEB-INF/web.xml file, click if necessary the Source tab at the bottom of the editor, and add the following context parameter:
   

   
   
       javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL
       true
   
   

   
   If necessary hit Ctrl+Shift+F to format the xml file nicely.
   
   
   
   
   


7. Save and close the file.

Back to top

Create JSF hello world in Eclipse - The model

As a hello world project, we'll create a simple ajax-flavored form which treats the use case of "Register User". We first need to create a data model. That's a class which represents a real world entitiy, in this case the User. It holds all the information about the user. It should be written as a Javabean. A Javabean is a class which holds properties as private fields which are exposed by public getters and setters.

1. Open the newly created Playground project, rightclick at Java Resources folder and choose New » Class. In the wizard, enter the package name com.example, enter the class name User, keep the other fields default and click Finish. The package and the class will be created and the editor box will show the class source.
   
   
   
   
   
   
   
   
   


2. Let the class implement Serializable. This is not mandatory per se, but this is useful in order to let the HTTP session survive server restarts. Also, as we're going to use a JSF view scoped bean, which will be stored in the component tree (the `UIViewRoot`) in the HTTP session, the view scoped bean itself and all of its properties should be Serializable as well.
   

   package com.example;
   
   import java.io.Serializable;
   
   public class User implements Serializable {
   
       private static final long serialVersionUID = 1L;
   
   }

   
   Note that when you add implements Serializable, Eclipse will show a warning that the class needs to have a serialVersionUID field. You can if necessary just let Eclipse include it with a default or autogenerated ID. Click the yellow bullet on the left hand side and choose it.
   


3. Add five fields to the class (note that Date is to be imported as java.util.Date, not as java.sql.Date):
   

   
   
       private Long id;
       private String username;
       private String password;
       private String email;
       private Date birthdate;
    
   

   
   
   
   


4. Let Eclipse auto-generate the necessary getters and setters. Rightclick somewhere in blank space of the source code inside the source editor, choose Source » Generate Getters and Setters, or hit Alt+Shift+S, then R. In the wizard, click Select All and then untick the serialVersionUID one, if necessary choose the insertion point (I like to have getters and setters at the whole bottom of the class, thus Last member) and the sorting (it defaults to getter/setter pairs, which is okay) and then click at OK. If necessary, hit Ctrl+Shift+F to format the code again so that methods get separated by a blank line. You can configure formatting preferences in Window » Preferences » Java » Code Style » Formatter.
   
   
   
   
   
   
   
   
   


5. Save the class by choosing File » Save in the top menu or by pressing Ctrl+S.

Create JSF hello world in Eclipse - The controller

The backing bean is in turn the glue between the view (the JSF page) and the data model (the entity). The backing bean is linked to the view and all properties of the model are by the backing bean exposed in the view. The backing bean can contain action methods which are linked in the view. The backing bean is basically a mini-controller at its own (in the bigger picture of JSF, the FacesServlet is actually the real web MVC controller).

1. Rightclick at com.example package and choose New » Class. In the wizard, enter the class name Register, keep the other fields default (if you rightclicked on the package to create a new class, the package name should already be com.example) and click Finish. The class will be created and the editor box will show the class source.
   
   
   
   
   
   
   


2. First let the class implement Serializable. Then add a new line above the class declaration, enter @ManagedBean, press Ctrl+Space and ensure that you choose the javax.faces one to import. Do the same for @ViewScoped annotation as well. Note that we can also use @RequestScoped here as well since the bean doesn't do any significantly expensive operations during the construction such as obtaining some data from a database, but if it did and you declared it @RequestScoped, then the bean will be constructed and thus the DB will be hit on every ajax request, keep this in mind!
   

   package com.example;
   
   import java.io.Serializable;
   
   import javax.faces.bean.ManagedBean;
   import javax.faces.bean.ViewScoped;
   
   @ManagedBean
   @ViewScoped
   public class Register implements Serializable {
   
       private static final long serialVersionUID = 1L;
   
   }

   
   
   
   
   
   
   


3. Add a property for the User model, along with a getter and (optionally) a setter, add a @PostConstruct method with which initializes a new User and finally add an action method which just adds a success message (in real world, we would save the newly registered user in the DB as well, but that's beyond the scope of this tutorial):
   

   
   
       private User user;
   
       @PostConstruct
       public void init() {
           user = new User();
       }
       
       public void submit() {
           FacesMessage message = new FacesMessage("Registration succesful!");
           FacesContext.getCurrentInstance().addMessage(null, message);
       }
       
       public User getUser() {
           return user;
       }
   
   

   
   
   
   


4. Save the class.

Back to top

Create JSF hello world in Eclipse - The view

blah

1. Rightclick at WebContent folder and choose New » XHTML page. In the wizard, enter the File name register, click Next (the .xhtml extension will be appended automatically anyway), select the template New Facelet Page (which we have definied in the preferences) and click Finish.
   
   
   
   
   
   
   
   
   
   
   
   


2. Change the