|
Oracle® Application Development Framework Developer's Guide
10g Release 3 (10.1.3) B25386-01 |
|
 Previous |
 Next |
|
Oracle® Application Development Framework Developer's Guide
10g Release 3 (10.1.3) B25386-01 |
|
|
Previous |
Next |
You register a JSF application's resources—such as validators, converters, managed beans, and the application navigation rules—in the application's configuration file. Typically you have one configuration file named faces-config.xml.
|
Note: 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. For details see, Section 4.2.3, "What You May Need to Know About Multiple JSF Configuration Files". |
In JDeveloper, when you create a project that uses JSF technology, an empty faces-config.xml file is created for you in /WEB-INF.
Typically you would want to configure the following in faces-config.xml:
Application resources such as default render kit, message bundles, and supported locales. Refer to Section A.10.1.1, Section A.10.1.3. and Section A.10.1.4.
Page-to-page navigation rules. See Section A.10.1.5.
Custom validators and converters. See Section A.10.1.6.
Managed beans for holding and processing data, handling UI events, and performing business logic.
If you use ADF data controls to build databound web pages, you also need to register the ADF phase listener in faces-config.xml. Refer to Section A.10.1.2.
The following JSF tasks are supported by the faces-config.xml file.
When you use ADF Faces components in your application, you must add the ADF default render kit in the <application> element of faces-config.xml. As mentioned earlier, JDeveloper creates one empty faces-config.xml file for you when you create a new project that uses JSF technology. When you insert an ADF Faces component into a JSF page for the first time, JDeveloper automatically inserts the default render kit for ADF components into faces-config.xml (see Example A-20).
Example A-20 Configuring faces-config.xml for ADF Faces Components
<?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">
...
<!-- Default render kit for ADF components -->
<application>
<default-render-kit-id>oracle.adf.core</default-render-kit-id>
</application>
...
</faces-config>
The ADF phase listener is used to execute the ADF page lifecycle. When you use ADF data binding, you need to specify a phase listener for ADF lifecycle phases. In JDeveloper when an ADF data control is inserted into a JSF page for the first time, a standard ADF phase listener is added to faces-config.xml in the <lifecycle> element.
The ADF phase listener listens for all the JSF phases before which and after which it needs to execute its own phases concerned with preparing the model, validating model updates, and preparing pages to be rendered. See Section 6.2.2.4, "The JSF and ADF Lifecycles", for more information about how the ADF lifecycle phases integrate with the JSF lifecycle phases. Example A-21 shows part of a faces-config.xml that contains the ADF phase listener.
You may want to subclass the standard ADF phase listener when custom behavior, such as error handling, is desired. See Section 12.8, "Handling and Displaying Exceptions in an ADF Application" for details about subclassing the ADF phase listener. JDeveloper will not readd the standard phase listener to faces-config.xml if it detects a subclass.
When you use a resource bundle for localized labels and messages, add the resource as a <message-bundle> in the <application> element of faces-config.xml (see Example A-22). The SRDemo sample uses a resource properties file to hold the strings for the UI.
Example A-22 Registering a Message Bundle in faces-config.xml
<faces-config xmlns="http://java.sun.com/JSF/Configuration">
...
<application>
...
<message-bundle>oracle.srdemo.view.resources.UIResources</message-bundle>
...
</application>
...
</faces-config>
To reference a message bundle in a page, see Section 14.4, "Internationalizing Your Application".
Register the default and all supported locales for your application in the <application> element of faces-config.xml (see Example A-23).
Example A-23 Registering Default and Supported Locales in faces-config.xml
<faces-config xmlns="http://java.sun.com/JSF/Configuration">
...
<application>
...
<locale-config>
<default-locale>en</default-locale>
<supported-locale>en-US</supported-locale>
<supported-locale>es</supported-locale>
<supported-locale>fr</supported-locale>
</locale-config>
</application>
...
</faces-config>
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 instance in the file. You'll need to edit the file directly using the XML editor for any other <application> elements.
While you can enter navigation rules and cases directly in the faces-config.xml file, Oracle recommends you use the JSF Navigation Modeler. The Navigation Modeler enables you to lay out the pages in your JSF application and add navigation between the pages in the form of a diagram. To open the Navigation Modeler, double-click the faces-config.xml file in the Application Navigator. In the visual editor, activate the Diagram tab to display the Navigation Modeler.
When JDeveloper first creates an empty faces-config.xml, it also creates a diagram file to hold diagram details such as layout and annotations. JDeveloper always maintains this diagram file alongside the faces-config.xml file, which holds all the settings needed by your application. This means that if you are using versioning or source control, the diagram file is included along with the faces-config.xml file it represents.
The navigation cases you add to the diagram are reflected in faces-config.xml, without your needing to edit the file directly.
A navigation rule defines one or more cases that specify an outcome value. A navigation component in a web page specifies an outcome value in its action attribute, which triggers a specific navigation case when a user clicks that component. For example, in the SRList page of the sample application, when the user clicks the View button, the application displays the SRMain page. The action attribute on the View button has the string value View (see Example A-24). The corresponding code for the navigation case within the navigation rule for the SRList page is shown in Example A-25.
Example A-24 Action Outcome String Defined on View Button
<af:commandButton text="#{res['srlist.buttonbar.view']}"
action="View"/>
Example A-25 Creating Static Navigation Cases in faces-config.xml
<faces-config xmlns="http://java.sun.com/JSF/Configuration">
...
<navigation-rule>
<from-view-id>/SRList.jspx</from-view-id>
<navigation-case>
<from-outcome>Edit</from-outcome>
<to-view-id>/SREdit.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>View</from-outcome>
<to-view-id>/SRMain.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>Search</from-outcome>
<to-view-id>/SRSearch.jspx</to-view-id>
</navigation-case>
<navigation-case>
<from-outcome>Create</from-outcome>
<to-view-id>/SRCreate.jspx</to-view-id>
</navigation-case>
</navigation-rule>
...
</faces-config>
For information about creating JSF navigation rules and cases, as well as creating navigation components, see Chapter 9, "Adding Page Navigation Using Outcomes".
JSF and ADF Faces standard validators and converters provide common validation checks for numeric ranges and string lengths, and the most common datatype conversions. If you need more complex validation rules and checks, or if you need to convert a component's data to a type other than a standard type, you can create your own custom validator or converter.
The custom validator or converter must implement the javax.faces.validator.Validator or javax.faces.convert.Converter interface, respectively. To make use of your custom validator or converter in an application, you have to register it in faces-config.xml using the <validator> or <converter> element (see Example A-26). For a custom validator, you can register it under an identifier (ID); for a custom converter you can register it under an ID or a fully qualified class name for a specific datatype.
Example A-26 Registering Custom Validators and Converters in faces-config.xml
<faces-config xmlns="http://java.sun.com/JSF/Configuration">
...
<validator>
<validator-id>oracle.srdemo.core.CreditCard</validator-id>
<validator-class>oracle.srdemo.core.CreditCardValidator</validator-class>
</validator>
<converter>
<converter-id>oracle.srdemo.core.CreditCard</validator-id>
<converter-class>oracle.srdemo.core.CreditCardConverter</converter-class>
</converter>
...
</faces-config>
In JSF, managed beans are the JavaBeans used to manage data between the web tier and the business tier of the application (similar to a data transfer object). At runtime, whenever the bean is referenced in a page through a value or method binding expression, the JSF implementation instantiates a bean, populates it with any declared, default values, and places it in the managed bean scope as defined in the faces-config.xml.
To register a managed bean in faces-config.xml, use the <managed-bean> element (see Example A-27). You have to specify the following for a managed bean:
Name—Determines how the bean will be referred to within the application using EL expressions, instead of using the bean's fully qualified class name.
Class—This is the JavaBean that contains the properties that hold the data, along with the corresponding accessor methods and/or any other methods (such as navigation or validation) used by the bean. This can be an existing class (such as a data transfer class), or it can be a class specific to the page (such as a backing bean).
Scope—This determines the scope within which the bean is stored. The valid scopes are:
application—The bean is available for the duration of the web application. This is helpful for global beans such as LDAP directories.
request—The bean is available from the time it is instantiated until a response is sent back to the client. This is usually the life of the current page.
session—The bean is available to the client throughout the client's session.
none—The bean is instantiated each time it is referenced.
Managed properties are any properties of the bean that you would like populated with a value when the bean is instantiated. The set method for each declared property is run once the bean is constructed. To initialize a managed bean's properties with set values, including those for a bean's map or list property, use the <managed-property> element. When you configure a managed property for a managed bean, you declare the property name, its class type, and its default value.
Managed beans and managed bean properties can be be initialized as lists or maps, provided that the bean or property type is a List or Map, or implements java.util.Map or java.util.List. The default for the values within a list or map is java.lang.String.
Example A-27 Registering Managed Beans in faces-config.xml
<faces-config xmlns="http://java.sun.com/JSF/Configuration">
...
<!-- This managed bean uses application scope -->
<managed-bean>
<managed-bean-name>resources</managed-bean-name>
<managed-bean-class>
oracle.srdemo.view.resources.ResourceAdapter
</managed-bean-class>
<managed-bean-scope>application</managed-bean-scope>
</managed-bean>
<!-- Page backing beans typically use request scope-->
<managed-bean>
<managed-bean-name>backing_SRCreate</managed-bean-name>
<managed-bean-class>oracle.srdemo.view.backing.SRCreate</managed-bean-class>
<managed-bean-scope>request</managed-bean-scope>
<!--oracle-jdev-comment:managed-bean-jsp-link:1app/SRCreate.jspx-->
<managed-property>
<property-name>bindings</property-name>
<value>#{bindings}</value>
</managed-property>
</managed-bean>
<managed-bean>
<managed-bean-name>backing_SRManage</managed-bean-name>
<managed-bean-class>
oracle.srdemo.view.backing.management.SRManage
</managed-bean-class>
<managed-bean-scope>request</managed-bean-scope>
<!--oracle-jdev-comment:managed-bean-jsp-link:1app/management/SRManage.jspx-->
<managed-property>
<property-name>bindings</property-name>
<value>#{bindings}</value>
</managed-property>
</managed-bean>
<!-- This managed bean uses session scope -->
<managed-bean>
<managed-bean-name>userState</managed-bean-name>
<managed-bean-class>oracle.srdemo.view.UserSystemState</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
</managed-bean>
...
</faces-config>
