Build a Web Application with ADF Faces and Oracle TopLink
Build a Web Application with ADF Faces and Oracle TopLink
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.
60 minutes
The tutorial covers the following topics:
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.
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
Before starting the tutorial, you should:
| 1. |
Have access to or have installed Oracle JDeveloper 10g Release 3 (10.1.3) Production. You can download it from Oracle Technology
Network.
|
| 2. |
Have access to or have installed the Oracle Sample Schemas.
Specifically, the tutorial uses the HR schema. The application's
pages work with the DEPARTMENTS and EMPLOYEES
tables.
Instructions for installing the HR schema and creating
a connection to it in JDeveloper are available online at:
http://www.oracle.com/technology/obe/obe1013jdev/common/OBEConnection.htm
|
| 3. |
Start JDeveloper. Double-click the JDeveloper executable
(jdeveloper.exe)
found in the root directory where you installed it.
If the Migrate User Settings dialog box opens, click No.
Close the Tip of the Day window and the Start page. |
Back to Topic List
If you haven't already created a JDBC connection to the HR
schema, then perform the following steps:
|
1.
|
Click the Connections tab.
If the Connections tab is not showing, choose View | Connection Navigator
from the JDeveloper main menu.
|
|
2.
|
Right-click the Database node and choose New Database Connection
from the context menu.
|
| 3. |
If the Welcome page of the Create Database Connection wizard opens, click Next.
On the Type page of the wizard, enter hrconn as the Connection Name. Click Next to continue.
|
| 4. |
On the Authentication page of the wizard, enter hr in the Username field and hr in the Password field. Select Deploy password.
Click Next to continue.
|
| 5. |
On the Connection page of the wizard, the default values for the connection should be the following:
Driver: thin
Host Name: localhost
JDBC Port: 1521
SID: ORCL
Leave the fields set to these default values if you have the database installed locally. If you are using a remote database, enter the appropriate values
for the connection to the database. If you do not know these values, check with your database administrator.
Click Next to continue.
|
| 6. |
Click Test Connection.
If the database is available and the connection details are correct, you see the word Success! displayed in the Status window.
If an error occurs, verify the connection settings, click Back to make any necessary changes, and then retest the connection.
If the connection is successful, click Finish to complete the connection.
You have just created a connection to the database that supplies data
for the application you build in this tutorial.
|
Back to Topic List
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:
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.datamodel
as the Application Package Prefix.
Select
the No Template [All Technologies] value
from the Application Template drop-down list.
Click OK.
|
| 3. |
The Create Project dialog is displayed. Enter DataModel as
the Project Name, and then click OK.
|
| 4. |
Having created a project for the data model, you now create a new project
for the client (user interface).
Create another project at the same level as the DataModel project.
In the Applications Navigator, right-click the MDToplink
node and select New Project from the context menu.
|
| 5. |
In the New Gallery, verify that Empty Project is selected
and click OK.
|
| 6. |
In the Create Project dialog, enter UserInterface as the Project Name and click OK.
|
| 7. |
In the Applications Navigator, right-click the UserInterface project and select Project Properties from the context menu.
|
| 8. |
In the Project Properties window, select the Project Content node in the tree at the left.
At the bottom
of the Project content panel, set the Default Package to oracle.view.
|
| 9. |
Still in the Project Properties window, select the Technology Scope node in the tree at the left.
In the Available Technologies list, select JSF and click Add  to shuttle it to the Selected Technologies list.
Note: Adding JSF to the techonology scope automatically adds Java and JSP and Servlets as well.
Click OK. Separating the data model and the user interface into different projects and packages enables you to better manage classes and files.
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, 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, uncomment the line beginning with results by removing the two leading forward slashes. You are uncommenting the code because the application edits the results of this method.
Note: If you cannot see the Structure window, select View | Structure from the JDeveloper menu.
|
| 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
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
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
JSF HTML 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. Select the panelPage component and click the page editor.
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
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
JSF HTML 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 and click the page editor.
|
| 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
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
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.
|
Bookmark
