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 steps you through the development of a data model for an order entry
application.
You have been
given the task of creating a data model to support an Order Entry application.
The data model must contain logic that supports the rules of the business. Because
the rules are enforced inside the data model, all client applications that use
the model will always follow the basic rules of the business. You will build these
rules using Orace ADF Business Components.
In this step you will create a new application
workspace and project to help organize your application. All of the work you do
in JDeveloper is organized into projects within an application workspace. After
you have created a workspace and project, you will create a default Business Components
Model for your business.
Create a new Application workspace
to hold the business model components. Select File | New, then select
the Application workspace node. Click OK.
This will open a dialog
where you can define location, templates, and application package prefix
2.
Change the name of the application
to OEApplication. Accept the other defaults for the application and click OK.
3.
On completion you should have an application
named OEApplication and two projects named Model and ViewController.
You will only use the Model project for this exercise.
It is generally
easier and more effective to start with a set of default business components than
to create each one individually. Whichever technique you use will result in a
set of components that you can customize to fit your specific business needs.
To
create a set of default business components, right-click the Model project
node in the System Navigator and select New.
2.
This opens the New Gallery wizard.
From this gallery, select the Business Components category and Business
Components from Tables.
3.
Selecting Business Components from
Tables opens the Business Components wizard. The first step of this wizard
is to establish a connection to your database. Select the connection name that
connects to the OE schema.
Note: If you have not established this connection to the OE schema,
please see the prerequisites section.
4.
In step 1 of the Business Component wizard, select the tables for which you
want to create entity objects. Select the Customers, Inventories,
Orders, OrderItems, ProductDescriptions, and ProductInformation
tables.
5.
In step 2 of the wizard, select which
view objects you want to create from the default entity objects. These view objects
will be updateable. In the next step, you can create view objects that are read-only
and that are based on tables, not on entity objects. Select all of the available
entity objects and click the shuttle button.
6.
In step 3 of the wizard, you can
create view objects that are based on tables, not on entity objects. These view
objects are useful for any view that will not be updateable.
7.
In step 4 of the wizard, change the
name of the Application Module to OEAppModule. If the Application Module
checkbox is checked, the wizard will create a default application module for you.
If
it is not checked, check it.
8.
The last step of the wizard confirms
what Business Component objects you are about to create.
9.
Your project should now include an
application module with entity and view objects.
JDeveloper
includes a built-in Business Components Browser that tests business components.
The browser works without requiring you to build any client code.
To
invoke the tester, right-click the Application Module you just created in the
System Navigator and select Test from the context menu.
2.
The first step of the Tester is to
select a database connection to use for this test. Select the database connection
you used to create the default objects and click Connect.
3.
The Business Components Browser shows
all of the View objects defined in your Application Module.
4.
Double-click a view object instance
to display a single-record data viewer.
You can scroll through the rows in this View object using the controls
on the top of the window. You can double-click other View objects to run multiple
data viewers.
The Business Components Browser gives you a view of the application
module that you have just created.
The Business Component wizard creates
a single View object for each Entity object created. While this is useful in most
cases, you will probably need to create a View object that combines attributes
from multiple Entity objects. For example, the OrderItemsView contains information
about the Item within an Order but does not include information about the Item,
such as a description of the item. In this step, you will add some product information
to the OrderItemsView.
1.
In the System
Navigator, right-click OrderItemsView and select Edit from
the context menu
2.
Use the View Object Editor to add
the ProductInformation entity to the list of selected entities for this
View object.
3.
Now that you have selected the additional
entity, you need to select the attributes you want to add. Click the Attributes
node and select ProductName and ProductDescription from the available
attributes list and shuttle them to the selected list.
4.
Click the Query node to inspect
the changes that JDeveloper made to the query. Notice that the query now includes
a join to the ProductInformation table and that it includes the two new
columns.
Click OK to accept the new query.
5.
Run the Tester again only this time
double-click the OrderItemsView1 view object. Notice that it now shows
all of the attributes it did before plus the new attributes ProductName
and ProductDescription. If you need help running the Tester, see Testing
Business Components in Step 1 of this tutorial.
So far, you have created some default business
logic and have expanded a view to meet your requirements. Now you need to add
some validation to the business model. In ADF Business Components, validation
is done in the business logic tier, not in the client. To validate business rules,
you modify the objects responsible for persisting data, which are entity objects.
There
are two different types of validation that you can add to the business model:
Attribute-level validation and Row-level validation. Attribute-level
validation is used to check values within a single attribute. Row-level
validation is used when a value must be checked against other attributes or entities.
In this step, you will add validation of both types to your model.
In our business, we
keep track of many orders. Each order is assigned a status code that indicates
the current status of the order. There is a list of valid codes, but the numbers
range from 0 to 10. In this step, we will add a validator that will make sure
that only values in that range are entered.
In the System
Navigator, right-click the Orders entity and choose Edit Orders.
2.
In the Entity Object Editor, click
the Validation node. The Editor now shows the entity and all of the attributes.
3.
Select the OrderStatus attribute
and click New. This will launch the Validation Rule editor for the OrderStatus
attribute.
4.
In the Validation Rule Editor, select
the RangeValidator rule and the Between operator. Enter a 0 (zero)
in the Minimum Value and a 10 (ten) in the Maximum Value. Enter a message in the
Error Message field that will help a user correct the error if they enter an invalid
status.
Click
Ok to accept the new rule.
5.
After accepting the rule you that just created, you can continue to create
additional attribute-level rules.
When you are done with the attribute-level rules, click OK.
6.
Now that you have added a rule, it's
time to test it. You test the rule by running the Business Components Browser.
Right-click the application module and select Test
from the context menu, just as you did earlier.
7.
Double-click the OrdersView1 node
to open the OrdersView window.
8.
Try to modify the OrderStatus
to a value that is not in the valid range (0-10). Notice that when you enter a
value that is outside the range, ADF Business Components raises an exception that
includes the error message you entered on the validation rule.
When
you are finished testing the rule, close the Tester.
Adding
Row-level Validation
The next business rule you
will add to the model is a rather simple rule. The rule is that customers cannot
order items that we don't have in stock. In other words, we don't allow backorders.
Although the rule is simple enough, it will take a little code to enforce the
rule. ADF Business Components provides hooks and accessor methods that make it
easy to implement.
In this section, you will add some validation
code and add a new validation rule to the OrderItems entity. We provide the code
for you to make it a little easier for you.
Click the OrderItems entity
in the System Navigator. The Structure pane now displays all of the components
that are part of the entity.
2.
OrderItemsImpl.java
is the java class that you will use to validate row level data.
Double-click
OrderItemsImpl.java to edit the implementation class for the OrderItems
entity. This will open the java file in the editor window.
3.
Add the following method to the end
of the class. Take a look at the previous image to see where it goes. You can
copy and paste this code directly into the code editor.
public
boolean validateOnHandQuantity (Number ordered) { /**
Create a RowIterator of all the Inventories for the Product you are * ordering.
We are traversing the association from OrderItems to * ProductInformation
to Inventories. These methods are created * automatically when the association
is created. */
RowIterator inventoryItems = getProductInformation().getInventories();
int quantityOnHand = 0;
/** Loop through all the Inventories and sum
the QuantityOnHand */
while (inventoryItems.hasNext()) {
InventoriesImpl inventoryItem = (InventoriesImpl)inventoryItems.next();
int quantity = inventoryItem.getQuantityOnHand().intValue(); quantityOnHand
+= quantity; }
/** Check if the ordered quantity is less than or
equal to the total onHand */
if (ordered.doubleValue() <= quantityOnHand)
return true; else return false;
}
4.
After you have added the code, right-click
anywhere in the code editor window and select Make from the context
menu. This compiles the code and checks for errors. Notice that there is an error
"class RowIterator not found". This error is because we have not added
the proper import statement to this class yet.
Notice also that in the code
editor, RowIterator is underlined
in blue. JDeveloper is giving you hints on what needs to be fixed in this class.
In the next step, we'll use a JDeveloper feature to add the proper import for
this class.
5.
Move the cursor over the RowIterator
statement in the code editor. JDeveloper shows a balloon-style message that says
"Import oracle.jbo.RowIterator ( Alt + Enter)". If you hit Alt
+ Enter, JDeveloper will add the import statement for you.
Hit Alt
+ Enter to add the import statement.
6.
Now that you have added the import
statement, compile the class again.
Right-click anywhere in the code editor
and select Make from the context menu.
This
time you get a message saying that the class compiled successfully.
Now
that you have a method that will validate the number of items in stock, you can
add the validation rule that will use that method.
7.
Right-click the OrderItems
entity object in the System Navigator and select Edit OrderItems.
You could also double-click the OrderItems entity to open the editor.
8.
In the Entity Object Editor, click
the Validation node. The Editor now shows the entity and all of the attributes.
9.
Select the Quantity attribute
and click New to open the Validation rule dialog and create a new rule.
10.
Select MethodValidator from
the Rules drop-down list. JDeveloper will automatically look in the Implementation
class for any custom methods that you have added. Select the one that you want
to use for this rule. In this case, there is only one method available which is
validateOnHandQuantity(oracle.jbo.domain.Number
ordered.
Select that method and add a reasonable error message
in the error message field.
Click
OK to accept the new rule.
Click OK to accept the changes
you have made to the OrderItems entity.
11.
Now that you have added this rule,
it's time to test it. You test the rule by running the Business Components Browser.
Right-click the application module and select Test
from the context menu, just as you did earlier.
12.
Double-click the OrdersItemsView1
node to open the OrderItemsView window.
13.
Try to modify the Quantity
to a value that is probably not in stock (try 800). Notice that when you enter
a value that is over what is in stock, ADF Business Components raises an exception
that includes the error message you entered on the validation rule.
When
you are finished testing the rule, close the Tester.
Summary
In
this tutorial you learned how to use ADF Business Components to build a model
that supports your business rules. You have learned how to add simple, declarative
validation rules and how to add custom methods to validate more complex business
needs.
You have also learned how to test your business
model using the built-in ADF Business Components Tester.
Bookmark
