How To Use JSF with JDeveloper 10g

An Oracle JDeveloper How To Document
Written by Chris Schalk, Oracle Corporation
April, 2004

Index

Introduction

JavaServer Faces is a new Java technology which provides a standard way to build thin client/HTML based applications using Java. Although JDeveloper 10g's complete and enhanced support for JSF development will be provided in post 10g releases, it is still possible to productively do JSF 1.0 development JDeveloper 10g. This document describes how to install and work with JavaServer Faces 1.0 in JDeveloper 10g.

How to install the JSF libraries into JDeveloper

Creating a "JSF" Library and registering the JSF JSP tag libraries

  1. Download the JSF 1.0 Reference Implementation. Unzip this file to a separate directory such as d:\jsf. This directory will contain the subdirectories: docs, javadocs, lib, samples and tlddocs. The lib directory will contain the required jar files and tld (tag library descriptors) files for JDeveloper to work with JSF.
  2. Create a JDeveloper "JSF" library to manage the required JSF jar files in JDeveloper.
    • Select Tools-> Manage Libraries from the main menu.
    • Select the "Libraries" tab.
    • Select the "System Libraries" node and click "New".
    • Name the library "JSF".
    • For "Class Path:" click "Edit..." and add all of the jar files: jsf-api.jar, jsf-impl.jar and commons*.jar located in your JSF bundle's lib directory: "d:\jsf\lib".
  3. Now register the JSF (JSP) tag libraries with JDeveloper and add them to the Component Palette.
    • Again, select Tools-> Manage Libraries from the menu.
    • This time select the "JSP Tag Libraries" tab and click "New".
    • Add the " JSF Core" tag library by specifying the following:
      • TLD File: D:\jsf\lib\jsf_core.tld (Use the Browse button to locate the JSF Core tag library descriptor: TLD.)
      • Libraries: JSF (Click on the Browse button and select your new "JSF" library.)
      • URI: (Should be autofilled)
      • Prefix: f
    • Leave the "Execute Tags in JSP Visual Editor" checkbox unchecked and click "OK".
    • Answer " Yes" to the dialog asking to add the tag library to the Component Palette.
    • Name the Palette Page name: " JSF Core". (You can edit the combobox.)
  4. Repeat this process to add the second " JSF HTML" tag library with the following:
    • Select Tools-> Manage Libraries, choose the "JSP Tag Libraries" tab and click "New".
      • TLD File: D:\jsf\lib\html_basic.tld
      • Libraries: JSF (Click browse and select the same JSF library as before.)
      • URI:
      • Prefix: h
    • Leave the "Execute Tags in JSP Visual Editor" checkbox unchecked and click "OK".
    • Answer "Yes" to the dialog asking to add the tag library to the Component Palette, and this time specify the Palette Page name as: " JSF HTML".

      Note: By leaving the "Execute Tags..." checkbox unchecked, you are turning off the JSF UI Component visualization for now. This means that the JSF UI Components will just render as icons in the JSP Visual Editor. It is usually easier to start working with JSF UI Components in their non-rendered (iconic) state and then later turn on the visualization for both JSF tag libraries to get a better view of the application.
  5. That's it, you're done! You've just configured JDeveloper 10g to work with JSF. The next step is to configure a project to use JSF.


How to configure a project to use JSF

To start building a JSF application, you will need to configure a project's web.xml and include a starter faces-config.xml file.

  1. To get started you'll need an Application Workspace containing an empty project:
    • Select File->New...->General->Application Workspace.
    • Name the workspace "jsf_app" and accept the defaults for Directory Name: and Application Package Prefix:.
    • For Application Template:, choose "No Template [All Technologies]".
    • Click OK to proceed.
    • A new Application Workspace along with an empty Project (named "Project") will be generated. You can use it for your JSF application. (You may rename it to "jsftest" using File->Rename...)
  2. In the project, create a new JSP.
    • File->New...->Web-Tier->JavaServer Pages->JSP Page.
    • Name it "hellojsf.jsp". This will also generate a web.xml file in project's WEB-INF/ directory.
  3. In the Application Navigator, locate the web.xml file and double-click to edit it.
  4. Add the following after the <description>..</description> tags in your web.xml:

    <!-- Faces Servlet -->
    <servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup> 1 </load-on-startup>
    </servlet>

    <!-- Faces Servlet Mapping -->
    <servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>/faces/*</url-pattern>
    </servlet-mapping>

    Note: You can actually use any Faces servlet mapping. For example: <url-pattern>*.faces</url-pattern>.
  5. Now create a faces-config.xml file in the same location as your web.xml.
  6. Create a new simple file:
    • File->New->General->Simple File...
  7. Name the file faces-config.xml and use the Browse... button to specify it's location in your project's WEB-INF subdirectory.
  8. Copy and paste the content below into your new faces-config.xml file:

    <?xml version="1.0"?>

    <!DOCTYPE faces-config PUBLIC
    "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
    "http://bit.ly/199R3Wz">

    <faces-config>

    </faces-config>
  9. That's it! Your project is configured to work with JSF. You may want to save a copy of this project in the file system so you can use this in the future.

Creating a simple JSF application from scratch

Now that you've configured project for JSF, you can test your configuration by creating a simple test JSF application.

  1. If not already open, open the new JSP "hellojsf.jsp" in the JSP Visual Editor.
  2. Switch the Component Palette to the "JSF Core" page.
  3. Drag and drop the "view" tag onto the page. The "view" tag is required for all JSF pages.
  4. Now switch the Component Palette to "JSF HTML".
  5. Drag and drop an "outputText" tag inside of existing "view" tag. The black border denotes containership.
  6. In the Property Inspector, set the value attribute of the outputText tag to "hello JSF!".
  7. Save all your work by clicking on the "Save All" icon  on the main menu.
  8. Start the embedded OC4J, by running the page.
  9. Important: This will NOT work immediately as you will have to insert the "/faces" servlet mapping into the url of your browser in order to make a request using the Faces servlet.
    Insert as follows: http:// yourhost:8988/ YourJ2EEContextRoot/ faces/hellojsf.jsp into your browser's url window.
  10. As you access the page with the proper url, you should see your page with a "hello JSF!" message..
  11. Congratulations! You just built your first JSF application in JDeveloper 10g!

Importing an existing JSF application from a WAR file

Another helpful exercise in getting started with JSF development in JDeveloper is to open any of the JSF Sample Applications in JDeveloper 10g. This can easily be done by using the (Create) Project from War File feature in JDeveloper.

Let's open the JSF Car Demo application in JDeveloper 10g, observe how to edit it visually, and then run it from JDeveloper.

  1. Invoke the "Create a new project from War file" wizard.
    • File->New->Project->Create Project from War File.
  2. In step 1 of the wizard, name the project "mycardemo" and accept the default directory location.
  3. In step 2, locate the War file containing the CarDemo sample (jsf-cardemo.war). The JSF sample applications are located in the <jsf_home>/samples subdirectory. Ex:"d:\jsf\samples".
  4. Click Finish. This will expand the War file contents into your new project directory. You should now see your new project in the Application Navigator.
  5. Take a few seconds to familarize yourself with the various files in this application. You'll find the faces-config.xml along with other additional files in the WEB-INF directory.
  6. Open the storeFront.jsp page in the JSP Visual Editor.

    Observe how the JSF tags render in their iconic form in the visual editor.
  7. Now let's turn on the Tag Execution in the Visual Editor to get a more intuitive view of the page.
    • Invoke the Library Manager (Tools->Manage Libraries..->JSP Tag Libraries)
    • Locate the Faces "JSF Core" tag library: " f".
    • Check the "Execute JSP Tags in Visual Editor" checkbox.
    • Before clicking "OK", locate the other JSF tag library, " h", and check the same checkbox:
    • Click "OK" to continue..
  8. To see the "rendered" JSF UI Components in the Visual Editor, click on the refresh  button.
  9. Your page should now appear as:
Running the JSF Car Demo in JDeveloper
  1. To run the JSF Car Demo in JDeveloper 10g, we'll first have to address two issues:
    • This sample has an extra security constraint in the web.xml which makes running it a little difficult so we'll just remove it.
    • This sample comes with J2EE 1.4 version jstl.jar and standard.jar files and will cause compilation problems for JDeveloper's embedded OC4J which is for J2EE 1.3. We'll simply remove the included jar files and use JDeveloper's built in jstl and standard jar files.
  2. To remove the security constraint, edit the WEB-INF/web.xml and remove the entire <security-constraint> tag and it's content's:.
    <security-constraint>...</security-constraint>
  3. To remove the unneeded 1.4 version jstl and standard files, simply open a file browser (Explorer in Windows) and delete them manually from the application's WEB-INF/lib directory.
  4. (Optional) Save all  and make your project  . The project will compile now because JDev uses it's own jstl and standard classes.
  5. You can now run the application from JDeveloper by running index.jsp page.
    (The index.jsp forwards to the Faces mapped "url: chooseLocale .faces")

Summary

As you can see, even though post 10g releases will offer JDeveloper's full and comprehensive JSF support which includes numerous visual and productive JSF development features, it is possible to be very productive with JSF in the current JDeveloper 10g. Stay tuned for more helpful tips and tricks on using JSF with JDeveloper 10g!