Build a Web Application with ADF Business Components and JavaServer Faces
Build an End-to-End Web Application with ADF Business
Components and JavaServer Faces
Purpose
In this tutorial, you use Oracle JDeveloper (10.1.3.1.0) and
ADF Business Components to build a web application. ADF Business Components
is used to build the data model, and JavaServer Faces is used for the web client,
which will include a master-detail page, a search page and an edit page.
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
The application reflects the Model-View-Controller architecture.
The model is provided by ADF Business Components, while the view and controller
are provided by JavaServer Faces. You will be using the JSF-standard ADF Faces
component library to build an attractive web user interface. ADF Faces is a
set of JSF components that provide simple to complex data-aware controls.
You will first build the data model portion of the application.
This is where you place middle-tier business logic and validation rules. The
ADF Model layer provides the
declarative data binding between the three layers (model-view-controller). You
will then create a master-detail form for viewing customer information along
with the orders they have placed. Following this basic master-detail page creation,
you will create more complex pages including features such as a Search and Edit
function.
While developing and testing the application, you will use
the embedded Java EE application server that Oracle JDeveloper 10g
provides. When the application is complete, it can be deployed to Oracle Application
Server 10g or another external application server.
Java Database Connectivity (JDBC) is a standard application
programming interface (API) that is used for connecting a Java application
to
relational databases. JDeveloper uses a connection navigator to maintain connection
information for your application. The connection navigator makes it easy to
create, manage, and test database connections.
If you haven't already established a connection to the database,
then do so by performing the following steps:
1.
Click the Connections tab on the Applications
Navigator. 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.
In the Create Database Connection Wizard, review the information on the
Welcome page and then click Next.
4.
In the Connection Name field, enter oeconn. Click Next to continue.
5.
On the Authentication page: enter oe in
the Username field and oe
in the Password field. Select Deploy password.
Note: It is secure to deploy the password since
it gets encrypted.
Click Next to continue.
6.
On the Connections page, 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.
Click Next to continue.
7.
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 will supply data for the application you build in this tutorial.
Building the Data Model with ADF Business
Components
The data model provides data access and validation for an
application. 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.
In the next few steps, you create an application in JDeveloper
and create a Business Components model for your application.
In JDeveloper, you always work with
projects contained in an application. The application is the highest point in
the control structure.
A JDeveloper project is an organization structure used to
logically group related files You can add multiple projects to your application
to easily organize, access, modify, and reuse your source code. In the Applications
Navigator, projects are displayed as the second level in the hierarchy, under
the application.
Note that it is considered best practices to use projects
to separate the model code from the code written for the view. In this hands-on
we will create one project for the ADF Business Components model, and a second
one later for the JSP views.
Before you create any components, you must first create the
application and a project. To do this, perform the following steps:
1.
Click the Applications 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
OrderEntry. 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, ADF BC] value from
the Application Template drop-down list.
Click the Manage Templates... button.
3.
In the Application Templates tree, for the Web Application [JSF,
ADF BC] node, select View and Controller
and in the View and Controller pane, set Project Name to UserInterface.jpr
and Default Package to view.
4.
n the Applications Templates tree, for the Web Application
[JSF, ADF BC] 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 the 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.
In the next few steps, you create a model for your application.
In this section, you create ADF Business Components based
on tables in the database. You use the oeconn database connection, which
you created earlier. You create these objects in the Model project.
1.
In the Applications Navigator, right-click the DataModel project
and select New from the context menu.
2.
In the New Gallery, expand Business Tier and select ADF Business
Components in the Categories list.
Select Business Components from Tables in the Items list.
Click OK.
3.
In the Business Components Project Initialization window, select the
oeconn connection from the Connection list, and then click OK.
4.
If the Welcome page of the Create Business Components wizard appears,
click Next.
If no package name is specified when creating the application,
by default
it takes the
project name which is model.
Note: An ADF Entity Object is a Java component that
represents a row in an underlying database table as a domain business
object in your Java EE application. It encapsulates the business rules
for that domain object and automatically handles saving any change
made by the user back to the database. If you are familiar with Oracle
Forms, the entity object provides functionality similar to the Oracle
Forms record manager, but with the ability to associate encapsulated
business rules with each type of 'business record' structure.
Select OE from the Schema drop down list.
Click Query to populate the list of available tables.
Control-click to select both CUSTOMERS and ORDERS in
the Available list.
Click the Add button to
shuttle both tables to the Selected list.
Click Next to continue.
5.
On the "Updatable View Objects" page of the Create
Business Components Wizard, select both Entity objects and click the
Add button to
shuttle both tables to the Selected list.
Note: An ADF View Object is a Java component that
represents a SQL query against one or more underlying tables. It allows
you to project, join, filter, and sort business information in exactly
the way the end-user needs to see it for the user interface you need
to provide to your end users. When related to underlying ADF Entity
Objects, the view object allows users to create, update, and remove
rows with automatic enforcement of business rules. If
you are familiar with Oracle Forms, the view object provides
functionality similar to the Oracle Forms Data Block, but adds the
flexibility to finely tune the SQL query and to automatically
leverage centralized business rules encapsulated by the entity
object.
Click Next.
6.
Skip the "Read-only View Objects" page of the wizard by clicking
Next. You will only be using view objects that can be updated.
7.
On the Application Module page of the wizard, name the application
module OrderEntryAM.
Note: An ADF Application Module is a Java component
that represents a transactional data model of master/detail-related
view object queries. It allows client interface technologies of any
kind in a service-oriented architecture to easily manipulate the business
information exposed by the view object instances contained in its data
model. If you are familiar with Oracle Forms, the application module
provides the functionality of a transactional data container similar
to the Oracle Forms Form object, but is designed to allow any kind of
user interface to work with the data in its view object 'data blocks'.
Click Next.
8.
JDeveloper provides several different techniques for managing components.
One is to use a diagram of the components and their relationships. In
this step, JDeveloper provides such a diagram option.
For this tutorial, you will not use this option. Click Next
to continue.
9.
The final page of the Business Components Wizard shows the objects
and relationships that will be created.
Click Finish to complete the wizard actions.
10.
The Applications Navigator should now look like this:
Using the far right button of the toolbar in the navigator pane,
sorts elements by type.
In the previous sections, you created some default Business
Components from two tables (Customers and Orders). The default view objects
expose all of the columns from those tables. For your application, you want
to expose only a few of those columns. ADF BC allows you to easily customize
those objects to fit your specific application needs.
In the following steps, you remove some of the exposed
attributes from the CustomersView view object.
1.
In the Applications Navigator, right-click the CustomersView
node and select Edit CustomersView from the context menu.
2.
Select the Attributes node to show all the attributes in the
view object.
3.
In the Selected pane of the View Object Editor, control-click all of the
attributes except:
CustomerId
CustFirstName
CustLastName
CustEmail
4.
Use the Remove button
to shuttle the selected attributes from the Selected list.
5.
Next, you will add an Order By clause to the CustomersView to make
sure the returned data is sorted by customer ID.
In the left pane, select the SQL Statement node.
6.
Enter Customers.CUSTOMER_ID in the Order By field near
the bottom of the SQL Statement pane.
Click OK to apply the changes and exit the View Object Editor.
7.
Click the Save All
icon on the JDeveloper menu bar, or select File > Save All from
the menu.
You have now customized the Customers view to meet the specific needs
of your application. The next step is to create a web client that uses
the OrderEntry model.
Conforming to the JSF standards, ADF Faces lets you concentrate
on the application and layout rather than markup language and tags. Due to the
integration of ADF Faces and ADF Business Components, you can easily change
the default field labels for the user interface from within ADF Business Components.
In the next few steps, you create an ADF Faces application
based on the ADF BC model that you just built. You also modify some of the ADF
BC default settings to help enhance the default UI.
1.
When you created the application, two projects were defined: DataModel
and UserInterface. The DataModel project contains the business components
that serve as the data model for your application. The UserInterface
project will include the View portion of your application, which defines
the user interface.
Collapse the DataModel node so that the Applications
Navigator appear as follows:
2.
Create a new JSF by right-clicking UserInterface
in the Applications Navigator and selecting New from the context
menu.
3.
In the New Gallery, expand Web Tier and select
JSF in the Categories list. Select JSF JSP
in the Items list.
4.
Selecting a new JSF opens the Create JSF JSP Wizard. Click Next
to skip the Welcome page of the JSF JSP Wizard (if it appears).
5.
Name the new JSP CustomerOrders.jsp. Accept the other defaults
and click Next to continue.
6.
On the next page, Component Binding, select the Do Not Automatically
Expose UI Components option. Leave other default values
and click Next.
7.
Make sure the following libraries are selected:
JSF Core 1.0
JSF HTML 1.0
ADF Faces Components
ADF Faces HTML
Click Next to accept these libraries.
8.
Click Finish to accept the default HTML options and create the
new JSP.
You now have an empty CustomerOrders.jsp page.
In the next few steps, you add a data-bound ADF Faces component to the
page. This component displays a customer
along with the orders that the customer has placed.
9.
When you created the CustomerOrders.jsp page, JDeveloper opened it
in a visual editor in the center of the JDeveloper IDE. You add the
ADF Faces components by dragging them from either the Component Palette
or the Data Control Palette to the visual
editor. Here you will drop some databound components based on the
view objects you created earlier using the Data Control Palette.
First, expand OrderEntryDataAMControl in the Data Control palette.
10.
Expand CustomersView1.
Note: By default, the Business Components from Tables
wizard noticed the foreign key relationships between the ORDERS and
CUSTOMER tables and created a default data model in the OrderEntryDataAM's
data model that features both an OrdersView1, allowing us to see all
orders, as well as an OrdersView2 which is linked with the OrdersView1
showing all of the customers. In this scenario, we'll use the CustomersView1
and the OrdersView2 which will display customers and each customer's
set of orders.
11.
Drag OrdersView2 to the visual editor. JDeveloper opens a context
menu with the available options for that data control.
12.
Place your cursor over the Master-Details option, and then select
ADF Master Form, Detail Table.
13.
JDeveloper adds the ADF Master Detail component to your JSF page.
You now have a complete JSF that is databound to your ADF BC business
services. In the next section, you will test your new application.
Now that you have built your new ADF Faces application,
you need to test it. JDeveloper makes it easy to test JSF through a built-in
OC4J server. The server is automatically launched when you test a page from
within JDeveloper.
The next few steps take you through the testing process.
1.
To test the page, right-click CustomerOrders.jsp in the Applications
Navigator and select Run from the context menu. (You can also
right-click inside the visual editor and select Run from that context
menu.)
2.
Your page should look like the following:
Note: JDeveloper will open your default web
browser and display the page. If this doesn't happen, visit the Tools > Preferences and select the Web Browser
and
Proxy category.
Here you can enter the command line to your preferred browser. Then, try running
the page again after setting this
preference.
3.
Navigate through the customer rows to see the differences in the orders
that each customer has placed. Note that the first few customers in
the list have multiple orders.
Now that you have a working version of a JSF application,
let's spend a moment to customize some of the labels on the page. You created
the page using default values for all of the layout components. This is a good
way to start, but you will probably want to have more control over the complete
page.
The field labels on your page are not hard-coded, but rather
are derived at runtime. The values for those fields are retrieved from ADF
Business
Components definitions at runtime. ADF BC provides a way to customize those
runtime properties. One of the properties you can modify is called Control
Hints.
These Control Hints allow you to create display properties such as label,
field size, and format mask that will be rendered at runtime by ADF Faces.
In the next few steps, you will modify the Control Hints for
the CustomersView object and retest your application to see those changes applied.
1.
The changes you are about to make are in the Model project.
Select the CustomersView in the Applications Navigator (DataModel
> Application Sources > oracle.datamodel).
2.
Right-click CustomersView and select Edit CustomersView
from the context menu.
3.
Select and expand the Attributes node.
4.
Select CustomerId in the Attributes list.
5.
Click the Control Hints tab.
6.
Enter a value such as Customer ID: in the Label Text field. This
now becomes the field label for the CustomerID field.
7.
Click the following fields and add the text to the Label Text field (just
as you did for CustomerId).
CustFirstName
First Name:
CustLastName
Last Name:
CustEmail
Email:
Click OK to accept and apply your changes.
Note: the supplied control hints
can be translated into
other locales and then ADF runtime will use the labels
appropriate to the current user based on their browser's language
settings.
8.
Right-click CustomerOrders.jsp in the View project
and select
Run from the context menu.
9.
Notice
that your page uses the field labels you just added to the CustomersView
object. Because of the integration of the ADF components, you didn't
need to change anything in the view.
In this part of the tutorial, you add business components
to the existing data model to add view objects to the application module's data
model to support a Search page and a related Edit page. The Search page is based
on a join of information between Customers and Orders.
In the next few steps, you add business components in the
data model.
Creating a View
Object Based on a SQL Statement (I)
In this section, you create a read-only View Component, based
on a SQL statement, that queries the Promotions table. The view object provides
the available values stored in the Promotions table. These values will be used
as a Drop Down list in the Edit page.
1.
In the Applications Navigator, right-click the DataModel project
and select New from the context menu.
2.
In the New Gallery, expand Business Tier and select ADF
Business Components in the Categories list. Select View Object in the Item pane.
Click OK.
3.
Click Next to skip the Welcome page of the Create
View Object wizard. In Step 1 name the view PromotionsLOV.
Check the Rows Populated by a SQL Query option and
choose Read-Only Access.
Click Next to continue.
4.
In Step 2 enter the following Query Statement:
SELECT Promotions.PROMO_ID, Promotions.PROMO_NAME
FROM PROMOTIONS Promotions
ORDER BY Promotions.PROMO_NAME
Click the Test button to validate the SQL statement,
click OK. Then click Next twice,
then Finish.
5.
The Applications Navigator should now look like this:
Creating a View
Object based on a SQL statement (II)
In this section, you create a read-only View Component based
on a SQL statement that makes up the authorized values for the Mode column
of the Orders table. These values will be used as a Drop Down list in an Edit
page.
1.
In the Applications Navigator, right-click the DataModel project
and select New from the context menu.
2.
In the New Gallery, expand Business Tier and select Business
Components in the Categories list. Select View Object
in the Item pane.
Click OK.
3.
Click Next to skip the Welcome page of the Create
View Object wizard. In Step 1 name the view ModelLOV,
check the
Rows Populated by a SQL query option and choose Read-Only
Access.
Click Next to continue.
4.
In Step 2 enter the following Query Statement:
select 'direct' as modevalue
from dual
union all
select 'online' from dual
order by 1
Click the Test button to validate the SQL statement.
Then click Next twice and Finish.
5.
The Applications Navigator should now look like this:
Creating a New View
Object for the SearchOrders Page
In the following steps, you create a view object to present
data
from both the Customer and Orders entity objects. The wizard will
automatically create the appropriate join query between their
underlying database tables.
1.
In the Applications Navigator, right-click the DataModel
node and select New from the context Menu.
2.
In the New Gallery, expand Business Tier and select Business
Components in the Categories list. Select View Object
in the Item pane.
Then OK.
3.
Click Next to skip the Welcome page of the Create
View Object wizard. In Step 1 name the view SearchOrders
Check the Rows Populated by a SQL Query option, and
choose Updatable
Access through Entity Objects access.
Click Next
4.
In Step 2 Select the Orders Entity object and
click the Add button to
shuttle the selection, then select Customers
and click the Add button to
shuttle the selection.
Note: it is important to follow the above order for
shuttling the selected entities.
Click Next
5.
In Step 3, click the Attributes node and select the following
attributes:
In Step 4, select the OrderId attribute,
note that it is automatically marked as a Key Attribute because it
is the key
attribute of the underlying Orders entity object. Since each row of this query
is
uniquely
identified by this OrderId you can remove the optional key
attributes that are contributed by the underlying Customers entity
object.
Select the CustomerId attribute
from the dropdown list and uncheck the Key Attribute check
box.
Click Next
7.
Now we want to provide a search page that allows the end user to search
on a customer's first name or last name in a case-insensitive way, as
well as search for orders whose order total falls in a given range.
In this step, you will add a custom WHERE clause to the view object
that references named bind variables for the parameters we'd like the
user to be able to supply at runtime. You will reference the bind variables
here, and then formally define the bind variables names, data types,
and default values, in the next step of the wizard.
In Step 5 click the ExpertMode check
Box and in the query statement dialog, add the following code at
the end of the statement:
AND ORDER_TOTAL BETWEEN
:TotalLow AND :TotalHigh AND (UPPER(CUST_FIRST_NAME) LIKE UPPER(:CustName)
||'%' OR UPPER(CUST_LAST_NAME) LIKE UPPER(:CustName)||'%')
Click the Test button to make sure the SQL statement
is valid. Click Next twice.
8.
In Step 7 use the new button to create
create three named bind variables with the following properties:
Name
Type
Default
CustName
String
TotalLow
Number
0
TotalHigh
Number
50000
9.
You can define control hints for the named bind variables
as you
did earlier for view object attributes.
Select the CustName variable and click the Control
Hints tab. Type Customer Name in the
label text field
10.
For TotalLow type Order Total Greater Than
in the label text field
11.
For TotalHigh type Order Total Lower Than
in the label text field
Refining the View
Objects and Updating the Application Module
1.
Right click the SearchOrders node in the Applications
Navigator and select the Edit option from the context
menu.
2.
Next, you add a format mask so that the OrderTotal displays
as a currency value.
Expand the Attributes node, select OrderTotal and
In the Control Hints tab set the Format Type to Currency.
Click OK
Note: Since the format is specified at the view object level,
only components using this specific view definition will inherit this
Format definition.
3.
Right click the Orders Entity Object node in the Applications
Navigator, and select the Edit option from the context
menu.
4.
Expand the Attributes node, select OrderDate and
in the Control Hints tab set the Format Type to Simple
Date and specify the following format:
dd-MMM-yyyy
Click OK
Note: Since the format is specified at the entity object level,
all views based on this entity definition will inherit this Format
definition.
5.
In the Applications Navigator, right click the OrderEntryAM and
select Edit from the context menu.
6.
You need to include instances of the new view object components
in the application module's data model.
In the Application Module Editor, select the Data Model
node and in the list of available objects, select ModelLOV.
Click the Add button
to shuttle the selection in the Data Model pane.
Repeat the shuttle operation for SearchOrders, and PromotionsLOV.
Then click OK.
Note: the Instance Name field can be used to change
the name of the selected view object instance in the data model.
7.
Click the Save All icon
on the JDeveloper menu bar, or select File > Save All from
the menu.
8.
You have now customized the SearchOrders view to meet the specific needs
of your application. The next step is to create JSF pages that use this
data model.
In the next few steps, you create an ADF Faces page based
on the ADF BC model using the SearchOrders view that you just defined.
1.
In the Applications Navigator, collapse the DataModel project and
expand the UserInterface one. Double click the faces-config.xml
node to open a diagram.
Note: Alternatively, you can right click the
UserInterface node and select the Open JSF Navigation
option from the context menu.
2.
From the component palette,drag and drop a JSF page
icon onto the diagram.
3.
Rename the page Search.
Double click the JSF page icon to launch the page
creation wizard.
4.
Selecting a new JSF opens the Create JSF JSP Wizard. Click Next
to skip the Welcome page (if it appears) of the JSF JSP Wizard.
5.
Select JSP Page (*.JSP) as the type for the Search.jsp.Accept the other defaults.
Click Next to continue.
6.
On the new page, Component Binding, select the Do Not Automatically
Expose UI Components option. Leave other values to their
defaults.
Click Next.
7.
Make sure the following libraries are selected:
JSF Core 1.0
JSF HTML 1.0
ADF Faces Components
ADF Faces HTML
Click Next to accept these libraries.
8.
Click Finish to accept the default HTML options and create
the new JSP. You now have an empty Search.jsp
page.
In the next few steps, you add data-bound
ADF Faces components to the page. These
components display search criteria for retrieving the rows that
match the selection criteria.
9.
In the Data Control palette, expand the following nodes OrderEntryAMDataControl
> SearchOrders1 > Operations
and select the ExecuteWithParams action.
10.
Drag and Drop the ExecuteWithParams onto the page
and in the context menu, select Create > Parameters >
ADF Parameter Forms...
The Edit Form Fields dialog opens.
Click OK.
The page displays in the editor.
11.
In the Data Control palette, select SearchOrders1
and Drag and Drop it below the parameters form.
12.
In the new dialog, select Create > Tables > ADF Read
Only Table
13.
In the Edit Table Columns dialog, click the Enable Selection
and Enable Sorting boxes
then click OK.
You now have a complete JSF Page that is databound to your
ADF BC business services.
14.
Click the Green Arrow
in the toolbar to run the Search page.
15.
Experiment with the Search page, specifying values for Customer
Name, Total Low and Total High
fields, then click the ExecuteWithParams button.
Note: the search on the customer name is case-insensitive
and matches either in the first name or the last name, based on
how we specified our WHERE clause in the underlying view object. In a real application
you could easily rename the ExecuteWithParams
button to "Find" or "Search" using the property inspector.
16.
Try various Search combinations. Test the sorting facility
by clicking in the header of any column. A second click in the header
switches the order from ascending to descending and vice versa. Close
the browser window when finished.
In the next few steps, you create an ADF Faces page based
on the ADF BC model using the Orders , PromotionsLOV and ModelLOV views that
you just built.
1.
In the Applications Navigator, double click the faces-config.xml
node to open a diagram.
2.
From the component palette, drag and drop a JSF page icon on the diagram.
3.
Rename the page EditOrder.
Double click the EditOrder JSF page icon to launch
the wizard.
4.
Selecting a new JSF opens the Create JSF JSP Wizard. Click Next
to skip the Welcome page of the JSF JSP Wizard.
5.
The JSP standard supports creating pages that are well-formed XML
documents. These can be especially handy because they allow the
page's source to be easily parsed using XML tools, and they
encourage the best practice of not mixing code into your
page. JDeveloper supports working with either *.jsp pages or these
in the toolbar to run the Search page.
Bookmark
on the toolbar to save your work. Alternatively, you can select File
| Save All from the menu.
to
shuttle both tables to the Selected list.
to shuttle the selected attributes from the Selected list.