0) { obj.className = "imgborder_on"; } } } function hideImage(obj) { if (obj.className.substr(0, 10) == "imgborder_") { obj.src = eyeglass.src; obj.className = "imgborder_off"; } } function showAllImages() { imgs = document.images; for (i=0; i < imgs.length; i++) { showImage(imgs[i]); } } function hideAllImages() { imgs = document.images; for (i=0; i < imgs.length; i++) { hideImage(imgs[i]); } } //-->

Developing Business Services with ADF Business Components

Purpose

In this tutorial, you create the business services for an application. Business services are the parts of the application that are responsible for persisting the data in your application and implementing business rules in the middle tier. There are several different technology options that you could use. In this tutorial, you use Oracle ADF Business Components for the middle tier business services, and then you add validation and business rules to the model.

Time to Complete

Approximately 50 minutes

Topics

This tutorial covers the following topics:

 Overview
 Scenario
 Prerequisites
 Building the Business Model

Implementing Business Rules

 Testing the Model
 Summary

Viewing Screenshots

 Place the cursor over this icon to load and view all the screenshots for this Component Palette. (Caution: This action loads all screenshots simultaneously, so, depending on your Internet connection, may result in a slow response time.)

Note: 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

When you develop Java applications, you can use ADF Business Components to map to underlying database tables and to persist data in the application before committing it to the database. ADF Business Components consist of entity objects, view objects, and application modules.

You create a number of entity objects and view objects and add them all to a single application module. You then implement validation and business rules and test the model to ensure that it performs correctly.

Back to Topic List

Scenario

The planned application manipulates data from the CUSTOMERS and ORDERS tables. However, not all table columns are displayed in the planned application, and some pages display data from multiple tables. You need to specify the data that you want to display from the database tables, and you also need to implement business rules in the model so that they will be enforced from any user interface.

Back to Topic List

Prerequisites

Before starting this tutorial, you should:

1.

Have access to or have installed Oracle JDeveloper (10.1.3.1.0). You can download it from Oracle Technology Network.

 

2.

Have access to or have installed the Oracle Sample Schemas, included with Oracle Database 10g.

The tutorial uses the OE schema. Specifically, the pages work with the EMPLOYEES table.

Instructions for installing the OE schema and creating a connection to it in JDeveloper are available online at:

http://www.oracle.com/technology/obe/obe1013jdev/common/OBEConnection.htm

3.

Start JDeveloper. Double-click the JDeveloper executable jdeveloper.exe found in the root directory ( <jdev_home> ) where you unzipped it.

If the Migrate User Settings dialog box opens, click NO.

Close the Tip of the Day window.

 

4.

The JDeveloper IDE should now be displayed.

Back to Topic List

Building the Business Model

There are a number of approaches you can take to create ADF Business Components. In the tutorial, you use a combination of these. Building an ADF Business Components model for your application involves the following tasks:

 Creating a Database Connection
 Creating an Application and Projects
 Creating ADF Business Components
 Customizing the Business Components

Creating a Database Connection

Java Database Connectivity (JDBC) is a standard application programming interface (API) that is used for connecting a Java application to relational databases. To create a JDBC connection to the OE schema that is used in this lab, perform the following steps:

1.

Click the Connections Navigator tab, or if the Connections Navigator is not visible, select View | Connection Navigator.

Place the cursor over this icon to see the image

 

2.

Right-click the Database node and choose New Database Connection from the context menu. Click OK.

Place the cursor over this icon to see the image

 

3.

If the Welcome page of the Create Database Connection wizard displays, click Next.

On the Type page of the wizard, enter the name oeconn, and then click Next.

Place the cursor over this icon to see the image

 

4.

On the Authentication page of the wizard, enter a Username of oe and a Password of oe. Select the Deploy Password checkbox and click Next.

Place the cursor over this icon to see the image

 

5.

On the Connection page of the wizard, enter a Host Name of localhost and change the SID to XE . Click Next.

Place the cursor over this icon to see the image

 

6.

Click Test Connection.

If the database is available and the connection details are correct, you will see Success! in the Status window.

If an error occurs, click Back to make any changes necessary, and then retest the connection.

When the connection is successful, click Finish.

Place the cursor over this icon to see the image

 

7.

The connection now appears below the Database connection node in the Connections Navigator.

Place the cursor over this icon to see the image

 

8. Click Save All Save All button or select File | Save All to save your work.

Back to Topic

Creating an Application and Projects

In JDeveloper, files are organized into applications and projects. An application is the highest level in the control structure, and is made up of one or more projects. JDeveloper projects are organizational structures used to logically group related files. You can use projects to organize your source code.

JDeveloper uses templates to expose only those technology choices required for the particular aspect of work you are interested in. When you apply the Web Application [JSF, ADF BC] template to an application, JDeveloper creates two projects for you: Model and ViewController.

To create the application and projects needed for this tutorial, perform the following steps:

1.

Click the Applications Navigator tab.

In the Applications Navigator, right-click the Applications node and select New Application from the context menu.

 

2.

In the Create Application dialog, change the Application Name to OrderEntry. Notice that as you enter the application name, the directory name changes automatically.

Select Web Application [JSF, ADF BC] from the Application Template dropdown list, and then click OK.


3.

The Applications Navigator now shows the OrderEntry application and two projects. In this tutorial, you build the business components in the Model project. In another tutorial, you use the ViewController project to build the user interface.

Back to Topic

Creating ADF Business Components

Now you can begin to build the ADF Business Components. You can create business components in several ways, but in this lab you use a wizard.

The wizard steps you through creating:

  • Entity objects, which are data access objects that are responsible for persisting and caching data, performing validation, and encapsulating business rules
  • View objects, which are based on entity objects and represent the data you want to view and manipulate (view objects are often referred to as the query)
  • An application module, which is a service object that coordinates view objects for a specific task; it contains only the business services that the application requires

To create the business components that serve as the data model for your application, perform the following steps:

1.

In the OrderEntry application, right-click the Model project and select New from the context menu.

Place the cursor over this icon to see the image

 

2.

In the New Gallery expand Business Tier in the Categories list and select ADF Business Components, then select Business Components from Tables from the Items list.

Click OK.

Place the cursor over this icon to see the image

 

3.

In the Initialize Business Components Project dialog, select oeconn from the Connection dropdown list, and then click OK.

Place the cursor over this icon to see the image

 

4.

If the Welcome page of the Create Business Components from Tables wizard displays, click Next.

On the Entity Objects page of the wizard, you can specify the name of the package where the entity objects should be created. Accept the default package, named model.

You also specify the database tables on which to base the entity objects. Click Query to display a list of the available tables.

Place the cursor over this icon to see the image

 

5.

In the Available list, [Ctrl]+[click] to multi-select the following tables: CUSTOMERS and ORDERS. Click Add  to shuttle them to the Selected list.

Place the cursor over this icon to see the image

Click Next.

 

6.

On the Updatable View Objects page of the wizard, you can create view objects that query data from the entity objects.

Packages are very useful for grouping logical pieces of work together. To place the view objects in their own separate package, change Package to model.queries .

Click Add All  to shuttle the entity objects to the Selected list, and then click Next.

Place the cursor over this icon to see the image

 

7.

On the Read-Only View Objects page of the wizard, click Next, because you want to create only updatable view objects.

Place the cursor over this icon to see the image

 

8.

On the Application Module page of the wizard, select the Application Module checkbox.

To place the application module into its own package, change the Package to model.services .

Specify the name CustomerOrderBusinessService for the application module, and then click Next.

Place the cursor over this icon to see the image

 

9.

On the Diagram page of the wizard, you have the option to create a visual representation of your business components. To do so, select the Business Components Diagram checkbox.

Set the Package to model and the Name to CustomerAppBC_Diagram .

Deselect the Domains checkbox, and then click Next.

Place the cursor over this icon to see the image

 

10.

On the Finish page of the wizard, you can review the list of objects and then click Finish to create them.

Place the cursor over this icon to see the image

 

11.

After the creation is complete, the business components diagram opens in the editor. You can zoom in or out on the diagram or change the arrangement of the components by using the tools at the top of the editor window, and you can scroll around to see the objects that were created.

Place the cursor over this icon to see the image

 

12.

In the Applications Navigator you can also see the objects that were created. Expand the Model project and the Application Sources node. You should see three packages and the business component diagram

Expand each of the packages to see the entity objects that were created in the model package, the view objects that were created in the model.queries package, and the application module that was created in the model.services package.

Place the cursor over this icon to see the image

.

13. Click Save All Save All button or select File | Save All to save your work.

Back to Topic

Customizing the Business Components

The business components that are created with the wizard may need modifications, depending on the application in which you intend to use them. In this section of the lab, you customize the default business components.

Usually an entity object's attributes have a one-to-one mapping to the columns in the database, and they are reused in a number of view objects in the application. However, there may be circumstances when you want to limit the attributes in the entity objects. In this example, you remove an attribute from an entity object that is never used by the application, but you first have to remove the attribute from the dependent view object. You also remove an attribute from a view object, but leave it in the entity object.

Another modification that you make is to delete from the data model an instance of the OrdersView view object that can access order information independent of customer information. Your planned application accesses orders only as they relate to customers, so this additional instance of OrdersView is not needed in the model.

To make these modifications to the business components, perform the following steps:

1.

To remove an attribute from an entity object, you first must remove it from the dependent view object.

You can edit business components in various ways. In this tutorial, you use the both the Applications Navigator and the diagram to edit the objects. The business components in the diagram remain synchronized with the objects in the Applications Navigator.

In the Applications Navigator, right-click the CustomersView view object and select Edit CustomersView from the context menu.

 

2.

In the View Object Editor, select the Attributes node in the tree at the left

In the Selected List at the right, select CustGeoLocation and click Remove  to shuttle it out of the Selected list.

Click OK.


3.

In the diagram, right-click the Customers entity object and select Properties from the context menu.

 

4.

In the Entity Object Editor, select Attributes from the tree on the left and the CustGeoLocation attribute from the Entity Attributes panel on the right. Click Remove to delete the attribute.

Click OK.

Note: Alternatively you can delete the attribute from the diagram directly. Be sure to delete just the attribute and not the entire entity.

5.

As mentioned earlier, the view object is a query and does not necessarily mirror all the attributes in the entity object. You do not need the PromotionId attribute from the Orders entity object in the OrdersView view object; however, you leave it in the entity object because it may be used by a different application.

In the diagram, double-click OrdersView to invoke the View Object Editor, and select the Attributes node. Select the PromotionId and click Remove Add Instance button to shuttle the attribute from the Selected list.

Click OK.

 

6.

Double click the CustomerOrdersBusinessService application module to invoke the Application Module Editor. Notice the hierarchical relationships between the view objects in the Data Model.

 

7.

Notice in the Application Module Editor that CustomersView1 has a detail view object called OrdersView2. This association was created by default based on the foreign keys in the database.

The application module also contains another instance of the OrdersView, named OrdersView1. You could use this instance to access orders directly. However, in the planned application you intend to access orders only as they relate to customers, so you do not need this independent instance of OrdersView and can remove it from the data model.

To delete it from the model, select OrdersView1 and click Remove Instance  .

Click OK to update the application module and dismiss the Application Module Editor.

 

8.

On the diagram, notice that the OrdersView1 view object instance no longer appears within the application module.

To adjust the size of the application module on the diagram, right-click the CustomerOrderBusinessService application module and select Optimize Shape Size | Height and Width from the context menu.

 

9.

Click Save All Save All button or select File | Save All to save your work.

Back to Topic

Back to Topic List

Implementing Business Rules

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 section of the tutorial you use business components to declaratively impose validation at the middle tier before committing the data to the database.

To add business rules to the model, perform the following steps:

 Adding Simple Validation Rules
 Defining a Format Mask
 Specifying a Default Value
 Modifying View Object Properties
 Adding Custom Validation

Back to Topic List

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 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 set 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 validation rule 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.

Leave the Entity Object Editor open for the next section of the tutorial.

Back to Topic

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

Place the cursor over this icon to see the image

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.

Place the cursor over this icon to see the 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.

Leave the Entity Object Editor open for the next section of the tutorial.

Back to Topic

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

Select CreditLimit from the expanded Attributes node and select the Entity Attribute tab.

Set Default to 100 and click OK to update the entity object and close the editor.

 

2.

Click Save All Save All button to save your work.

Back to Topic

Modifying View Object Properties

The above changes were made at the entity object level. You can also make similar changes at view object level.

In an application there may be 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 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.

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.

Place the cursor over this icon to see the image

 

4.

This dialog enables you to create a complex expression. For this tutorial you just want to add a single column. As the dialog starts off quite compact, it is worth resizing it to see more detail.

Click New Add button to add a new value to the expression.

In the Order By dialog, expand Customers in the Expression Palette.

Place the cursor over this icon to see the image

 

5.

Select CUST_LAST_NAME and click Insert column Add button to shuttle it to the Expression field on the left hand side.

Place the cursor over this icon to see the image

 

6.

Click Validate to add the column to the Order By list and then click OK.

Place the cursor over this icon to see the image

Note: The view object is just a SQL query, so you can tune it using Optimizer Hints, and you can also 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.

Place the cursor over this icon to see the image

 

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

Back to Topic

Adding Custom Validation

The validation that you have added so far has been mostly declarative. JDeveloper gives you the flexibility to define much more complex validation than is possible declaratively. When using ADF Business Components, one way to perform custom validation is to augment 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.

Place the cursor over this icon to see the image

 

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 ( }):

public boolean validateEmail (String value)
{
  return (value.indexOf('@') != -1 );
}

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.

Place the cursor over this icon to see the image

 

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.

Place the cursor over this icon to see the image

 

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.

Click OK.

Place the cursor over this icon to see the image

Click OK to update the Customers entity object.

 

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

Back to Topic

Back to Topic List

Testing the Model

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. Right-click CustomerOrdersBusinessService and select Test from the context menu.

Place the cursor over this icon to see the image

 

2.

In the Connect window of the Oracle Business Component Browser, select oeconn from the Connection Name dropdown list and click Connect.

Place the cursor over this icon to see the image

 

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. The CreditLimit field should be displayed with the currency format mask.

You should also see that any attribute labels you changed, such as the CustFirstName, display instead of the default label, and that the VO label, rather than the one defined at the EO level, displays for the last name.

Place the cursor over this icon to see the image

 

4.

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

Place the cursor over this icon to see the 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.

Place the cursor over this icon to see the image

 

6.

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

Place the cursor over this icon to see the image

Click Delete Delete button to delete the inserted record.

 

7.

Remove the @ sign from the email address and verify that your error message displays

Place the cursor over this icon to see the image

Click OK and replace the @ sign into the email address so that you can continue.

 

8.

Now double-click the OrdersCustomerIdFkLink1 view link. This invokes both the CustomersView1 and the Orders View2 view objects, joined by the view link.

Click the Delete button to see the results in a separate window.

Click Specify View Criteria  and enter a CustomerId of 102 , and then click Find to display a customer who has orders. 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.

. Place the cursor over this icon to see the image

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

Back to Topic List

Summary

You learned how to use a wizard to create entity objects based on tables in the database and with the same names as those tables. The wizard also created view objects that represent the data (specific columns) that you plan to use in the application, and view links, which preserve a master-detail relationship between the view objects. The wizard additionally created an application module to contain and coordinate the view objects and view links to be used for the order entry task, and it created a business components diagram for a visual depiction of the components.

You edited the properties of entity objects and view objects to modify the default behavior of business components, and you tested the model that you built.

In the tutorial, you've learned how to:

 Create and modify ADF Business Components: entity objects, view objects, and application modules
 Create and edit a business components diagram
 Add declarative and custom validation
 Set default values
 Set format masks
 Change default labels
 Set tooltips
 Change the order of displayed records
 Test the model with the Business Components Browser

Related material:

Developing JSF User Interfaces with ADF Faces

Back to Topic List

 Place the cursor over this icon to hide all screenshots.

 

 

 

Left Curve
Popular Downloads
Right Curve
Untitled Document