Creating an ADF JClient Application for Business Components
Creating an ADF JClient Application for Business Components
Purpose
This tutorial shows you how to use JDeveloper to create
databound forms. When you complete this tutorial, you will have experience with
several Oracle technologies for creating and deploying thin Java clients:
Oracle ADF JClient–enabled Swing components
to create databound forms
Oracle ADF Business Components framework to provide
the data-access layer
Place the cursor on this icon to show all screenshots. You can also place the
cursor on each icon to see only the screenshot associated with it.
Overview
This tutorial shows you how to use JDeveloper to create
a databound client that uses JClient forms to interact with ADF Business Components.
The client, in this case, provides order-entry services with master-detail views
based on the Order Entry schema.
You can run the JClient application after completing the tutorial to query and
update records in several frames that also demonstrate master-detail navigation
functionality.
The primary goal of this tutorial is to show how JClient's
databinding mechanism, together with ADF Business Components, supports thin
client application development. The key concepts illustrated are:
Partitioning the client application so that separate
"end-user branches" or UI tasks have their own databinding
Creating a single frame to control the branches
without requiring any code changes in the branch applications
Ensuring that each branch remains a runnable application
Creating a Business Components project that supports partitioning of branches with unique databindings
Permitting the client application to reuse a single Business Components connection throughout
Lazy loading of data, wherein each branch gets its databinding, depending on the end user's action at the level of the calling frame
This application contains three JClient
forms: the Customers and Orders forms display data from their associated tables
(CUSTOMERS and ORDERS) in the database, the MainForm
is a launch pad to run the Customers and Orders forms.
In order to create an ADF JClient application based on an
ADF Business Components application module, you must first create a project
to contain the business components. This procedure shows you how to set up your
workspace and use the Create Business Components from Tables Wizard to populate
the model project.
Create a new Application workspace to hold
the Model and ViewController components.
From the Menu File | New select the Application Workspace node
and Click OK. This launches a dialog box that you can
use to define the location, template, and application package prefix.
2.
Change the name of the Application workspace to JavaForms.
For the application template, select Java
Application (Default).
Click OK.
3
.
On completion, you should have an application named JavaForms
and two projects named Model and View.
To build the business components for this tutorial,
follow the steps given in the dialog boxes.
Right-click the Model project and select New. This launches the
New Gallery dialog box.
In the New Gallery dialog box, select the Business Components category
and then the Business Components from Tables item, and click OK.
If you need more details regarding building business services, refer
to Creating
a Business Model using ADF Business Components. In this section,
you simply generate a business service and make some small changes to
the model, as needed for the tutorial.
2.
In the Business Components Project Initialization dialog box,
select your OE database connection. If you do not have one, create a new
connection pointing to the OE schema. Install the sample schema and create
a connection to the HR or HR8 schema to use in this lesson. See the Installing
the Sample Schemas and Establishing a Database Connection
tutorial.
Click OK. This launches the Create Business Components
from Tables Wizard.
3 .
Click Next on the Business Components Wizard's Welcome page.
In Step 1 of the wizard, select the CUSTOMERS, ORDERS, and ORDER_ITEMS tables from the Available list and click the
Move button to move the selected tables to the Selected list. Click Next
to continue.
4 .
In Step 2, the View Objects page, move CustomersView, OrderItemsView,
and OrdersView to the Selected list. Click Next
to continue.
Click Next to skip Step3 of the Business Components
Wizard.
5 .
On the Application Module page, deselect the ApplicationModule
option. Later, you create specific application modules with a different
Business Components wizard.
6.
Click Finish to create the business components
in the Model project.
7.
Select the Model project from the Navigator, and right-click and choose
Make to compile and save the project.
Before you can use the business components in your Model project for the
JClient forms, you must first create the data model based on ADF Business
Components application modules. This procedure shows you how to use the New
Application Module Wizard.
With the Model package node selected in the Navigator, right-click
and choose New and select Application Module from the
Business Components node, to create the first application module for
your Model project.
2.
Click Next on the Welcome page to begin.
Enter the Name MasterDetailDetailAppModule
and click Next.
3 .
In the Available Objects pane, select the CustomersView
object from the Available View Objects list and click the Move
button to move this single selection to the Data Model pane.
4 .
In the Data Model pane, select the CustomerView1
object you just added. Then, in the Available View Objects pane, select
the child node OrdersView via
OrdersCustomerIdFkLink and move it to the Data Model pane.
5 .
Select the node (OrdersView1
via OrderCustomer via OrdersCustomer IdFkLink) you just added to
the Data Model pane. Then, in the Available View Objects pane, select
the child node of the OrdersView
(OrderItemsView via OrderItemsOrderIdFkLink)
object and move it to the Data Model pane.
The application module looks like the screenshot below:
6 .
In the Data Model Pane, select the application module name (MasterDetailDetailAppModule).
Then, in the Available View Objects pane, select the OrdersView
node and move it to the Data Model pane.
7 .
A new data model instance is created, named OrdersView2.
Select it and in the Available Objects pane, select the child node OrderItemsView
via OrderItemsOrderIdFkLink. Move it to the Data Model pane.
A child instance of OrdersView2
should be created, named OrderItemsView2
via OrderItemsOrderIdFkLink2.
The application module looks like the screenshot below:
8 .
Click Finish to add the application module to your project.
With the Model package node selected in the Navigator, right-click
and choose New and select Application Module from the
Business Components node, to create the first application module for
your Model project.
2.
Click Next on the Welcome page to begin.
Enter the Name RootAppModule
and click Next.
3
.
This time you are not going to use the Data Model page, so click Next
on the Step 2 of 4: Data Model page of the wizard.
4
.
In the wizard's Step 3 of 4: Application Modules page, select the MasterDetailDetailAppModule
object in the Available list and click the Move button to move
this single selection to the Selected list.
5
.
Make no further selections, and click Finish to add the application
module to your project.
Right-click the Model and choose Make to compile the project.
6
.
In the Navigator, your Model node should look like this:
Create the JClient Customer Form
In this topic, you use the Create JClient Form Wizard to
create a single table form for browsing the Customer
table.
With the View project selected in the
Navigator, right-click and choose New.
2.
In the Categories list, expand Client Tier and select Swing/JClient
for ADF. Then select Form from the Items list and click OK.
3 .
Click Next to step past the Welcome page of the Create JClient
Form Wizard.
On the Form Types page, accept the default selections, Single Table as
the form type, and Form (A form is a top-level window.)
Click Next.
4 .
On the Form Layout page, accept the defaults and click Next.
5 .
The Data Model page appears and is blank; click New
to define a data model for the page.
The ADF Business Components Client Data Definition Wizard is launched.
6 .
Click Next to step past the Welcome page.
Open the Application Module drop-down list and view the previously created
application modules from your Model project. Select the model.MasterDetailDetailAppModule
item. No other selections are needed. Click Next.
7 .
View the default name for the JClient data model, and then click Finish.
JDeveloper adds the JClient configuration file (DataBindings.cpx)
to the JClient project. The file will eventually contain all of the data
model definitions that your Swing client uses.
8 .
Confirm that the newly-created data model (MasterDetailDetailAppModelDataControl)
is displayed on the wizard page and click Next.
9 .
On the Panel View page, ensure that CustomersView1
is selected as the view object, and click Next.
10 .
On the Attribute Selection page for view object attributes, move the
CustAddress, PhoneNumbers,
and CustGeoLocation attributes
to the Available attributes list, and leave the rest in the Selected Attributes
list.
Click Next.
11 .
In the File Names page, change the Package Name to customerform
and accept the file names.
12.
Click Next, and then click Finish to create the
form.
13 .
View your JClient project in the Navigator. It should contain
the files as below:
14 .
JDeveloper opens the file in the UI Editor where you can
view the components that the wizard created for the form's panel.
Save your work.
15 .
In the Navigator, right-click FormCustomersView1.java,
and then select Run from the context menu.
16 .
The Customer's form is displayed.
Close the JClient form.
Create the JClient Orders Form
The following steps show you how to use the Create JClient
Form Wizard to create a master-detail form for browsing the Orders
and Order Items tables.
With the View project selected in the
Navigator, create a form by selecting File | New.
2.
In the Categories list, expand Client Tier and select Swing/JClient
for ADF. Then select Form from the Items list and click OK.
3 .
Click Next to step past the Welcome page of the wizard.
In the Form Types page, accept the default selections Master/Detail Table
as the form type and Form (A form is a top-level window.).
Click Next.
4 .
On the Form Layout page, accept the defaults and click Next.
5 .
On the Data Model page, ensure the MasterDetailAppModuleDataControl
data model definition is selected from the drop-down list.
6 .
On the Panel View page, select the OrdersView2
as the master and OrderItemsView2
as the detail. Click Next.
7 .
On the Attribute Selection page for master view object attributes, select
the OrderMode attribute
from the Selected attributes list and click the Remove button to move
this selection to the Available attributes list. Do the same for the OrderStatus,
PromotionId, and SalesRepId
attributes.
The Selected attributes list should now show only OrderId,
OrderDate, CustomerId,
and OrderTotal. Click Next.
8 .
On the Attribute Selection page for detail view object attributes, select
the ProductId attribute
and click the Remove button to move this selection to the Available attributes
list.
The Selected attributes list should now show only OrderId,
LineItemId, UnitPrice,
and Quantity.
Click Next.
9 .
On the File Names page, change the Package Name to ordersform
and accept the file names.
10 .
Click Next, and then click Finish to add the JClient files to
your project.
11.
The new form opens in the UI Editor.
12 .
Make and Run ordersform.FormOrdersView2OrderItemsView2.java
.
Choose Run | Make View.jpr to compile the project, then run the
project.
Edit UI Properties of Business
Components
The following steps show how to set control hints on Business
Components. Using control hints, you can customize the UI for attributes that
your forms display.
Choose View | Structure if the Structure
window is not already visible in the Navigator window.
In the Navigator, expand the "model" node of the Model project
and select OrdersView.
2.
In the Structure window's Attributes folder, right-click OrderId
and choose Edit OrderId to modify the display properties of this
Business Components attribute.
The Attribute Editor opens for the OrderId
attribute.
3
.
Select Control Hints to display the Attribute page. Enter Order
ID in the Label Text field. Click OK.
The Business Components project saves these attribute-level properties
in a .java resource file
for use by the client at run time. The control hint values you define
for the Business Components attributes also appear in the UI Editor where
you lay out the form.
4
.
In the Structure window, open the Attribute Editor for
the OrderDate element and
enter Order Date in the
Label
Text control hint.
5
.
In the Structure window, open the Attribute Editor for the OrderTotal
element and enter Order Total
in the Label Text control hint.
6
.
In the Structure window, open the Attribute Editor for
the CustomerId element
and enter Customer Identifier
in the Label Text control hint.
7
.
From the Navigator, select View, right-click the FormOrdersView2OrderItemsView2
class, and choose Run FormOrdersView1OrderItemsView2.java as an Application
to run the application.
8
.
You should see the Orders form with the orders data
and customized labels displayed in a table. At the top, you should see
the Next and Previous navigator buttons that you can use to browse through
the orders data.
Close the application window or choose Run | Terminate View.jpr
before moving on to the next step.
Create a Frame to Run the Application
The following steps describe how to create an empty JClient
form that you can customize with JClient code in order to create a Business
Components connection that two JClient forms will reuse. The JFrame includes
a main() routine to run the frame
and execute the JClient code.
To create an empty JClient form to serve as the application's main window,
perform the following steps:
With the View project selected in the Navigator, create a frame by selecting
File | New.
2.
In the Categories list, expand Client Tier and select Swing/JClient
for ADF. Then select Empty Form from the Items list.
The Create JClient Empty Form Wizard opens.
Click Next to step past the Welcome page.
3.
In the Form Name page, change the package name to rootpartition
and change the form name to MainForm.
Deselect the "Generate a menu bar" check box to generate a form
without a menu bar.
Click Next, and then click Finish to add the JClient
empty form to your project.
JDeveloper opens the file in the UI Editor where you will eventually lay
out the form with components from the Swing component palette.
4.
The Create JClient Empty Form Wizard generates the empty form with the
navigation bar and status bar for use with a form to which you add databound
components. In this tutorial the empty form is not used to display data.
5 .
In the UI Editor, with MainForm.java
displayed, select the grayed-out navigation bar, right-click, and choose
Cut to remove this component from the empty form.
Select the grayed-out status bar at the bottom of the empty form, right-click,
and choose Cut to remove it from the empty form.
6 .
To modify the JClient code:
With MainForm.java open
in the UI Editor, click the Source tab.
7 .
Add these import statements to the list, at the top of the
source code (be careful not to remove the existing import statements):
You can use these statements to call the constructor for the Customers
and Orders forms in the action handlers that you are going to add later.
Select File | Save All to save all the files.
9 .
View your JClient project in the Navigator. It should contain
these files:
Adding Navigation to Open the
Forms
The following steps describe how to add buttons to the main
application window in order to display the Customers and Orders forms. The action
handlers for each button include JClient-specific code that works with the previously
created ADF Business Components connection.
To add buttons to the standard frame:
Right-click MainForm.java
in the Navigator and choose Open. Click the Design tab so
that the UI Editor opens with the frame displayed.
2.
In the Structure window, click the UI Struture tab
and expand the UI node until you see the dataPanel. Select the
dataPanel node.
3.
Click the JButton icon in the Component Palette.
4 .
Click inside the UI Editor to add the component to the
frame.
Repeat this procedure to add a second button to the frame.
5 .
Choose View | Property Inspector if the Property
Inspector is not already visible.
With one of the buttons selected in the UI Editor, locate the text
property in the Property Inspector and click inside the field to change
the button's label. Change the text property for JButton1
and JButton2 to Customer
and Orders, respectively.
To create the action handlers for the Customer
and Orders views:
Select the button now labeled Customer in the UI Editor and click the
Events tab in the Property Inspector.
2 .
Click inside the actionPerformed event field and
click the ellipsis button to edit the action handler.
The actionPerformed dialog box opens.
Click OK to add the method stub for the action handler to the frame.
The actionPerformed dialog box disappears.
3 .
Click the Source tab of the UI Editor and replace the
entire jButton1_actionPerformed
action handler with this code:
if (customerframe==null)
{ customerframe = new FormCustomersView1();}
// Create the panel binding for
the Customer form.
customerframe.setBindingContext(panelBinding.getBindingContext());
int width = 300;
int height = 300;
customerframe.setSize(width, height);
// Determine the new location
of the window.
int w = customerframe.getSize().width;
int h = customerframe.getSize().height;
Dimension dim = Toolkit.getDefaultToolkit().getScreenSize();
int x = (dim.width-w)/2;
int y = (dim.height-h)/2;
// Move the window.
customerframe.setLocation(x, y);
customerframe.setVisible(true);
}
4 .
With the MainForm.java
file selected in the Navigator, click the Design tab.
The UI Editor opens again with the frame displayed.
5 .
Select the button labeled Orders in the UI Editor and click the Events
tab in the Property Inspector.
Bookmark
