Place the cursor over this icon to load and view all
the screenshots for this tutorial. (Caution: Because this action loads all screenshots
simultaneously, response time may be slow depending on your Internet connection.)
Note: Alternatively, you can place the cursor
over each individual icon in the following steps to load and view only the screenshot
associated with that step.
Overview
Within a tool such as Oracle Forms or Designer, you
can declaratively define simple business rules and validation. For example,
you can specify that a commission rate must be within certain range or you can
define the default value for a field.
Similarly, Oracle JDeveloper and ADF also provide you
with declarative validation, and in many ways, offer you a richer choice of
declarative validation than you have in Forms.
The database schema you are working with already imposes a number of business rules on the data through constraints and PL/SQL in the database. For example, the credit limit for the customer must be less than or equal to 5000. However, in this tutorial you use business components to declaratively impose validation at the middle tier before committing the data to the database.
Corporate business rules define 5000 as the absolute upper limit of credit that a customer can have. However, for order entry purposes, it has been decided to never allow the customer credit limit to be set to more than 4000. This business rule is to be implemented within the order entry application.
To implement validation within an entity object, perform the following steps:
1.
In the Applications Navigator, expand the OrderEntry | Model
project and the Application Sources | model package.
Right-click the Customers entity object and select
Edit Customers from the context menu.
2.
In the Entity Object Editor, select Validation from the tree control.
Select CreditLimit from the Declared Validation Rules list.
Click New to add a new set of validation criteria.
3.
Use the Rule dropdown list to review the different types of Rules available
to you.
In this case you need the Compare Validator, so select
that from the Rule dropdown list, and select or enter the following
values:
Attribute
CreditLimit
Operator
LessOrEqualTo
Compare With
Literal Value
Enter Literal Value
4000
Error Message
Credit limit for the customer must be less than 4000
Click OK.
You have added a piece of validation. Note that this validation rule
has been added at the entity object level. This means that it is reused
in all the view objects and application modules that access it.
If you have time: Try adding other simple validation rules, such as:
Restrict the values for Marital Status to either 'married' or 'single'.
Restrict the values for Gender to either 'M' or 'F'.
Hint: Use a List Validator rule for
this type of validation. The available help gives advice on how the
list items should be added.
You want to ensure that data appears with a consistent format, regardless of how it is accessed. In this case, the credit limit is a monetary amount and so should appear with the correct currency symbol and decimal separators. In addition, the date of birth should appear in MM/DD/YY format.
To add format masks to the credit limit and date of birth attributes, perform the following steps:
1.
With the Entity Object Editor open for the Customers
entity object, expand the Attributes node in the tree
control.
Select CreditLimit from the expanded node and select the Control Hints tab.
2.
Select Currency from the Format Type dropdown list.
Enter Tooltip Text of your choosing.
3.
Select the DateOfBirth attribute from the tree on the left and click the Control Hints tab.
Select Simple Date from the Format Type dropdown list.
The predefined format masks in the Format dropdown list do not fit
your needs, so enter your own format mask into the Format field: MM/dd/yy
and click Apply to accept these changes.
Note: The format mask is case-sensitive and must be
typed exactly as shown.
4.
While the Control Hints tab is active on
the right, click the attributes in the tree on the left and update the
Label Text for the attributes CustFirstName to display the label "Name"
and CustLastName to display the label "Surname".Click Apply to accept these changes.
Note: This formatting has been added at the entity
object level. This means that it is reused in all the view objects and
application modules that access it.
There are some fields which should automatically be populated with default values. In this case, the CreditLimit for a new customer is defaulted to 100. The operator can of course override this, but the default should be imposed within this application, similar to an initial value in Forms.
To add the default value to the entity object,
perform the following steps:
1.
If you have closed the editor, then open the Entity Object Editor for
the Customers entity object and expand the Attributes
node in the tree control.
Select CreditLimit from the expanded node and select
the Entity Attribute tab.
Set Default to 100 and click OK to
update the entity object and close the editor.
The above changes were made at the entity object level.
You can also make these changes at view object level. In the OrderEntry application
there are a number of view objects that use the same entity object. In most
cases it makes sense to update the properties at the entity object level. If
you think of the view object as a query, for example, selecting columns from
a number of tables, then in some instances you may want to change some attribute
properties at the view object level instead of the entity object level. You
may for example want to create a view object for a list of values web page or
have an order by clause on the view object. In this exercise, all we do is make
a few adjustments at the View object level to illustrate the point.
Oracle Designer users may be familiar with this concept.
In Designer you can set display properties at Table definition level and all
module components then reuse these settings, or you can set them at module component(block)
level, where only those modules (forms) that use the module components are affected.
To modify a view object, perform the following steps:
1.
In either the diagram or the Applications
Navigator, double-click CustomersView to invoke the
View Object Editor. The CustomersView is in Model | Application
Sources in the model.queries package
Expand the Attributes node in the tree control and
select CustLastname and then select the Control
Hints tab.
2.
Note that the Label Text is blank. This
means that the default label is used, or that the Label Text set at
entity object level applies.
Change the Label Text to VO Last Name in order to
demonstrate that the VO will override the EO attribute setting. Leave
the others unchanged.
3.
Change the order of objects queried by setting the ORDER
BY clause on the query.
Select SQL Statement in the tree control.
Click Edit to the right of Order By.
4.
This dialog allows you to create a complex expression.
For this tutorial we just want to add a single column. As the dialog
starts off quite compact, it is worth resizing it to see more detail.
Click
to add a new value to the expression.
In the Order By dialog, expand Customers in the Expression
Palette.
5.
Select CUST_LAST_NAME and click
to shuttle it to the Expression field on the left hand side.
6.
Click Validate to add the column to
the Order By list and then click OK.
Note: The view object is just a SQL query, so you can tune it using
Optimizer Hints and view the Explain Plan. See the Tuning section in
the tree control.
7.
Click OK to finish editing the view
object.
If asked if you want to test the SQL query syntax for correctness,
click Yes, then click OK to acknowledge
that the query is valid.
Oracle JDeveloper contains a Business Components Browser
that enables you to test business components without the need to build any client
code.
To use the Business Components Browser to test the functionality
that you have built for your business model, perform the following steps:
1.
In the Applications Navigator, expand model.services
and right-click CustomerOrdersBusinessServices and
select Test from the context menu.
2.
In the Connect window of the Oracle Business
Component Browser, select oeconn from the Connection
Name dropdown list and click Connect.
3.
Double-click CustomersView1 in the Business
Component Browser to run it.
Verify that CreditLimit format mask has been applied and that the tooltip
is working by hovering over the CreditLimit field.
You should also see that any attribute labels you changed, such as
the CustFirstName display, rather than the default label, and that the
VO label, rather than the one defined at the EO level, displays for
the last name.
4.
Update the credit limit to 6000 and
verify that your error message displays
Click OK and change the value back to a value below
4000 so that you can continue.
5.
Scroll through the records by clicking Next
to see that the ordering of the returned customers is by the Last Name.
6.
Click Create
to add a new record. You should see the default value for the credit
limit.
Click Delete
to delete the inserted record.
7.
Now double-click the OrdersCustomerIdFkLink1
view link. This invokes both the CustomersView1 and the Orders
View1 view objects, joined by the view link.
Click the
to see the results in a separate window.
Scroll through the Customers until you find one with at least one order
(e.g. CustomerId 102). If you click back to the other open view object,
CustomersView1, you can see that the same customer
is displayed, because the application module automatically coordinates
all the views.
.
8.
When you are finished testing, you can close the Business
Components Browser window.
6.
Adding a Calculated Field (The rest of this tutorial is optional)
The ORDER_ITEMS table stores only the
quantity of items ordered and the unit price. You would like to display the total
price for each line. You need to add an extra attribute to display this value
and set the calculation.
To add a calculated attribute, perform the following
steps:
1.
In the Applications Navigator or the diagram,
double-click the OrderItemsView to open the View Object
Editor.
Select the Attributes node in the tree
control.
Click New to add a new attribute.
2.
In the New View Object Attribute dialog, set the following properties:
Name
LineTotal
Type
Number
Updatable
Always
Mapped to Column or SQL
Selected
Selected in Query
Selected
Alias
LINE_TOTAL
Expression
UNIT_PRICE * QUANTITY
Click OK.
These values are case sensitive.
3.
When you have added the item you can verify the query
by selecting SQL Statement from the tree control. Select Test to check
your query.
Your query should look like this:
4.
Set the format mask for LineTotal
and UnitPrice as you did for attributes earlier in
the tutorial. Set the Format Type to Currency.
Enter Tooltip Text of your choosing.
5.
Click OK. The modified business components
are now created in the selected project.
7.
Adding Validation to Recalculate a Calculated Field
The LineTotal you added calculates the total when you
query the Orders. Should you change either UnitPrice or Quantity, you want this
value to be recalculated and the new value displayed.
To do this you need to
modify the default behavior that is called when the line total is populated. For each attribute, there are getter and setter methods that are called when the value of the attribute is obtained or written. You need to add code to calculate LineTotal whenever the getter method is called. To recalculate
the calculated attribute, perform the following steps:
1.
To start, you need to generate a view row
object for OrderItemsView. This is called OrderItemsViewRowImpl.java.
To do this, double-click OrderItemsView to invoke
the editor and select the Java node in the tree control.
In the View Row Class: OrderItemsViewRowImpl section, select Generate
Java File. Leave the other values as default. Click OK.
2.
Select OrderItemsView in the Applications
Navigator. You should see the generated Java files in the Structure
window below. You may need to expand the Sources node in the Structure
window.
Double-click OrderItemsViewRowImpl.java to open it
in the editor.
3.
In order for the total to be recalculated when a price or quantity is changed, you need to modify the code in the getter method for LineTotal.
Find the following code:
public Number getLineTotal()
{
return (Number)getAttributeInternal(LINETOTAL);
}
Change it to:
public Number getLineTotal()
{ return new Number(getQuantity().floatValue() *
getUnitPrice().floatValue());
}
The image below is an extract of the changed code.
4.
Now you need to add code to call setLineTotal(null)
to the setter methods for Quantity and UnitPrice. This marks
the row as “dirty” and forces the framework to perform the
recalculation.
The setters for Quantity and UnitPrice should be adjusted as follows:
public void setQuantity(Number value)
{
setAttributeInternal(QUANTITY, value); setLineTotal(null);
}
public void setUnitPrice(Number value)
{
setAttributeInternal(UNITPRICE, value); setLineTotal(null);
}
The image below is an extract of the changed code.
The validation that you have added so far has been mostly declarative and equivalent to what can be done declaratively in Forms. As in Forms, JDeveloper gives you the flexibility to define much more complex validation than is possible declaratively. In Forms you code When-Validate-Item or When-Validate-Record triggers to perform complex validation. When using ADF Business Components, one way to perform custom validation is to modify the Java code for the entity object or the view object.
To add custom validation for the customer's email address, perform the following steps:
1.
In the Applications Navigator, right-click the Customers entity object and select Go to Entity Object Class from the context menu.
2.
CustomersImpl.java, the Java implementation of the Customers entity object, opens in the editor.
Add the following method to the end of the file, just above the closing curly bracket (}):
This code merely checks for the presence of the @ sign in the email address. Of course, in reality you would probably want to make a more complex validation.
The method that you use to validate an attribute must be defined as public, accept a single argument of the same type as
the attribute, and return a boolean value. The method name must start with the keyword validate.
3.
Double-click Customers in the Applications Navigator to invoke the Entity Object editor.
In the Entity Object Editor, select Validation in the tree at the left.
Under Declared Validation Rules, select CustEmail and click New.
4.
In the Add Validation Rule dialog, select MethodValidator from the Rules dropdown list.
Select the validateEmail(String value) method, then type an appropriate
error message, such as Invalid email address.
Once again you can test the changes you have made to
the business components without the need to build any client code. Use
the Business Components Browser to test the functionality that you have built
for your business model as you did before:
1.
In the Applications Navigator, right-click
CustomerOrdersBusinessService and select Test
from the context menu.
As before, select oeconn from the Connection Name
dropdown list In the Connect window of the Oracle Business Component
Browser and click Connect.
2.
Double-click CustomersView1 in the Browser
to run it. Remove the @ sign from the email address and verify that
your error message displays.
Click OK and replace the @ sign into the email address
so that you can continue.
3.
Double-click OrdersCustomerIdFkLink1.
Find the CustomerId 109 or any customer with orders.
Double-click the ViewLinkInstance1 view link. This
invokes both the OrdersView1 and the OrderItemsView1 view objects, joined
by the view link.
In the detail of the Order Items, notice the Product Name is displayed.
Also the LineTotal is displayed with its calculation. If you had time
for the format masks, these should appear too.
Change a value in either Quantity or Unit Price and notice that the
LineTotal recalculates.
When you are finished testing, you can close the Business Components
Browser window.
In this tutorial you edited the properties of entity objects
and view objects to modify the default behavior of business components. You
implemented simple validation rules, set a default value and format masks, changed
default labels, set tooltips, and changed the sort order of records. You also
tested that behavior in the Business Components Browser.
Bookmark
Place the cursor over this icon to load and view all
the screenshots for this tutorial. (Caution: Because this action loads all screenshots
simultaneously, response time may be slow depending on your Internet connection.)
to save your work. 
to add a new value to the expression. 
to shuttle it to the Expression field on the left hand side. 
to see that the ordering of the returned customers is by the Last Name.
to add a new record. You should see the default value for the credit
limit. 
to delete the inserted record.
to see the results in a separate window.