< faces-config.xml Editor Appendices >

A Sample JSF Application



Overview

This is a tutorial in which we create a simple JSF application to demonstrate FacesIDE's functionality. This is a "login" application, which asks an user for an ID and password, verifies the information, and forwards the user to a success or error page.

The application will use a few JSP pages with JSF elements, and a session-scoped managed bean to coordinate their interactions. Along the way we'll use the following FacesIDE functionality:

As a prerequisite for the tutorial, make sure FacesIDE and required plugins have been installed; see Installing & Uninstalling. We don't assume that a J2EE server-specific plugin, such as the Sysdeo Tomcat plugin has been installed.



Creating A Project

Here we create an Eclipse project, and set up folders for a web application. The folder structure created is simply one that works for this author; your mileage may vary.

  1. From the menubar select File/New/Project.... The New Project wizard appears.
  2. Select Java Project; click Next.
  3. Enter project name, say, jsf-login; click Finish
  4. Create the web root folder: in Package Explorer select the jsf-login project, and from the menubar select File/New/Folder; name the folder webroot
  5. Create the web pages folder: in Package Explorer select the webroot folder, and from its context menu select File/New/Folder; name the folder pages. This folder will contain all "functional" pages.
  6. Use FacesIDE to add JSF support: we use a FacesIDE wizard to create J2EE-prescribed folders and files in webroot, and to add JSF libraries to the project.
    1. in Package Explorer select the jsf-login project
    2. from the menubar select File/New/Other...
    3. in the wizard that appears, select Amateras/JSF/Add JSF Support; click Next
    4. in the Add JSF Support page, for Web Application Root enter /jsf-login/webroot; make sure all checkboxes are checked; click Next.
  7. From the menubar open Project/Properties
  8. Select the Amateras node; note that Root: has automatically been set to /webroot; make sure HTML validation and DTD/XSD validation are enabled.
  9. Create the source folder: select the Java Build Path node; select the Source tab; click Add Folder...; in the dialog that appears create a folder named src directly under the project folder (jsf-login); click Yes through messages that appear.
  10. Set the output folder: in the Default output folder textbox at the bottom, enter jsf-login/webroot/WEB-INF/classes; click OK to dismiss the properties dialog.
Your folder structure should now be as follows:
            jsf-login
              |
              +-- src
              |
              +-- webroot
                    |
                    +-- WEB-INF
                    |     |
                    |     +-- classes (not shown in Java perspective)
                    |     |
                    |     +-- lib
                    |
                    +-- pages



Creating & Configuring Managed Beans

Here we create a class called LoginManager which will be used as a backing bean for the login process. We then configure it to be a managed bean.

  1. In Package Explorer select the src folder; from its context menu select New/Class. The New Java Class wizard appears.
  2. In the Package field, enter login; in the Name field enter LoginManager. Click Finish. The Java code editor opens.
  3. Enter and save the following code for the LoginManager class:

    // LoginManager.java package login; public class LoginManager { private String _uid = ""; private String _pwd = ""; public String getUserID() { return _uid; } public void setUserID(String uid) { _uid = uid; } public String getPassword() { return _pwd; } public void setPassword(String pwd) { _pwd = pwd; } public String loginAction() { String action = null; if ( _uid.equalsIgnoreCase("foo") && _pwd.equalsIgnoreCase("bar") ) action = "loginPass"; else action = "loginFail"; return action; } }

  4. Use FacesIDE to configure the bean: we use a FacesIDE editor to configure LoginManager as a session-scoped managed bean.
    1. in Package Explorer select jsf-login/webroot/WEB-INF/faces-config.xml; from its context menu select Open With/faces-config.xml Editor. The faces-config.xml editor opens.
    2. along the bottom of the editor there are 3 tabs; click Managed Bean.
    3. click Add; input widgets appear
    4. for name enter mgr; for class enter login.LoginManager; for scope select session.
    5. from the menubar select File/Save, then close the editor


Creating JSP Pages

Here we create the JSP pages that make up the application's user interface. We will have 4 pages: a start page (index.jsp), and 3 content pages (login.jsp, success.jsp and error.jsp). Content pages are placed in webroot/pages; index.jsp is placed directly in webroot, and its sole function is to forward users to the login page.

All pages except login.jsp are simple pages with static content, so we create them first, using the Workbench's standard file-creation facilities. Then we create login.jsp using a FacesIDE wizard.

  1. Create index.jsp:
    1. in Package Explorer select webroot; from its context menu select New/File; the New File wizard appears.
    2. for File name enter index.jsp; make sure that the parent folder is set to /jsf-login/webroot; click Finish; the JSP Editor opens.
    3. enter the following code, save the file and close the editor.

    <!-- webroot/index.jsp --> <html> <body> <jsp:forward page="faces/pages/login.jsp" /> </body> </html>

  2. Create success.jsp: create this file similarly to index.jsp, but in webroot/pages. Enter the following code:

    <!-- webroot/pages/success.jsp --> <html> <head> <title>jsf-login</title> </head> <body> <h2>Success!</h2> </body> </html>

  3. Create error.jsp: create this file similarly to index.jsp, but in webroot/pages. Enter the following code:

    <!-- webroot/pages/error.jsp --> <html> <head> <title>jsf-login</title> </head> <body> <h2>Error!</h2> The user-id and or password were invalid. Please try again. </body> </html>

  4. Create login.jsp:
    1. in Package Explorer select webroot/pages; from its context menu select New/Other...; the New wizard appears.
    2. select Amateras/JSF/Faces JSP File; click Next
    3. for File name enter login.jsp; make sure that Container is set to /jsf-login/webroot/pages, and that Use MyFaces Tomahawk components and Use MyFaces SandBox components are unchecked, and choose default for Template; click Finish; the FacesIDE JSP Editor opens, with the following template code.

      <%@ page contentType="text/html; charset=Cp1252" %> <%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> <%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=Cp1252"/> <title></title> </head> <body> <f:view> <h:form> </h:form> </f:view> </body> </html>

      We will now edit this page to contain our input widgets, etc.
    4. place the cursor between the <title></title> elements; enter jsf-login
    5. Open the JSF palette, and dock it along the right. (See Show View Dialog)
    6. create a few blank lines between the <h:form> elements; place your cursor in one of these lines, expand the JSF HTML panel in the palette, and click on the icon for <h:inputText>; this inserts the corresponding JSF element at the cursor location.

      Note: the JSP editor is aware of referenced tag libraries, and uses them for code completion as well. Thus if you were to type <h: and hit CTRL + Spacebar, you would get a popup window of JSF HTML elements.

    7. now we want to add attributes to this element, and the JSP Editor can help with code- completion. To see this in action, place the cursor inside the <h:inputText> element, and hit CTRL + Spacebar; a code-completion window pops up, as shown below.

    8. in the code-completion window scroll down to value, and hit Enter; this inserts value="" at the cursor. We will now bind this to the userID property of LoginManager; FacesIDE can provide code completion here as well.
    9. place the cursor between the quotes in value="", enter #{mgr., and hit CTRL + Spacebar; a code-completion window pops up, with bean properties available in mgr. This is shown below:

      (Recall that we configured LoginManager as a managed bean called mgr.)
    10. select userID from the code-completion window; complete the expression with the closing {
    11. insert another <h:inputText> element; set its value binding expression to value="#{mgr.password}"
    12. insert a <h:commandButton> element; set its value to Login, and its action to the value binding expression #{mgr.loginAction}

    The final code, with the barest presentational formatting, is shown below:

    <%@ page contentType="text/html; charset=Cp1252" %> <%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> <%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=Cp1252"/> <title>jsf-title</title> </head> <body> <f:view> <h:form> UserID: <h:inputText value="#{mgr.userID}"/> <br/>Password: <h:inputText value="#{mgr.password}"/> <br/><h:commandButton value="Login" action="#{mgr.loginAction}"/> </h:form> </f:view> </body> </html>



Creating Navigation Rules

Here we create navigation rules among pages, using a FacesIDE editor.

  1. Open faces-config.xml; it should open in the faces-config.xml Editor.
  2. Select the Navigation tab
  3. from the Navigation panel in the palette at left, click on Page, then click inside the editor window; this inserts a page icon into the editor, and the page's properties appear in the Workbech's Properties view. This is shown below.

    Note that the icon has a small triangle overlay--this indicates that something is wrong, specifically that FacesIDE could not locate a page at path /page1.jsp

  4. in the Properties view, change the value of path to /index.jsp. You can also change it on the diagram directly (select the page and click once more); notice that the warning triangle disappears.
  5. add 3 more pages, and set them to /pages/login.jsp, /pages/success.jsp and /pages/error.jsp. Arrange them as shown below:

    Now we'll add navigation rules among the pages.
  6. from the palette at left, select Navigation Case, then click first on the icon for login.jsp and then on the icon for success.jsp. This inserts a forward-action between the two pages, and is represented by an arrow. "Decharge" the mouse pointer by clicking on the pointer icon in the palette, then click on the newly-added forward-action icon to select it. Its properties appear in the Properties view. This is shown below:

  7. in the Properties view (or direct editing on the diagram), change the value of from-outcome to loginPass. Recall that this is the success-value returned by LoginManager's loginAction method. You can also change values by direct-editing (select once and re-click) in the diagram
  8. Similarly add a forward-action from login.jsp to error.jsp, and set its from-outcome to loginFail

We're done with setting up navigation rules. We'll set some properties in web.xml, and we'll then be ready to deploy the application.



Editing web.xml

Here we edit web.xml for the specifics of our application. As it turns out, since we have such a trivial application, all we need do in web.xml is indicate the Faces Servlet mapping.

  1. open web.xml; scroll to the bottom and look for the comment

    <!-- Faces Servlet Mapping -->

  2. by default virtual path-based mapping is commented out, and extension-based mapping is turned on. We want virtual path-based mapping, so uncomment it. You may comment out the entry for extension-based mapping, or leave it as-is.

The application is now complete, and you should be able to deploy it to your server of choice. Once deployed browse to index.jsp, and you should be automatically forwarded to login.jsp. Use UserID/Password of foo/bar, and you should be sent to the success page; any other id/password should send you to the error page.



Deployment to some servers is described below:


Deploying To Tomcat 5.0

  1. start Tomcat; open its Manager application in a browser; the default URL for this is http://localhost:8080/manager/html
  2. scroll down to Deploy; we'll deploy our app by providing its directory; for Context path enter /jsf-login; for WAR or Directory URL enter the path to webroot, as file:///...; leave XML Configuration File URL blank; click Deploy
  3. the Manager application should reload, and you should see /jsf-login in the list of running applications. Click on its link to launch the application.
< faces-config.xml Editor Appendices >
FacesIDE User Guide (https://amateraside.dev.java.net/)