Building Enterprise JSF Applications with Oracle JHeadstart for ADF (10.1.3)

A step-by-step, end-to-end tutorial on how to be effective immediately with J2EE application development using Oracle tools.

Author: Steve Muench, Oracle ADF Development Team
Contributions from Steven Davelaar & Sandra Muller, JHeadstart Team

Date: April 17, 2007

Abstract

There is good chance you've heard that developing database-centric business applications for the J2EE platform is a complex endeavor. Luckily, there is hope. Over the past few years, analysts like Gartner Group coined the term "J2EZ" for a class of tools and frameworks that make J2EE application development easy. These so-called "J2EZ" tools target developers for whom time to market, low implementation costs, and productivity are driving factors, by providing a visual, declarative, and highly productive environment. This document provides step-by-step instructions to evaluate what you can achieve today using production versions of Oracle's offerings in this "J2EZ" space by combining the 10.1.3 versions of Oracle's JDeveloper 10g IDE, the Oracle Application Development Framework (ADF), and the Oracle JHeadstart 10g Application Generator for Oracle ADF.

By following this tutorial, you'll experience first-hand how Oracle JHeadstart 10g turbo-charges your developer productivity for Oracle ADF-based web applications. You will build an attractive, consistent, interactive, and skinnable web application with browse, search, insert, update, and delete functionality against six related database tables from the Oracle HR sample schema. Your application will feature single- and multi-row editing, page-by-page scrolling, master/detail handling, tabbed pages, dropdown lists, a pop-up list of values (LOV) window, a wizard, a shuttle picker, a tree control and a graph. Since no Java coding is required to implement the tutorial, even developers with minimal-to-no Java skills can follow along. This is possible because Oracle ADF-powered J2EE applications only require custom code to add application-specific business logic or to augment default framework behavior.


NOTE:

If you prefer reading this document offline, a PDF version of this paper [ 1] is available. In addition, the tutorial files download contains this same HTML page and images for offline viewing as well. A completed version of the tutorial application [ 2] is available for your reference.


Contents

1 Overview of Oracle ADF and Oracle JHeadstart 10g
2 Tutorial Setup
2.1 Download the Tutorial Files
2.2 Start with JDeveloper 10g, Release 10.1.3.2
2.3 Install Oracle JHeadstart 10g 10.1.3.1 Using "Check for Updates"
2.4 Setup the Oracle HR Schema and Sample Data
2.5 Define a JDeveloper Connection for the HR Schema
2.6 Set ADF Business Components Java Generation Preferences
3 Creating a Default Web Application
3.1 Create and Configure a New Workspace
3.2 Create Default ADF Business Components
3.3 Generate Default Web Tier with JHeadstart
3.4 Run the Application
3.5 Observe Default Application Functionality
4 Change Layout Styles and Query Behavior
4.1 Change How Employees Group Gets Generated
4.2 Change How the Departments Group Gets Generated
4.3 Change How the Jobs Group Gets Generated
4.4 Change How the Countries Group Gets Generated
4.5 Change How the Regions Group Gets Generated
4.6 Regenerate and Run the Application
5 Create Department Manager List of Values (LOV)
5.1 Add Manager Name to Departments Query
5.2 Create a List of Values (LOV) Group
5.3 Use the LOV on ManagerName and Hide the ManagerId
5.4 Regenerate and Run the Application
6 Creating a Wizard Including a Shuttle Control
6.1 Add View Object Instances to the Data Model to Support the Wizard and Shuttle
6.2 Create and Configure a New EmpWizard Group
6.3 Create and Configure Three Item Regions for the EmpWizard Group
6.4 Configure Subordinates Detail Group to Use Shuttle
6.5 Regenerate and Run the Application
7 Using Stacked Tabs for Table Overflow Items
8 Adding a Conditionally Dependent Field
9 Generating a Graph and Summary Information
10 Using "Deep Linking" to Support Targeted Hyperlinks
10.1 Configure the Job Group for Deep Linking
10.2 Changing JobId to a Hyperlink Using the JDeveloper Visual Editor
10.3 Run the Application to Test the JobId Hyperlink
11 Preserving Customizations Using Generator Templates
11.1 Moving the Customization into a Generator Template
11.2 Using the New Template for the JobId Column
11.3 Regenerate and Run the Application
12 Applying Custom Skins to Change Look and Feel
13 Adding a Validation Rule and Customizing Error Reporting
13.1 Defining Some Declarative Validation Rules
13.2 Rerunning the Application to See Validation Rules in Action
13.3 Declaratively Customizing the Way Errors are Reported
14 Conclusion
14.1 No Generated Java Code For Any Functionality in the Entire Tutorial!
14.2 Simplified Multi-Lingual Applications with Message Files
14.3 J2EE Applications Give Choice of Application Server
14.4 Useful Links for Additional Information on JHeadstart, JDeveloper, and Oracle ADF
14.5 Now You Can Try On Your Own Schema
Related Documents

1 Overview of Oracle ADF and Oracle JHeadstart 10g

On their own, the Oracle Application Development Framework (ADF) together with the Oracle JDeveloper 10g IDE give developers a productive, visual environment for building richly functional J2EE applications without having to implement J2EE design patterns and low-level plumbing code by hand. As its name implies, Oracle JHeadstart 10g offers a significant additional productivity advantage in creating sophisticated web-based, J2EE business applications. Standing squarely on the shoulders of the base Oracle ADF framework, Oracle JHeadstart adds an additional capability for generating fully-working JavaServer Faces (JSF) web tier for the data model exposed by your ADF application module. The ADF web applications you generate with JHeadstart leverage the powerful ADF Faces components for JSF so can easily support multi-row editing, lists of values (LOVs) with validation, tree and shuttle displays, and consistent search pages, among many other features.

JHeadstart automates creating and iteratively evolving the web tier of your ADF application based on a declarative application definition. Once you've allowed JHeadstart to generate the bulk of your application's web user interface, you can spend your time using JDeveloper's productive environment to tailor the results or to concentrate your effort on real showcase pages that need special attention.

Like all Oracle ADF-based applications, those leveraging Oracle JHeadstart are J2EE compliant and therefore easy to deploy to any J2EE application server. They also inherit Oracle ADF's implementation all of the best practice J2EE design patterns [ 3] required to implement robust, functional business applications.

As we'll see in this step-by-step demo, the JHeadstart Application Generator does not generate any Java code. Instead, it generates web pages, ADF metadata describing the data needed on those pages, JavaServer Faces (JSF) metadata describing the page flow, and translatable message bundle files. We'll also see that all of the basic functionality provided by the underlying Oracle ADF framework components in the demo does not require any generated Java code either. We hope you'll walk away impressed by what you can do without writing a single line of Java code using this powerful combination of J2EE tools and frameworks from Oracle. Any lines of code that you would eventually write in a real application would be squarely focused on enhancing all of the built-in functionality provided with your own custom business application logic.


NOTE:

Oracle JHeadstart 10g for ADF is a separate extension for Oracle JDeveloper 10g for which a fully-functional trial version is available for your evaluation purposes. Complete information on pricing, support, and additional services available for JHeadstart 10g is available in the JHeadstart Frequently Asked Questions document on the JHeadstart Product Center [ 4] on OTN.



TIP:

After you've followed the demo steps yourself, the same steps work well as a scripted demo you can show to others to spread the good word about the many powerful features provided by the combination of Oracle JDeveloper 10g, Oracle ADF, and Oracle JHeadstart working together.


2 Tutorial Setup

This section outlines the steps you'll need to follow to get your machine ready to go through this tutorial. We recommend not skipping any steps in this section without reading them!

2.1 Download the Tutorial Files

If you are reading this tutorial online, download the jhs-step-by-step.zip [ 5] file that contains the database setup scripts. Extracting this zip file into the root directory of your C:\ drive will create a jhs-step-by-step directory. You can browse the index.html page to read this same tutorial offline. The database setup scripts (described more in detail below) are in the hr_schema subdirectory.

2.2 Start with JDeveloper 10g, Release 10.1.3.2

This tutorial requires Oracle JDeveloper 10g Studio Edition, release 10.1.3.2 Production. If you have a version of Oracle JDeveloper installed, you can verify what version it is by selecting the Help | About option from the main menu.


NOTE:

JHeadstart 10.1.3.1 will also work with JDeveloper release 10.1.3.1 Production.

JHeadstart 10.1.3.1 is not certified to work with JDeveloper 10.1.3.0 Production.


If you need to download JDeveloper 10g Release 10.1.3.2 look for the correct version on this JDeveloper Downloads [ 6] page.

To install JDeveloper, create a convenient directory (e.g. C:\jdev1013) and extract the jdevstudio10132.zip file into this directory using the standard Java jar utility, WinZip, or other zip-compatible tool you prefer.

To start JDeveloper 10g, double-click on jdeveloper.exe in the C:\jdev1013 folder as shown in Figure 1 . You can create a desktop shortcut for C:\jdev1013\jdeveloper.exe to make launching JDeveloper easier on future occasions.

Launching JDeveloper 10g on Windows
Figure 1: Launching JDeveloper 10g on Windows

NOTE:

On Unix-based platforms, run the ./jdev/bin/jdev shell script to launch JDeveloper 10g.


Upon starting JDeveloper 10g for the first time, the Migrate User Settings alert may appear asking "Would you like to migrate from a previous version of JDeveloper?" If it does, just click (No) to continue.

Dismiss the Tip of the Day dialog if it appears by clicking (Close) .

2.3 Install Oracle JHeadstart 10g 10.1.3.1 Using "Check for Updates"

Oracle JHeadstart is an Oracle JDeveloper extension (or "plug-in") that you install using JDeveloper's "Check for Updates" functionality. If anything about these installation instructions doesn't work for you as indicated, check the JHeadstart 10g Product Center [ 4] on OTN, under the Downloads heading, for further assistance.

To install the JHeadstart 10g Evaluation Version into your JDeveloper 10g 10.1.3 environment, perform the steps below.

2.4 Setup the Oracle HR Schema and Sample Data

The demo steps are based on the standard Oracle sample HR schema of human resources information. For your convenience, this tutorial comes with the SQL scripts to create the HR schema tables if you didn't install the sample schemas when you installed your database.


NOTE:

If the steps in this section do not work for you, then as a fallback please refer to the Installing the Sample Schemas and Establishing a Database Connection [ 7] tutorial and follow the instructions for the database version you are using.


2.4.1 Create the HR Schema If Necessary

If you don't already have an HR user account created in your database, you can follow these steps to create it.

C:\jhs-step-by-step> sqlplus /nolog
SQL> connect sys as sysdba
SQL> create user hr identified by hr;
created.
SQL> alter user hr default tablespace users;
altered.
SQL> grant connect, resource to hr;
SQL> connect hr/hr
connected.
SQL> quit

2.4.2 Create the HR Schema Sample Tables

In the hr_schema subdirectory of this tutorial, you'll find the hr.sql script. This script drops, recreates, and repopulates all the tables in the HR sample schema. Change directory to the hr_schema subdirectory, and run the script as the HR user, with the command:

C:\jhs-step-by-step> cd hr_schema
C:\jhs-step-by-step\hr_schema> sqlplus hr/hr @hr.sql

NOTE:

If you are using an Oracle 9i database, you can ignore the error you'll receive at the end for the PURGE RECYCLEBIN command. That command is specific to Oracle 10g.


2.5 Define a JDeveloper Connection for the HR Schema

Select View | Connection Navigator to show the Connection Navigator and follow these steps:

2.6 Set ADF Business Components Java Generation Preferences

By default, the ADF Business Components design time is configured to generate skeleton Java classes where developers could eventually write their code. Producing these skeleton classes by default is not required, and there is an IDE preference to control it. If you don't generate them by default, you can easily add them on a case-by-case basis should custom Java code ever become required for a given component type.

In order to better understand what ADF application functionality requires Java code and what does not, it's useful to set the ADF Business Components Java generation preferences at the IDE level so that the wizards and editors create no custom Java classes by default. By doing this, at the end of the demo we can see what Java classes actually are part of our working, finished application to get a better understanding of what combined, built-in functionality Oracle ADF and Oracle JHeadstart 10g provide.

To change this preference, select Tools | Preferences... from the JDeveloper main menu and click on the Business Components category. Uncheck any of the checked boxes in the panel at the right as shown in Figure 10 , then click (OK) .

Setting ADF Business Components to Generate No Java by Default
Figure 10: Setting ADF Business Components to Generate No Java by Default

3 Creating a Default Web Application

In this section we will:

  • Create a new workspace,
  • Create the ADF Business Components to handle our backend database access, and
  • Generate a default set of web pages with JHeadstart

Then, we'll run the application inside JDeveloper 10g to see what default behavior we get before starting to iteratively modify the application to further tailor it to work like our end users want.

3.1 Create and Configure a New Workspace

  1. Create a new Application Workspace

    Choose File | New... from the JDeveloper main menu, and double-click the Application icon in the General category of the New Gallery. In the Create Application dialog, select the application template named Web Application [JSF, ADF BC] as shown in Figure 11 . To make it easier to follow along in this tutorial, please enter the Application Name ( MyDemo), Directory Name ( C:\MyDemo), and Application Package Prefix ( mydemo) exactly as shown. By doing this you'll make it easiest to follow this tutorial's step-by-step instructions.

    Creating a New Application Workspace
    Figure 11: Creating a New Application Workspace

    When you click (OK) to create the workspace, JDeveloper will create your new MyDemo workspace that will contain two (initially empty) projects named Model and ViewController.



  2. Give Your Web Application a Meaningful Web Context Root Name

    Select the ViewController project still selected in the Application Navigator, and choose Project Properties... from the right-mouse menu. Visit the J2EE Application category and notice that the default web context root name is MyDemo-ViewController-context-root. The J2EE web context root name is the first part of your application's web URL that users will see, so having a short, meaningful name is preferable to this long default name. So let's set the J2EE Web Context Root to just “ MyDemo” instead. Technically, this step is optional, but it gives your application a nicer-looking runtime URL and it's nice to know where you would change it for your own applications.



  3. Simplify Running the Application By Changing a Project Setting

    While still in the Project Properties dialog, to make it easier to quickly run the application, disable JDeveloper's default behavior of trying to run the current file. To do this, do the following:

    • Visit the Run/Debug category
    • Select the Default configuration in the Run Configurations list
    • Click (Edit...)
    • Uncheck the checkbox Attempt to Run the Active File before Default .
    • Click (OK) to dismiss the Edit Run Configuration dialog.


Finally, click (OK) to dismiss the Project Properties dialog, saving your changes.

3.2 Create Default ADF Business Components

The ADF Business Components handle all of the database access for you in a way that is cleanly separated from the user interface. The application module provides the transactional component clients use to browse and modify view object data. The view object performs SQL queries and coordinates with entity objects to handle updates. The entity object encapsulates business domain data and validation for rows in a table. In this step we'll use wizards to create all three types of components based on existing tables in the database.


NOTE:

For additional background to ADF Business Components, including information on how their functionality maps to features of Oracle Forms, see the ADF Developer's Guide for Forms/4GL Developers [ 8] and my ongoing columns in the Oracle Magazine DEVELOPER: Frameworks [ 9] series.


  1. Create Default Business Components for Tables in HR Schema


    NOTE: For a more detailed explanation of this step, see the "Setting Up the Business Components Package" section in Chapter 2. Getting Started from the JHeadstart Developer's Guide [ 10] .



  2. Organize Your Application Navigator

    After creating your default set of business components in the mydemo.model, mydemo.model.entities and mydemo.model.queries packages, your Application Navigator may look like what you see in Figure 17 . The Flat Level control in the Application Navigator toolbar controls how many levels of dot-separated package names should be flatted for presentation in the tree. The Sort by Type toggle button switches between sorting your components:

    • Alphabetically, and
    • By component type, then alphabetically.
    Model Project in the Application Navigator with Default Flat Level of 3 and Sorted Alphabetically
    Figure 17: Model Project in the Application Navigator with Default Flat Level of 3 and Sorted Alphabetically

    For example, if you set the Flat Level to 1 and enable the Sort by Type toggle button, your navigator will change to look like what you see in Figure 18 .

    Model Project in the Application Navigator with Flat Level 1 and Sorted By Type
    Figure 18: Model Project in the Application Navigator with Flat Level 1 and Sorted By Type


  3. Add Five-level Master/Detail to the Application Module's Data Model

    In the Application Navigator, inside your Model project find the HRModule component. It's in the mydemo.model package. Edit the HRModule application module by double-clicking it. This will open the Application Module Editor . Visit the Data Model panel, and as shown in Figure 19 you'll see both the list of Available View Objects from the current project, and the named, master/detail-coordinated usages of those view objects in this application module's Data Model . The view object usages in the data model are also known as view object instances since at runtime they represent an instance of the reusable view object component.

    Initial HRModule Data Model
    Figure 19: Initial HRModule Data Model

    We're going to modify the default data model to add nested view object usages in order to get a 5-level deep nesting of region → country → location → department → employee.

    We start by adding a LocationsView view object instance as a child/detail of CountriesView2, by doing the following:

    • In the Data Model tree control, select the existing view instance CountriesView2 that will become the new master (for the next-level detail we're about to add).

    • Expand the CountriesView view object in the Available View Objects list

    • Select the LocationsView view object that is indented under CountriesView in the Available View Objects list. This indenting means that it is an available detail view for any instance of a CountriesView master in the data model.

    • Click the (>) button to shuttle a new LocationsView3 instance into the data model as detail of the existing, selected CountriesView2.

    We can repeat the process to add an instance of DepartmentsView as a detail of the LocationsView3, and then again to add an instance of EmployeesView as a detail of the DepartmentsView4.

    When finished adding the three extra levels, your application module's data model will look like what you see in Figure 20 . Click (OK) to save your changes.

    Default Application Module Modified to Have Five-Level Master/Detail
    Figure 20: Default Application Module Modified to Have Five-Level Master/Detail


3.3 Generate Default Web Tier with JHeadstart

The Oracle JHeadstart extension for JDeveloper uses metadata to capture the high-level definition of the layout and features of your desired web application. The JHeadstart application generator then uses that application definition metadata to generate the set of web pages that comprise your web application user interface. In this section we'll enable our project to use JHeadstart, ask JHeadstart to create a default application definition metadata file, and then kick off the JHeadstart application generator to see what kind of web application we get before proceeding to tailor the output further in subsequent steps of the tutorial.

  1. Enable JHeadstart on the ViewController Project

    Select the ViewController project in the navigator and choose Enable JHeadstart on this Project from the right-mouse menu. Click (Next>) from the welcome page, then click (Finish) to proceed with enabling JHeadstart.

    As shown in Figure 21 , after clicking (Finish) the first time the wizard will proceed to create a number of necessary files and configure your project appropriately to contain them. Each step it performs is listed in the text box in this panel of the wizard. When done, click (Finish) again to close the wizard. Then, click the Save All button in the JDeveloper main toolbar to save all the changes.

    Enabling JHeadstart on ViewController Project
    Figure 21: Enabling JHeadstart on ViewController Project


  2. Create the Default JHeadstart Application Definition

    Select the ViewController project in the navigator, and choose the New JHeadstart Application Definition item from the right-mouse menu. After clicking (Next>) to leave the welcome screen, on the next panel as shown in Figure 22 , select the HRModuleDataControl to use, leave the Create default Groups for all Data Collections checkbox checked, and click (Next>) again.

    Selecting the Application Module (Data Control) to Use
    Figure 22: Selecting the Application Module (Data Control) to Use

    On the following panel, take the defaults for the service/application name as shown in Figure 23 , and click (Next >) .

    Choosing a JHeadstart Service/Application Name
    Figure 23: Choosing a JHeadstart Service/Application Name

    On the next panel, take the defaults for the default layout styles as shown in Figure 24 .

    Before proceeding, take a moment to notice the option to Generate LOV's instead of dropdown lists? . While we won't enable this preference for this tutorial, it's worth remembering that this option may be useful to you when you try the Oracle JHeadstart Evaluation Edition on a subset of your own production schema. JHeadstart can generate foreign key lookups as dropdown lists or as pop-up list-of-values (LOV) windows. Dropdown lists are more appropriate for smaller-sized lists of choices (e.g. less than 100 rows), while pop-up LOV windows are more appropriate to select an foreign key value when many choices exist and your end user might need to perform a search to find what they are looking for.

    Now, click (Next >) to continue.

    Choosing Default Layout Styles
    Figure 24: Choosing Default Layout Styles

    On the final panel click (Finish) to create the new application definition file. As shown in Figure 25 the wizard will display each of the steps it performs. When done, click (Finish) again to close the wizard.

    Creating the Default Application Definition File
    Figure 25: Creating the Default Application Definition File


  3. Save Your Changes

    Click the Save All button in the JDeveloper main toolbar to save all the changes.



  4. Observe the Default Application Definition

    To view the JHeadstart application definition you just created, select the ViewController project and choose Edit JHeadstart Application Definition from the right-mouse menu. This opens the JHeadstart Application Definition Editor, which is a modeless window that you can keep open while you continue to work with the main JDeveloper window.

    Notice that JHeadstart has used the hierarchical structure of the application module's data model to create the default application definition for the web tier. In practice you will end up iteratively changing the default application definition, but having a nice default definition to start with is a big plus as we'll see.

    As shown in Figure 26 , you can see the 5-level nesting of the view object instances for regions, countries, locations, departments, employees . You also notice that the JHeadstart New Application Definition wizard has created you a rich set of default lookup definitions (called domains) where foreign key relationships exist in the base business component model. These domains are referenced by items in the application definition for which drop-down lists will be generated for the end-user to select a valid choice.

    Application Definition Editor Showing Default Structure
    Figure 26: Application Definition Editor Showing Default Structure


  5. Generate the Application

    To run the JHeadstart application generator, select your ViewController project in the Application Navigator and choose Run JHeadstart Application Generator from the right-mouse menu as shown in Figure 27 .

    Running the JHeadstart Application Generator for the First Time
    Figure 27: Running the JHeadstart Application Generator for the First Time

    During the generation process, the JHeadstart Application Generator log window tab will display the detailed progress, including errors (if any), warnings, and informational messages. Figure 28 shows what this log window tab should look like after your first successful generation run. If you should see entries in an Errors category, which would appear at the top of the list with a "red ball" icon, the message always gives helpful details about how to correct the problem. Note that even when you see a few Warnings , these are suggestions of "next steps" you need to do as the developer or best-practices suggestions that the Generator cannot do automatically. Scrolling through the messages in the Information section gives you an idea of the amount of work that the JHeadstart application generator is saving you. In this case, it has generated twenty-two (22) JSF pages and their corresponding declarative databinding metadata, along with numerous other declarative artifacts that support the application!

    For your convenience, on future runs of the JHeadstart application generator, in addition to the right-mouse menu option we picked here, you can also just click on the Run JHeadstart Application Generator toolbar button ( ) at the top of the JHeadstart Application Definition Editor window. Both actions do the same thing.

    Warnings and Informational Messages in the JHeadstart Application Generator Log Window
    Figure 28: Warnings and Informational Messages in the JHeadstart Application Generator Log Window



NOTE:

If you did get errors in the JDeveloper log, make sure that you did not forget to do the setup step Rename the Velocity Version 1.3 JAR File above. If you did forget, exit JDeveloper, perform the task recommended in that step, restart JDeveloper, and then try running the JHeadstart application generator again.


3.4 Run the Application

Run the ViewController project by selecting it in the application navigator and then pressing F11 (or clicking on the toolbar run icon ). JDeveloper will launch your default browser, startup the embedded OC4J container with your web application deployed, and show you the initial page of the application that will look like what you see in Figure 29 .

Initial JHeadstart-Generated Web Application
Figure 29: Initial JHeadstart-Generated Web Application

TIP:

If instead of seeing the initial application page you see some kind of timeout error in your browser as shown in Figure 30 , then you'll need to change a configuration property of JDeveloper's embedded J2EE container (OC4J) to avoid this problem. This typically occurs when you are on a network using DHCP to get a dynamically-assigned IP address.

Running Web App in JDeveloper Times Out in Browser
Figure 30: Running Web App in JDeveloper Times Out in Browser

Before changing the necessary setting, terminate the currently running embedded server by selecting the Run | Terminate > Embedded OC4J Server .

Next, select the Tools | Embedded OC4J Server Preferences... main menu item in JDeveloper, and change the Host Name of IP Address Used to Refer to Embedded OC4J setting to Specify Host Name , and enter a hostname of localhost as shown in Figure 31 . Then, try rerunning the application and it should work this time.

Changing IDE Preference for Embedded OC4J Host Name
Figure 31: Changing IDE Preference for Embedded OC4J Host Name

3.5 Observe Default Application Functionality

By playing with the default application yourself, you can experience some of the built-in features that Oracle ADF and JHeadstart support by default, and which the Oracle JHeadstart Application Generator generates for you based on your declarative application definition file.

Highlights of these features include:

  • Switch Between Top-Level Application Functionality with Tabs




  • Browse Data and Drill-Down to Details or Related Information


  • Automatic "Breadcrumbs" Provide User Hierarchical Navigation Assistance




  • Create and Edit Data for Any Table Out of the Box




  • Insert, Update, and Delete Multiple Rows on a Page




  • Select Related Data from Automatically Created Lookups




  • Scroll Through Data Without Refreshing Entire Page




  • Rapidly Find Data Using Quick Search Region




  • Search More Precisely Using Advanced Search Region




  • Easily Set Optional Fields to Null Using Drop-Down Lists




  • Avoid Accidentally Losing Pending Changes When Switching Top-Level Application Function




  • Never Wonder Whether Changes are Saved with Positive User Feedback




4 Change Layout Styles and Query Behavior

In this step of the demo, we'll change a number of declarative application definition properties about the Employees, Departments, Jobs, and Regions groups to affect how the JHeadstart application generator generates the web tier pages. We'll wait until making them all before re-running the application generator.

To make the changes described here, make sure you have the JHeadstart Application Definition Editor open. If you don't, just select your ViewController project and select Edit JHeadstart Application Definition from the right-mouse menu.


NOTE:

Since the JHeadstart Application Definition Editor dialog is modeless, you can keep it open and Alt+ Tab between it and the main JDeveloper IDE window.


4.1 Change How Employees Group Gets Generated

4.2 Change How the Departments Group Gets Generated

4.3 Change How the Jobs Group Gets Generated

To apply the changes in this section, make sure you've selected the top-level Jobs group in the JHeadstart Application Definition Editor.

4.4 Change How the Countries Group Gets Generated

We'll change the Countries group and its Locations2 child group to display as a table with a nested table display.

4.5 Change How the Regions Group Gets Generated

We're going to change the Regions group, and its four child groups, to display as a tree with multi-level form editing by doing the following steps...

4.6 Regenerate and Run the Application

At this point we're done making our goodly number of iterative, declarative changes to the application definition, so all that's left is to regenerate the application using the JHeadstart application generator, and running it to see the effects of our changes.

  • Regenerate the Application

    From the JHeadstart Application Definition Editor, click the Run the JHeadstart Application Generator toolbar button ( ). Alternatively, you can select your ViewController project in the Application Navigator and choose Run JHeadstart Application Generator from the right-mouse menu. When completed, the Generation Finished alert will appear confirming the generation has finished successfully.



  • Run the Application

    Run the ViewController project by selecting it in the application navigator and then pressing F11 (or clicking on the toolbar run icon ).



After regenerating, once the application is running in your default browser, we can try the following things to see how our changes to the application definition were realized in the generated pages...

5 Create Department Manager List of Values (LOV)

In this step, we are going to change the dropdown list for selecting the manager of a department to be a popup list-of-values (LOV) window instead. When valid choices for a foreign key value are large in number, this kind of LOV window is more appropriate than a dropdown list. Specifically, we want to change the ManagerId dropdown list shown in Figure 74 to be a text field with a popup LOV instead.

EmployeeList Lookup as Dropdown List for Setting ManagerId
Figure 74: EmployeeList Lookup as Dropdown List for Setting ManagerId

If we were to choose to show the ManagerId as a text field, the value that the user will see would be the numeric id of the manager which is not exactly what we want. It would be nicer for our end-users to show the manager's last name in the text field, and hide the numeric ManagerId value altogether. Then the user will see the last name, and popup the LOV to select last names from list. This will provide a lot better usability for our application. The following sections lead you through the few steps required with JHeadstart to accomplish this.

5.1 Add Manager Name to Departments Query

If we're going to show the name of a department's manager, we need to edit the definition of our DepartmentsView view object — back in our Model project — to include that bit of information.

  1. Add Employees Entity Object to the DepartmentsView View Object

    Select the mydemo.model.DepartmentsView view object in the application navigator, and double-click it to launch the View Object Editor . On the Entity Objects panel of the editor, notice that the Departments entity object is already in use in this query. To add the Employees entity object as a second entity usage, as shown in Figure 75 select it in the Available list, and press (>) to shuttle it into the Selected list.

    Notice that by default the second entity object participating in this view object is marked as being Reference information and not updateable. While you can override this default setting, in this case the information we need to display from the Employees entity is read-only reference information — showing the department manager's last name — so we'll leave the default setting intact.

    Adding Employees Entity to DepartmentsView
    Figure 75: Adding Employees Entity to DepartmentsView


  2. Add LastName Attribute to the Attributes List

    On the Attributes panel of the editor, select the Employees entity's LastName attribute in the Available list, and press (>) to shuttle it into the Selected list as shown in Figure 76 . Notice that the primary key attribute ( EmployeeId) is also automatically added by the wizard.

    Adding the Employees.LastName Attribute to the List
    Figure 76: Adding the Employees.LastName Attribute to the List


  3. Remove the Additional EmployeeId Key Attribute

    Since the manager-related information is contributing reference information to this view of department information, the DepartmentId attribute alone is enough to uniquely identify each row. Therefore, disable the Key Attribute setting of the additional EmployeedId attribute that JDeveloper enables by default.

    To do this, select the EmployeeId attribute in the Attributes section of the tree and uncheck its Key Attribute checkbox.


    NOTE: For more information on why this is a best practice, see section 7.3.1.4 Removing Unnecessary Key Attributes from Reference Entity Usages [ 11] in the ADF Developer's Guide for Forms/4GL Developers.



  4. Rename the LastName Attribute to ManagerName

    To make it clearer that this employee last name is the name of the department's manager in this particular view object, we can rename the attribute from LastName to ManagerName. To do this, select the LastName attribute name indented under the Attributes node in the tree at the left, and type the new name attribute name into the Name field as shown in Figure 77 .

    Renaming the LastName Attribute to ManagerName
    Figure 77: Renaming the LastName Attribute to ManagerName


  5. Add the Employee Email Attribute and Rename to ManagerEmail

    Repeat steps 2 & 3 above to add the Email attribute from the Employee entity usage to the view object as well, and then rename this view attribute to ManagerEmail as shown in Figure 78 to make its name more meaningful.

    Renaming the Email Attribute to ManagerEmail
    Figure 78: Renaming the Email Attribute to ManagerEmail


  6. Change SQL Query to Outer Join to EMPLOYEES Table

    Since departments are allowed to have no manager, their ManagerId foreign key attribute value might be null. To insure that we query all departments, whether or not they have a corresponding employee as their manager, we need to change the SQL query for this DepartmentsView to be an outer join.

    To accomplish this, visit the Query panel of the editor, and type a " (+)" after the EMPLOYEE_ID column name the Where clause box as shown in Figure 79 . Make sure there is a space between EMPLOYEE_ID and the " (+)" characters.

    Changing the DepartmentsView to an Outer Join
    Figure 79: Changing the DepartmentsView to an Outer Join

    Finally, click (OK) to accept all your changes to the DepartmentsView view object definition, then click the Save All toolbar button to save the changes.



5.2 Create a List of Values (LOV) Group

With our view object modified to include the ManagerName attribute, we're ready to define a new group to be used to layout the LOV window. Follow these steps...

5.3 Use the LOV on ManagerName and Hide the ManagerId

Select the undefined <= undefined return item node that appears and as shown in Figure 93 , set its Source Item property to EmployeeId and the Target Item property to ManagerId.

Configuring an LOV Return Item for the Primary Key of the Selected Employee
Figure 93: Configuring an LOV Return Item for the Primary Key of the Selected Employee

To also have the managers email returned when the value is selected, repeat the steps above to add a third LOV return item and set its Source Item property to Email and the Target Item property to ManagerEmail as shown in Figure 94 .

Configuring a third LOV Return Item for the Managers Email
Figure 94: Configuring a third LOV Return Item for the Managers Email

5.4 Regenerate and Run the Application

We're done setting up our list of values (LOV) field on ManagerName, so let's regenerate the application and run it. When generation finishes, run the application again by clicking on the ViewController project in the application navigator and press F11.

Figure 95 shows what the Departments tab looks like after we've used the Quick Search to find only departments whose DepartmentName contains " es".

ManagerName LOV Lookup in Departments Browse Page
Figure 95: ManagerName LOV Lookup in Departments Browse Page

The changes we made to the EmployeesLookup lookup definition above show up in the browse page with a ManagerName LOV field in every row. We can see that our outer join is working correctly, since the "Shareholder Services" department has no manager and it was included in the query results.

If you try typing a letter " p" in the ManagerName field for the "Shareholder Service" department — or alternatively, changing one of the existing manager names in a different department to the letter " p" — and then pressing Tab to leave the field, you'll see the LOV window pop-up automatically showing the filtered list of choices that start with the letter " p" as shown in Figure 96 .

LOV Window Showing Filtered List of Matches
Figure 96: LOV Window Showing Filtered List of Matches

Back on the Departments browse page, if instead of typing just the letter " p" in one of the ManagerName fields, you type "ph" instead and Tab out of the field, you'll see another treat. Without bringing up the LOV window at all, the manager named "Philtanker" is automatically filled in, along with the manager's email id "HPHILTAN". This is the " Use LOV for Validation " behavior at work that JHeadstart enables by default for the list of values you generate. The selected data is returned from the LOV thanks to the "return items" we configured above.

Of course, you can also just click on the "searchlight" icon and pop-up the LOV window for you to filter and select the choice yourself.


NOTE:

Although a roundtrip from the browser to the application server is made to check the number of matching rows, only the ManagerName and ManagerEmail fields in the current row are actually refreshed on the page. This is accomplished through an ADF Faces feature called Partial Page Rendering (PPR) that we will explain in more detail in the Adding a Conditionally Dependent Field section.


If we drill-down to edit the details for a department, as shown in Figure 97 the same EmployeesLookup changes we made above result in showing a ManagerName LOV field in the Edit Departments form as well.

EmployeeLookup LOV Also Available in Edit Forms
Figure 97: EmployeeLookup LOV Also Available in Edit Forms

6 Creating a Wizard Including a Shuttle Control

In this step we will generate a wizard consisting of four pages to enter a new employee. The fourth wizard page will contain a shuttle control to assign subordinates to the new employee if applicable.

6.1 Add View Object Instances to the Data Model to Support the Wizard and Shuttle

To ensure that the employee creation wizard and its shuttle control behaves in a way that is independent of other employee and subordinate data queried in the application, we can add an additional instances of the appropriate view object components to the data model of our HRModule, and then use these new view object instances as the data collections for the groups involved in the wizard. To accomplish this, follow these steps:

We're done making the required data model changes, so click (OK) to accept the changes, then click the Save All button in the JDeveloper main toolbar to save them.

6.2 Create and Configure a New EmpWizard Group

To create an configure a new group with a wizard layout, perform these steps:

6.3 Create and Configure Three Item Regions for the EmpWizard Group

To define three item regions and assign group items to them, follow these steps:

6.4 Configure Subordinates Detail Group to Use Shuttle

Select the EmpWizard group's detail group named Subordinates and set the following properties on it:

Property Category Property Name Set to Value
Group Layout Layout Style parent-shuttle
Group Layout Same Page? (unchecked)
Labels Tabname "Unassigned"
Labels Display Title (Plural) "Assign Subordinates"
Labels Display Title (Singular) "Assigned"

Like a dropdown list or radio group, a shuttle control presents the user with a list of available choices. This list contains a Meaning Attribute that reflects what the end-user will see in the list, and a Value Attribute that represents the underlying value in the database row. In your JHeadstart application definition, a named domain defines a list of available choices that can either be a static set (e.g. Open, Pending, Closed) or a dynamic set based on a view object's query results. When you ran the New JHeadstart Application Definition Wizard earlier in the tutorial, the JHeadstart application generator automatically generated a number of dynamic domains to support the selection of foreign key values from dropdown lists wherever it noticed those foreign keys existed.

Since we introduced a new EmployeesAvailableToAssign view object instance to provide the list of available choices for the "Subordinates" shuttle above, the last two steps in configuring the shuttle require:

  • Defining a new dynamic domain for this data collection, and then
  • referencing that new domain in the Subordinate group's Domain for Unselected List in Shuttle property.

To accomplish this task, perform these steps:

6.5 Regenerate and Run the Application

We're done defining the new Employee wizard, so regenerate the application and run it. When generation finishes successfully, run the application again by clicking on the ViewController project in the application navigator and press F11.


NOTE:

The application generation confirmation dialog may say "JHeadstart Application Generator has finished successfully with warnings." You can click on the JHeadstart Application Generator tab in the JDeveloper Log Window to review the warnings. They are informational and recommend an additional best practice for create-only view objects that isn't necessary for this basic tutorial.


Clicking on the Employee Wizard tab in the browser, you'll see the first page of the wizard as shown in Figure 109 , ready to collect the information related to the Identification step of the process.

First Step in the Four-Step Wizard Layout
Figure 109: First Step in the Four-Step Wizard Layout

Clicking (Next) to proceed onto subsequent steps, you can enter the information for the Functional step in the process as shown in Figure 110 .

First Step in the Four-Step Wizard Layout
Figure 110: First Step in the Four-Step Wizard Layout

Clicking (Next) to enter the Financial information in step 3, and clicking (Next) again, you can see that the last step of the wizard is the Subordinates step that we configured to generate as a shuttle. As shown in Figure 111 , you can select a few subordinates, then click (Finish) to commit the transaction.

Shuttle Control to Assign Subordinates to a New Employee
Figure 111: Shuttle Control to Assign Subordinates to a New Employee

7 Using Stacked Tabs for Table Overflow Items

Another use for the item regions we saw above is to organize items into stacked tabs. In this section will configure two item regions for the Employees3 detail group of the top-level Departments group and drag and drop some of its items into these item regions, which we'll configure to generate as stacked tabs on the same page as the parent group. To accomplish this task, follow these steps:

8 Adding a Conditionally Dependent Field

The ADF Faces components that JHeadstart application generator uses for your web tier pages cleverly combine Asynchronous JavaScript, XML, and Dynamic HTML to deliver a much more interactive web client interface for your business applications. In ADF Faces, the feature is known as partial page rendering because it allows selective parts of a page to be re- rendered to reflect server-side updates to data, without having to refresh and redraw the entire page. This combination of web technologies for delivering more interactive clients is known more popularly by the acronym AJAX [ 12] . ADF Faces supports this powerful feature for any JavaServer Faces (JSF) page with no coding. JHeadstart automatically configures the necessary properties on the controls to enable a maximal use of this great feature. We've seen a few examples of this AJAX-style partial-page rendering in previous sections of the tutorial. Here we'll study a final example that involves using it to enable dynamically-changing, conditionally-dependent fields.

Sometimes, one field value (or its enabled status) might depend on another field. JHeadstart makes it simple to generate pages that support this kind of conditionally-dependent field. For example, imagine that the commission percentage of an employee only is relevant if they are an Account Manager. In this section we'll configure a simple example to implement the disabling of the CommissionPct item in the Employees group unless the value of the JobId is equal to ' AC_MGR'. To accomplish this task, follow these steps:

  • Conditionalize the Value of the Disabled Property Using an Expression

    In the JHeadstart Application Definition Editor, expand the top-level Employees group, its Items folder, and select the CommissionPct item. As shown in Figure 115 , set its Disabled? property to the expression value:

    #{$DEPENDS_ON_ITEM_VALUE$ != 'AC_MGR'}

    The token $DEPENDS_ON_ITEM_VALUE$ gets substituted by the JHeadstart application generator so that the expression ends up referencing the correct value of the item on which the current item depends. We'll setup this item dependency next...

  • Set the CommisionPct Item to Depend on the JobId Item

    Set the Depends on Item property of the CommissionPct item to JobId. After doing this, your application definition will look like Figure 115 .

    Using a Conditional Disabled Expression Referencing a Dependent Item
    Figure 115: Using a Conditional Disabled Expression Referencing a Dependent Item

After regeneration and running the application, in the Employees tab, if you use the Quick Search area to find all employees whose LastName starts with the letter H, and then drill down to the details, you can navigate between employees like Michael Hartstein and Shelly Higgins to notice that the CommissionPct field on the screen as disabled for Michael, as shown in Figure 116 , but enabled for Shelly (whose JobId = 'AC_MGR').

CommissionPct is Disabled for Employees Who Are Not Account Managers
Figure 116: CommissionPct is Disabled for Employees Who Are Not Account Managers

Perhaps even more interesting is the fact that the screen updates dynamically as you change the value of the dependent JobId field. For example, if you use the dropdown list to change the JobId of an employee who is currently not an account manager to have the new value of AC_MGR, you'll see that the CommissionPct field becomes enabled automatically, without refreshing the entire web page.

9 Generating a Graph and Summary Information

In this section we will add some Business Intelligence functionality to the top-level Jobs group and its Employees3 detail group. Assume an HR employee who needs to evaluate salary differences for employees with the same job. For this task it is convenient to see the average salary for a job, as well as a graph visualizing the differences in salary within a job. To add this functionality to our application, follow these steps:

10 Using "Deep Linking" to Support Targeted Hyperlinks

Sometimes you might want to allow a user to navigate to a page in your application to display or edit a particular row that they identify using an URL parameter. For example, for a page that edits jobs, you might want to allow a jobId URL parameter like this to indicate what job to display/edit:

http://yourserver.com/MyDemo/faces/pages/SelectJobs.jspx?jobId=AC_MGR

Since the page to which you allowing direct access like this might be "deep inside" your web application page hierarchy, this kind of direct link support is known commonly as "deep linking".

In this step, we will use JHeadstart's deep link support in combination with a custom generator template to generate the JobId in the Employees group table as a hyperlink that navigates to the "Job Edit" page querying the proper Job row in the process.

To accomplish this task, follow the steps in the sections below.

10.1 Configure the Job Group for Deep Linking

In the JHeadstart Application Definition Editor, start by enabling "Expert Mode" by clicking the "chess pawn" toolbar button ( ). It will toggle to a "chess king" icon ( ) to indicate you are in "Expert Mode".

Select the Jobs group and in the Deep Linking category and set its:

  • Type of Deep Linking property to Query By Key Value.
  • Deep Linking Key Expression property to the expression: #{param.jobId}

10.2 Changing JobId to a Hyperlink Using the JDeveloper Visual Editor

In this step, after moving the JobId back to the main table for the Employees group, we'll customize the generated page manually to show how this is possible. The simple result we want to achieve is to change how the JobId item in the Employees group appears to the end user, making it a clickable hyperlink instead of a dropdown list.

So, start by moving the JobId back to the main Employees table and regenerating the application by following these two steps:

  • Move the JobId Item Back to the Main Employees Table Layout

    In the JHeadstart Application Definition Editor, select the JobId item in the top-level Employees group and set its Display in Table Layout? to true and its Display in Table Overflow Area property to false. This will cause the JobId item to display again in the main table instead of in the overflow area.

  • Regenerate the Application, Without Running It Yet

    Run the JHeadstart application generator to generate the latest version of the application's ViewController artifacts from the JHeadstart application definition, however don't run the application yet since we're not done with this step.

    Click the Save All button in the JDeveloper main toolbar to save all the generated changes.

Now, we'll proceed to make some manual modification to the generated EmployeesTable.jspx page. Since JHeadstart generates pages that are the same as ones you could have created by hand using JDeveloper itself, after you have gotten the generated pages as close to your final requirements as possible, you can use the JDeveloper visual editor and other rapid application development facilities to tailor the generated result. Once you've customized a generated page you can either:

  • Change the corresponding group setting in the JHeadstart Application Definition Editor to avoid having the JHeadstart application generator ever regenerate the page, or as we'll see later in the tutorial,
  • "Teach" the JHeadstart application generator how to generate your customized output by creating and using generator templates.

To change the generated dropdown list for JobId to be a hyperlink, do the following:

10.3 Run the Application to Test the JobId Hyperlink

Without regenerating, just run the application to test the change we've prototyped in the EmployeesTable.jspx page. As shown in Figure 132 , the JobId attribute now displays as a hyperlink.

JobId Now Appears as a Hyperlink in the EmployeesTable Search Page
Figure 132: JobId Now Appears as a Hyperlink in the EmployeesTable Search Page

Clicking on a the hyperlink for the FI_ACCOUNT for employee Luis Popp jumps straight to the Edit Job page with that specific job selected for editing as shown in Figure 133 , illustrating the runtime use of the "deep linking" feature.

Clicking JobId CommandLink "Deep Links" to the Edit Job Page for that JobId
Figure 133: Clicking JobId CommandLink "Deep Links" to the Edit Job Page for that JobId

TIP:

If your version fails to work as explained, go back and make sure that you haven't mismatched the name of the Deep Linking Key Expression and the Name of the <f:param> element you added to the <af:commandLink> component. The key linking expression was #{param.jobId} and the name of the parameter needs to be exactly (case-sensitive!) jobId to match.


11 Preserving Customizations Using Generator Templates

Once you've prototyped a customization to a generate page, instead of disabling future generation of the corresponding JHeadstart group in the application definition, you can also "teach" the JHeadstart application generator how to generate your preferred layout in the future by creating a custom generator template. This enables you to have the JHeadstart application generator generate the page in a customized way going forward, allowing you to continue making iterative application definition changes to the corresponding group.

In this step we'll illustrate an example of this second, more powerful approach. We will create a new generator template based on the customization we made in the previous section to the JobId item's generated control in the EmployeesTable.jspx page.

11.1 Moving the Customization into a Generator Template

We will now move the customization of the JobId column to a custom template. We'll do this by creating a copy of the default template used to generate the JobId item and then applying our customizations to it. To perform this task, follow these steps:

11.2 Using the New Template for the JobId Column

Now that we've turned our prototyped change into a custom template, we just need to tell the JHeadstart application generator to use this custom template whenever it generates the JobId item in the Employees group.

Back in the JHeadstart Application Definition Editor, select the JobId item of the top-level Employees group.

As shown in Figure 136 , click the Templates tab and set the TABLE_DROP_DOWN_LIST property in the Table Items category to the relative path to the custom template: default/item/table/JobIdColumn.vm

Setting a Custom Template for Employees.JobId When Used as a Dropdown List in a Table
Figure 136: Setting a Custom Template for Employees.JobId When Used as a Dropdown List in a Table

11.3 Regenerate and Run the Application

Now you can rerun the JHeadstart application generator and run the application again. You'll see that manually-prototyped feature is now something you can regenerate automatically!


NOTE:

JHeadstart used the open-source Velocity [ 13] template engine. Every line generated into the .jspx pages comes from a velocity template. And for each of these templates you can define a custom replacement like we did for the JobId column. This allows you to make any layout change you want, and still keep your pages fully generatable. See the links to the JHeadstart Developer's Guide and JHeadstart web log in the "Related Documents" section at the end of the tutorial. These resources are great to learn other examples of this powerful technique.


12 Applying Custom Skins to Change Look and Feel

You have undoubtedly noticed that the ADF web application we've built in this tutorial has a consistent look and feel on all the pages. This consistency is an important ingredient in delivering the attractive and easy-to-use experience that all application developers want for their end users. You might have also noticed that the pages we've built resemble those in the self-service web applications of the Oracle e-Business Suite. By default, ADF Faces pages are configured to have this Oracle Browser Look and Feel [ 14] ...and with good reason. Over 4000 developers inside Oracle who implement and enhance the e-Business Suite use Oracle ADF to build these self-service web applications, the same key technologies we're using in this tutorial.

But if it's not your style to have your application look like the Oracle e-Business Suite, no worries. The ADF Faces technology supports changing the look and feel of all your pages in a consistent way by applying a skin [ 15] . As we'll see, applying a skin does not require any changes to the application pages that you've built. It's just a configuration setting.

ADF Faces comes with two built-in skins, oracle and minimal. The oracle skin is the default. The minimal skin provides an alternative look that is simpler and that tries to minimize the use of downloaded images.

To change the look and feel of our tutorial application...

  • Find the adf-faces-config.xml file under the WEB-INF directory of your ViewController project's Web Content folder.
  • Double-click the adf-faces-config.xml file in the application navigator to view it in the code editor.
  • Find the <skin-family> tag in this XML configuration file and notice that it looks like this:

    <adf-faces-config xmlns="http://xmlns.oracle.com/adf/view/faces/config">

      <skin-family>oracle</skin-family>

    </adf-faces-config>
  • To change to use the minimal look and feel, type over the oracle skin family name and make it say minimal instead, so that your adf-faces-config.xml file looks like this:

    <adf-faces-config xmlns="http://xmlns.oracle.com/adf/view/faces/config">

      <skin-family>minimal</skin-family>

    </adf-faces-config>
  • Then save the file

The first thing we notice is that, as shown in Figure 137 , the JDeveloper visual designer for the EmployeesTables.jspx page changes to show the page in the minimal look and feel. This underscores how the visual page designer really does offer a true "What You See Is What You Get" (WYSIWYG) environment.

Visual Designer Updates to Reflect Custom Skin
Figure 137: Visual Designer Updates to Reflect Custom Skin

By rerunning the application, as shown in Figure 138 you can experience the effect of changing to the minimal skin at runtime as well. All of our application's functionality works the same as it did before, but the look and feel has been consistently modified with one edit to a configuration file.

Tutorial Application Running with "Minimal" Skin
Figure 138: Tutorial Application Running with "Minimal" Skin

Keep in mind that if neither of the two built-in skins suits your fancy, you can also create your own custom ADF Faces skins. To more radically change the look and feel of your application, for example to seamlessly match the look and feel of an existing site, you can use ADF Faces skinning in combination with a set of custom generator templates.

13 Adding a Validation Rule and Customizing Error Reporting

In this section of the tutorial, we'll add some declarative validation logic to one of our business domain objects. This will illustrate how business logic and user interface are cleanly separated in an Oracle ADF application, as well as show how the errors are displayed by default to the end-user.

13.1 Defining Some Declarative Validation Rules

Using Oracle ADF our business validation logic is nicely encapsulated inside the entity objects that represent our business domain objects. You can capture a number of aspects of business domain validation declaratively. Here we'll illustrate two simple examples of enforcing that an attribute is mandatory, and that its value lie within a certain numerical range.

Finally, click (OK) to dismiss the Entity Object Editor.

13.2 Rerunning the Application to See Validation Rules in Action

At this point, let's re-run the application to see the effect of having added two simple validation rules. As we've done before, select the ViewController project in the Application Navigator and press F11 to run.

When the initial Employees tab appears, enter a LastName of King in the quick-search Filter By field and click (Go) to find the employees with a last name of King. Select the employee "Steven King" and click the (Details) button to edit the data.

First try blanking out the existing value of Salary and pressing the (Save) button. You'll see an error as shown in Figure 143 .

Mandatory Validation of Salary Now Automatically Enforced
Figure 143: Mandatory Validation of Salary Now Automatically Enforced

Next, try to enter a Salary value of 25001 and click (Save) again. Since this value is outside of the valid range, as shown in Figure 144 we see that the end-user is shown the custom error message we provided when we added the range validation rule on the Employee entity object's Salary attribute.

Validation Errors Presented Automatically to User
Figure 144: Validation Errors Presented Automatically to User

Under the covers, what makes this work is the automatic coordination that's occurring between the front-end ADF Faces components and the view objects in the back-end ADF application module. Those view objects, in turn, coordinate with your underlying busing domain layer — realized as a set of ADF entity objects — which encapsulate the business validation. Any errors raised by the business layer automatically "bubble up" back to the user interface and are presented to the user. Again — as we've seen throughout this tutorial — all of this infrastructure is provided for you by the Oracle ADF framework so you don't have to write the "application plumbing" code.

13.3 Declaratively Customizing the Way Errors are Reported

If you take a closer look at the error message displayed in Figure 144 , you may have noticed that it displayed an odd-looking error code prefix of " JBO-Salary_Rule_0" before the actual error message. This is not too user-friendly, so let's see what we can do about that.

When generating your web application artifacts, JHeadstart makes clever use of the JavaServer Faces managed bean facility. This built-in JSF feature allows developers to use simple XML files to declaratively configure any Java beans their application may need to reference, and also allows them to declaratively initialize any of the properties in those beans to a fixed or dynamic value.

The JSF configuration file that contains the bean definition related to how errors are reported is called the JhsCommon-beans.xml file. As shown in Figure 145 , if you:

  • Double-click on this XML file in the Application Navigator,
  • Visit the Overview tab in the editor
  • Select the Managed Beans section and specifically the errorReportingUtils managed bean in the list
  • Expand its Managed Properties section to see its declaratively configured properties, and
  • Select the showJBOErrorCode property,

you can change its value from true to false.

Changing Value of a Managed Bean Related to Error Reporting
Figure 145: Changing Value of a Managed Bean Related to Error Reporting

Doing this will suppress the display of the JBO-XXXXXX error code prefix in errors messages that are displayed to the user.

After saving your changes, just rerun the application to immediately see the effect of changing this declarative error reporting setting. If you repeat the steps we tried above to set a salary of 25001 for Steven King, you'll now see the more friendly error message shown in Figure 146 .

Validation Errors Presented Without the JBO-XXXX Prefix
Figure 146: Validation Errors Presented Without the JBO-XXXX Prefix

NOTE:

The manual change you made to the JhsCommon-Beans.xml file would be lost the next time you generate. Since the JhsCommon-Beans.xml file is also generated from Velocity templates, to make the change permanent you need only modify the default/misc/facesConfig/jhsCommonBeans.vm template file for your application.


14 Conclusion

In this end-to-end tutorial we've experienced first-hand how Oracle JHeadstart 10g turbo-charges developer productivity for Oracle ADF-based web applications. Using a JDeveloper wizard to generate the back-end ADF Business Components that handle database interaction, and using the declarative JHeadstart Application Generator to iteratively generate the entire web front end, we built an attractive, consistent, interactive, and skinnable web application with browse, search, insert, update, and delete functionality against six related database tables from the Oracle HR sample schema. The application featured single- and multi-row editing, page-by-page scrolling, master/detail handling, dropdown lists, a pop-up LOV, a wizard, a shuttle picker, a tree control, and more. We saw an example of how the JHeadstart Application Generator can be customized using a powerful templating mechanism to locally (or globally) change the basic structure of the pages it generates. We also saw that since JHeadstart is generating standard ADF artifacts and metadata, we can use the standard tools that JDeveloper provides to customize the generated pages where needed.


NOTE:

For customers working today with Oracle Designer [ 16] — accustomed to the productivity they gain from model-driven, repository-based generation of complete applications — JHeadstart offers the one-two productivity "punch" that combines an enhanced generation of ADF Business Components from a Designer module component, as well as a fully-working JSF web application generated on top of them. This means that you can generate both the back-end and the front-end of your web application off the Designer repository using JHeadstart. For more information, see the JHeadstart Developer's Guide [ 10] .


14.1 No Generated Java Code For Any Functionality in the Entire Tutorial!

We claimed at the outset that no Java code was required to build the demo, and in fact none of the steps we followed above required our writing any Java code. But you must be thinking, "Surely JHeadstart or JDeveloper itself must have generated some Java code to make all of that functionality work, right?" You might be surprised.

After first deleting any compiled output from our project by selecting the ViewController project and choosing Run | Clean ViewController... , we can simply go to a command shell and try to count the number of Java source code files that were generated during the course of this tutorial.

Figure 147 shows the result of opening a command shell, changing directories to the C:\MyDemo root directory where we've been working on the tutorial, and doing a recursive directory search for any *.java files. The executive summary: 1 File(s) Found. And we'll see in the next section why that single file does not really even count as Java code, since it is a file that just contains translatable error messages.

While a search for *.jspx files, *.properties, or *.xml files will produce a number of hits — other than the single message bundle file — no Java code was needed to build this demo. All of the base functionality to support the features we have employed lives in the base ADF framework library components and some standard framework extension libraries that JHeadstart provides to complement its declarative application generation.

No Written or Generated Java Code Required For Functionality of This Tutorial
Figure 147: No Written or Generated Java Code Required For Functionality of This Tutorial

This does not imply that building your own business applications with Oracle ADF and JHeadstart 10g Application Generator won't require any Java code. They undoubtedly will. However, what we're illustrating here in the tutorial is that Java code is not required for a huge amount of the basic functionality every business application needs. The code you'll end up writing will be code that is specific to your business application functionality, and not to making the basics of screen management, data management, or business rules enforcement work correctly.

14.2 Simplified Multi-Lingual Applications with Message Files

A Java message bundle file is the standard way a Java component — like the Employees entity object in your Model project — can save its translatable string resources. Oracle ADF and JHeadstart 10g use a combination of *.properties files and Java message bundles to save translatable string resources for your web tier in the ViewController project and business service tier in your Model project. If we look a little more closely at this lone Java file ( EmployeesImplMsgBundle.java). you'll see that there's no real code in there, just the error message for the Employees entity object's range validation rule on the Salary attribute that we added above:

sMessageStrings = {
      {"Salary_Rule_0", "Salary must be between 1 and 25000"}
    };

Using a combination of *.properties files and Java message bundles like this, the applications you build with Oracle ADF and Oracle JHeadstart 10g for ADF are setup out of the box to use the best-practice techniques to make building even multi-lingual applications easy!

14.3 J2EE Applications Give Choice of Application Server

Another interesting point to note in closing is that while we've been testing the tutorial application on the embedded Oracle Containers for J2EE (OC4J) server inside JDeveloper, the same ADF-based web application can run inside any J2EE application server. As shown in Figure 148 , in addition to support Oracle's J2EE server, JDeveloper offers automated installation of the ADF Runtime libraries on a number of other popular J2EE servers as well. For servers not included in this automated list, JDeveloper can prepare a standard J2EE EAR file to be deployed using the deployment tool provided by that application server.

ADF Runtime Installer Automated Installation Options
Figure 148: ADF Runtime Installer Automated Installation Options

14.4 Useful Links for Additional Information on JHeadstart, JDeveloper, and Oracle ADF

So, in hoping that this tutorial has been both educational and eye-opening for you, we close with a few links to where you can find additional information, samples, and tutorials about JDeveloper 10g, Oracle ADF, and Oracle JHeadstart.

If you have any questions on JHeadstart that are not answered with the above links, you can post them on the OTN JHeadstart Discussion Forum [ 17] . In addition, if you have any questions on Oracle ADF in general, you can post them to the OTN JDeveloper Discussion Forum [ 25] on OTN.

14.5 Now You Can Try On Your Own Schema

At this point you are ready to try Oracle JHeadstart Evaluation Version on your own database schema. Keep in mind that the evaluation version of JHeadstart is fully-functional and has no time-limit, however it does limit you to working with a maximum of only ten (10) different view objects in your workspace. If you try to run the JHeadstart application generator in a workspace with more than ten view objects, you'll see the JAG error:

JAG-00130 [ JHeadstart ] You can have only 10 ViewObjects in your workspace when using the JHeadstart Evaluation Version.

This lets you experiment with every feature of the powerful JHeadstart product on a selected group of your real-world application tables to demonstrate to yourself, your colleagues, and your management the boost in development productivity it can provide you. If you like what you see, you can find information on getting the full JHeadstart product on the JHeadstart Product Center on OTN [ 4] .

Related Documents

  1. Building Enterprise JSF Applications with Oracle JHeadstart for ADF (10.1.3) [PDF] [ http://otn.oracle.com/products/jdev/tips/muench/jhstutorial/jhs-step-by-step.pdf]

  2. Completed Version of the Tutorial [ http://otn.oracle.com/products/jdev/tips/muench/jhstutorial/MyDemo.zip]

  3. ADF Business Components Design Pattern Catalog [ http://www.oracle.com/technology/products/jdev/tips/muench/designpatterns/index.html]

  4. JHeadstart Product Center [ http://www.oracle.com/technology/consulting/9iServices/JHeadstart.html]

  5. Tutorial Files for Offline Viewing and Database Setup [ http://otn.oracle.com/products/jdev/tips/muench/jhstutorial/jhs-step-by-step.zip]

  6. JDeveloper Downloads [ http://www.oracle.com/technology/software/products/jdev/index.html]

  7. Installing the Sample Schemas and Establishing a Database Connection [ http://www.oracle.com/technology/obe/obe_as_1012/j2ee/common/obeconnection.htm]

  8. ADF Developer's Guide for Forms/4GL Developers [ http://www.oracle.com/technology/documentation/jdev/b25947_01/index.html]

  9. Oracle Magazine DEVELOPER: Frameworks [ http://www.oracle.com/technology/products/jdev/tips/muench/oramag/index.html]

  10. JHeadstart Developer's Guide [ http://download.oracle.com/consulting/jhsdevguide1013.pdf]

  11. 7.3.1.4 Removing Unnecessary Key Attributes from Reference Entity Usages [ http://download.oracle.com/docs/html/B25947_01/bcvoeo003.htm#sthref527]

  12. Asynchronous JavaScript and XML (AJAX) [ http://en.wikipedia.org/wiki/AJAX]

  13. Velocity [ http://jakarta.apache.org/velocity/]

  14. Oracle Browser Look and Feel [ http://www.oracle.com/technology/tech/blaf/index.html]

  15. Wikipedia Definition of 'Skin' [ http://en.wikipedia.org/wiki/Skin_(computing)]

  16. Oracle Designer Product Center on OTN [ http://www.oracle.com/technology/products/designer/index.html]

  17. OTN JHeadstart Discussion Forum [ http://forums.oracle.com/forums/forum.jsp?forum=38]

  18. JHeadstart Blog [ http://blogs.oracle.com/jheadstart/]

  19. JDeveloper Product Center on OTN [ http://www.oracle.com/technology/products/jdev/index.html]

  20. ADF Learning Center on OTN [ http://www.oracle.com/technology/products/adf/learnadf.html]

  21. ADF and J2EE for Forms and Designer Developers [ http://otn.oracle.com/formsdesignerj2ee]

  22. Dive into ADF Blog [ http://radio.weblogs.com/0118231/]

  23. Oracle Technology Network [ http://otn.oracle.com]

  24. Oracle Community Weblogs (Oracle Blogs) [ http://blogs.oracle.com]

  25. OTN JDeveloper Discussion Forum [ http://forums.oracle.com/forums/forum.jsp?forum=83]

false ,,,,,,,,,,,,,,,