As Published In July/August 2004

Developing Faces
By Chris Schalk

Use Oracle JDeveloper 10g to develop JavaServer Faces applications.

Building enterprise J2EE Web applications has always been a bit of an art. Although J2EE provides more-than-adequate foundational technologies for building scalable enterprise Web applications, it previously lacked a high-level API to glue these technologies together and provide a single, consistent way to build J2EE Web applications. The recent introduction of JavaServer Faces (JSF) 1.0, however, brings standardization and consistency to J2EE Web application development.

Oracle JDeveloper 10g is Oracle's integrated development environment for Java, Web services, XML, PL/SQL, and more. This article describes how to work with JSF in Oracle JDeveloper 10g.

Behind JavaServer Faces

JSF is built on standard J2EE technologies, which include JSP tag libraries, a controller servlet, and other Java classes that make up its UI component library and event-processing model.

A typical JSF application development scenario involves building a user interface, a navigation model, and application classes (managed beans). You specify the navigation model and managed beans in the application's faces-config.xml file. You can build the user interface with JSF UI components in JSPs, using the JSF JSP tag libraries.

Setting Up Oracle JDeveloper 10g to Work with JSF

Although JSF 1.0 is not yet bundled into Oracle JDeveloper 10g, configuring JSF to work with JDeveloper is straightforward. Let's step through how to configure JDeveloper 10g to work with JSF 1.0. The instructions in this section assume that you have Oracle JDeveloper 10g installed and running. Download JSF 1.0 from Sun. Download the JSF 1.0 Reference Implementation from Sun at java.sun.com/j2ee/javaserverfaces/download.html.

Unzip the Reference Implementation package into a local directory such as: D:\jsf. I'll refer to this location later as your <JSF_HOME>. This directory will contain the following subdirectories: docs, javadocs, lib, samples, and tlddocs. The lib directory will contain the required jar files and tag library descriptors (tld) files that enable Oracle JDeveloper 10g to work with JSF.

Create a JSF system library. In Oracle JDeveloper, create a JSF system library, which will contain the location of the JSF jar files.

1. From the Oracle JDeveloper main menu, select Tools->Manage Libraries.
2. Select System Libraries, and click on New.
3. Name the library JSF.
4. In the Class Path, add all of the jar files: jsf-api.jar, jsf-impl.jar, and all the commons*.jar files. These are located in your JSF bundle's lib directory: <JSF_HOME>\lib.

Register the JSF JSP tag libraries. Register the JSF JSP tag libraries with Oracle JDeveloper, so you can use them from the Component Palette.

1. Select Tools->Manage Libraries.
2. Select the JSP Tag Libraries tab, and click on New.
3. Add the JSF Core tag library, by specifying the following:
   TLD File: D:\jsf\lib\jsf_core.tld (Use the Browse button to obtain this value. If you installed JSF 1.0 somewhere other than D:\jsf, specify that location.)
   Libraries: JSF
   URI: http://java.sun.com/jsf/core (This value should be autofilled.)
   Prefix: f
   Execute Tags in JSP Visual Editor checkbox: unchecked (By leaving the "Execute Tags in JSP Visual Editor" checkbox unchecked, you are turning off the tag execution/visualization feature in the JSP visual editor. This feature allows you to see what the tag looks like at runtime, for a more intuitive design experience. In practice, it is best to start out with this turned off, so you can work with tags in their nonruntime rendered state, and later turn on the rendering to get a better view of the application.)
4. Click on OK.
5. Answer Yes to the dialog box that asks whether to add the tag library to the Component Palette.
6. Enter the Palette Page name, JSF Core, and click on OK.

Register the JSF HTML tag library. Repeat the library registration process for the JSF HTML tag library.

1. Select Tools->Manage Libraries.
2. Select the JSP Tag Libraries tab, and click on New.
3. Add the JSF HTML tag library, by specifying the following:
   TLD File: D:\jsf\lib\html_basic.tld
   Libraries: JSF
   URI: http://java.sun.com/jsf/html
   Prefix: h
   Execute Tags in JSP Visual Editor checkbox: unchecked
4. Click on OK.
5. Answer Yes to the dialog box that asks to add the tag library to the Component Palette.
6. Enter the Palette Page name, JSF HTML, and click on OK.

That's it. Oracle JDeveloper now has the JSF UI components on the Component Palette. Your next step is to configure an empty project to work with Oracle JDeveloper.

Basic JSF Development

Start developing JSF applications in Oracle JDeveloper 10g by configuring a JDeveloper project to work with JSF, and then build your JSF application.

Configuring a project to work with JSF. To build a JSF application in Oracle JDeveloper, first configure an empty J2EE project to work with JSF. This involves editing the web.xml file to include an entry for the Faces Servlet as well as adding an empty faces-config.xml file to your project. The following steps detail how to configure a project for JSF:

1. Create an application workspace that will contain your projects: Choose File->New...->General->Workspaces ->Application Workspace. This gives you a new workspace with an initial project you'll configure to work with JSF.
2. In the Application Workspace wizard, enter the name of the application, ADF_JSF_App; leave the application package prefix empty; and choose the application template No Template [All Technologies].
3. Click on OK to generate your workspace and a default starter project.
4. Create a new JSP named FacesHello.jsp in the new project: Choose File->New...->Web-Tier-> JSP Page. This also generates a new web.xml file in the /WEB-INF subdirectory. Edit the web.xml file to add the Faces Servlet mapping, by inserting the following code after the <description> tag:

   <!-- 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>
   

5. Create a faces-config.xml file in the same location as your web.xml file. Create a new simple file—choose File ->New->General->Simple File—and name it faces-config.xml.

   Copy and paste the following content into this file:

   <?xml version="1.0"?>
   <!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc. //DTD JavaServer Faces Config 1.0 //EN" "http://java.sun.com/dtd/web-facesconfig_1_0.dtd">
   <faces-config>
   </faces-config>
   

   Your Oracle JDeveloper project is now configured for JSF applications.

Building a simple JSF application from scratch. To test your project's JSF configuration, create a small test JSF application:

Next Steps READ more about JSF java.sun.com/j2ee/javaserverfaces www.jsfcentral.com Oracle JDeveloper and JSF DOWNLOAD JSF 1.0 Oracle JDeveloper 10g

1. While editing FacesHello.jsp in the visual editor, switch the Component Palette to the JSF Core page and then drag and drop the view tag onto the page.
2. Switch the Component Palette to JSF HTML, and drag and drop an outputText tag inside the existing view tag.

   (Note: All JSF UI components must reside in the JSF view tag.)

3. Using the Property Inspector, set the value attribute of the outputText tag to "Hello!".

   Your source code will look like this:

   <f:view>
     <h:outputText value="Hello!"/>
   </f:view>
   

4. Save your project.
5. Before you run your application, build a simple starter page that automatically forwards to the correct URL with the Faces Servlet mapping included. Create a new JSP: index.jsp.
6. While editing index.jsp, switch the Component Palette to JSP, drag and drop a jsp:forward tag, and set the page attribute to /faces/FacesHello.jsp. You will use this page to start your JSF application.
7. To run index.jsp, select it, then right-click, and choose Run.
8. The index.jsp page should forward to your Faces page with the correct URL. You should see a "Hello!" message from the JSF UI component outputText tag in your browser.

Now that you've configured Oracle JDeveloper for JSF and built a simple test application, let's switch gears a bit and observe some prebuilt JSF sample applications in Oracle JDeveloper to see how easy it is to work with them.

Importing JSF Sample Applications

Oracle ADF: The Future of JSF and JDeveloper Oracle JDeveloper 10g allows developers to productively build J2EE applications and Web services using the Oracle Application Development Framework (Oracle ADF). Based on the Model-View-Controller (MVC) architecture, Oracle ADF lets application developers focus on the business domain rather than on the underlying technologies. A future release of Oracle JDeveloper will contain Oracle's full JSF development support, which includes complete integration with Oracle ADF. This support will include ADF databinding for JSF and visual page flow design, as well as a whole new set of JSF UI components based on Oracle's UIX technology. The following links provide information on Oracle JDeveloper's support of JSF and Oracle ADF: otn.oracle.com/products/jdev/jsf.html otn.oracle.com/products/jdev/collateral/sod_10g.html otn.oracle.com/oramag/oracle/04-jul/jsf.html

One way to familiarize yourself with JSF development in Oracle JDeveloper 10g is to import any of the JSF sample applications provided in the JSF 1.0 Reference Implementation bundle. To import JSF sample applications into Oracle JDeveloper 10g, use the "Project from War File" wizard. Here's how to import the JSF Car Demo application into Oracle JDeveloper 10g:

1. In your existing workspace, invoke the "Project from War File" wizard: Choose File->New..->Projects->Project from War File.
2. In step 1 of the wizard, name the JDeveloper project "mycardemo" and accept the default directory location.
3. In step 2 of the wizard, locate the JSF car demo War file. You can find it at <JSF_HOME>\samples\jsf-cardemo.war.

Click on Finish to generate your new project based on the JSF War file.

Now locate and open the JSP page chooseLocale.jsp. The page looks like the screen in Figure 1. Observe how it renders in the JSP visual editor. Note how all of the JSF tags are rendered as icons. This is because you specifically chose not to execute the tags in the visual editor when you first added the tag libraries. Sometimes it is easier to work with the tags in their nonrendered state.

Now let's have a look at the same page with the tag execution turned on. To turn on tag execution, do the following:

1. Invoke the library manager from the Tools menu: Choose Tools-> Manage Libraries.
2. Click on the JSP Tag Libraries tab.
3. Locate the tag libraries you configured earlier, f and h.
4. For both JSF tag libraries, check the "Execute Tags in JSP Visual Editor" check box and then click on OK.
5. Back in the JSP visual editor, click on the refresh button in the upper left corner to see the change.
6. The JSP visual editor now renders the JSF components in their runtime state. Figure 2 shows the same chooseLocale.jsp page in its rendered state.

Figure 1: chooseLocale.jsp with JSP tags not rendered

Figure 2: chooseLocale.jsp with JSP tags rendered

Note that it is still possible to work with the tags in the visual editor, even in their rendered state. For example, I can select any of the rendered tags and then modify its properties in the Property Inspector. I can also do any other operation I would normally do in the visual editor, such as moving, cutting, copying, and pasting. Figure 3 shows the optionsPanel.jsp, whose attributes can be modified via the Property Inspector.

Running the Car Demo. To run the Car Demo in the Oracle JDeveloper 10g embedded Oracle Application Server Containers for J2EE (OC4J) environment, you'll have to make two minor modifications to the application. First remove the jstl.jar and standard.jar files from the /WEB-INF/lib directory of the application, to compile the application in Oracle JDeveloper 10g. (This is because the jstl.jar and standard.jar provided in the War file are compatible with a J2EE 1.4 environment, not with the J2EE 1.3 environment of Oracle JDeveloper 10g.) The second modification is to remove the application's security restrictions to make it easier to run. In the WEB-INF/web.xml file, remove the entire <security-constraint> tag and its contents: <security-constraint> ...</security-constraint>. (This constraint blocks access to the index.jsp starter page.)

Once you've modified your Car Demo application, run index.jsp by right-clicking on index.jsp and choosing Run. Once the embedded OC4J server starts, you will be able to choose the locale in the first page of the Car Demo application, as shown in Figure 4.

Figure 3: optionsPanel.jsp with configurable attributes

Figure 4: Running Car Demo (index.jsp running in OC4J)

JavaServer Faces provides a standard and flexible development architecture for thin-client, HTML-based Web application development in Java. The challenge now is for development tool vendors to provide an intuitive, productive, and powerful yet easy-to-use development environment for JSF. And this is a challenge Oracle will address in a future release of Oracle JDeveloper (see the sidebar "Oracle ADF: The Future of JSF and JDeveloper").