Build an End-to-End Web Application with ADF Faces and Oracle TopLink

Purpose

In this tutorial, you use Oracle Application Development Framework (ADF) to build a web application that includes a master-detail page and an associated Edit page. ADF Faces is used to build the client components. Oracle TopLink provides the data model. You also incorporate an EJB session bean to provide the model's session façade.

Time to Complete:

60 minutes

Topics

The tutorial covers the following topics:

	Overview
	Prerequisites
	Creating a Database Connection
	Building the Data Model with TopLink
	Defining the Page Flow
	Creating a Master-Detail JavaServer Faces Page
	Creating an Employee Edit JavaServer Faces Page
	Running the JSF
	Summary

Viewing Screenshots

Place the cursor over this icon to load and view all the screenshots for this tutorial. (Caution: This action loads all screenshots simultaneously, so response time may be slow depending on your Internet connection.)

Note: Alternatively, you can place the cursor over an individual icon in the following steps to load and view only the screenshot associated with that step. You can hide an individual screenshot by clicking it.

Overview

You will create a master-detail form for viewing department information along with the employees in each department. You will then create a button that calls an Edit page, enabling you to update an employee's detail information. Finally, you will test run the application in JDeveloper's embedded server.

Back to Topic List

Prerequisites

Before starting the tutorial, you should:

Back to Topic List

Creating a Database Connection

If you haven't already created a JDBC connection to the HR schema, then perform the following steps:

Back to Topic List

Building the Data Model with TopLink

The business model provides data access and validation for an application. When data is managed by the business model, the data is always validated by the model, regardless of the client implementation. This cleanly separates the validation and business rules from the user interface.

To create an application in JDeveloper and create a TopLink model for the application, you will perform the following tasks:

	Create a New Application and Projects
	Create the Data Model using Oracle Toplink
	Create an EJB Session Bean and ADF Data Controls

Back to Topic List

Create a New Application and Projects

In JDeveloper, you always work with projects contained in an application.

The application is the highest level in the JDeveloper control structure. It is a view of all related objects you need while working. An application keeps track of your projects while you are developing Java programs.

A JDeveloper project is an organization structure used to logically group related files. You can add multiple projects to an application in order to organize, access, modify, and reuse your source code. In the Applications Navigator, projects are displayed in the second level in the hierarchy, as subnodes of the application.

Before you create any application components, you must first create the application and an initial project. To do this, perform the following steps:

1.	Click the Applications Navigator tab to go back to the Applications Navigator. Right-click the Applications node and select New Application from the context menu.
2.	In the Create Application dialog box, enter the Application Name MDToplink. Notice that as you enter the application name, the directory name changes automatically. Enter oracle as the Application Package Prefix. Select the Web Application [JSF, EJB, Toplink] value from the Application Template drop-down list. Click the Manage Templates... button.
3.	In the Application Templates tree, for the Web Application [JSF, EJB, Toplink] node, select View and Controller and in the View and Controller pane, set Project Name to UserInterface.jpr and Default Package to view.
4.	In the Application Templates tree, for the Web Application [JSF, EJB, Toplink] node, select Data Model and in the Data Model pane, set Project Name to DataModel.jpr and Default Package to datamodel. Click OK.
5.	Back in Create Application, click OK to create the application.
6.	Click Save All on the toolbar to save your work. Alternatively, you can select File | Save All from the menu. The Applications Navigator should look like the image below. You are now ready to create application components for the tutorial.

Back to Topic

Back to Topic List

Creating the Data Model Using Oracle TopLink

Oracle TopLink provides Java object-to-relational persistence, enabling you to create Java objects for accessing and persisting relational data. Oracle Application Development Framework (ADF) enables you use these TopLink objects in your user interface through ADF data controls. These data controls enable client applications to use the data without concern for the underlying technology choice (in this case, Oracle TopLink).

To create the data model for your application, perform the following steps:

1.	In the Applications Navigator, right-click the DataModel project and select New from the context menu.
2.	In the New Gallery, expand the Business Tier node in the Categories tree and select TopLink. Select Java Objects from Tables in the Items list and click OK.
3.	If the Welcome page of the Create Java Objects from Tables wizard displays, click Next. TopLink requires a TopLink map file for each project. This file contains information about how classes are mapped to database tables. Once the TopLink objects are created, you can edit this file to make changes to the default mappings. The wizard helps you to create a new map for your project. On the Select DB Connection page of the wizard, click the New button for the TopLink Map property.
4.	In the Create Object-Relational Map dialog, set the TopLink Map Name to HRMap and ensure that the Connection is set to hrconn. Click OK.
5.	JDeveloper displays a progress indicator as it creates the map file. When control returns to the wizard, click Next.
6.	On the Select Tables page of the wizard, you select the tables that you want represented as TopLink objects. Click Query to display the available tables. In the Available list, select DEPARTMENTS and EMPLOYEES, then click Add to move the selected tables to the Selected list. Click Next.
7.	On the General Options page of the wizard, confirm that the package name is oracle.datamodel. If not, then modify it. Click Next.
8.	The Specify Object Details page of the wizard enables you to edit the class name and source directory for each Java class being generated. Accept the defaults by clicking Next.
9.	On the Summary page of the wizard, click Finish to create the Java objects.
10.	Click Save All on the toolbar to save your work. Alternatively, you can select File | Save All from the menu. In the Applications Navigator, expand Application Sources and its subnodes. You can see the Java files and the TopLink map file that the wizard created for you. You have created TopLink POJOs (Plain Old Java Objects) for the Departments and Employees tables from the HR schema. The .java files contain the code for the attribute definitions, constructors, getters and setters.

Back to Topic

Back to Topic List

Creating an EJB Session Bean and ADF Data Controls

In this section, you create an Enterprise JavaBean (EJB) session bean to serve as the basis for data controls in the application. Data controls represent the plumbing between the data model and any client components. You could create a data control based directly on the TopLink persistence objects. However, in this tutorial you use an EJB session facade to access the TopLink objects, so the EJB session bean provides the interface for this plumbing to occur.

Session beans encapsulate business logic and business data while exposing the necessary interfaces. As such, the client tier can make use of the distributed services within the model without concern for its complexity. The session bean in this tutorial is made up of two files:

• HRPublicFacadeBean.java - contains the session code and implements the local interface
• HRPublicFacadeLocal.java - a local interface containing code to query and persist data

To make use of the TopLink POJOs and HRPublicFacadeBean, after creating the session bean you create a data control for the objects defined in the TopLink map (HRMap).

To create a session bean named HRPublicFacade in the oracle.datamodel package, and to create a data control from that bean, perform the following steps:

1.	In the Applications Navigator, right-click the DataModel project and from the context menu, select New.
2.	In the New Gallery, expand Business Tier in the Categories list and select the EJB node. In the Items list, select Session Bean and click OK.
3.	If the Welcome page of the Create Session Bean wizard displays, click Next. On the EJB Name and Options page of the wizard, set the values to those shown below. Field Value EJB Name HRPublicFacade Session Type Stateless Transaction Type Container Generate Session Façade Methods Check box selected (so that methods to query and persist data are generated) Entity Implementation TopLink POJOs option selected (because you are using TopLink POJOs as the basis of the data model) Stateless session beans do not have an internal state. They do not keep track of the information that is passed from one method call to another. Each invocation of a stateless business method is independent of its previous invocation. You would need a stateful session bean only for applications such as online shopping carts that need to maintain a conversational state across method invocations. By specifying a Transaction Type of Container, you are enabling the container to manage transactions so that you do not have to code transaction mechanisms. You would change this only if you wanted to write your own transaction mechanisms. Click Next.
4.	On the Session Façade page of the wizard, ensure that all the check boxes are selected, because you want to have the session facade incorporate all the methods and named queries. Click Next.
5.	On the Class Definitions page of the wizard, ensure that Bean Class is set to oracle.datamodel.HRPublicFacadeBean. The default directory is acceptable. Click Next.
6.	On the EJB Component Interfaces page of the wizard: Deselect Implement a Remote Interface. (Remote interfaces are needed to use a command line test client, which is not required here). Ensure that Implement a Local Interface is selected. This allows the web client to run in the same Java Virtual Machine (JVM). Click Next. Click Finish to complete the process.
7.	The new HRPublicFacadeBean class opens in the editor. In the Structure window ( View | Structure from the JDeveloper menu), expand the Methods node and double-click findAllDepartments() to locate that method in the HRPublicFacadeBean.java file that is displayed in the editor window. In that method, the application edits the results of this method.
8.	In the Applications Navigator, expand the DataModel project, then expand Application Sources and the oracle.datamodel package. Right-click HRPublicFacadeBean.java and select Create Data Control from the context menu. Click Save All on the JDeveloper toolbar, or select File | Save All from the menu.

Back to Topic

Back to Topic List

Defining the Page Flow

When you created the application, you created it with two projects: DataModel and UserInterface. The DataModel project contains the TopLink data controls that serve as the business model for your application. The UserInterface project is for the view portion of your application, which defines the user interface components.

You will now begin to define the user interface. You use JDeveloper's JSF Navigation Diagram to plan and create your application's pages and to define the navigation between them.

To diagram the page flow of the application, perform the following steps:

1.	In the Applications Navigator, right-click the UserInterface project and select Open JSF Navigation from the context menu.
2.	Ensure that JSF Navigation Diagram is selected from the dropdown list of the Component Palette Select JSF Page and click on the diagram in the position where you want the page to appear. Note that the page appears with a yellow warning symbol. This is because you have depicted a page on the diagram that does not yet exist. The yellow warning disappears later when you create the page.
3.	Rename the page deptEmp by typing over the name. You need only to type the name; JDeveloper automatically adds the leading forward slash and the .jsp extension when you press [Enter].
4.	In a similar fashion, add another JSF Page to the diagram next to the previous one. Rename the page editEmp.
5.	Select JSF Navigation Case in the Component Palette. Click the source page (deptEmp), and then click the destination page (editEmp) to create a navigation case.
6.	Modify the default label, 'success', by clicking it and typing edit over it. Alternatively, you can change the value of the From Outcome property in the Property Inspector to edit. When you press [Enter] or click elsewhere, the value in the diagram changes as well. JDeveloper adds the leading hyphen to the diagram automatically.
7.	Click the Overview tab at the bottom of the editor. Select Navigation Rules in the list on the left side. Notice that the rule you just created in the diagram is listed in the table. Click the Source tab. The <from-view-id> tag identifies the source page and the <to-view-id> tag identifies the destination page. The wavy lines under the page names remind you that the pages have not yet been created.
8.	Switch back to the diagram view by clicking the Diagram tab. Select JSF Navigation Case in the Component Palette. Click the source page (editEmp), and then click the destination page (deptEmp) to create another navigation case.
9.	Modify the default label to commit, either by typing over it or by changing the From Outcome property in the Property Inspector.
10.	Click Save All to save your work. Your diagram should now look something like the image below.

Back to Topic List

Creating a Master-Detail JavaServer Faces (JSF) Page

In this section, you use ADF Faces components to create a master-detail JSF page that displays departments and their associated employees.

Oracle ADF Faces is a rich set of user interface components based on the new JavaServer Faces JSR (JSR-127). These components are various user-interface elements with built-in functionality that can be customized and re-used in your application. Examples of such components include data tables, hierarchical tables, and color and date pickers.

To create the page, perform the following steps:

1.	On the JSF Navigation Diagram, double-click deptEmp.jsp to launch the Create JSF JSP wizard. If the Welcome page of the wizard displays, click Next. On the JSP File page of the wizard, for Type, select the JSP Document option. This creates an XML representation of a JSP page, ensuring that the page uses well-formed XML syntax. Click Next to continue.
2.	On the Component Binding page, select the Automatically Expose UI Components in a New Managed Bean option. Leave other values as their defaults and click Next.
3.	Ensure that the libraries shown below are in the Selected Libraries list. JSF Core 1.0 ADF Faces Components ADF Faces HTML If they are not, select them in the Available Libraries list and click Add to shuttle them to the Selected Libraries list. Note that the library version numbers may be different from those shown. Click Next to accept these libraries that you need in order to create the ADF Faces components on your page.
4.	Click Next to accept the default HTML options, then click Finish to create the new JSF JSP. The empty deptEmp.jspx page opens in the editor. In the next few steps, you add a data-bound ADF Faces component to the page. This component displays a department and its employees.
5.	In the Component Palette, select ADF Faces Core from the dropdown list and select the panelPage component to add it to the page. Note: If you do not see the Component Palette displayed to the right of the editor window, select View | Component Palette from the JDeveloper menu.
6.	The panelPage component is a layout for an entire page. It provides placeholders for various facets that you may want to use in your application. In this application, you need only the Title. If not defined, the other facets will not show up at run time. In the Property Inspector, change the Title value for the panelPage to Department/Employees. When you press [Enter] or click elsewhere, the title on the diagram changes.
7.	Click the Data Control Palette tab (if you do not see this tab next to the Components tab, then select View | Data Control Palette from the menu). Expand the HRPublicFacadeLocal, findAllDepartments(), and Departments nodes. Select the departmentCollection node. This represents the nested collection of employees for departments. Drag and drop the departmentCollection onto the panelPage... ...and from the dynamic menu select the Create Master-Details | ADF Master Form, Detail Table. Acknowledge the message in the Client Project Libraries Added dialog by clicking OK.
8.	JDeveloper adds the ADF Master Detail component to your JSF page. The page should now look like this: The master form has default navigation buttons and the detail table has a default Submit button.
9.	Select the Submit button on the page. In the Property Inspector, change the value of the Text property to Edit. Notice that the label on the button changes when you press [Enter] or click elsewhere. From the dropdown list for the Action property, select edit. Note that this action corresponds to the name of the From Outcome in the navigation case from this page to the editEmp page that you defined earlier in the JSF Navigation Diagram. This ensures the use of that navigation case when the user clicks the button, so that navigation from this page to the editEmp page occurs.
10.	In the Structure window, expand the af:panelGroup node. Select the af:panelHeader - oracle.datamodel.Departments component ... ...and in the Property Inspector set the Text attribute to Departments. The header for that panel changes on the page.
11.	In a similar fashion, set the Text property of the af:panelHeader - departmentCollection component to Employees, thus changing the header for that panel. Click Save All to save your work. You now have a complete JSF JSP that is databound to the TopLink business services.

Back to Topic List

Creating an Employee Edit JavaServer Faces Page

In this section, you use ADF Faces components to create a page where employee details can be edited. To create the page, perform the following steps:

1.	Switch back to the JSF Navigation Diagram by clicking the faces-config.xml tab in the editor. If you have closed the diagram, you can reopen it by right-clicking the UserInterface project and selecting Open JSF Navigation from the context menu. Click the Diagram tab at the bottom of the editor, then double-click editEmp.jsp to begin creating the page.
2.	If the Welcome page of the Create JSF JSP wizard displays, click Next. On the JSP File page of the wizard, for Type select the JSP Document option. Then click Next to continue.
3.	On the Component Binding page, select the Automatically Expose UI Components in a New Managed Bean option. Default the other values and click Next.
4.	Ensure that the libraries shown below are in the Selected Libraries list. JSF Core 1.0 ADF Faces Components ADF Faces HTML If they are not, select them in the Available Libraries list and click Add to shuttle them to the Selected Libraries list. Note that the library version numbers may differ from those shown. Click Next to accept these libraries.
5.	Click Next to accept the default HTML options, then click Finish to create the new JSF JSP. The empty editEmp.jspx page opens in the editor.
6.	Click the Components (or Component Palette) tab. In the Component Palette, ensure that ADF Faces Core is selected in the dropdown list. Select the panelPage component to add it to the page.
7.	In the Property Inspector, change the Title value for the panelPage to Employee Details.
8.	Click the Data Controls tab. Select the departmentCollection node under findallDepartments | Departments and drag it to the Panel Page... ... and from the dynamic menu select Create Forms | ADF Form.
9.	In the Edit Form Fields dialog, select the Include Submit Button option and click OK. The edit table is now populated with default values and a Submit button.
10.	Now you add a method to enable users to commit changes. TopLink implements a commit in the mergeEntity() method. Drag the mergeEntity(Object) method from the Data Control Palette to the Submit button in the editor... ... and from the dynamic menu, select Bind Existing CommandButton.
11.	In the Action Binding Editor dialog, double-click the Parameters: Value field, then click Edit next to the Parameter Value. In the Variables dialog, expand ADF Bindings, bindings, departmentCollectionIterator, and currentRow. Select dataProvider and click the right arrow to shuttle it to the Expression field. Then click OK. Click OK to dismiss the Action Binding Editor dialog.
12.	Select the mergeEntity button in the editor. In the Property Inspector, set the Text property to Save Changes and select commit from the Action dropdown list. Note that this action corresponds to the name of the From Outcome in the navigation case from this page to the deptEmp page that you defined earlier in the JSF Navigation diagram. This ensures the use of that navigation case when the user clicks the button, so that navigation from this page to the deptEmp page occurs. Click Save All to save your work.

Back to Topic List

Running the Application

Now that you have built your new ADF Faces application, you need to test it. JDeveloper makes it easy to test JSF applications through a built-in J2EE server. This OC4J server is automatically launched when you test a page from within JDeveloper.

To complete the testing process, perform the following steps.

1.	Right-click deptEmp.jspx either in the Applications Navigator, the editor for that page, or the JSF Navigation Diagram, and select Run from the context menu. The embedded OC4J server starts and is initialized, and the page displays in a browser.
2.	Test the navigation buttons at the master form level and navigate to a department with more than one employee.
3.	In the Employee table, select one of the employees and click Edit.
4.	As specified by the navigation case that you defined in the JSF Navigation Diagram, the editEmp.jspx page that is labeled Employee Details is now displayed. Modify the email address for the employee (for example, change from PFAY to PATFAY) and click Save Changes .
5.	As specified by the navigation case that you defined in the JSF Navigation Diagram, the deptEmp.jspx page that is labeled Department/Employees is now displayed. Note that the new value for the employee is now reflected in the detail table.
6.	Now check that the update was performed against the database. In JDeveloper, click the Connections tab. Expand the Database, hrconn, HR, and Tables nodes. Double-click the EMPLOYEES table to open it in the editor. Click the Data tab and locate the record of the employee whose data you updated, to confirm that the update was committed to the database.

Back to Topic List

Summary

In this tutorial, you created a simple end-to-end application by using JDeveloper, Oracle TopLink, and ADF Faces. You learned how to:

	Use TopLink and EJB to create the business model and session facade
	Create a JSF Navigation Diagram to specify pages and navigation
	Create a master-detail page that uses ADF Faces components to show departments and related employees
	Create a related page to edit employee details and commit changes
	Test the application

Back to Topic List

Place the cursor over this icon to hide all screenshots.