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 for Java (BC4J) framework to provide
the data-access layer
Move
your mouse over this icon to show all screenshots. You can also move your mouse
over each individual 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 Business
Components for Java (BC4J). 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 BC4J, 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.
A single frame can be created to control the branches
without requiring any code changes in the branch applications.
Each branch remains a runnable application.
Creation of a Business Componets project that supports
partioning of branches with unique databindings
Permit the client application to reuse a single Business
Component connection throught
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 need to first create
a project to contain the business components. This procedure shows you
how to set up your workspace and use the Business Components from Tables
wizard to populate the model project.
Create a new Application workspace to hold
the Model and ViewController components File | New.
Select the Application workspace node.
Click OK. This launches a dialog which allows you to define location,
templates, 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, complete
the dialog in the wizard
Right-click on the Model project and select New. This launches
the New Gallery dialog.
In the New Gallery dialog 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 please refer
to the 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 please
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 Installing
the Sample Schemas and Establishing a Database Connection
tutorial.
Click OK. This launches the Create Business Components from Tables wizard.
3
.
The Business Components wizard
In Step 1 of the Wizard, CUSTOMERS, ORDERS and ORDER_ITEMS
tables in the Available list and click the Move button to move those selections
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.
5
.
In the Application Module page, deselect
the ApplicationModule option. Later, you create specific
application modules with a different Business Components wizard.
Click Finish to create the business components in the Model project.
6
.
Select the model project from the Navigator
right click and choose Make Model.jpr 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 Data Model page, select the CustomersView
object from the Available View Objects list and click the Move button
to move this single selection to the Data Model tree.
In the Data Model pane, select the CustomerView1
object, then in the Available View Objects pane move the OrdersView
via Customer FK1 to the Data Pane.
Move the other view objects to the Data Pane so that the application module
looks like the screen shot below.
The sequence to create the application module components is crutial:
To create the CustomerView:
In the Available Objects pane, select CustomerView
and move it to the Data Model Window.
Select the node (CustomerView1)
you just added to the Data Model pane.
Again,in the Available View Objects pane, select the child node (OrdersView
via OrdersCustomer IDFkLink) and move it to the Data Model pane.
Select the node (OrdersView1
via OrderCustomer via OrdersCustomer IDFkLink) you just added
to the Data Model pane.
Finally, in the Available View Objects pane, select the child node
of the OrdersView (OrderItemView
via OrderItemsOrderIdFkLink) and move it to the Data Model pane.
In the Data Model pane, it should appear as a grand child of the CustomerView1
instance.
To create the OrderView:
In the Data Model Pane, select the application Module name (MasterDetailDetailAppModule),
In the Available View Objects pane, select the OrdersView
node and move it to the Data Model pane.
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 window.
A child instance of OrdersView2
should be created, named OrderItemsView2
via OrderItemsOrderIdFkLink2.
4
.
Click Finish to add the Application Module to your
project.
Define
the Data Model for the Combined Application
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 aren't going to use the Data Model page,
so click Next.
4
.
In the wizard page Step 3 of 4: Application Modules, select
the MasterDetailDetailAppModule1
object in the Available list and click the Move button to move this
single selection to the Selected list.
5
.
Make no further selections, click Finish to add
the Application Module to your project.
Right-click on the Model and choose Make to compile the
project.
6
.
In the Navigator your Model node should look like
this.
Step 3- Create the JClient Customer Form
In this topic you use the 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.
In 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
.
In 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 launches.
6
.
Click Next to step past the Welcome page.
Open the Application Module dropdown 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, 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 in the wizard and click Next.
9
.
In the Panel View page, ensure that CustomersView1
is selected as the view object, and click Next.
10
.
In the Attribute Selection page for view object attributes,
move the CustAddress and
PhoneNumber
to the left window, 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 filenames.
12.
Click Next then click Finish to add the JClient
files to your project.
View your JClient project in the Navigator. It should contain the files
as below:
13
.
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.
14
.
In the Navigator, select FormCustomerView1.java,
then in the menu choose Run | Run FormCustomerView1.java.
The Customer's form will be displayed.
Close the JClient form.
Step 4- Create the JClient Orders Form
The following steps show you how to use the 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.
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
.
In the Form Layout page, accept the defaults and click
Next.
5
.
In the Data Model page, ensure the MasterDetailAppModuleDataControl
Data model Definition is selected from the drop down list.
6
.
In the Panel View page, select the OrdersView2
as the master and OrdersItemsView2
as the detail. Click Next.
7
.
In 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
.
In 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
.
In the File Names page, change the Package Name
to ordersform and accept
the filenames.
10
.
Click Next then click Finish to add the JClient
files to your project.
The new form opens in the UI Editor. Make and Run ordersform.FormOrdersView2OrderItemsView2.java
.
Choose Run | Make View.jpr to compile the project, then run the project.
Step 5- Edit UI Properties of Business Components
The following steps show how to set control hints
on the Business Components. Control hints let you 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 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
and in the Label Text field enter Order
ID. Click OK.
The Business Components project saves these attribute-level properties
in a .java resource file for use by the client at runtime. 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 Wizard for
the OrderTotal element and
enter Order Total in the
Label
Text control hint.
6
.
In the Structure window, open the Attribute Wizard for
the CustomerId element and
enter Customer Identifier
in the Label Text control hint.
7
.
From the Navigator, select View, and right-click
the FormOrdersView1OrderItemsView2
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. On the top you should see the Next
and Previous navigator buttons that let you browse through orders data.
Close the application window or choose Run | Terminate View.jpr
before moving on to the next step.
Step 6- Creating 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 the 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:
With the View project selected in the Navigator, create a frame by
selecting File | New.
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.
2.
Click Next to step past the Welcome page.
In the Form Name page, change the Package Name to rootpartition
and change the Form Name to MainForm.
Deselect Generate a menu bar
in order to generate a form without a menu bar.
Click Next 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.
3
.
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.
The 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.
4
.
To modify the JClient code:
With MainForm.java open
in the UI Editor, select the Source tab.
5
.
Add these import statements to the list, at the top of the
source code (be careful not to remove the existing import statements):
import customerview.FormCustomersView1;
//must match package.form for customers
import orderview.FormOrdersView2OrderItemsView2; //must match package.form
for orders
These two statements let you create the two forms from the JClient form
packages.
6
.
Below the form layout declarations add these class variable
declarations:
private
FormCustomersView1 customerframe; //must match customer form name
private FormOrdersView2OrderItemsView2 orderframe; //must match orders
form name
These statements let you call the constructor for the Customer and Orders
forms in the action handlers that you are going to add later.
Choose File | Save All to save all the files.
7
.
View your JClient project in the Navigator. It should contain
these files:
Step 7- Adding Navigation to Open the Forms
The following steps describe how to add buttons to
the main application window in order to display the Customer 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.
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
.
Select the JButton icon in the Component Palette,
then click inside the UI Editor to add the component to the frame.
Repeat this procedure to add a second button to the frame.
4
.
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 labels for JButton1
and JButton2 to Customer
and Orders.
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 opens.
Click OK to add the method stub for the action handler to the
frame.
The actionPerformed window disapears.
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();}
//must match customer form name
// 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, right-click and choose UI Editor from
the menu.
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.
6
.
Click inside the actionPerformed event field and
click the ellipsis button to edit the action handler.
The actionPerformed dialog opens.
7
.
Click OK to add the method stub for the action handler
to the frame.
The Code Editor opens with the second action handler inserted into
MainForm.java.
8
.
Replace the entire jButton2_actionPerformed action handler
with this code:
if (orderframe==null)
{ orderframe = new FormOrdersView2OrderItemsView2();}
//must match orders form name
// Create the panel binding
for the Orders form.
orderframe.setBindingContext(panelBinding.getBindingContext());
int width = 300;
int height = 300;
orderframe.setSize(width, height);
// Determine the new location
of the window.
int w = orderframe.getSize().width;
int h = orderframe.getSize().height;
Dimension dim = Toolkit.getDefaultToolkit().getScreenSize();
int x = (dim.width-w)/2;
int y = (dim.height-h)/2;
// Move the window.
orderframe.setLocation(x, y);
orderframe.setVisible(true);
}
9
.
In the Navigator, select the MainForm, right-click and
choose Run to compile the file. You should receive no errors or
warnings. Press the Customers button and the Orders button to see these
forms run.
Modify the data bindings for the Orders form.
In the Navigator, open the PanelOrdersView2UIModel.xml
file and in the Struture pane, double click on OrdersView2Iter,
change the name to OrdersView3Iter
and select OrdersView1
under CustomerView1.
Make sure to select the iterator binding nest below the CustomerView1
node. When you press OK, a message will popup informing you that the binding
will change and it may affect the application. This is not a problem for
us.
This step associates the customer's order instance with the iterator
you just created.
3
.
Select PanelOrderItemsView2UIModel.xml
and double-click on OrderItemsView2Iter:
rename it to OrderItemsView3Iter
and base it on the OrderItems instance OrderItemsView1.
Make sure to select the iterator binding nest below the CustomerView1
- OrderView1 node. When you press OK, a message will popup informing
you that the binding will change and it may affect the application. This
is not a problem for us.
This step associates the customer's order item instance with the iterator
you just created.
5
.
Run the MainForm.java
file and test for synchronization between Customers and Orders. As you
navigate through the customers in the Customer Form, the Orders form should
display only those orders for the displayed customer.
Summary
In this tutorial you assemblded an application and learned
about these features of JDeveloper:
Creating a workspace for multiple projects
Creating a Business Components project with BC4J wizards
Creating a project for your JClient application
Creating a master and detail form with JClient wizards
Utilizing the Component Palette to modify generated code
Utilizing the Code Editor to modify generated code
Utilizing the UI Editor to view and edit a JClient form
Utilizing the Structure window to view application elements
Bookmark
