Configure FacesIDE, Tomcat and Eclipse for JSF Development

This blog shows you how to configure an entirely open-source JSF development and test platform.

Eclipse can be easily set up to support JSF development with FacesIDE and Tomcat. The process is quite easy – if you have the right plugins.

In Eclipse architecture, plugins are additions to the basic platform. Actually, when you install eclipse, many plugins are already there for you under the hood. They serve as extensions, builts on the basic functionality provided by the platform.

If you want the basic eclipse to serve as a JSF development workbench, a good choice would be to add the FacesIDE plugin to it.

FacesIDE is an open source eclipse plugin designed for JSF development. It contains some functions that allow you to easily make your eclipse project a JSF project and code away without having to focus on JSF's tidbits.

What you need:

1. An eclipse installation.
   You may have some problems configuring the FacesIDE plugin on eclipse level lower than 3.2. I prefer using a Callisto distribution but a simple eclipse should suffice. You may download it from IBM's site (internal links there tend to change a lot, so just go to IBM site and search for 'callisto', Select the Java EE project bundle).
   
   

2. Tomcat.
   I use Tomcat 5.5 but any other will do.
   You can download Tomcat from here and installation is quite straightforward
   
   

3. Additionally, you may use SysDEO's Tomact plugin to ease deploying and testing your application. It is downloadable here. make sure that you download the version that supports your version of eclipse.
   
   
4. The FacesIDE plugin.
   These are actually two plugins that you need. Both are downloadable from here.
   You need both EclipseHTMLEditor and FacesIDE plugins.

You are now ready to set up your environment.

1. If you haven't got eclipse installed already, extract the archive that you downloaded. You can extract it anywhere, but for this tutorial I assume that it is extracted into c:\.
   
   
   

2. Install Tomcat if you haven't done it yet.
   
   
   

3. Eclipse's file structure is simple. You have a directory called c:\eclipse. Under this directory you have a plugins directory. This directory holds all the plugins that you have installed. You will now add the three plugins there.
   Extract both EclipseHTMLEditor and FacesIDE archives to c:\eclipse. The archives contatin a \plugins directory, and therefore the contents will be extracted to c:\eclipse\plugins, where plugins should reside.
   
   
   

4. Install Sysdeo Tomcat plugin under eclipse.
   Unzip the plugin's archive under c:\eclipse\plugins (this archive does not contain a \plugins directory, so you need to extract it there yourself).
   
   
   

5. Configure Eclipse
   If you already used this eclipse, you may have to restart it using –clean attribute on the command (right click the shortcut for eclipse, and select properties. Enter '-clean' at the 'Target' textbox). Remember to remove the -clean attribute after you verify that the plugins are active.
   
   
   

6. Confirm that the plugins are installed : Before we can start, we must confirm that eclipse registered the three new plugins.
   
   
   
   1. In eclipse, go to the Help menu, and select 'About Eclipse SDK'.
      
      
      

   2. A pop-up window opens. Click on the button labeled 'Plug-in Details'. This should display a list of all the plugins installed.
      
      
      

   3. Scroll down to the bottom of the list. You should see the following:
      
      
      Click here for a full screen image.
      
      Make sure that the FacesIDE, FacesIDE Visual page designer, the HTML/JSP/XML Editor and the SYSDEO plugins are listed. (They are shown on the bottom of the list).
      
      
      

   4. If the plugins are not found there, close this list, and click the 'Configuration Details' button. Check the error log there to see what went wrong.

   
   
   

7. In eclipse's main toolbar you should see Tomcat's buttons and menu item. If they are not present, you will need to do the following:
   1. From eclipse main menu select Window->Customize Perspective->Commands.
      
      
      

   2. Check the box next to Tomcat in the commands tab and click OK.
      
      
      Click here for a full screen image.
      
      
8. Before you can use Tomcat from eclipse, you need to set Tomcat's properties.
   
   1. In eclipse's menu select Window->preferences.
      Under Tomcat, set the tomcat version you use and Tomcat's home.
      
      
      Click here for a full screen image.
      
      
      In this example I am using Tomcat 5.5, so 'version 5.x' is selected. Tomcat home points to the containing directory of Tomcat's installation.
      
      

   2. If you are using Tomcat version 5.5.12 and above, make sure that the context declaration mode is 'Context files'.
      
      
      

   3. Inside the archive for Tomcat's plugin there's another archive named DevLoader.zip. extract this archive under %Tomcat's home%\server\classes (On my computer this will be C:\Program Files\Apache Software Foundation\Tomcat 5.5\server\classes)
      
      
      

   4. The plugin points Tomcat to eclipse's default JRE, however, this must be a JDK and not a JRE (Think: you need to be able to compile JSP's). So, you must make sure that the default runtime for eclipse is indeed a JDK (Open Window->Preferences, and expand the Java node. Under there, check Installed JREs, to make sure that you are indeed using a JDK as the default one for eclipse).

      Check that the configuration is correct by starting Tomcat from eclipse toolbar. You should see the server starting in the console with no exceptions :
      
      
      Click here for a full screen image.
      
      

   Creating a Tomcat/JSF project

   The last part of this blog describes how to create a Tomcat-ready JSF project in the configuration you just completed. In the next blog I will show how to create a simple JSF application and deploy it to Tomcat from within eclipse.

   1. A project in eclipse is a container for your code, and it's the first thing you need to create for your JSF application (or any application for that matter).
      
      1. In eclipse menu, select File->New->Project
         
         
         

      2. In the wizard you see, expand 'Java' and select 'Tomcat Project' underneath it. Click on Next.
         
         
         

      3. Enter a name for your project and click Next.
         
         
      4. In the next screen you see the 'Context Name' of your application. This is the place inside Tomcat that your application will be deployed. It defaults to the project name.
         Additionally you see a 'Subdirectory to set as web application root' text box. it defaults to '/' - which means the top level of your project file-structure. I usually prefer to set it to '/webcontent' and work from there. Click Finish.
         
         
         
         
         
   2. Eclipse creates a new project. It is Tomcat-ready, and you can see it in the Project Explorer view on the left of the eclipse window (workbench).
      Inside the project structure it has all the jars and definitions needed for Tomcat (you can see them in project properties, under Tomcat section). However, you now need to configure it for JSF development. (That is: tell eclipse that this is actually a JSF project and not an ordinary one).
      To achieve this, you need to create the file-structure for this project, and add JSF support. The plugins that you installed previously make this an easy task.
      1. The project contains a 'webcontent' folder inside (since we asked for this on project creation). Right click webcontent folder and create a new folder under it. This new folder will hold the JSF pages that you develop. Give this folder a meaningful name.
         
         
         

      2. Now we use the FacesIDE plugin to add JSF support to the project.
         Right click the project name in the Package Explorer, and select New->Other. In the wizard that you see, expand Amateras node and select 'Add JSF Support'.
         
         
         Click Next.

         In the next wizard screen you need to supply the Web Application root. Notice that the wizard defaults to the name of your project, but this will not do.
         The Amateras plugin can not guess where your application root resides, so you need to manually enter it.

         Click the Browse button, and navigate to the root (webcontent folder). Select it and click on OK.
         
         

         Make sure that the three checkboxes are checked, and click Finish.

         Note: It is possible to create the web root of the application (webcontent in the example) directly under the project's top directory. In my opinion, though, it is more manageable to divide the files in a certain directory structure.
         Moreover, keeping the structure this way, will ease deployment into Tomcat later on.

      3. Verify that the application web root is set.
         Right click your project, and select properties. In the screen that you see, select the Amateras node. See that the Root points to your web root
         
         
         Click here for a full screen image.
         
         

      4. You need to manually change web.xml for Tomcat to use the correct listener class for the JSF project.
         Open web.xml file under webcontent/WEB-INF and find the listener section inside it.
         change the listener-class tag to point to org.apache.myfaces.webapp.filter.ExtensionsFilter.
         
         
         

   You now have a JSF-oriented eclipse project under your hand. In the next blog we will use all the setup done here to develop and deploy a JSF application to Tomcat.