4.2 Setting Up a Workspace and Project

JDeveloper provides application templates that enable you to quickly create the workspace and project structure with the appropriate combination of technologies already specified. The SRDemo application uses the Web Application [JSF, EJB, TopLink] application template, which creates one project for the data model, and one project for the controller and view (user interface) components in a workspace.

To create a new application workspace in JDeveloper and choose an application template:

1. Right-click the Applications node in the Application Navigator and choose New Application.

2. In the Create Application dialog, select the Web Application [JSF, EJB, TopLink] application template from the list.

You don't have to use JDeveloper application templates to create an application workspace—they are provided merely for your convenience.

At times you might already have an existing WAR file and you want to import it into JDeveloper.

To import a WAR file into a new project in JDeveloper:

1. Right-click your application workspace in the Application Navigator and choose New Project.

2. In the New Gallery, expand General in the Categories tree, and select Projects.

3. In the Items list, double-click Project from WAR File.

4. Follow the wizard instructions to complete creating the project.

4.2.1 What Happens When You Use an Application Template to Create a Workspace

By default, JDeveloper names the project for the data model Model, and the project for the user interface and controller ViewController. You can rename the projects using File > Rename after you've created them, or you can use Tools > Manage Templates to change the default names that JDeveloper uses.

Note: The illustrations and project names used in this chapter are the JDeveloper default names. The SRDemo application, however, uses the project name UserInterface for the JSF view and controller components, and DataModel for the project that contains the EJB session beans and TopLink using plain old Java objects.

Figure 4-1 shows the Application Navigator view of the ViewController project after you create the workspace. Figure 4-2 shows the actual folders JDeveloper creates in the <JDEV_HOME>/jdev/mywork folder in the file system.

Figure 4-1 ViewController Project in the Navigator After You Create a Workspace

Figure 4-2 ViewController Folders in the File System After You Create a Workspace

When you use the Web Application [JSF, EJB, TopLink] template to create a workspace, JDeveloper does the following for you:

• Creates a ViewController project that uses JSF technology. The project properties include:

  • JSP Tag Libraries: JSF Core, JSF HTML. See Table 4-2.

  • Libraries: JSF, Commons Beanutils, Commons Digester, Commons Logging, Commons Collections, JSTL.

  • Technology Scope: JSF, JSP and Servlets, Java, HTML.

  When you work in the ViewController project, the New Gallery will be filtered to show standard web technologies (including JSF) in the Web Tier category.

  By default, JDeveloper uses JSTL 1.1 and a J2EE 1.4 web container that supports Servlet 2.4 and JSP 2.0.

• Creates a starter web.xml file with default settings in /WEB-INF of the ViewController project. See Section 4.2.1.1, "Starter web.xml File" if you want to know what JDeveloper adds to web.xml.

• Creates an empty faces-config.xml file in /WEB-INF of the ViewController project. See Section 4.2.1.2, "Starter faces-config.xml File" if you want to learn more about faces-config.xml.

• Adds jsf-impl.jar in /WEB-INF/lib of the ViewController project.

• Creates the faces-config.oxd_faces file in /ViewController/model/public_html/WEB-INF in the file system. When you plan out and build your page flow in the JSF navigation diagram, this is the diagram file that holds all the diagram details such as layout and annotations. JDeveloper always maintains this file alongside its associated XML file, faces-config.xml. For information about using the JSF navigation diagram, see Section 4.3.1, "How to Add a JSF Page".

• Creates a Model project that uses TopLink and EJB technology. For more information about the Model project, see Section 1.2.1.2, "Building the Business Service in the Model Project".

4.2.1.1 Starter web.xml File

Part of a JSF application's configuration is also determined by the contents of its J2EE application deployment descriptor, web.xml. The web.xml file defines everything about your application that a server needs to know (except the root context path, which is assigned by JDeveloper or the system administrator when the application is deployed). Typical runtime settings include initialization parameters, custom tag library location, and security settings.

Example 4-1 shows the starter web.xml file JDeveloper first creates for you.

Example 4-1 Starter web.xml File Created by JDeveloper

<?xml version = '1.0' encoding = 'windows-1252'?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
          http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
         version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee">
  <description>Empty web.xml file for Web Application</description>

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

The JSF servlet and servlet mapping configuration settings are automatically added to the starter web.xml file when you first create a JSF project.

• JSF servlet: The JSF servlet is javax.faces.webapp.FacesServlet, which manages the request processing lifecycle for web applications utilizing JSF to construct the user interface. The configuration setting maps the JSF servlet to a symbolic name.

• JSF servlet mapping: The servlet mapping maps the URL pattern to the JSF servlet's symbolic name. You can use either a path prefix or an extension suffix pattern.

  By default, JDeveloper uses the path prefix /faces/*. This means that when the URL http://localhost:8080/SRDemo/faces/index.jsp is issued, the URL activates the JSF servlet, which strips off the faces prefix and loads the file /SRDemo/index.jsp.

Tip: If you want to use the extension .jsf for your web pages instead of .jsp or .jspx, you need to add a servlet mapping in web.xml that will invoke the JSP servlet for files with the extension .jsf, and then set the javax.faces.DEFAULT_SUFFIX context parameter to .jsf, as shown in this code snippet: <context-param> <param-name>javax.faces.DEFAULT_SUFFIX</param-name> <param-value>.jsf</param-value> </context-param>

To edit web.xml in JDeveloper, right-click web.xml in the Application Navigator and choose Properties from the context menu to open the Web Application Deployment Descriptor editor. If you're familiar with the configuration element names, you can also use the XML editor to modify web.xml.

For reference information about the configuration elements you can use in web.xml when you work with JSF, see Section A.8, "web.xml".

Note: If you use ADF data controls to build databound web pages, JDeveloper adds the ADF binding filter and a servlet context parameter for the application binding container in web.xml. For more information, see Section 5.4, "Configuring the ADF Binding Filter".

4.2.1.2 Starter faces-config.xml File

The JSF configuration file is where you register a JSF application's resources such as custom validators and managed beans, and define all the page-to-page navigation rules. While an application can have any JSF configuration filename, typically the filename is faces-config.xml. Example 4-2 shows the starter faces-config.xml file JDeveloper first creates for you when you create a project that uses JSF technology.

Small applications usually have one faces-config.xml file. For information about using multiple configuration files, see Section 4.2.3, "What You May Need to Know About Multiple JSF Configuration Files".

Example 4-2 Starter faces-config.xml File Created by JDeveloper

<?xml version="1.0" encoding="windows-1252"?>
<!DOCTYPE faces-config PUBLIC
  "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.1//EN"
  "http://java.sun.com/dtd/web-facesconfig_1_1.dtd">
<faces-config xmlns="http://java.sun.com/JSF/Configuration">

</faces-config>

In JDeveloper you can use either editor to edit faces-config.xml:

• XML Source Editor

• JSF Configuration Editor

Oracle recommends you use the JSF Configuration Editor.

To launch the JSF Configuration Editor:

1. In the Application Navigator, double-click faces-config.xml to open the file.

   By default JDeveloper opens faces-config.xml in Diagram mode, as indicated by the active tab Diagram at the bottom of the editor window. When creating or modifying JSF navigation rules, Oracle suggests you use the Diagram mode of the JSF Configuration Editor.

   In JDeveloper a diagram file, which lets you create and manage page flows visually, is associated with faces-config.xml. For information about creating JSF navigation rules, see Chapter 9, "Adding Page Navigation Using Outcomes".

2. To create or modify configuration elements other than navigation rules, use the Overview mode of the JSF Configuration Editor. At the bottom of the editor window, select Overview.

Both editor modes, Overview and Diagram, update the faces-config.xml file.

Tip: JSF allows more than one <application> element in a single faces-config.xml file. The JSF Configuration Editor only allows you to edit the first <application> instance in the file. For any other <application> elements, you'll need to edit the file directly using the XML editor.

For reference information about the configuration elements you can use in faces-config.xml, see Section A.10, "faces-config.xml".

Note: If you use ADF data controls to build databound web pages, JDeveloper adds the ADF phase listener in faces-config.xml, as described in Section 5.2.3, "What Happens When You Create a Component From the Data Control Palette".

4.2.2 What You May Need to Know About the ViewController Project

The ViewController project contains the web content that includes the web pages and other resources of the web application. By default, the JDeveloper web application template you select adds the word "controller" to the project name to indicate that the web application will include certain files that define the application's flow or page navigation (controller), in addition to the web pages themselves (view).

Note: The concept of separating page navigation from page display is often referred to as Model 2 to distinguish from earlier style (Model 1) applications that managed page navigation entirely within the pages themselves. In a Model 2 style application, the technology introduces a specialized servlet known as a page controller to handle page navigation events at runtime.

The technology that you use to create web pages in JDeveloper will determine the components of the ViewController project and the type of page controller your application will use. The SRDemo application uses JSF combined with JSP to build the web pages:

• JSF provides a component-based framework for displaying dynamic web content. It also provides its own page controller to manage the page navigation.

• JSP provides the presentation layer technology for JSF user interfaces. The JSF components are represented by special JSP custom tags in the JSP pages.

JDeveloper tools will help you to easily bind the JSF components with the Java objects of the Model project, thus creating databound UI components. As described earlier, the ViewController project contains the web pages for the user interface. To declaratively bind UI components in web pages to a data model, the ViewController project must be able to access data controls in the Model project. To enable the ViewController project to access the data controls, specify a dependency on the Model project, as shown in the following procedure.

To set dependency on a Model project for a ViewController project in JDeveloper:

1. Double-click ViewController in the Application Navigator to open the Project Properties dialog.

2. Select Dependencies and then select the checkbox next to Model.jpr.

4.2.3 What You May Need to Know About Multiple JSF Configuration Files

A JSF application can have more than one JSF configuration file. For example, if you need individual JSF configuration files for separate areas of your application, or if you choose to package libraries containing custom components or renderers, you can create a separate JSF configuration file for each area or library.

To create another JSF configuration file, simply use a text editor or use the JSF Page Flow & Configuration wizard provided by JDeveloper.

To launch the JSF Page Flow & Configuration wizard:

1. In the Application Navigator, right-click ViewController and choose New.

2. In the New Gallery window, expand Web Tier. Select JSF and then double-click JSF Page Flow & Configuration (faces-config.xml).

When creating a JSF configuration file for custom components or other JSF classes delivered in a library JAR:

• Name the file faces-config.xml if you desire.

• Store the new file in /META-INF.

• Include this file in the JAR that you use to distribute your custom components or classes.

This is helpful for applications that have packaged libraries containing custom components and renderers.

When creating a JSF configuration file for a separate application area:

• Give the file a name other than faces-config.xml.

• Store the file in /WEB-INF.

• For JSF to read the new JSF configuration file as part of the application's configuration, specify the path to the file using the context parameter javax.faces.CONFIG_FILES in web.xml.

  If using the JSF Page Flow & Configuration wizard, select the Add Reference to web.xml checkbox to let JDeveloper register the new JSF configuration file for you in web.xml. Example 4-3 shows how multiple JSF configuration files are set in web.xml by JDeveloper if you select the checkbox.

This is helpful for large-scale applications that require separate configuration files for different areas of the application.

Example 4-3 Configuring for Multiple JSF Configuration Files in the web.xml File

<context-param>
  <param-name>javax.faces.CONFIG_FILES</param-name>
  <param-value>/WEB-INF/faces-config1.xml,/WEB-INF/faces-config2.xml</param-value>
</context-param>

Any JSF configuration file, whether it is named faces-config.xml or not, must conform to Sun's DTD located at http://java.sun.com/dtd/web-facesconfig_1_x.dtd. If you use the wizard to create a JSF configuration file, JDeveloper takes care of this for you.

If an application uses several JSF configuration files, at runtime JSF finds and loads the application's configuration settings in the following order:

1. Searches for files named META-INF/faces-config.xml in any JAR files for the application, and loads each as a configuration resource (in reverse order of the order in which they are found).

2. Searches for the javax.faces.CONFIG_FILES context parameter set in the application's web.xml file. JSF then loads each named file as a configuration resource.

3. Searches for a file named faces-config.xml in the WEB-INF directory and loads it as a configuration resource.

JSF then instantiates an Application class and populates it with the settings found in the various configuration files.