DOWNLOAD Oracle JDeveloper 10g Sample code

TAGS jdeveloper, adf, All

Creating a Databound List of Values in Oracle JDeveloper 10.1.3 10g

Learn how to implement list of values (LOV) functionality for ADF-based applications in JDeveloper 10g (10.1.3).

Published January 2007

Oracle JDeveloper 10g provides all the necessary infrastructure to create the list of values (LOV) elements in Oracle Application Development Framework (ADF) applications. LOV elements are used either when a selected list is too long and can’t be implemented as a drop-down list a Search Form has to be used to select a value.

Typical LOV functionality (as it is used in Oracle Forms and Oracle ERP Self-Service) includes the following steps:

1. Open a search form in the Dialog Page.
2. Select values in the Search Form.
3. Return selected values to the Originating Page.

In this article you will learn how to implement LOV functionality in JDeveloper 10g. The included sample JSF ADF BC ListOfValues application (download) uses the following ADF Business Components as the business service (Model project):

• EmployeesEntity, EmployeesView to expose record collections from the SCOTT schema EMPLOYEES table
• Read-only JobsView (based on the JOBS table) to display Job details in the Dialog Page (before example running, you should first run a JobsTable.sql file to create the JOBS table)

Figure 1: The ListOfValues application structure

The ViewController project contains four main files implementing LOV: Employees.jspx and Jobs.jspx—the Originating Page (Figure 2) and the Dialog Page (Figure 3), respectively—and their managed beans EmpBean.java and JobBean.java.

Figure 2: Employees.jspx (the Originating Page) with the af:selectInputText LOV field

Figure 3: Jobs.jspx (the Dialog Page)

The LOV in the sample application updates both the Job and Sal fields of Employees.jspx with values selected in the Jobs.jspx.

The purpose of JobsBean.java is to create and return some Java object (hereinafter <ReturnedObject>) from the Jobs.jspx to Employees.jspx.

The purpose of EmpBean.java is to get the Salary value from the <ReturnedObject> and to update the Sal field on Employees.jspx.

If you want LOV to update the Job field only on the Employees.jspx, EmpBean.java is redundant.

The Job field is another added value of the af:selectInputText element: its implementation class updates the Job value on the Employees.jspx using the value provided by the <ReturnedObject>.toString() method.

The implementation of JobsBean.java and EmpBean.java classes is discussed later in this article.

Downloading and Opening the LOV Application

• Download the example application and unzip the files to JDeveloper 10g working directory: $JDEV_HOME\jdev\mywork
• Start JDeveloper 10g and open the $JDEV_HOME\jdev\mywork\ListOfValues\ListOfValues.jws file.
• Specify the database connection for the Model project (Model ->Project Properties -> BusinessComponents) to the SCOTT schema.
• Log in to the database as SCOTT user and run the file JobsTable.sql to create the JOBS table.
• Rebuild the ListOfValues application. The application is ready for running.
• Copy ADF Faces archives $JDEV_HOME\lib\adf-faces-impl.jar and $JDEV_HOME\jsf-ri\jsf-impl.jar to $JDEV_HOME\jdev\mywork\ListOfValues\ViewController\public_html\WEB-INF\lib directory.

LOV Implementation in the Originating Page (Employees.jspx)

Suppose you create an Employees.jspx page and drag-and-drop EmployeesView to the page as an ADF Table (Figure 4).

Figure 4: Employees.jspx after drag-and-drop of EmployeesView as an ADF table

LOV implementation in the Originating Page is similar to the process of the Dialog Page launching. It is even simpler; you should:

1. Replace the Job column af:inputText tag with af:selectInputText (the af:selectInputText tag is a text field plus flashlight icon to support launching a dialog box, as shown in Figure 2).
2. Set af:selectInputText properties action, windowHeight, windowWidth.

If you want to update the Sal field (in addition to Job), you will have to

3. Define the ReturnListener property of the af:selectInputText field.
4. Create and implement the managed bean EmpBean.java.
5. Define the binding property of the Sal field .

To perform Steps 1 and 2, open the file Employees.jspx in the source tab and replace af:inputText in the Job column by the af:selectInputText element:

<af:column headerText="#{bindings.EmployeesView.labels.Job}  
sortProperty="Job" sortable="false">
        <af:inputText value="#{row.Job}" simple="true"
           required="#{bindings.EmployeesView.attrDefs.Job.mandatory}"
           columns="#{bindings.EmployeesView.attrHints.Job.displayWidth}"/>
        </af:column>

<af:column headerText="#{bindings.EmployeesView.labels.Job}  
sortProperty="Job" sortable="false">
<af:selectInputText value="#{row.Job}" simple="true"
           required="#{bindings.EmployeesView.attrDefs.Job.mandatory}"
           columns="#{bindings.EmployeesView.attrHints.Job.displayWidth} 
         action="dialog:openJobSearchDialogPage"
 windowHeight="500" 
    WindowWidth="400" />
</af:column>

The action property defines the JSF Navigation Path to the Dialog Page. To open the Dialog Page as a pop-up page, the action value must start with the dialog: prefix. (This value will be used in “Definition of the JSF Navigation Case from the Originating to the Dialog Page.”) windowHeight and windowWidth properties define the Dialog Page size.

To perform Steps 3 and 4, define the ReturnListener property of af:selectInputText as #{emp_bean.handleReturn}.

Figure 5: The ReturnListener property of the af:selectInputText field

To do it, use the ReturnListener (Figure 6), Create Managed Bean (Figure 7), and Create Method (Figure 8) dialog boxes.

Figure 6: The ReturnListener dialog box

Figure 7: The Create Managed Bean dialog box

Figure 8: The Create Method dialog box

It creates the EmpBean.java file with an “empty” handleReturn() method:

public void handleReturn(ReturnEvent returnEvent) {
    // Add event code here...
} 

(The implementation code of the handleReturn() method will be provided later.)

To perform Step 5, define the Binding property of Sal af:inputText as #{emp_bean.salInputText}.

Figure 9: The Binding property of the Sal field

To do it, use the Binding (Figure 10) and Create Property dialog boxes (Figure 11).

Figure 10: Binding dialog box

Figure 11: Create Property dialog box

Step 5 adds to the managed bean emp_bean reference salInputText of Sal together with its accessors:

public class EmpBean {
    private CoreInputText salInputText;
........
    public void setSalInputText(CoreInputText salInputText) {
        this.salInputText = salInputText;
    }
    public CoreInputText getSalInputText() {
        return salInputText;
    }
........}

LOV Implementation in the Dialog Page (Jobs.jspx)

ADF Developer’s Guide for Java Developers 11.3.1.3 says that the Dialog Page “ …is just like any other JSF page, with one exception. In a Dialog Page you must provide a way to tell ADF Faces when the dialog process finishes, that is when the user dismisses the dialog. ” At this very moment, we will return the selected values (Job Title and Salary) to the Originating Page.

It is important to note that the Dialog Page can be created in many different ways, depending on concrete requirements. (See ADF Developer’s Guide for Java Developers, 10.8, “ Creating Search Pages” and Creating Three Simple Search Pages with ADF Business Components and JSF blog).

The Jobs.jspx in the ListOfValues application contains Search Criteria and Results regions, as illustrated in Figure 3. It was created according to the first screencast “Part 1: Web-Style Search Form” from the above blog.

Select and Cancel buttons were added to the Jobs.jspx Dialog Page to return selected JobTitle and Salary values and/or dismiss this page afterwards. Thus the LOV implementation in the Dialog Page comes to implementation of the Cancel and Select buttons.

Implementing the Cancel button. The Cancel button should return a null object to Employees.jspx and dismiss Jobs.jspx. Consequently you should define empty ReturnListener for the Cancel button. It can be done either programmatically or declaratively, as described in ADF Developer’s Guide for Java Developers.

To do it declaratively, open the Jobs.jspx file and add to the Cancel button empty ReturnActionListener and immediate attribute.(immediate=”true” means that the button default ActionListener should be executed without data validation.

<af:commandButton text="Cancel" /> 

<af:commandButton text="Cancel" immediate="true">
  <af:returnActionListener/>
</af:commandButton> 

Implementation of the Select button. The Select button returns the selected JobTitle and Salary values to Employees.jpsx and dismisses the Jobs.jspx page. Unlike the Cancel button, the Select button LOV implementation can be done programmatically only. It is implemented in button ActionListener method.

LOV implementation for the Select button consists of two steps:

1. Definition of the ActionListener property of the Select button
2. Definition of the Binding property of the Results Table

Definition of the ActionListener property of the Select button. Define the ActionListener property of the Select button as #{job_bean.returnObject} (Figure 12).

Figure 12: The ActionListener property of the Select button

To do it, use the ActionListener (Figure 13), Create Managed Bean (Figure 14), and Create Method (Figure 15) dialog boxes.

Figure 13: The ActionListener dialog box

Figure 14: The Create Managed Bean dialog box

Figure 15: The Create Method dialog box

This step creates the JobBean.java file with the “empty” method returnObject():

    public void returnObject(ActionEvent actionEvent) {
        // Add event code here...
    }

(The implementation code of the returnObject() method will be provided later .)

Definition of the Binding property of the Results Table. To return the JobTitle and Salary values of the selected row, we need to create a reference to the Results Table in the JobBean.java file.

Define the Binding property of the Results Table as #{job_bean.jobResultsTable} (Figure 16).

Figure 16: The Binding property of the Results Table

To do it, use the Binding (Figure 17) and Create Property (Figure 18) dialog boxes .

Figure 17: Binding dialog box

Figure 18: Create Property dialog box

This step adds to the JobBean.java file the reference jobResultsTable to the Results Table together with its accessors:

public class JobBean {
    private CoreTable jobResultsTable;
    ......... 
    public void setJobResultsTable(CoreTable jobResultsTable) {
        this.jobResultsTable = jobResultsTable;
    }
    public CoreTable getJobResultsTable() {
        return jobResultsTable;
    }
.........
}

LOV Implementation in JobBean.java

Now, after the modification of the Employees.jspx and Jobs.jspx pages and creation of managed beans files (EmpBean.java and JobBean.java, respectively), we can start the implementation of LOV functionality in these managed bean files.

The role of the JobBean.java file is to return the <ReturnedObject> to the Employees.jspx page. This <ReturnedObject> should have access to the Salary value of the selected row. Besides it its toString() method should return the JobTitle value of the selected row. As mentioned previously, the implementation class of the af:selectInputText tag automatically updates the Job field of the Employees.jspx with a value provided by the <ReturnedObject>.toString() method.

The code of the JobBean.java file, under these conditions, is as follows:

Explanation of the method code:

• Lines 12 to 23 are accessors to the JobTitle and Salary values. These lines were added to the JobBean.java file manually.
• Lines 24 to 29 are accessors to the JobResultTable. JDeveloper created them during the definition of the Binding property of the ResultsTable.
• Lines 30 to 37 are the returnObject() method. JDeveloper created the empty method during the definition of the ActionListener property of the Select button.
• Lines 31 to 32 get selectedRowData() of the ResultsTable, using the table’s binding property.
• Lines 35 to 36 return null to the Originating Page if no row was selected in the ResultsTable.
• Lines 39 to 42 get the JobTitle and Salary values from the selected row of the ResultsTable and save it in an instance.
• Line 44 returns the JobBean instance to the Originating Page. We decided that the <ReturnedObject> could be JobBean itself. Doing so, we avoid creating and instantiating an additional Java object.
• Lines 46 to 48 toString() method of JobBean (<ReturnedObject>). As mentioned previously, this method must return JobTitle. The implementation class of the af:selectInputText tag uses it to update the Job field of Employees.jspx.

LOV Implementation in EmpBean.java

EmpBean.java should get the Salary value from this <ReturnedObject> and update the Sal field of Employees.jspx. The code of the EmpBean.java file, under these conditions, is as follows:

Explanation of the method code:

• Lines 9 to 14 are accessors to the Sal field of Employees.jspx. JDeveloper created them during the definition of the Binding property of the Sal field.
• Lines 15 to 23 are the handleReturn() method. JDeveloper created the empty method during the definition of the ReturnListener property of the af:selectInputText Job field.
• Line 16 accesses the <ReturnedObject> from the returnEvent and casts it to the JobBean class (see also lines 43 to 44 of the JobBean.java).
• Line 17 breaks the method if the <ReturnedObject> jobBean is null.
• Line 18 gets the selected Salary value from the JobBean object.
• Line 19 erases any submitted value in the salInputText component bound to the Sal field.
• Line 20 sets the Salary value in the Sal field of Employees.jspx.
• Line 21 gets the current instance of AdfFacesContext.
• Line 22 registers the salInputText component as a partial target, because only components registered as partial targets are re-rendered.

Definition of the JSF Navigation Case from the Originating to the Dialog Page

To launch the Jobs.jspx page from Employees.jspx, create the JSF Navigation Case in the JSF Navigation Diagram.

• Double-click the faces-config.xml configuration file, and click the Diagram tab.
• Drag-and-drop Employees.jspx and Jobs.jspx onto the Diagram window.
• Define the JSF Navigation Case from the Employees.jspx to Jobs.jspx files: the success text appears above the arrow.
• Replace the success text with dialog:openJobSearchDialogPage.

This value must be the same as the action property of the af:selectInputText field.

Figure 19: JSF Navigation Diagram

Running the LOV Application

• Open and rebuild the LOV application in JDeveloper 10g as described previously.
• Run the Originating Page Employees.jspx (Figure 20).

Figure 20: Employees.jspx with original data

• Press the flashlight icon to launch the Jobs.jspx Dialog Page (Figure 21).

Figure 21: Jobs.jspx

• Enter values A% and >2000 in the Search Criteria fields JobTitle and Salary. Press the Execute button. The Results Table is updated (Figure 22).

Figure 22: Jobs.jspx matching Search Criteria

• Select the second row, and click the Select button. Jobs.jspx is dismissed. Employees.jspx is displayed back: the Job and Sal fields are updated with values “ACCOUNTANT” and “2500” selected in the Jobs.jspx Dialog Page (Figure 23).

Figure 23: Employees.jspx—the Job and Sal fields are updated with the values selected in Jobs.jspx

Conclusion

This document has explained how to implement LOV functionality in ADF JSF applications. It can be easily done using both the af:selectInputText tag and the built-in support for pop-up dialog boxes in ADF JSF.Table 1 summarizes all the steps of LOV implementation described in this document.

Table 1. LOV Implementation Actions

*This step is optional. It must be done to update the Sal field with the value returned from Jobs.jspx.

For further information, refer to the tutorials, sample applications, and ADF Developer’s Guides on the JDeveloper page on Oracle Technology Network.