Skip Headers
Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1)

Part Number B31973-03
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

1 Introduction to ADF Faces Rich Client

This chapter introduces ADF Faces rich client, providing a history, an overview of the framework functionality, and an overview of each of the different component types found in the library. It also introduces the ADF Faces Demonstration application that can be used in conjunction with this guide.

This chapter includes the following sections:

1.1 Introduction to Oracle ADF Faces Rich Client

Oracle ADF Faces rich client (known also as ADF Faces) is a set of JavaServer Faces (JSF) components that include built-in Asynchronous JavaScript and XML (AJAX) functionality. While AJAX brings rich client-like functionality to browser-based applications, using JSF provides server-side control, which reduces the dependency on an abundance of JavaScript often found in typical AJAX applications.

In addition to providing the JSP tags and UIComponent instances that would be expected of any JSF component set, the ADF Faces rich client framework (RCF) provides a client-side programming model familiar to developers accustomed to the JSF development model. However, the RCF is specifically different where necessary to deal with practical realities of JavaScript development required in standard AJAX development practices. Most of the RCF differs little from any standard JSF application; the server programming model is still JavaServer Faces, and the framework still uses the JavaServer Faces lifecycle, server-side component tree, and the expression language (EL). However, the RCF also provides a client-side programming model and lifecycle that execute independently of the server. Developers can find and manipulate components from JavaScript, for example use get and set properties, receive and queue events, and so forth, entirely from JavaScript. The RCF makes sure changes to component state are automatically synchronized back to the server to ensure consistency of state, and events are delivered, when necessary, to the server for further processing.

Before providing more detailed information regarding ADF Faces, it may help to have a brief history of the ADF Faces library and Rich Internet Applications (RIAs) and AJAX in general.

1.1.1 History of ADF Faces

As the development community at large started to recognize the need for a standard view-layer framework, the Java Community Process (JCP) developed JSF as a user interface standard for Java web applications. From the formative years of JSR-127 in 2001, through the first release in 2004, up to the current release (JSR-252) in 2006, the JCP has brought together resources from the community, including Oracle, to define the JSF specification and produce a reference implementation of the specification. JSF is now part of the Java EE standard.

With JSF being a standard for building enterprise Java view components, any vendor can develop its own components that can run on any compliant application server. Oracle developed a set of components called ADF Faces that could be used on any runtime implementation of JSF. Oracle ADF Faces provided a set of over 100 components with built-in functionality, such as data tables, hierarchical tables, and color and date pickers, that exceeded the functionality of the standard JSF components. To underline its commitment to the technology and the open source community, Oracle has since donated that version of the ADF Faces component library to the Apache Software Foundation, and it is now known as Apache MyFaces Trinidad. This component library is currently available through the Apache Software Foundation.

Now with the advent of RIA, web applications that come close to emulating desktop applications are becoming a possibility. AJAX has been a big part of this. AJAX is a combination of asynchronous JavaScript, dynamic HTML (DHTML), XML, and the XmlHttpRequest communication channel, which allows requests to be made to the server without fully rerendering the page.

Using ADF Faces, for example, you could build a stock trader's dashboard application that allows a stock analyst to use drag and drop to add new stock symbols to a table view, which then gets updated by the server model using an advanced push technology. To close new deals, the stock trader could navigate through the process of purchasing new stocks for a client, without having to leave the actual page.

While it is possible to write Rich Internet Applications by hand using AJAX techniques, using an RIA framework like ADF Faces insulates the developer from the need to deal with the intricacies of JavaScript and the DHTML differences across browsers.

1.1.2 ADF Faces as Rich Client Components

The latest version of Oracle ADF Faces pairs the AJAX development techniques with JSF technology. Using Apache MyFaces Trinidad as the foundation, ADF Faces adds AJAX functionality, bringing RIA capabilities to a JSF application. By utilizing the component-based JSF framework, the complexities of AJAX are encapsulated in reusable and easy-to-use components. You can develop full RIAs while application logic can continue to live on the server, eliminating the need to employ JavaScript and DHTML experts to write your application.

Unlike other JavaSever Faces libraries that are AJAX enabled, ADF Faces is specifically made for AJAX and provides native AJAX platform features, including drag-and-drop, lightweight dialogs, a navigation and menu framework, and a complete JavaScript API.

ADF Faces provides over 100 RIA components, including hierarchical data tables, tree menus, in-page dialogs, accordion panels, dividers, and sortable tables. ADF Faces also includes data visualization components, which are Flash- and SVG-enabled components capable of rendering dynamic charts, graphs, gauges, and other graphics that provide a real-time view of underlying data. Each component also offers customizing and skinning, along with support for internationalization and accessibility.

To achieve these capabilities, ADF Faces components use a rich JSF render kit. This kit renders the components' content and also provides any JavaScript objects that initiate XMLHttpRequest calls and handle callbacks. This built-in support enables you to build RIAs without needing extensive knowledge of the individual technologies. For more details about the architecture of ADF Faces, see Section 1.2, "Architecture of ADF Faces Components"


You can use ADF Faces in conjunction with Oracle ADF Model data binding, allowing you to declaratively bind ADF Faces components to the business layer. Using ADF Model data binding, most developer tasks that would otherwise require writing code are declarative. However, this guide covers only using ADF Faces components in a standard JSF application. For more information about using ADF Faces with the ADF Model, see the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

In addition to an extensive library of RIA components, Oracle also offers Oracle JDeveloper, a full-featured development environment with built-in declarative support for ADF Faces components, allowing you to quickly and easily build the view layer of your web application. JDeveloper contains a visual layout editor that displays JSF pages in a WYSIWYG environment. The Component Palette in JDeveloper holds visual representations of each of the ADF Faces components, which allows you to drag and drop a component onto a page in the visual editor, instead of having to manually add tag syntax to a page. You can use JDeveloper throughout the complete development lifecycle, as it has integrated features for modeling, coding, debugging, testing, tuning, and deploying. For more information about using JDeveloper, see Chapter 2, "Getting Started with ADF Faces".

1.2 Architecture of ADF Faces Components

Unlike typical AJAX-enabled frameworks where most of the application logic resides on the client, with ADF Faces application logic resides mostly on the server, executing in the JSF lifecycle. The Java data model also remains on the server; the ADF Faces framework performs initial rendering of its components on the server, generating HTML content that is consumed directly by browsers. This addresses security and performance concerns that can result from sending too much data to the client, and simplifies marshalling logic.


Because ADF Faces adheres to the standards of the JSF technology, this guide is mostly concerned with content that is in addition to, or different from, JSF standards. Therefore, it is recommended that you have a basic understanding of how JSF works before beginning to develop with ADF Faces. To learn more about JSF, visit Sun's web site at

1.2.1 Client-Side Architecture

JavaScript performance can suffer when too many objects are created. To improve performance, the RCF minimizes the number of component objects present on the client, and the number of attributes sent to the client. The framework also has the JavaScript files that make up the components housed in configurable partitions, allowing your application to load only the required JavaScript. Client-side Components

In JSF, as in most component-based frameworks, an intrinsic property of the component model is that components can be nested to form a hierarchy, typically known as the component tree. This simply means that parent components keep track of their children, making it possible to walk over the component tree to find all  descendents of any given component. While the full component tree still exists on the server, the ADF Faces client-side component tree is sparsely populated. Client-side components primarily exist to add behavior to the page by exposing an API contract for both application developers as well as for the framework itself. It is this contract that allows for example, toggling the enabled state of a button on the client. Therefore, client-side components are created only for those components that are truly needed on the client, typically those that have been explicitly configured to have client representation.

It is also possible for JavaScript components to be present that do not correspond to any existing server-side component. For example, some ADF Faces components have client-side behavior that requires popup content. These may create AdfRichPopup JavaScript components to make this easier to implement, even though no Java RichPopup component may exist.

The JavaScript class that you will interact with most is AdfUIComponent and its subclasses. An instance of this class is the client-side representation of a server-side component. Each client component has a set of properties (key/value pairs) and a list of listeners for each supported event type. All RCF JavaScript classes are prefixed with Adf to avoid naming conflicts with other JavaScript libraries. For example, RichCommandButton has AdfRichCommandButton, RichDocument has AdfRichDocument, and so on.

While the Java UIComponent object represents the state of the component, and is what you interact with to register listeners and set properties, the Renderer handles producing HTML and receiving postbacks on behalf of the component. In the RCF client-side JavaScript layer, client-side components have no direct interaction with the document object model (DOM) whatsoever. All DOM interaction goes through an intermediary called the peer. Peers interact with the DOM generated by the Java renderer and handle updating that state and responding to user interactions.

Peers have a number of other responsibilities including:

  • DOM initialization and cleanup

  • DOM event handling

  • Geometry management

  • Partial page response handling

  • Child visibility change handling JavaScript Library Partitioning

A common issue with JavaScript-heavy frameworks is determining how best to deliver a large JavaScript code base to the client. On one extreme, bundling all code into a single JavaScript library can result in a long download time. On the other extreme, breaking up JavaScript code into many small JavaScript libraries can result in a large number of round trips. Both approaches can result in the end user waiting unnecessarily long for the initial page to load.

To help mitigate this issue, ADF Faces aggregates its JavaScript code into partitions. A JavaScript library partition contains code for components and or features that are commonly used together. By default ADF Faces provides a partitioning that is intended to provide a balance between total download size and total number of round trips.

One benefit of ADF Faces's library partitioning strategy is that it is configurable. Because different applications make use of different components and features, the default partitioning provided by ADF Faces may not be ideal for all applications. As such, ADF Faces allows the JavaScript library partitioning to be customized on a per-application basis. This allows application developers to tune the JavaScript library footprint to meet the needs of their application. For more information about configuring JavaScript partitioning, see Section A.9, "Using JavaScript Library Partitioning".

1.2.2 ADF Faces Architectural Features

The RCF enables many architectural features that can be used throughout your application. For example, because processing can be done on the client, small amounts of data can be exchanged with the server without requiring the whole page to be rendered. This is referred to as partial page rendering (PPR). Many ADF Faces components have PPR functionality implemented natively. For example, the ADF Faces table component comes with built-in AJAX-style functionality that lets you scroll through the table, sort the table by clicking a column header, mark a row or several rows for selection, and even expand specific rows in the table, all without requiring a roundtrip to the server, and with no coding needed. For more information, see Chapter 7, "Rerendering Partial Page Content".

The RCF also adds functionality to the standard JSF lifecycle. Examples include a client-side value lifecycle, a subform component that allows you to create independent submittable regions on a page without the drawbacks of using multiple forms on a single page, and an optimized lifecycle that can limit the parts of the page submitted for processing. For more information, see Chapter 4, "Understanding the JSF and ADF Faces Lifecycles".

The RCF uses the standard JSF event framework. However, events in the RCF have been abstracted from the standard JavaScript DOM event model. Though the events share some of the same abstractions found in the DOM event model, they also add functionality. Consequently, you need not listen for click events on buttons, for example. You can instead listen for AdfActionEvent events, which may or may not have been caused by key or mouse events. RCF events can be configured to either deliver or not deliver the event to the server. For more information, see Chapter 5, "Handling Events"

ADF Faces input components have built-in validation capabilities. You set one or more validators on a component by either setting the required attribute or by using the prebuilt ADF Faces validators. In addition, you can create your own custom validators to suit your business needs.

ADF Faces input components also have built-in conversion capabilities, which allow users to enter information as a string and the application can automatically convert the string to another data type, such as a date. Conversely, data stored as something other than a string can be converted to a string for display and updating. Many components, such as the inputDate component, automatically provide this capability. For more information, see Chapter 6, "Validating and Converting Input".

In addition to these architectural features, the RCF also supports the following:

1.3 ADF Faces Components

ADF Faces components generally fall into two categories. Layout components are those that are used to organize the contents of the page. Along with components that act as containers to determine the layout of the page, ADF Faces layout components also include interactive container components that can show or hide content, or that provide sections, lists, or empty spaces. Certain layout components support geometry management, that is, the process by which the size and location of components appear on a page. The RCF notifies these components of browser resize activity, and they in turn are able to resize their children. This allows certain components to stretch or shrink, filling up any available browser space. JDeveloper provides prebuilt quick-start layouts that declaratively add layout components to your page based on how you want the page to look. For more information about layout components and geometry management, see Chapter 8, "Organizing Content on Web Pages".

The remaining components are considered to be in the common category, and are divided into the following subcategories:

1.4 ADF Faces Demonstration Application

ADF Faces includes a demonstration application that allows you to both experiment with running samples of the components and architecture features, as well as view the source code. The demo application contains the following:

In order to view the demo application (both the code and at runtime), install JDeveloper, and then download and open the application within JDeveloper.

1.4.1 How to Download and Install the ADF Faces Demo Application

You can download the ADF Faces demo application from the Oracle Technology Network (OTN) web site. Go to and click the link for Installing the ADF Faces Rich Client Demo. The resulting page provides detailed instructions for downloading the WAR file that contains the application, along with instructions for deploying the application to a stand-alone server, or for running the application using the integrated WebLogic server included with JDeveloper.

If you do not want to install the application, you can run the application directly from OTN by clicking the ADF Faces Rich Client Components Hosted Demo link.

1.4.2 Overview of the File Explorer Application

Because the File Explorer is a complete working application, many sections in this guide use that application to illustrate key points, or to provide code samples. The source for the File Explorer application can be found in the fileExplorer directory.

The File Explorer application uses the fileExplorerTemplate page template. This template contains a number of layout components that provide the basic look and feel for the application. For more information about layout components, see Chapter 8, "Organizing Content on Web Pages". For more information about using templates, see Chapter 19, "Creating and Reusing Fragments, Templates, and Components".

The left-hand side of the application contains a panelAccordion component that holds two areas: the directory structure and a search field with a results table, as shown in Figure 1-9.

Figure 1-9 Directory Structure Panel and Search Panel

Directory panel and search panel

You can expand and collapse both these areas. The directory structure is created using a tree component. The search area is created using input components, a command button, and a table component. For more information about using panelAccordion components, see Section 8.9, "Displaying or Hiding Contents in Accordion Panels and Tabbed Panels". For more information about using input components, see Chapter 9, "Using Input Components and Defining Forms". For more information about using command buttons, see Chapter 18, "Working with Navigation Components". For more information about using tables and trees, see Chapter 10, "Using Tables and Trees".

The right-hand side of the File Explorer application uses tabbed panes to display the contents of a directory in either a table, a tree table or a list, as shown in Figure 1-10.

Figure 1-10 Directory Contents in Tabbed Panels

panel tabs show contents

The table and tree table have built-in toolbars that allow you to manipulate how the contents are displayed. Additionally, you can drag a file or subdirectory from one directory and drop it into another. You can right-click a file, and from the context menu, you can view the properties of the file in a popup window. For more information about using tabbed panes, see Section 8.9, "Displaying or Hiding Contents in Accordion Panels and Tabbed Panels". For more information about table and tree table toolbars, see Section 10.8, "Displaying Table Menus, Toolbars, and Status Bars". For more information about enabling drag and drop, see Chapter 32, "Adding Drag and Drop Functionality". For more information about using context menus and popup windows, see Chapter 13, "Using Popup Dialogs, Menus, and Windows".

The top of the File Explorer application contains a menu and a toolbar, as shown in Figure 1-11.

Figure 1-11 Menu and Toolbar


The menu options allow you to create and delete files and directories and change how the contents are displayed. The Help menu opens a help system that allows users to provide feedback in dialogs, as shown in Figure 1-12.

Figure 1-12 Help System

help system

The help system consists of a number of forms created with various input components, including a rich text editor. For more information about menus, see Section 14.2, "Using Menus in a Menu Bar". For more information about creating help systems, see Section 17.5, "Displaying Help for Components". For more information about input components, see Chapter 9, "Using Input Components and Defining Forms".

Within the toolbar of the File Explorer are controls that allow you navigate within the directory structure, as well as controls that allow you to change the look and feel of the application by changing its skin. Figure 1-13 shows the File Explorer application using the simple skin.

Figure 1-13 File Explorer Application with the Simple Skin

File Explorer using the Simple Skin

For more information about toolbars, see Section 14.3, "Using Toolbars". For more information about using skins, see Chapter 20, "Customizing the Appearance Using Styles and Skins".

1.4.3 Viewing the Source Code In JDeveloper

All the source files for the ADF Faces demo application are contained in one project (you give this project a name when you create it during installation). The project is divided into two directories: Application Sources and Web Content. Application Sources contains the oracle.adfdemo.view package, which in turn contains packages that hold managed beans that provide functionality throughout the application.


The managed beans for the component demos are in the component package and the managed beans for the File Explorer application are in the explorer package.

The Web Content directory contains all the web resources used by the application, including JSPX files, JavaScript libraries, images, configuration files, and so on.


The components subdirectory contains the resources for the component demos. The docs directory contains the tag and Javadoc documentation. The fileExplorer directory contains the resources for the File Explorer application.