Tutorial:

Slingshot Yourself into JavaServer Faces 2.0: Learning JSF

By Cameron McKenzie & Sal Pece

TheServerSide.com

Starting with the Basics

The formatting of code in the article is not displaying properly. You can view the code, properly formatted, here. It's also a good spot to ask a question about getting the configuration to work.

Ok, you have to understand that I'm a little bit loath to do this. That is, I'm not overly joyed about going through the process of setting up a basic development environment that will facilitate the development and testing of JSF applications. Personally, I'd rather just assume that you've already got some type of development environment, such as Sun's NetBeans or IBM's Rational Application Developer, already set up and ready to go. That way, I could jump right into the guts of application development with JavaServer Faces. But I guess it is important to discuss what the basic, system and software requirements are, if an individual wants to do JSF 2.0 development; and correspondingly, I guess I do have an obligation to demonstrate how someone might get a basic development environment up and running.

The NetBeans IDE from Sun is GNU licensed & ideal for JSF development.

Watch this tutorial as an online video.

Environment Configuration Can Be Frustrating...

One thing I must say is that setting up a development environment can often be the toughest, most frustrating part, of learning JSF. If you have someone with JSF experience on your team, or know someone that is a bit of a Java Guru, ask them to help you configure your local environment, and maybe even ask them to walk you through the development and deployment of a very simple JSF 'Hello World' type of application. And if you can't get some local help, and you do run into a problem or two, don't be afraid to reach out to the Java community for some help. I regularly lurk in the JavaRanch's JSF forum, (www.javaranch.com). If you're running into a problem, I stridently urge you to post a question in there. The faster you can get your development environment up and running, the sooner you'll be learning the ins and outs' of JSF development.

Getting Started

If you want to start working with JSF, the first thing you need to do is set up some sort of development environment. There are plenty of great Java development environments out there, ranging from NetBeans to Eclipse. Unfortunately, I have neither the time nor the patience to discuss how to configure each and every Java development tool in existence, so instead, I'm just going to describe how to configure the cheapest, most simple and basic environment one could 'muster up' on a Windows based computer. If you can get a JSF application working with nothing more than what I am going to describe here, that being Wordpad, a JDK installation, and a distribution of Apache's Tomcat Servlet engine, well, you should be able to take that knowledge and apply it to just about any Java development environment out there.

The World's Most Basic Development Environment

So, here's the basic minimum that you need in order to start developing and testing a JSF 2.0 application on a Windows machine:

  • Java Development Kit, version 5 (aka 1.5) or higher. I will be using JDK 1.6 update 18.
  • A Servlet Engine supporting the Servlet 2.5 API and the JSP 2.1 API (Tomcat 7 or better will more than fit this bill)
  • A JSF Implementation (jsf-api.jar and jsf-impl.jar files)
  • The JSTL implementation jar files (standard.jar and jstl.jar)
  • A text editor such as Wordpad or EditPad
  • The command prompt to compile and run your JSF applications

Obtaining the Right JDK Version

It should come as no surprise to find out that if you want to do some Java based web development, at the very least, you'll need to install the standard edition (SE) of the Java Development toolKit, or as it's more affectionately know, the JDK. JSF 2.0 requires support for generics, which is a feature that only became available in Java 5, so a JDK that provides at least a Java 5 runtime environment is the bare minimum. At the time of writing, Java 7 is a few months from being released, so I'm going to split the difference between versions five and seven, and subsequently download and install JDK 1.6, which provides a Java 6 runtime.

The JDK can be download from:

http://www.oracle.com/technetwork/java/javase/downloads/index.html
(http://goo.gl/4FBBp).

Be careful when browsing through Oracle's website for a JDK. When you get to the Java downloads part of Oracle's website it can become pretty darned confusing; you'll see all sorts of links for downloading everything from the 'JDK with NetBeans', to the 'JDK with JavaFX.' That's all great stuff that Oracle is offering up, but all you really want is a nice, clean, simple JDK. Find the JDK and download it.

Installing the JDK

The installation of the Java Development toolKit is relatively straightforward. After reading and accepting the license agreement, you will be asked for two installation directories, the first being the directory to install the JDK, and the second being the directory to install the Java Runtime Environment (JRE). Much to the chagrin of everyone else on my development teams, I like to install important programs into a directory that starts with a leading underscore; so I'm going to install the JDK into the C:\_jdk1.6 directory. I suggest you do the same, as hunting for the JDK installation under the 'Program Files' directory can become somewhat tiring. On the other hand, I could really care less about where the JRE gets installed, so feel free to accept the default directory location for the JRE.

Configuring the JAVA_HOME

Installation of the JDK is not complete until you have configured the JAVA_HOME variable for your computer. So, from the Advanced tab of the 'System' window in a Windows environment (accessed from the Control Panel), Click the 'New' button to add a 'System Variable.' The Variable Name must be JAVA_HOME, and if you installed your JDK to the same location as me, the Variable Value will simply be C:\_jdk1.6 (don't forget the underscore!)

By the way, you may need to reboot your system for Windows to recognize this setting. So, f you start trying to run Tomcat (the next set of steps) and you keep getting a "JAVA_HOME could not be found" error, and you're sure you've followed these steps properly, you just might need to bounce your machine.

The Servlet Engine

With the JDK installed, and the JAVA_HOME system variable configured, you need to get yourself a web based runtime environment that will allow you to deploy and test your JSF applications. As far as Servlet Engines go, you can use IBM's WebSphere or Sun's GlassFish, but I'm simply going to use the open source Apache Tomcat Server. Version 7 of the Tomcat Server supports the Servlet 3.0 API and the JSF 2.2 specification, sufficiently more than the minimal Servlet 2.5 and JSF 2.1 specifications required by JSF 2.0. By the way, Tomcat 6, because it doesn't support Java EE 6 EL (expression language) out of the box will cause you a headache or two when you deploy JSF 2.0 applications to it, so you're best to stick with Tomcat 7.

You can find the download page for Tomcat 7 at the apache website:  

http://tomcat.apache.org

 

To install Tomcat, you simply need to head over to tomcat.apache.org and download the Core Binary Distribution in zip format. I simply unzipped the downloaded file to my C:\ drive, and then renamed the folder the 'unzipping' created to C:\_tomcat, preceding the name tomcat with a single underscore, just as I did with the JDK installation.

Testing the Tomcat Installation

 To test your Tomcat and JDK installations, simply navigate a command prompt to the \bin directory of your tomcat installation and issue the command startup.

 C:\_tomcat\bin> startup

A new Tomcat command window should appear, indicating that the Tomcat Server has started up, and is running on http port 8080. The last line of my Tomcat Window says the following:

 INFO: Server startup in 699ms

So, with a promising little log message like this guiding you on your way, you can open up a web browser and type in following URL:

 http://localhost:8080

That little URL should bring up the welcome page of the Tomcat Server, indicating that both Tomcat and the JDK have been installed successfully, and the JAVA_HOME system variable has been properly configured. Congratulations if it all works properly. If it doesn't, head over to JavaRanch and start asking some questions.

Verifying our installation is great, but we're not quite done yet. There are a few little resources we need to acquire before we can actually start writing JSF applications. Most importantly, we need to obtain an implementation of JSF itself.

What is JSF?

Now, technically speaking, JSF is just a specification. JSF is simply a document and a set of unimplemented APIs and JavaDocs that describe a neat, cross-platform technology that can be used to write web based enterprise applications in Java. But to actually use JSF you need an implementation of the JSF specification; that is, somebody must have taken the time to implement all of the things that are defined in the spec. Fortunately for us, Sun provides a 'freely' downloadable JSF implementation through what is affectionately known as the Mojarra project. A working link for the Mojarra project at the time of writing is:

 https://javaserverfaces.dev.java.net/ (who knows when this will change?)

This link will lead you to a downloads page where you are provided with far too many download options. The download you need is the binary download for the most current 2.0.x release, which for me was release 2.0.3(3).

Once the file is downloaded, extract the contents to the C:\ drive. The bytecode implementation of JSF can be found in the lib directory of the JSF binary download. This folder contains two critically important jar files named: jsf-api.jar and jsf-impl.jar. These two jar files are of vital importance to us, and must be included in each and every JSF application we deploy.

It should also be noted that the JSF binary distribution also contains a folder named docs. Navigating to this folder, and then extracting the javadocs zip file will lead you to a folder that includes a file named index.html. This is the landing page of the JavaDocs for the entire JSF 2.0 specification. If you're going to be doing a lot of JSF development, I strongly suggest bookmarking this page, and referring back to it whenever you need a clarification with respect to the JSF API.

The JSTL Dependency: jstl.jar and standard.jar

And finally, we actually have two more jar files we need to obtain in order to start hacking out some JSF code, namely the two library files that embody the Java Standard Tag Library (JSTL). JSF leverages JSTL in a few of its custom tags, so any application that we deploy must include these additional two jar files that make JSTL work, jstl.jar and standard.jar. One way to find the jstl.jar and standard.jar files is to dig into your tomcat installation and look inside the webapps folder. In Tomcat, the pre-deployed web application named examples contains the jstl.jar and standard.jar files in its WEB-INF\lib directory.

Alternatively, a JSTL implementation, and the corresponding jstl.jar and standard.jar files, can be downloaded from Sun or Apache at the following locations:

 https://jstl.dev.java.net/ (Sun Microsystems) http://jakarta.apache.org/taglibs/index.html (Apache.org)

So, what's next?

Now that you've got your JDK installed, your Tomcat 7 server up and running, and the required JAR files downloaded and readily accessible, you're ready to create a super-simple JSF 2.0 application.

Watch this tutorial as an online video.

A Simple JSF 2.0 Application

Let's put together a very simple JSF application, using this opportunity to examine the structure of a JSF application, while at the same time, testing our ability to create and deploy applications to our test environment.

The Web Application Folder Structure

JSF applications are simply standard web applications that conform to the requirements of the Servlet and JSP specification. As such, every JSF application has an application root. For this example, I'm going to create a new folder off the root of the C:\ drive named _easyjsf that will act as the root of my JSF application.C:\_easyjsf

Under the root of a Java web application there is always a folder named WEB-INF. A variety of fabulous things can reside within this folder, including a lovely \lib folder in which you can throw any number of jar files, xml files or other resources that your web application might need at runtime. So, under the _easyjsf folder, we need to add a subfolder named WEB-INF, and under that WEB-INF folder, we need another folder named lib.

Furthermore, any Java code that gets compiled and distributed with your JSF application will go in a classes directory that also resides under the WEB-INF folder. Although we won't be compiling any code in this example, it's worthwhile adding in the classes folder while we're puttering around in WEB-INF.

Acquiring the Required JSF Libraries

Now, JSF isn't a built in feature of a servlet engine, and it's certainly not part of the Servlet and JSP specification. So, if you want to create a web application that will leverage JSF technology, you need to first acquire, and then add in the various jar files that provide an implementation of the JSF spec. Furthermore, these jar files need to go in a very specific directory - the directory we just created named lib that resides directly under the WEB-INF directory of a web application.

The four jar files that need to go in the lib folder of a JSF web app are:

  • jsf-api.jar
  • jsf-impl.jar
  • jstl.jar
  • standard.jar

The jsf-api.jar and jsf-impl.jar files were downloaded from Sun as part of the binary JSF distribution. The jstl.jar and standard.jar files can either be downloaded from apache.org, or more easily, can be found in the lib folder of the example application that is included in the binary distribution of the Tomcat 7 server.

Make sure these four files are placed in the \lib directory of the WEB-INF folder of the web application.

Dealing with the Deployment Descriptor: web.xml

Our goal here is to create a very basic JSF application from scratch. But, before a JSF application can be a JSF application, it must first and foremost be a Java web application. The folder structure we have implemented so far is forced upon us by the requirements of the Servlet and JSP specification. Along with this uncompromising folder structure, every Java based web application must contain a special file known as a deployment descriptor, which resides in the WEB-INF folder of the app, and is always given the name web.xml. This supremely important web.xml file provides information to the runtime web environment, such as Tomcat or any other servlet engine, about how to configure the environment in which the application will run. Our web application will need a web.xml file.

Take a quick look at the web.xml file we'll be using in this JSF application, as we'll soon be discussing it in detail.

 <?xml version='1.0' encoding='UTF-8'?> <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"> <display-name>JSF Made Easy</display-name> <servlet id="JSF_Front_Controller_Servlet"> <servlet-name>Faces Servlet</servlet-name> <servlet-class>javax.faces.webapp.FacesServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>*.faces</url-pattern> </servlet-mapping> </web-app>

JSF and the web.xml File

For a JSF application, the web.xml file can be pretty lean. However, there are two extremely important parts of a web.xml file that pertain directly to JSF and bear mentioning.

The web.xml file of a JSF application must reference the FacesServlet. In a JSF application, all JSF centric requests go through a single, central Servlet which is most uncreatively named FacesServlet. All JSF centric requests that come into a given web based application are routed through this single, monolithic servlet, which is then responsible for handling the incoming request, invoking the appropriate components, and then generating a response that will get sent back to the client.

Here's the part of the web.xml file that references the JSF FacesServlet:

 <?xml version='1.0' encoding='UTF-8'?> <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"> <display-name>JSF Made Easy</display-name>  <servlet id="JSF_Front_Controller_Servlet"> <servlet-name>Faces Servlet</servlet-name> <servlet-class>javax.faces.webapp.FacesServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>*.faces</url-pattern> </servlet-mapping> </web-app>

JSF Centric Requests and the Servlet Mapping

As I mentioned, all JSF centric requests that come into a given web application go through the FacesServlet. However, that begs the question, 'how does a given application know that an incoming request is a JSF centric request?' Well, that's an easy question to answer, and to answer it, all you have to do is look at the web.xml file.

As we develop our Java based web application, all JSF based requests coming into the server will share a common extension. So, rather than requesting a .jsp file or .html file, URLs requesting a JSF centric resource will end with a .faces extension.

So, when we finally get this little HelloWorld application we're working on up and running, the URL requesting our application will look like this:

http://localhost:8080/easyjsf/helloworld.faces

As you can see, the request URL ends with a '.faces' extension, telling the servlet engine that this is a JSF based request. This 'extension mapping' is achieved by configuring a 'servlet mapping' in the web.xml file.

 <?xml version='1.0' encoding='UTF-8'?> <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"> <display-name>JSF Made Easy</display-name> <servlet id="JSF_Front_Controller_Servlet"> <servlet-name>Faces Servlet</servlet-name> <servlet-class>javax.faces.webapp.FacesServlet</servlet-class> </servlet>  <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>*.faces</url-pattern> </servlet-mapping> </web-app>

The formatting of code in the article is not displaying properly. You can view the code, properly formatted, here.

Notice how the servlet-name in the <servlet-mapping>, Faces Servlet, matches the exact name used when configuring the FacesServlet in the <servlet> entry of the web.xml file? Essentially, we are telling the Servlet Engine that any request that comes in with a .faces extension should be handled by the Faces Servlet, which is implemented through the Java class named javax.faces.webapp.FacesServlet.

Rounding Out the web.xml Deployment Descriptor

Along with the <servlet> and <servlet-mapping> entries, the web.xml file should also include a <display-name> element. We're just going to use the simple display name of JSF Made Easy:

 <display-name>JSF Made Easy</display-name>.

The ?xml Preamble and xmlns Garbage

All of the elements, starting with the <display-name> tag, and ending with the <servlet-mapping> get nested within a fairly verbose <web-app> tag that includes version, schema name, and schema location elements. As I said, it's fairly verbose, and typing it out by hand is simply insane.

If you look at the various web.xml files that are in the WEB-INF folder of the various sample applications that come with the JSF binaries, you'll find plenty of examples of the web-app entry that you can just copy and paste into your own deployment descriptor. That's what I do. Of course, if you're a masochist that wants to type it all out by hand, I'm not going to stop you, but I recommend against it.

By the way, there's also a ?xml element that should go at the very top of every web.xml file as well.

 <?xml version='1.0' encoding='UTF-8'?> <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"> <display-name>JSF Made Easy</display-name> <servlet id="JSF_Front_Controller_Servlet"> <servlet-name>Faces Servlet</servlet-name> <servlet-class>javax.faces.webapp.FacesServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>Faces Servlet</servlet-name> <url-pattern>*.faces</url-pattern> </servlet-mapping> </web-app> The formatting of code in the article is not displaying properly. You can view the code, properly formatted, here.

The JSF Configuration File: faces-config.xml

Right alongside the web.xml file, every JSF application should have a configuration file named faces-config.xml, which like the web.xml file, is stored right there in the WEB-INF folder. Now that annotations are all the rage, the need for the faces-config.xml file has been minimized significantly, and you could probably get some pretty crazy JSF application up and running completely without a faces-config.xml file, but there are times when you need one, so just for the sake of foresight and posterity, I'm going to suggest add a basic one into the mix.

As the name implies, the faces-config.xml file can contains a variety of salacious nuggets of information about your JSF application, and as your application grows, so can the number of contained elements and entries. For now, however, our faces-config.xml file will be pretty nascent, with nothing more than the requisite <?xml> entry, the top level <faces-config> tag, and the verbose and intimidating namespace, version, and schema location attributes that are required.

Here's what the faces-config.xml file looks like for the application we're building in this chapter. I know, it's not too exciting, but then again, XML never is.

 <?xml version="1.0"?> <faces-config xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd" version="2.0"> </faces-config>

The formatting of code in the article is not displaying properly. You can view the code, properly formatted, here.

As with the verbose entries in the web.xml file, these attributes are so long and verbose that it's practically impossible to type them out by hand without some type of dictational mistake. It's best to just copy the full <faces-config> element and attributes from one of the sample applications that come bundled with the binary distribution of the JSF implementation. Just make sure you're copying from a version 2.0 implementation and not an older 1.2 or 1.1 version.

The HelloWorld.xhtml File

With the basic configuration stuff done, it's time to write a little 'Hello World' page that will be deployed to our servlet engine and served up by the JSF framework. We're not going to win any programming awards with this rudimentary xhtml page, but it will introduce a few important concepts, and it will also help verify that indeed, we can get a basic JSF application working in our local environment.

 Our file is simply going to be named helloworld.xhtml, in all lower case letters, and indeed, it will have a .xhtml extension. JSF 1.2 used jsp files, but JSF 2.0 favours the use of .xhtml files as it pushes developers to work more with with facelets and less with the JSP API. Having said that, it is still possible to use JavaServer Pages in a JSF application.

Non-secured resources can sit fearlessly right in the root of the web application, so this helloworld.jsp file will be placed right into the _easyjsf folder. If you're anxious to type the whole thing out before we actually discuss it, here's the complete code for our helloworld.xhtml file.

 <!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> <title>Simple JSF Page - xhtml</title> </h:head> <h:body> <h:outputText value="Hello World!"/> </h:body> </html>

Debriefing the helloworld.xhtml File

So, there's really nothing too intimidating here.

First of all, we see the !DOCTYPE tag, which all good xHTML documents should have. There is no teachable moment here.

Next we see the html tag declaring four namespaces, with the first being the xhtml namespace, and the other three being JSF centric. Out of the box, JSF provides three tag libraries for helping to build your view pages, the html tag library, which is denoted by the letter h, the core libraries that are denoted by the letter f, and new to JSF 2.0, the ui libraries, which thrust you into user-interface design technology known as facelets. You only actually need to declare the namespaces that are being used on the page, so for this example, we could get away with just mentioning the xhtml and the jsf/html namespaces, but it's a good practice to include all of the JSF namespaces right off the top, just in case someone else comes in at a later date and adds a tag or two.

<h:head> is the first JSF custom tag we see, in which a timid little title tag is wrapped, demonstrating how JSF tags and normal HTML tags can easily work together.

The body of the page is quite simple, using the JSF <h:body> tag to delineate a start and finish, all of which wraps a lonely <h:outputText> tag that instructs the framework to spit out the words "Hello World." There's nothing earth shattering here, but that's the whole point - to keep it simple and make sure it works; that way we confirm that our JSF environment is indeed working propertly, and learn a tiny bit about JSF as we do it.

Code It and Save It

Type out the code for the xhtml file into any standard text editor, such as Microsoft's Notepad, and save the file as helloworld.xhtml in the application root folder, which for me, is C:\_easyjsf. Now, remember, we save the file as helloworld.xhtml, not helloworld.jsf or helloworld.jsp. And also keep in mind that Java is case sensitive. Don't go throwing a bunch of capital letters in where they don't belong!

Creating a WAR File for Deployment

With your application created and conforming to the required folder structure, loaded with the required jar files, configured with the correct deployment descriptor, and your helloworld.xhtml file coded and saved to the root of your web application, it's time to 'WAR-up' your JSF application and deploy it!

A WAR file, or Web Application aRchive, is the standard format for distributing and deploying Java EE, web based applications. A WAR file itself is really little more than a ZIP or compressed file with the contents of that compressed file conforming to the Servlet and JSP specification.

The jar utility that comes with the JDK is great at compressing your web applications into deployable WAR files. To WAR-up your application, simply navigate a command prompt to the C:\_easyjsf> folder, and issue the following command:

 C:\_easyjsf> C:\_jdk1.6\bin\jar -cvf easyjsf.war *.*

Now, this command relies on the fact that the JDK has been installed to a folder named C:\_jdk1.6. If you have a different folder location for your JDK, you will need to reference that JDK installation folder explicitly. Alternatively, if JAVA_HOME has been configured in your operating system, you could simply use that environment variable in your command:

 C:\_easyjsf> %JAVA_HOME%\bin\jar -cvf easyjsf.war *.*

Regardless of how you run the command, once the command is issued successfully, a war file will be created in the folder from which the command was issued. In this case, our easyjsf.war file will be found in the C:\_easyjsf directory. We then need to deploy this application to our Servlet Engine.

Application Deployment to the Tomcat Servlet Engine

The compressed, easyjsf.war file, will end up smack dab in root of your _easyjsf folder if you run the command exactly as it was described. There's really no need to have the war file in the application root folder. What we really want is to deploy this easyjsf.war file to our Servlet Engine. To deploy this war file to Tomcat, all we need to do is move, through a simple cut and paste, the easyjsf.war file into the webapps folder of the tomcat installation. For me, the full name of this folder is: C:\_tomcat\webapps

By the way, if we were really smart, we would have issued a jar command that saved the war file in the webapps folder right off the bat. If you want to get real fancy, the command to do such a thing would look like this:

 %JAVA_HOME%\bin\jar -cvf C:\_tomcat\webapps\easyjsf.war *.*

We want to test our application, so make sure your tomcat server is started, after all, nothing will run if your server isn't started. If there's any doubt about your server status, you can always do a quick bounce of your tomcat installation by issuing the following commands:

 C:\_tomcat\bin> shutdown C:\_tomcat\bin> startup

Tomcat Deployment

If Tomcat is running, it will automatically recognize the fact that a new war file as been placed in the webapps directory, and it will attempt to deploy that application.

If you look at the command window from which tomcat was started, you should see some mumbo-jumbo about a JSF 2.0.3 context being successfully initialized for your easyjsf application. (You may need to stop and start your Tomcat server to have the application loaded properly the first time.) Here's what my tomcat console output looked like

 INFO: Initializing Mojarra 2.0.3 (FCS b03) for context '/jsf-guessNumber2.0'
Aug 8, 2009 9:21:16 PM org.apache.catalina.startup.HostConfig deployWAR

Testing the Web Application at Runtime

With the context successfully initialized, it's time to open up a web browser and navigate to your JSF application. You can invoke your application using the following URL:

 http://localhost:8080/easyjsf/helloworld.faces

The key elements in this URL are the IP address and port (localhost:8080), the context root, which is easyjsf, (it matches the name of the war file, minus the .war extension), all followed by the name of the helloworld web resource we are invoking. However, you should notice that the url says helloworld.faces, not helloworld.xhtml.

Remember, for our application, only requests that end with the .faces extension are handled by the FacesServlet, which is in essence, the entry point into the JavaServer Faces framework. By putting the .faces extension on our URL, the JSF framework knows to locate a resource named helloworld. Our xhtml file gets compiled and run, and as a result, we see a little 'Hello World' message in the web browser.

Get the URL Right!

Again, the URL we use must end with the .faces extension. This was the whole point of configuring a servlet mapping for *.faces in the web.xml file. Only requests that end with a .faces extension will be handled by the Faces Servlet. Here's the web.xml file from earlier in this chapter, just to refresh your memory:

 <?xml version='1.0' encoding='UTF-8'?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
<display-name>JSF Made Easy</display-name>
<servlet id="JSF_Front_Controller_Servlet">
<servlet-name>Faces Servlet</servlet-name>
<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>*.faces</url-pattern>
</servlet-mapping>
</web-app> The formatting of code in the article is not displaying properly. You can view the code, properly formatted, here.

Alternatively, if you tried to access your web page using a URL that ended in .jsp or .xhtml instead of .faces, you'd end up getting some esoteric error message like this:

 The server encountered an internal error...JasperException: An exception occurred at line 8 5: <title>Simple JSF Page</title> 6: 7: </head> 8: <f:view> 9: <body> 10: <p>Hello World!</p> 11: </body> Stacktrace:JspServletWrapper.handleJspException (JspServletWrapper.java:505) JspServletWrapper.service(JspServletWrapper.java:416) root cause java.lang.RuntimeException: Cannot find FacesContext UIComponentClassicTagBase.getFacesContext

Wrapping it Up!

Of course, there's no point focusing on what might go wrong when you've already successfully created and deployed your application. And if you did indeed get your application up and running, you should give yourself a big pat on the back, because that means you've managed to properly build and deploy a JSF application from scratch. Plus, you also know that your runtime application environment is working properly, which should give you the confidence to continue to expand your JSF skills and knowledge. And speaking of expanding your JSF skills and knowledge, that's exactly what we're going to do in the next set of steps.

Watch this tutorial as an online video.

01 Feb 2011