3. Implementing Business Rules

Purpose

This tutorial covers adding validation and business rules to business components.

Time to Complete

Approximately 30 minutes

Topics

This tutorial covers the following topics:

 

Viewing Screenshots

Show all images

Place the cursor over this icon or hit Alt-a (Alt-Shift-a on Firefox) to load and view all the screenshots for this tutorial. 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

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.

Back to Topic List

Scenario

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.

Back to Topic List

Prerequisites

Before starting this tutorial, you should:

  1. Have complied with prerequisites stated in previous hands-on tutorials.

  2. Have completed the previous hands-on tutorials in this tutorial.

Back to Topic List

1. Adding Simple Validation Rules

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 Open Customers from the context menu.

    Hover to see image

  2. In the Entity Object Editor, select Validators from the list on the left.

    Hover to see image

    Select CreditLimit from the tree of existing Validators.

    Click New New icon to add a new set of validation criteria.

    Hover to see image

  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 The value entered for the credit limit ({x}) must be less than 4000

    Hover to see image

    Click the tab named Failure Handling to enter the Error message and the Token Expression newValue:

    Hover to see image

    You have added a piece of validation. The message token inserted within curly brackets, {}, will resolve to the new value of the field (without the brackets). The error message will thus contain the value entered, perhaps making it easier to understand. 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.

Back to Topic List

2. Adding a Format Mask

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 a 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, select the Attributes node in the list to the left

    Double click on the CreditLimit attribute to bring up the Edit Attribute dialog. Click on the Control Hints link in the list on the left.

    Hover to see image

  2. Select Currency from the Format Type dropdown list and enter Tooltip Text of your choosing.

    Hover to see image

    Click OK to apply the format mask.

  3. Now double click on the DateOfBirth attribute and click the Control Hints link in the dialog.

    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 or OK to accept the changes.

    Hover to see image

    Note: The format mask is case-sensitive and must be typed exactly as shown.

  4. Change the Label Text for the attributes CustFirstName to display the label " Name" and CustLastName to display the label " Surname". A label is the text any UI controls will be labeled with to identify them to the user.

    Hover to see image

    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.

Back to Topic List

3. Adding a Default Value

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. Double click on the CreditLimit in the Attributes list and click on the node Entity Attribute.

    Set Default to 100 in the Value field.

    Hover to see image

    Click OK to confirm the change.

  2. Click Save All Save All button to save your work.

Back to Topic List

4. Modifying View Object Properties

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, right-click CustomersView and select Open CustomersView to invoke the View Object Editor. The CustomersView is in Model | Application Sources in the model.queries package

    Hover to see image

    Select the Attributes node and select CustLastname and then right-click and select Edit CustLastName in the context menu.

    Hover to see image

    The View Object Editor is shown:

    Hover to see image

  2. Note that the Label Text says "Surname". This means that the default label is used, in this case the text set at entity object level.

    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.

    Hover to see image

  3. Change the order of objects queried by setting the ORDER BY clause on the query.

    Select Query in the left side list.

    Click the black down arrow to the right of Order By.

    Hover to see image

    We want to add a single column. As the dialog starts off quite compact, it is worth resizing it to see more detail.

    Select Customer.CUST_LAST_NAME and click Add button to shuttle it to the list on the right hand side.

    Hover to see image

    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.

    The same task can be done by clicking the Edit icon in the View Editor:

    Hover to see image

    Hover to see image

  4. The finished Query:

    Hover to see image

  5. Click Save All Save All button to save your work.

Back to Topic List

5. Testing the Application

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 Run from the context menu.

    Hover to see image

  2. In the Connect window of the Oracle Business Component Browser click Connect.

    Hover to see image

  3. Double-click CustomersView1 in the Business Component Browser to show 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.

    Hover to see image

  4. Update the credit limit to 6000 and verify that your error message displays

    Hover to see image

    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 Next button to see that the ordering of the returned customers is by the Last Name.

    Hover to see image

  6. Click Create Create button to add a new record. You should see the default value for the credit limit.

    Hover to see image

    Click Delete Delete button 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.

    Scroll through the Customers until you find one with at least one order (try CustomerId 102). The application module automatically coordinates all the views.

    Hover to see image

  8. When you are finished testing, you can close the Business Components Browser window.

Back to Topic List

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 tabs to the left.

    Click New to add a new attribute.

    Hover to see image

  2. In the New View Object Attribute dialog, set the following properties:

    Name LineTotal
    Type Number
    Updatable Never
    Mapped to Column or SQL Unchecked
    Selected in Query Unchecked
    Queryable Checked

    Click OK.

    Hover to see image

    These values are case sensitive.

  3. You want the LineTotal Attribute to be recalculated and the new value displayed both when you query an order item and when you change either the Price or the Quantity. You can do this with a Script Expression as a validator on the LineTotal column:

    Select Expression for the Value Type and then click the Edit... button next to the field labeld Value to invoke the expression editor.

    Enter Quantity*UnitPrice (these are attributes in the view that you base the value on) as the Expression.

    Shuttle the two attibutes we used in the expression to the list at the bottom of the screen lableled " Selected". This will make LineTotal dependent on these two attributes and cause a recalculation when either one changes.

    Hover to see image

  4. Click OK twice.

  5. Run the application to see the validator in action. Find customer 109. Its first order has many items. Change the Quantity or the UnitPrice to see the recalculation in action.

    Hover to see image

    Click Save All Save All button to save your work.

Back to Topic List

7. Adding Validation with Regular Expressions

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 Regular Expressions for the entity object or the view object.

To add validation for the customer's email address, perform the following steps:

  1. Double-click Customers in the Applications Navigator to invoke the Entity Object editor.

    In the Entity Object Editor, select Validators in the tabs at the left.

    Under Declared Validation Rules, select CustEmail and click New.

    Hover to see image

  2. In the Add Validation Rule dialog, select Regular Expression from the Rule Type dropdown list.

    Select "Email Address" in the Predefined Expressions drop down and click the Use Pattern button:

    Hover to see image

    In the Failure Handling tab, type an appropriate error message, such as " The email address {e} is not valid. Please reenter". Type "newValue" in the Expression field at the bottom to have the variable "e" be populated with the value the user has entered.

    Hover to see image

    Click OK to update the Customers entity object.

  3. 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.

    Hover to see image

  4. Click OK. The modified business components are now created in the selected project.

    Click Save All Save All button to save your work.

Back to Topic List

8. Testing the Application

Once again you can test the changes you have made to the business components without the need to build any client code. U se 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 Run from the context menu.

    Hover to see image

    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.

    Hover to see image

    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.

    Hover to see image

    When you are finished testing, you can close the Business Components Browser window.

Back to Topic List

Summary

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.

Back to Topic List

Hide all images Place the cursor over this icon or press Shift-Alt-h to hide all screenshots. Click the icon to show a navigation bar.

false ,,,,,,,,,,,,,,,