Tomcat/JSF Installation Instructions

Required Skills

• Download files from the internet to a location in your local computer where you can find them later
• Open zip files (using jar or a graphical zip utility)
• Open a command shell and issue basic commands (changing directories, listing directories, creating directories)

Installation Instructions

1. Locate the latest stable version of Tomcat from http://jakarta.apache.org/tomcat/. You want the binary distribution, not source.
   
2. To minimize installation complexities, choose the "zip" file.
3. Save the zip file (named something like jakarta-tomcat-5.5.7.zip) to your computer.
4. Unzip the file into a directory of your choice (such as /usr/local or c:\). The program is contained in a subdirectory named something like jakarta-tomcat-5.5.7.
   NOTE: For your own sanity, do not unzip into a directory containing spaces (such as Program Files or My Documents).
   
5. Download the latest version of the JSF Reference Implementation from http://java.sun.com/j2ee/javaserverfaces/download.html
   
6. Save the zip file (named something like jsf-1_1_01.zip) to your computer.
7. Unzip the file into a directory of your choice (such as /usr/local or c:\). The program is contained in a subdirectory named something like jsf-1_1_01.
   NOTE: For your own sanity, do not unzip into a directory containing spaces (such as Program Files or My Documents).
8. Copy all JAR files files from the lib subdirectory of your JSF installation (such as c:\jsf-1_1_01\lib) to the common/lib subdirectory of Tomcat (such as c:\jakarta-tomcat-5.5.7\common\lib). At the time of this writing, these files are
   
   • jsf-api.jar
   • jsf-impl.jar
   • commons-beanutils.jar
   • commons-collections.jar
   • commons-digester.jar
   • commons-logging.jar
9. Copy the following two JAR files from the webapps/jsp-examples/WEB-INF/lib subdirectory of your Tomcat installation (such as c:\jakarta-tomcat-5.5.7\webapps\jsp-examples\WEB-INF\lib) to the common/lib subdirectory of Tomcat (such as c:\jakarta-tomcat-5.5.7\common\lib):
   • jstl.jar
   • standard.jar

Starting and Stopping Tomcat

1. Open a command shell and change your directory to the Tomcat directory (such as /usr/local/jakarta-tomcat-5.5.7 or c:\jakarta-tomcat-5.5.7)
2. Change to the bin subdirectory
3. Type startup.sh (Unix) or startup.bat (Windows) followed by ENTER
   
   
   
   
4. Point your web browser to http://localhost:8080. You should get a "Congratulations" page.
   
   
   
   
5. To stop the Tomcat server, type shutdown.sh (Unix) or shutdown.bat (Windows) followed by ENTER.
   

Building Applications

1. Create a subdirectory with the name of your web application (such as myproject) inside the webapps directory of your Tomcat directory (such as c:\jakarta-tomcat-5.5.7\webapps\myproject)
   
2. Inside that subdirectory, create the following directory structure:
   myproject
      WEB-INF    
         classes
            mypackage         
   
   
3. Place your files as follows:
   
   • index.jsp and other web pages into myproject
   • faces-config.xml and web.xml into myproject/WEB-INF
     Your faces-config.xml file depends on your application. It contains your bean definitions and navigation rules.
     Your web.xml file is always the same, like this:
     

     ---

     <?xml version="1.0"?>
     
     <!DOCTYPE web-app PUBLIC
        "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
        "http://java.sun.com/dtd/web-app_2_3.dtd">
     
     <web-app>
        <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>*.faces</url-pattern>
        </servlet-mapping> 
     </web-app>
     

     ---

   • Source code for your beans into myproject/WEB-INF/classes/mypackage (where mypackage should be the package name that you use for your classes, such as bigjava).
     
   Here is an example:
   
   
   
4. Compile your beans, from the classes directory. Open a shell and issue commands similar to these:
   

   cd c:\jakarta-tomcat-5.5.7\webapps\myproject\WEB-INF\classes
   javac mypackage\*.java
   

5. Point your browser to http://localhost:8080/myproject/index.faces. (NOT .jsp!)
   Your application should start.
   
   
   

Troubleshooting tips

• If you get an exception stack trace, read it. There is often a useful tip in there somewhere.
  
  
  
  
• If your page is displayed but it seems dysfunctional, choose "View Source" from the browser menu.
  
  
  
  
• Logs are available in the logs subdirectory of the Tomcat directory (such as c:\jakarta-tomcat-5.5.7\logs). The most useful log is catalina.out. The newest error messages are at the end of the file
• Carefully check that all XML tags match up in the JSP and XML files. An XML-aware editor can be very helpful for this task.
  
• If all else fails, try stopping and restarting Tomcat.