JSF tutorial with Eclipse and Tomcat

Fast menu Introduction Download and install Java SE 6 JDK Download and install Eclipse Europa 3.3 IDE Download and install Tomcat 6.0 Download and install JSTL 1.2 Download and install Mojarra 1.2 Run and configure Eclipse Integrate Tomcat in Eclipse Prepare JSF web project in Eclipse Create JSF hello world in Eclipse Run JSF web project in Tomcat And now?

Introduction

In this tutorial you will learn how to setup a JSF RI 1.2 (Mojarra) playground with Eclipse Europa 3.3 and Tomcat 6.0. A JSF 1.2 environment requires at least the Java 5.0, JSP 2.1 and Servlet 2.5 API's. We'll download and install Java SE 6 SDK, Eclipse Europa 3.3 IDE (with WTP for Java EE development) and Tomcat 6.0 Application server (which supports JSP 2.1 and Servlet 2.5 API's). Additionally we'll also download and install JSTL 1.2 which can be used in combination with JSF, thanks to unified EL.

There are also another IDE's available next to Eclipse Europa, e.g. Sun Netbeans, Sun Java Studio Creator, Oracle JDeveloper, IntelliJ IDEA, etcetera. The choice for Eclipse Europa 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 which 1GB is reserved to Eclipse. Also at least a Pentium4 CPU around 3GHz, or a Core 2 Duo CPU around 2GHz, or a Athlon64 CPU around 2.5GHz is recommended. Also make sure that you install trusted 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 Tomcat, e.g. Sun Java Application Server (also known as Glassfish in its current release), Jetty, Jonas, etcetera. The choice for Tomcat is made because it's small, lightweight, relatively fast and is supported by Eclipse by default by an excellent plugin. The only disadvantage of Tomcat is that it doesn't support EJB's. So if you ever want to develop with EJB's, then you'll have to switch to another application server which supports EJB's, such as Glassfish.

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 the standard Java API. You can also consider to download and install the Java EE 5 SDK instead which contains the Sun implementation of the enterprise Java API next to the standard Java API. But the Java EE 5 SDK ships with a Glassfish Application Server implementation, while we need the Tomcat Application Server implementation. The Tomcat Application Server implementation already contains at least the javax.el and javax.servlet implementations of the Java EE 5 API, which are required by JSF. The javax.servlet.jsp.jstl implementation, which is also required by JSF, is missing in the Tomcat implementation, but it can be downloaded and installed separately. So we can just skip the download and installation of Java EE 5 SDK, the Java SE 6 JDK is sufficient.

1. Surf to the Java SE 6 JDK download page.
2. Pick the latest JDK without Java EE SDK and/or Netbeans, currently it is called JDK 6 Update 3.
3. Accept the License Agreement and click at Windows Offline Installation, Multi-language.
4. You will get the file jdk-6u3-windows-i586-p.exe (naming may differ per version), save it to disk.
5. Install the JDK and JRE in C:\Java\jdk1.6.0_03 and C:\Java\jre1.6.0_03 respectively.
   

Back to top

Download and install Eclipse Europa 3.3 IDE

The Eclipse IDE is available in several tastes. As we're going to develop Java EE web applications with JSF, we need the Java EE variant. It contains under each the WTP (Web Tools Platform) which eases the development of web applications. The currently latest version is Eclipse Europa 3.3.

1. Surf to the Eclipse download page.
2. Click at Eclipse IDE for Java EE Developers.
3. Select a mirror and you will get the file eclipse-jee-europa-fall2-win32.zip (naming may differ per version), save it to disk.
4. Extract the zip and move the child directory \eclipse to C:\Java\eclipse.

Back to top

Download and install Tomcat 6.0

The Tomcat Application Server is available in several releases, each supporting a different JSP/Serlvet specification. As we're going to develop with JSF 1.2, we need at least the Tomcat release supporting JSP 2.1 and Servlet 2.5. However, if you're using another view technolocy than JSPs, such as Facelets or JSFTemplating, then you can run JSF 1.2 on JSP 2.0 and Servlet 2.4 without issues.

1. Surf to the Tomcat 6.0 download page.
2. Scroll a bit down the page and under Binary Distributions » Core click at the zip link.
3. You will get the file apache-tomcat-6.0.14.zip (naming may differ per version), save it to disk.
4. Extract the zip, rename the child directory \apache-tomcat-6.0.14 to \tomcat and move it to C:\Java\tomcat.

Back to top

Download and install JSTL 1.2

The servlet-api.jar of Tomcat doesn't contain the JSTL API, while it is also required by JSF. So we need to download it separately and place it in the classpath of Tomcat.

1. Surf to the JSTL 1.2 download page.
2. Click at the jstl-1.2.jar link.
3. You will get the file jstl-1.2.jar (naming may differ per version), save it to disk.
4. Move it unchanged to the C:\Java\tomcat\lib directory, which is the main classpath of Tomcat.

Back to top

Download and install Mojarra 1.2

Since the 1.2_07 release of Sun JSF RI, the Sun JSF RI project got a codename called "Mojarra". You can find the project home page at http://javaserverfaces.dev.java.net.

1. Surf to the Mojarra download page.
2. Download the binary of the latest release, so click at the 1.2_07 binary link.
3. You will get the file jsf-1_2_07.zip (naming may differ per version), save it to disk.
4. Extract the zip and move the child directory \jsf-1.2_07-b03-FCS to C:\Java\jsf-1.2_07-b03-FCS.

Back to top

Run and configure Eclipse

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 side: Go to the workbench.
   
3. In the top menu, go to Window » Preferences » Java » Installed JREs. Select the current JRE (it should automatically be the same as you have installed, in this case the jre1.6.0_03, located at C:\Java\jre1.6.0_03) and click Edit. Select the C:\Java\jre1.6.0_03\lib\rt.jar, click at Source Attachment, click at External File, navigate to C:\Java\jdk1.6.0_03, select the src.zip file and add it. Now the source code of the Java SE API is available in Eclipse.
4. In the Preferences dialogue, go to Web and XML » JavaServer Faces Tools » Libraries and click New. Give the library an unique name, e.g. Mojarra 1.2_07. Set Version Supported to v1_2. Under Library Jars, click Add, navigate to C:\Java\jsf-1.2_07-b03-FCS\lib, select the both JAR's jsf-api.jar and jsf-impl.jar and add them. Check Is JSF Implementation and click Finish.
   
5. In the Preferences dialogue, go to Web and XML » JSP Files » Templates and click New. Enter name New JSF File (xhtml), select context New JSP, enter description JSF with xhtml markup, copypaste the following snippet in the pattern field and click OK:

   <%@taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
   <%@taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
   <%@taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %>
   
   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   
   <f:view>
       <html>
           <head>
               <title>Insert title here</title>
           </head>
           <body>
               ${cursor}
           </body>
       </html>
   </f:view>

   
6. In the Preferences dialogue, 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 and so on ;)
7. Here are some more screenshots of how I configured some other preferences (Errors/Warnings and Text Editors):
   
8. Click OK to close the Preferences dialogue.

Back to top

Integrate Tomcat in Eclipse

1. At the bottom box click at the Servers tab. Rightclick at the box and choose New » Server. In the wizard, select the server type Apache » Tomcat v6.0 Server and click Next. In the next page, click at Browse, point to C:\Java\tomcat and click Finish. Now Tomcat is integrated in Eclipse.
   
2. Doubleclick the Tomcat server entry in the Servers tab, you'll get the server configuration. At the left column, under Server Locations, select Use Tomcat installation and save the configuration by choosing File » Save in the top menu or by pressing CTRL+S. At the right column, under Ports, please note the HTTP/1.1 port. This defaults to 8080, keep it in mind. You can change it there if you want. Close the server configuration by clicking at the cross of the tab, or by pressing CTRL+F4.
   
3. Rightclick the Tomcat 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. If you're running a firewall, you'll probably get kind of a warning during the first time of Tomcat startup. Just accept/allow it.
4. Once it is started, go to http://localhost:8080 (where 8080 is supposed to be the HTTP/1.1 port of Tomcat). You should get the default Tomcat home page.
   
   If you get a timeout or kind of an unknown host error message, then doublecheck if Tomcat is started properly and if the port is correct. In Eclipse you can find the Tomcat logs at the Console tab of the bottom dialogue box.
5. You can stop the server by rightclicking at the Tomcat 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

1. At the left box click at the Project Explorer tab. Rightclick at the box and choose New » Dynamic Web Project.
2. In the wizard, give it the name Playground, check if Target Runtime is set to Apache Tomcat v6.0, under Configurations select JavaServer Faces v1.2 project and click Next.
   
3. In the next page, it should contain at least the selections Dynamic Web Module with version 2.5, Java with version 5.0 and JavaServer Faces with version 1.2. Click Next.
   
4. 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. Click Next.
   
5. In the next page, you need to define JSF Capabilities. At JSF Libraries, select Mojarra 1.2_07 (which we have definied in the preferences). At URL Mapping Patterns, select the default /faces/* and remove it. Then add a new pattern with the value *.jsf. Finally click Finish.
   
6. During the creation of the web project you'll probably get a license agreement for the facesconfig_1_2.xsd file from sun.com. If you don't have any intentions to do bad things, just click at I Agree.
   
7. After creation of the web project, you should get a directory structure similar to the screenshot below.
   

Back to top

Create JSF hello world in Eclipse

1. Create a backing bean class: rightclick at Java Resources of the Playground project and choose New » Class. Enter the package name mypackage, enter the class name MyBean, 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. Add two properties to the bean:

   
       private String input;
       private String output;
    
   

   
3. Add getters and setters: the input property will be used by an UIInput component, so it require both a getter and a setter. The output property will be used by an UIOutput component, so it require at least a getter. The setter is optional, but it won't be used by the JSF component. Rightclick somewhere at one of the both properties inside the source editor, choose Source » Generate Getters and Setters, or hit ALT+SHIFT+S, then R. In the wizard, select the desired getters and setters, if necessary choose the sorting (I personally like to have getters first and then setters) and then click at OK. Eclipse will generate the suitable getters and setters. Useful if you ever would have a lot of properties. 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.
   
4. Add an action method to the bean:

   
       public void action() {
           output = "Welcome at the JSF world, " + input;
       }
    
   

   Save the mypackage.MyBean by choosing File » Save in the top menu or by pressing CTRL+S.
   
5. Define the backing bean in the faces-config.xml: doubleclick the WebContent/WEB-INF/faces-config.xml file to open the Faces Configuration editor. Navigate to the ManagedBean tab, select the request scope and click Add. In the wizard, enter the qualified class name mypackage.MyBean or click Browse and enter MyBean to get the matching items and select the mypackage.MyBean. Finally click at Finish. Go to the Source tab to see the managed bean entry. If necessary, hit CTRL+SHIFT+F to get the XML formatted. Save the faces-config.xml by choosing File » Save in the top menu or by pressing CTRL+S.
6. Create a JSF file: rightclick at WebContent of the Playground project and choose New » JSP. Enter the file name test.jsp, click Next, select the template New JSF File (xhtml) (which we have definied in the preferences) and click Finish.
7. Add a basic form to the body of the test.jsp:

   <h:form>
       <h:inputText value="#{myBean.input}" required="true" />
       <h:commandButton value="submit" action="#{myBean.action}" />
       <h:outputText value="#{myBean.output}" />
       <h:messages />
   </h:form>

   Save the test.jsp by choosing File » Save in the top menu or by pressing CTRL+S.
   

Back to top

Run JSF web project in Tomcat

1. Rightclick the Tomcat server entry in the Servers tab and choose Add and Remove Projects. In the wizard, select the Playground project under Available Projects and click Add to add it to Configured Projects. Click Finish.
2. Rightclick the Tomcat 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.
3. Once it is started, go to http://localhost:8080/playground/test.jsf. Note the .jsf extension, it will be covered by the FacesServlet mapping in the WebContent/WEB-INF/web.xml. So this request will be passed through the FacesServlet and the FacesServlet will map it to the default JSP extension, which is .jsp. The FacesServlet will also create the FacesContext and pass the specific request through the JSF lifecycle.
   
   If you get a timeout or kind of an unknown host error message, then doublecheck if Tomcat is started properly and if the port is correct. If you get an internal server error exception, then doublecheck if the code is all correct. Also try to interpret and understand the exception message and the trace, if necessary with help of Google. In Eclipse you can find the Tomcat logs at the Console tab of the bottom dialogue box.

Back to top

And now?

Play with it!

This whole blog site contains lot of useful JSF material. You can find them in the Articles section at the right column of this blog site. Copy'n'paste them, or, preferably, type it over, and play, experiment and run it.

The JSF API documentation, the JSF TLD documentation and the Java EE tutorial also contains a lot of important information. Check the Favorites section at the right column of this blog site for links.

Back to top

Copyright - None of this article may be taken over without explicit authorisation.

(C) January 2008, BalusC