7 Creating a Master-Detail Application Using Oracle ADF

Oracle ADF Business Components

Oracle ADF Business Components is Java EE-compliant technology for developing business services for database-centric, enterprise Java EE applications. Oracle ADF Business Components simplifies building business services for developers familiar with 4GL tools like Oracle Forms.

Oracle ADF Business Components technology:

• Automatically handles object-relational mappings and persistence for instances of its own library classes

• Allows you to make complex requests for data retrieval using SQL

• Automatically handles transaction management

• Provides a framework for implementing complex business logic

• Automatically implements many Java EE design patterns

• Has a powerful caching and data passivation system for increasing the performance and scalability of applications

All of this functionality is fully customizable. To create the ADF middle-tier for the application created in the book, you create ADF Business Components from database tables.

Oracle ADF Faces

Oracle ADF Faces is based on the JavaServer Faces (JSF) JSR 127 specification. Oracle ADF Faces components are used in the user interfaces of the application. These components can be used in any IDE that supports JSF.

You can use Oracle ADF Faces to determine a consistent look and feel for your application. This allows you to focus on user interface interaction rather than look and feel compliance. ADF Faces components also support multi–language and translation implementation as well as accessibility features.

JDeveloper provides several design tools, wizards, special dialogs, and property editors that help you insert and use ADF Faces components in your pages. For example, the Visual Editor lets you design user interfaces by dragging and dropping components from the Component Palette. If you are familiar with XML or JSP/HTML coding, you can also edit the source of the page files to insert ADF Faces component tags.

ADF Data Controls

Oracle ADF data controls permit the application client to access business services defined by the model object layer. Business services can be any collection, value, or action that your model project defines. At runtime, the databound UI components can access the business services defined by the business services.

If you use Oracle ADF Business Components as your business service technology, your data model components will be exposed in the model layer as Oracle ADF data controls. In the sample application, it is not necessary to create data controls for the Oracle ADF Business Components you create, because they already implement the data control interfaces for you.

Creating a Project for the Application UI

To create the application UI, you define a project called view as follows:

1. In the Application Navigator, select the AnyCo_ADF_MD application and from the File menu, select New to display the New Gallery. From the General category, select Empty Project.

2. In the Create Project dialog box, enter view as the Name of the new project, and click OK.

Creating a JSP to Display Employee Details

Using the following instructions, you create a page called employees.jsp, which will be used to allow users to browse through a coordinated set of master-detail pages of departments and employees.

1. In the Application Navigator, select the view project. Right-click the project and select New to display the New Gallery.

2. In the New Gallery, expand the Web Tier category and select JSF. In the Item list, select JSF JSP and click OK.

3. On the Create JSF JSP – Welcome screen, click Next.

4. On the Web Application screen, accept the default and click Next.

5. On the JSP File screen, enter employees.jsp as the File Name, and ensure that JSP Page (*.jsp) is selected for the page type. Click Next.

6. On the Component Binding screen, ensure that Do Not Automatically Expose UI Components in a Managed Bean is selected. Click Next.

7. On the Tag Libraries screen, if they are not already included, add ADF Faces Components and ADF Faces HTML to Selected Libraries on the right-hand side. The JSF Core and JSF HTML tag libraries should also be listed as Selected Libraries on the right-hand side. This is shown in Figure 7-4.

   Figure 7-4 Selecting Libraries for the JSF JSP

   
   Description of "Figure 7-4 Selecting Libraries for the JSF JSP"
   
   

8. Click Finish.

The new empty employees.jsp is now displayed in the JSP/HTML Visual Editor, ready for you to start designing the page.

Defining the Page Layout and Heading

In these steps, you add items to the page to define the page layout. As in earlier chapters, you use the Component Palette to drop tags onto your page. For this page, you use the ADF Faces PanelPage component.

1. If the Component Palette is not displayed, use the View menu to display it. Select the ADF Faces Core tab of components. Drag and drop the PanelPage component on the blank page. The ADF Faces Core page of the Component Palette is shown in Figure 7-5.

   Figure 7-5 ADF Faces Core Component Palette

   
   Description of "Figure 7-5 ADF Faces Core Component Palette"
   
   

   After dropping it, you should see a dark blue line with the text Title 1, as shown in Figure 7-6.

   Figure 7-6 ADF Faces PanelPage Component

   
   Description of "Figure 7-6 ADF Faces PanelPage Component"
   
   

2. On the page, click on the PanelPage component and in the Property Inspector, change the value of Title field from Title 1 to Browse Employees, then press Enter. The title change is now reflected in the page in the Visual Editor.

3. In this step, you add another ADF Faces component onto the page to serve as the page title, by dragging a component into the branding section of the PanelPage. From ADF Faces Core page of the Component Palette, drag an OutputText component and drop it into the branding facet, that is, the dotted line square box with title branding in the upper left corner of the page.

4. The new OutputText is now displayed with a default value of outputText1. Change this to read AnyCo Corporation by changing the value of OutputText in the Property Inspector.

5. Now change the look and feel of the text by changing the StyleClass property of the OutputText to have the value AFHeaderLevelOne. This is a style which is defined by ADF Faces.

   Once changed, the text should appear larger and blue in the Visual Editor. Figure 7-7 shows the page in the Visual Editor after these steps.

   Figure 7-7 PanelPage Component with Added Text

   
   Description of "Figure 7-7 PanelPage Component with Added Text"
   
   

Displaying Master Data on a JSP Page

In these steps you will add items to the page to allow users to browse departments and their employees. In these steps you use the Data Control Palette, which by default is on the right of the JDeveloper display, alongside the Component Palette. The Data Control Palette allows you to drop data objects called ADF Data Controls onto your pages.

The first stage is to add a read-only form which will display the departments along with navigation buttons to step through the different departments and their related employees. To do this, you drag onto the page one of the data controls you created in the model project.

1. Select the Data Control Palette, and expand the AnyCoAppModule node. Figure 7-8 shows the Data Control Palette with the AnyCoAppModule expanded.

   Figure 7-8 Data Control Palette

   
   Description of "Figure 7-8 Data Control Palette"
   
   

2. In the Data Control Palette, select the DepartmentsView1 node and drag it onto the middle of the page just beneath the Browse Employees text.

3. As the drop occurs, a popup menu is displayed. Select Create, Forms, then ADF read-only form.

4. In the Edit Form Fields dialog, select Include Navigation Controls and click OK. This is shown in Figure 7-9.

   Figure 7-9 Adding Form Fields

   
   Description of "Figure 7-9 Adding Form Fields"
   
   

The Visual Editor now displays the read-only form with navigation buttons on the page. If the form does not appear, click the refresh button. The values of the form fields are provided by using expression language such as #{...}. This is how JSF identifies application data that is to be rendered on the page.

Figure 7-10 shows what the page looks like in the Visual Editor after these steps.

Figure 7-10 Form Fields in Visual Editor

Description of "Figure 7-10 Form Fields in Visual Editor"

Displaying Detail Data for Master Records

In these steps, you will first add a horizontal separator to the page, to separate the department data from the detail employee data. Then, to display the detail employee data for each master department, you use another of the data controls created from the Business Components you created in the model project. You choose the data control that links employee data to a particular master department. You display the employee data below the ObjectSeparator.

1. To add a separator to the page, from the ADF Faces Core page of the Component Palette drag an ObjectSeparator component and place it underneath the form in the Visual Editor. A dotted horizontal line is displayed beneath the form.

2. In the Data Control Palette, expand the DepartmentsView1 node.

   In addition to the fields of the departments table, there is also a child EmployeesView3 node. This node represents the detailed or set of employees restricted by its foreign key to the departments table.

3. Drag and drop the EmployeesView3 node onto the page beneath the dotted horizontal line (ObjectSeparator).

   As you hover the mouse before dropping, the Visual Editor and the Structure window on the lower left indicate where the drop will occur. Adjust the drop position in the Structure window so that it is after the af:objectSeparator as shown in Figure 7-11.

   Figure 7-11 Structure Window Showing Dropped Position

   
   Description of "Figure 7-11 Structure Window Showing Dropped Position"
   
   

4. As the drop is finished, a shortcut menu is displayed. Select Create, then Table, and ADF Read-only Table.

5. In the Edit Table Columns dialog, select Enable selection and Enable sorting.

   Before clicking OK, delete the three columns: DepartmentId, ManagerId, and CommissionPct. For each of these rows in turn, select the row, then click Delete.

   The Edit Table Columns dialog box is shown in Figure 7-12.

   Figure 7-12 Editing Table Columns

   
   Description of "Figure 7-12 Editing Table Columns"
   
   

   Then click OK to generate the table.

6. Save your work.

You should now see both the master form and detail table in the Visual Editor as in Figure 7-13.

Figure 7-13 Master-Detail View in Visual Editor

Description of "Figure 7-13 Master-Detail View in Visual Editor"

Testing the Application

After adding the departments and employees to the page is a good stage to test the application so far. To test the application:

1. In the Application Navigator, right-click the page employees.jsp and select Run. This will start up the application locally by using the embedded OC4J server in JDeveloper. When the application has started, the master-detail employees page is displayed in a browser.

2. To test the master-detail coordination, click on the navigation buttons in the departments form (Next, Previous, First, Last). Notice as you click on the navigation buttons, that the related employees are displayed in the table below.

   The page when viewed in a browser is similar to that shown in Figure 7-14.

   Figure 7-14 Employee Data Viewed in a Browser

   
   Description of "Figure 7-14 Employee Data Viewed in a Browser"
   
   

3. To conclude the test, shutdown the server. To do this, in JDeveloper, right-click in the log window titled Running: Embedded OC4J Server – Log, and select Terminate.

Creating a Page Using a JSF Navigation Diagram

To allow users to edit employee data, you will create a new page, edit.jsp. Onto this page you will drop an ADF input form from Data Control Palette.

In these steps, instead of creating a new page directly using the JSF JSP wizard, you will create it from the JSF navigation diagram. In later steps, you will also define the navigation between the pages visually on the diagram.

1. To open the JSF navigation diagram for the application, in the Application Navigator, right-click the view project and select Open JSF Navigation.

   A blank navigation diagram is displayed.

2. To start defining the navigation rules, drag the existing employees.jsp page from the Application Navigator onto the blank diagram.

   A page icon is displayed on the navigation diagram representing the employees.jsp page.

3. To create a new page, with the JSF navigation diagram still displayed in the editing window, from the JSF Navigation Diagram page of the Component Palette, drag JSF Page onto the diagram.

   As the new page icon appears on the diagram, enter the text edit.jsp to replace the name /untitled1.jsp and press Enter. (You do not need to add the forward slash in front of the name, because it will be added automatically.)

   At this point, a new page has been added to the diagram, but the page file itself does not exist. To indicate that, the page icon renders with a yellow caution sign.

4. To create the edit.jsp page, double-click the page icon for the page edit.jsp in the diagram.

5. In the Create JSF JSP wizard, if the Welcome page is displayed, click Next. The name of the page is already entered for you, and the remaining steps should be exactly as for the employees.jsp page created earlier, so you can click Finish.

   The new page is displayed in the Visual Editor, ready for you to design the page.

Navigating Between Pages

Navigation by a user through a JSF application is defined using navigation rules that determine which page is displayed next when the user clicks a link. The different cases, such as the different links on the page, are defined as navigation cases.

You can use a diagram to draw the navigation between the pages of the application representing the flow between the pages.

When you draw navigation on a JSF navigation diagram, two things happen: the navigation cases are added to the necessary configuration files automatically for you, and the navigation cases are shown on the diagram as arrows connecting pages, the direction of the arrow indicating the pages from which and to which the user will navigate.

A label is associated with each navigation case, to distinguish different navigation cases from a single page.

Defining Navigation Between Pages

In these steps, to allow for navigation between the two pages of the application, you will add navigation details to the application.

1. Return to the JSF navigation diagram to define the navigation between the two pages. To do this, among the items open in the editing window, select the tab for faces-config.xml. If the diagram is not still open, open it as before.

2. In the diagram, click on the employees.jsp page icon to establish focus on this page.

3. On the JSF Navigation Diagram page of the Component Palette, click (not drag) JSF Navigation Case.

4. On the diagram, click the employee.jsp icon again. After you have clicked on the page, as you start to move the mouse away from the page, a line appears, connected to the employees.jsp page. Connect this line to the new page by clicking on the edit.jsp page.

   A line now connects the two pages, representing a navigation case navigating from the employees.jsp page to the edit.jsp page. It has a label with a default value of success.

5. To change the value, click success, type edit, and press the Enter key. The text edit is now displayed on the diagram as the label for the line.

6. Add another navigation case navigating from the edit.jsp page to the employees.jsp page, and give the navigation case the name return. This navigation case represents navigating from the edit.jsp page back to the employees.jsp page.

7. Save your work.

The navigation diagram now shows both navigation cases: one for a user to navigate from the employees.jsp page to the edit.jsp page so they can edit employee details, and another for the user to return to the employees.jsp. Figure 7-15 shows the navigation diagram for the employees.jsp and edit.jsp pages.

Figure 7-15 Navigation Diagram

Description of "Figure 7-15 Navigation Diagram"

Creating an Edit Form

In these steps, you create the edit.jsp page:

1. Open the edit.jsp page in the Visual Editor.

2. On the edit.jsp page, from the ADF Faces Core page of the Component Palette, add a PanelPage component to the page. Change the title of the PanelPage to Edit Employee.

3. Also, add an OutputText component to the branding facet at the top of the page. Set the Value property to AnyCo Corporation and the StyleClass property to AFHeaderLevelOne.

4. In the Data Control Palette, expand the DepartmentsView1 node (if it is closed) and locate the same EmployeesView3 node beneath it. This must be the child of DepartmentsView1, as illustrated below.

5. Drag the EmployeesView3 node onto the center of the panel beneath the Edit Employee title. In the dialog box that is displayed, select Create, Forms, and ADF Form.

   Note:

   It is important to select the child EmployeesView3 node under parent DepartmentsView1 from the Data Control Palette. The child EmployeesView3 will show the detail Employee records for a particular parent Deparment as designated by the foreign key relationship.

6. In the Edit Form Fields dialog, select Include Submit Button and click OK.

The edit form is almost complete. The final task is to add a button that will allow the user to navigate back to the employees.jsp page. To do this:

1. From the ADF Faces Core page of the Component Palette, drag a CommandButton to the page and place it next to the Submit button at the bottom of the page.

2. Use the Property Inspector to change the Text property of the button from commandButton 1 to Return.

3. Again using the Property Inspector, change the Action property of the CommandButton to Return. You can use the arrow in the Action field to select the value return. This is the value you entered for the navigation case for a user navigating from the edit.jsp page back to the employees.jsp page.

4. Save the page.

The edit page is now complete, and should resemble the page shown in Figure 7-16.

Figure 7-16 Editing the Employees detail form in the Visual Editor

Description of "Figure 7-16 Editing the Employees detail form in the Visual Editor"

Navigating to an Edit Page

One remaining task is to allow users viewing the employees page to navigate to the edit page to edit employee details. To do this, you make use of the navigation case you defined on the navigation diagram, which had the name edit. The Employees table on the employees page already has a button, which can be used for the user to navigate to the edit page.

1. Open the employees.jsp page in the Visual Editor.

2. Select the Submit button to establish focus.

3. In the Property Inspector, change the Text property to Edit. Set the Action property to edit: use the arrow in the Action field to select the value edit. This is the value you specified on the navigation diagram as the navigation case for a user to navigate from the employees.jsp page to the edit.jsp page.

Now when a user clicks on this button, the application will navigate to the edit page with the selected record displayed.