Examining ADF Business Components New Features

Purpose

In this tutorial, you create a series of simple ADF business services scenarios in JDeveloper 11g. This is intended as a light introduction to some of the new ADF BC functionality in Release 11 of JDeveloper.

To run the pages successfully, you must use IE7 or Firefox.

Topics

The tutorial covers the following topics:

	Overview
	Prerequisites
	Building a Cascading List of Values
	Enhancing Calculations and Validation
	Creating a Named Query
	Examining Business Component Features in a JavaServer Faces Page
	Summary

Viewing Screenshots

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

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

The following are a set of complete scenarios which examine three of the ADF BC new features.

Cascading List of Values

The first scenario shows how setting up LOVs is easier than ever with Oracle JDeveloper 11g. Most data-intensive applications require users to select values from lists of choices. In many cases, the list of valid choices for one field depends on the selection a user makes in another field. For example, in a global commerce application, a user might first pick a country, leading the application to display a list of products for sale in that particular country.

The ability to simplify the creation of lists of values (LOVs) to support this kind of scenario has been one of the most common enhancement requests for Oracle Application Development Framework (Oracle ADF) 11g. In Oracle ADF 11g, you can configure a list of values as a declarative feature of any view object attribute. By defining the list of values at the model layer instead of within the user interface (UI), you can ensure that your UI presents a list of values correctly and consistently, regardless of the Oracle ADF-supported UI client technology you decide to use.

Enhanced Calculation and Validation

The second scenario shows how easy it now is to create calculated attributes, validate foreign key values, constrain mutually dependent attribute values, and define more complex validation rules without writing any Java code.

Groovy is a standards-based dynamic language for the Java platform, defined as Java Specification Request 241 (JSR 241). It provides a simpler syntax than Java for many common programming tasks, it interoperates seamlessly with any Java class, and it can be both compiled and interpreted 'on the fly'. Oracle ADF 11g provides extensive support for the Groovy language, and the first example in this column demonstrates how to use Groovy expressions to define calculated attributes.

Creating a Named Query

A named query you define lets you specify filter information for the rows of a view object collection. The named query object is a row set of one or more named query rows, whose attributes mirror those in the view object. The named query definition comprises query conditions that augment the WHERE clause of the target view object. Query conditions that you specify apply to the individual attributes of the target view object.

Back to Topic List

Prerequisites

	Start JDeveloper 11g
	Create a New Application

Back to Topic List

Start JDeveloper 11g

Back to Topic

Back to Topic List

Create a New Application and Project

Back to Topic

Back to Topic List

Building a Cascading List of Values

The topics below guide you through the steps to build two lists of values, one on the ManagerId field and one on the DepartmentId field. You also specify how you want the data in the lists to be displayed.

	Set up the Model
	Define the Lists of Values
	Configure the Lists of Values
	Test the Lists of Values

Back to Topic List

Setting up the Model

In this section you create a default entity and view object for the DEPARTMENTS and EMPLOYEES tables. These entity and view objects are the basis for the lists of values.

1.	The entity and view objects will both be created in the Model project. Right click the Model project and select New.
2.	In the New Gallery, expand the Business Tier category and select the ADF Business Components category. Then select the Business Components from Tables item, and click OK.
3.	Next to the Connection field, click the Add button to create a new connection to the HR schema using the following information. Connection Name HR Username/Password hr/<your hr password> Save Password & Deploy Password Both checkboxes checked Driver Thin Host Name The machine where the schema is installed SID The database where the HR schema is installed Test the connection to ensure it is available, then click OK. The connection should appear in the Initialize Business Components Project page. Click OK to continue defining the Business Components.
4.	JDeveloper connects to the schema allowing you to define the components you need. Create entity objects from the DEPARTMENTS and EMPLOYEES tables. Click the Query button on the right hand side of the page to retrieve all the tables from the connected schema. Select both the DEPARTMENTS and EMPLOYEES tables and shuttle them to the Selected pane. In the Selected pane, select each of the table names and change the Entity Names to shorter, singular forms. DEPARTMENTS - Dept EMPLOYEES - Emp Click Next to continue and define the view objects.
5.	In step two of the wizard, shuttle the Dept and Emp EOs to the Selected pane. This creates two updateable view objects. Click Next twice to take you to the Application Module page.
6.	In the Application Module step of the wizard, ensure that the Application Module checkbox is checked and click Finish. This builds an application module containing the view objects you just created. The Application Navigator should now look like the the image below. Save all your work.
7.	Right click AppModule and select Run. This invokes the Tester and allows you to validate the business components work correctly. Click the Connect button to use the default connection. When the tester is displayed double click the EmpsView1 node. By default all the employees records are displayed and there are no lists of values on the Mgr and Deptno items. Exit the tester.
	In the next section you incorporate lists of values to make the selection of departments and managers easier for the end user.

Back to Topic

Back to Topic List

Defining the Lists of Values

Now that the basic model layer objects are in place, the next step is to create the lists of values.

First you build a more complex list of values for the Mgr (manager) attribute. This list references a new view object that queries a filtered list of employees who can serve as the current employee's manager. For the sake of this exercise, you can assume that the list of available managers for a given employee is the list of other employees in the same department, including any employee without a manager (such as the president).

1.	Create a view object to display the managers that an employee can be assigned to. Right-click the Model project in the Application Navigator and select New. Select the ADF Business Components category, and double-click the View Object component to invoke the Create View Object wizard.
2.	In the Name page of the Create View Object wizard, change the name to ManagerListForDepartment and click Next.
3.	In the Entity Objects page, select the Emp entity object from the Available list, click the Add button to shuttle it into the Selected pane, and click Next. In the Attributes page, include the EmployeeId and LastName attributes, and click Next twice to navigate to the Query page.
4.	In the Where field, add the following WHERE clause: (DEPARTMENT_ID = :CurrentDept OR MANAGER_ID IS NULL) AND EMPLOYEE_ID ! = :CurrentEmp This clause filters the list of employees to produce the set described above. Click Next to add Bind Variables.
5.	In the Bind Variables page, create two new variables called CurrentDept and CurrentEmp (which are both referenced in the WHERE clause) and set both variables to be of type Number. Click Finish to create the view object.

Back to Topic

Back to Topic List

Configuring the Lists of Values

Now that the basic model layer objects are in place, the next step is to configure the two lists of values. In Oracle ADF 11g, you can configure a list of values as a declarative feature of any view object attribute. By defining the list of values at the model layer instead of within the user interface (UI), you can ensure that your UI presents a list of values correctly and consistently, regardless of the Oracle ADF-supported UI client technology you decide to use.

1.	Configure the Employee Deptno list of values. In the Application Navigator, begin by double-clicking EmpView to open the view object editor. Note that in Oracle JDeveloper 11g, the business component editors appear as tabs within the main editor area. Select the Attributes category along the left edge of the editor page, and then click on the DepartmentId attribute in the table.
2.	In the List of Values: DepartmentId section below, click the green plus-sign icon to create a list of values for the DepartmentId attribute. When the List of Values dialog box appears, click the green plus-sign icon to the right of the List Data Source field to add a datasource that will supply the list of valid choices for this attribute's value. In the View Accessors dialog box that appears, select the DeptView view object in the Available View Objects list on the left and click the Add Instance button to add a new view accessor named DeptView1. Then click OK.
3.	Note that the newly added view accessor datasource DeptView1 appears in the List Data Source field Click the arrow at the right of the List Attribute field, and select DepartmentId from the list of available attributes. Note that the List Return Values section updates to show how attributes in the list datasource will be assigned to attributes in the base view object when the user makes a choice from the list. You don't need to add any supplemental values for this example, but note that you could map additional return value attributes in your application by adding to this list.
4.	Before leaving the List of Values dialog box, click the UI Hints tab. These settings provide information that defines how the list should appear within the user interface. Note that the default list type indicates a Choice List display style. You use this default list type for this simple example, but if you click the list, you can see the other types of list controls available for use with your applications. In the Display Attributes section, select the DepartmentName attribute from the Available list and click the Add (right-arrow) button to add it to the list of selected attributes. This selection indicates that you want the user to see the department name, rather than the department number, in the list of values. Finally, click OK to close the List of Values dialog box.
5.	Configure the Employee Manager list of values. As before, select the ManagerId attribute in the Attributes section of the view object editor for the EmpView object. Then click the green plus-sign icon in the List of Values for the ManagerId section header.
6.	When the List of Values dialog box appears, click the green plus-sign icon in the List Data Source section to add a new datasource to supply the list of valid choices for this attribute's value. In the View Accessors dialog box, select the ManagerListForDepartment view object from the Available View Objects list on the left and click the Add Instance button to add a new view accessor named ManagerListForDepartment1 for the selected view object. Do not dismiss the pane, the next step modifies the properties of the accessor.
7.	As this view object has bind variables, you need to configure how those bind values get their values. To do so, make sure the ManagerListForDepartment1 view accessor is selected and click the Edit button. In the Edit View Accessor dialog box, note that the bind variable names CurrentDept and CurrentEmp appear in the Bind Parameter Values section (you need to scroll to check that both variables are there). You want to assign the value of the CurrentEmp bind variable to be the value of the EmployeeId attribute in the current row, so enter the (case-sensitive) expression EmployeeId in this cell. Similarly, double-click the value column for the CurrentDept bind variable, and enter the expression DepartmentId to assign this bind variable's value to the value of the Deptno attribute in the current row. Click OK to dismiss the Edit View Accessor window, and click OK again to dismiss the View Accessor window.
8.	In the List of Values dialog box, click the arrow in the List Attribute field and select the EmployeeId attribute from the list. Then, click the UI Hints tab. Shuttle LastName into the Selected pane as the list's display attribute. Click OK to close the List UI Hints dialog box and OK again to close the List of Values dialog box. Save all your work.

Back to Topic

Back to Topic List

Testing the Lists of Values

You can use the enhanced Oracle ADF 11g Oracle Business Component Browser to immediately test the LOVs you've just configured.

1.	To run the application module in the Oracle Business Component Browser, right-click the AppModule component in the Application Navigator and select Run.
2.	After you click Connect in the dialog box that appears, the Oracle Business Component Browser will appear. Double-click the EmpView1 view object instance to see its data. Both ManagerId and DepartmentId appear as lists.
3.	If you select the ManagerId list, you'll notice that the list includes the employees in the current department and employees such as KING who have no manager. When you navigate to different rows in the result set, you see the lists automatically change to reflect the current department for the current employee. If you change an employee's department by choosing a different department name from the list, you'll notice that when you select the Mgr list, the set of choices will automatically update to reflect the new department. When you're done experimenting, select File - Exit to exit the Oracle Business Component Browser. Because the Oracle Business Component Browser has been reimplemented in the Oracle JDeveloper 11g release with Oracle ADF Swing, this example also serves as a quick illustration of how Oracle ADF Swing applications can make automatic use of model-defined LOVs.

Back to Topic List

Enhancing Calculations and Validations

In this section, you see how easy it is, with JDeveloper 11g, to create calculated attributes, validate foreign key values, constrain mutually dependent attribute values, and define more complex validation rules without writing any Java code. Each of the following topics guides you through these features of JDeveloper 11g.

	Create Calculated Attributes
	Validate Foreign Keys
	Constrain Dependent Values
	Write Groovy Validation Rules

Back to Topic List

Creating Calculated Attributes

In the ADFBC application you've been using, the Emp entity object needs a transient attribute called TotalComp. Create and update this attribute definition to be the sum of the employee's salary and that person's commission (as defined by the Salary and CommissionPct attributes, respectively). In the formula, you must allow for the fact that CommissionPct and Salary might be null.

1.	In the Application Navigator, double-click the Emp entity in the Application Navigator to open the Entity Object Editor.
2.	Click Attributes tab to go to the Attributes page, and click the Add button to create a new transient attribute named TotalComp with a Type of Number. Uncheck the Persistent check box and choose Never for the attribute Updatable property. Click OK. Then double-click on the TotalComp attribute to invoke the editor to specify the calculation. In the Attribute Editor dialog box, ensure that the Expression radio button in the Value Type radio group is selected. In the Value field, enter the following formula: (Salary!=null?Salary:0)+(Salary*(CommissionPct!=null?CommissionPct:0)) This formula uses a ternary operator that tests a Boolean condition (Salary!=null) to return the value of Salary if it is not null and zero otherwise. It then performs a similar calculation on the value of CommisionPct, and multiplies it by the Salary, then returns the sum of both calculations. Do not exit the editor.
3.	To complete the attribute definition, go to the Dependencies page of the Attribute Editor, and shuttle the Salary and CommissionPct attributes into the Selected pane. Finally, click OK to save the changes and save all your work.
4.	In the Application Navigator, double-click the EmpView. In the editor, select the Attributes tab and click the Add from Entity... button. Select TotalComp in the Available pane and shuttle it over to the Selected pane. Click OK.
5.	To test your changes, right-click the AppModule application module in the Application Navigator and select Run from the menu that appears.
6.	When the Business Components Browser - Connect dialog box appears, click Connect. Double-click the EmpView1 object instance, and advance to a record that contains a Commission Percentage to see the calculation. If you change the Commission Percentage, the total compensation changes when you navigate to any other item in the record. Close the Business Component Browser.

Back to Topic

Back to Topic List

Validating Foreign Keys

An earlier section looked at how to define declarative lists of values (LOVs) for a view object attribute to assist users in choosing existing foreign key lookup values. Keep in mind that, although these LOVs are handy for end users, they are not a substitute for proper validation of the foreign key at the entity object level. For example, some UI components, such as text fields with a pop-up LOV, allow the user to type a foreign key value directly. Furthermore, the service may be accessed in a variety of methods, some of which may bypass the conventional user interface. Fortunately, the new Key Exists validation rule makes it easy to validate foreign key attributes, making quick work of what is normally a programming chore.

1.	This example adds a Key Exists validation rule to the Emp entity in the Model project. In the Application Navigator, double click the Emp entity to open it in the Editor. Select the Validators tab and select the Entity node, then click the Add button, to the right of the Validators heading on the page.
2.	In the Add Validation Rule dialog box, select Key Exists from the Rule Type list. Also in the Rule Definition tab, ensure that EmpDeptFkAssoc is selected in the Association Name field. This selection denotes a one-to-many association between the Dept and Emp entity objects that represents the foreign key relationship to be validated.
3.	Next, click the Failure Handling tab, and enter the error message Department does not exist in the Message Text box. Click OK to define the new validation rule. The validation appears in the Editor. Save all your work.
4.	Remove the LOV from EmpView you created earlier. Invoke the EmpView view object in the editor and in the Attributes tab, select the DepartmentId attribute. Click on the plus-sign to the left of the List of Values: DepartmentId field to expand it. Select LOV_DepartmentId and click the red X to delete the LOV. Save all your work.
5.	Run the AppModule again, and change the value of the DepartmentId of an existing employee to any two-digit invalid number (such as 99). When you commit or navigate to a different row, an exception with your custom error message will be raised.

Back to Topic

Back to Topic List

Constraining Dependent Values

Another common kind of validation involves comparing two attributes in the same row. The next example enforces a rule that says that an employee's commission must be less than 50%. This rule will be applied only when both the commission and salary are non-null, and it will be re-evaluated when either the commission or the salary value changes. The enhanced Compare validation rule in Oracle JDeveloper 11g makes this check easy to implement.

1.	In the Application Navigator, double click the Emp entity to open it in the Editor. Clickt the Validators tab and select the Entity node, then click the Add button,on the right of the page. In the Add Validation Rule dialog box, select Compare from the Rule Type list.
2.	On the Rule Definition tab, select CommissionPct from the Attribute list and LessThan from the Operator list. From the Compare With list, select Literal Value, and enter .5 in the Literal Value box below.
3.	These steps set up the basic comparison in the validation rule. Next, on the Validation Execution tab, enter the formula Salary!=null && CommissionPct!=null in the Conditional Execution Expression field. This field causes the rule to be applied only when the specified condition is true. Note that the expression is case-sensitive, so be sure to type CommissionPct and not commissionpct. Next, go to the Triggering Attributes section, select Salary from the Available Attributes list, and click the Add button to shuttle Salary into the Selected Attributes list, along with CommissionPct. At runtime, when the value of any attribute in this list changes, the rule will be re-evaluated.
4.	Finally, go to the Failure Handling tab and enter the following validation error message in the Message Text box: The {attr1} of {val} must be less than 50% Be sure to include the two message expressions in curly braces.
5.	In the Token Message Expressions table below, click the row for the attr1 token and double-click the Expression cell in that row. Enter the expression source.hints.CommissionPct.label to reference the value of the user-friendly display label for the CommissionPct attribute of the source entity object being validated. Similarly, enter the expression CommissionPct for the val token to reference the value of the CommissionPct attribute. These message expressions, like those in the calculated attribute example above, use Groovy syntax. Although these are very simple expressions, it's important to understand that developers can leverage the full power of Groovy when necessary. To finish, click OK to define the new rule. Click OK to save your validation rule. Then save all your work.
6.	Run the AppModule again to test the rule. Try to enter a value of .7 for the commission of an existing employee. When you commit, the parameterized error message "The CommissionPct of .7 must be less than 50%" should display. If you change the value of the salary of an employee with no commission, you can verify that no exception is raised, because the CommissionPct value is null. Finally, you can verify that the triggering attributes work properly, by changing the salary of an employee to a value lower than that person's existing commission.

Back to Topic

Back to Topic List

Writing Groovy Validation Rules

In this section you create a more complex validation rule, using the Groovy language. This rule specifies that if an employee belongs to a department whose name ends with the letter s, the salary must be a multiple of 5. This rule requires conditional logic and also accesses an attribute of the associated Dept entity object.

1.	In this section you create a validation rule that references values from the Dept entity object. To do this you need to use the Accessor of the association between the Emp and Dept entity objects. You need to know what the accessor name is before creating the expression. In the Application Navigator, double-click the EmpDeptFkAssoc and select the Relationship tab. Expand the plus sign for Accessors. In this example the accessor name is Dept1 which is the name that will be used in the groovy expression. If the name you have used is different, that is ok, but write it down and alter the code to use it rather than Dept1 in the example code.
2.	Click to return to the Entity Object Editor for Emp, select the Validators tab, then select the Entity node and click the Create new validator button again. In the Add Validation Rule dialog box, click the Rule Type list, scroll down and select Script Expression.
3.	On the Rule Definition tab, enter the following expression: if (Dept1?.DepartmentName?.toUpperCase()?.endsWith("S") && Salary % 5 != 0) { return false; } return true; The Boolean expression in the if statement references the DepartmentId of the current Emp object being validated, to access the associated Dept entity object (if one exists). In this case the default name of the association for the employee's department is Dept1. You can see this name if you look at the definition of the EmpDeptFkAssoc object in the Accessor section. In general, you should change the name of all your associations to represent the business (like EmpWorkingInDept). In this OBE you use the default name for all the objects. It then references the DepartmentName attribute found at the end of the Dept1 association, converts it to uppercase to perform a case-insensitive comparison, and uses the String class endsWith() method to test whether the DepartmentName value ends with s. If your accessor name (from step 1) is different from Dept1, replace the name in the first line of code where Dept1 is located. Note that instead of writing Dept1.DepartmentName.toUpperCase().endsWith(), you've replaced the normal dot operator with Groovy's "?." safe-navigation operator. This operator works like the dot operator to allow navigation from an object to properties of that object. However, if the left-side value is null, the Groovy operator doesn't throw a NullPointerException but instead evaluates to null. Conveniently, when null is encountered in Groovy as a Boolean value, it evaluates to false, so using the ?. operator can make lots of expressions more compact. After this initial check, the expression above uses the integer modulo operator (%) to test whether the salary is a multiple of 5. If the department name ends with 's' and the salary is not a multiple of 5, then it returns false, which causes the rule to fail. Otherwise, it returns true.
4.	Click the Failure Handling tab. Note that because Groovy validation rules can conditionally raise one of several exceptions, you can add multiple error messages in this tab. The message you select is used when the validation rule returns false. To add a message, click the Existing Message button (denoted by a magnifying glass). In the Select Text Resource dialog box, enter the following value in the Key field IF_DEPARTMENT_NAME_ENDS_IN_S and enter the following error message in the Value field. If department name ends in S the salary must be multiple of five. Also enter this same message in the Description field. Then click Save and Select, and finally click OK to define the new validation rule. Save all your work.
5.	Return to EmpView and reset the LOV on DepartmentId. Click the Attributes finger to display the attribute details page. Select the DepartmentId attribute, and in the List of Values: DepartmentId field, click the green plus-sign to add a list of values. In the List of Values dialog, click the arrow in the List Data Source field, and choose DeptView1 from the list. Click the arrow in the List Attribute field and select DepartmentId. Note that the List Return Values section updates to show how attributes in the list datasource are assigned to attributes in the base view object when the user makes a choice from the list. Before leaving the List of Values dialog box, click the UI Hints tab, to open the UI Hints dialog box. These settings provide information that defines how the list should appear within the user interface. Note that the default list type indicates a Choice List display style. You use this default list type for this simple example, but if you click the list, you'll see the other types of list controls you can use within your own applications. As before, in the Display Attributes section, select the DepartmentName attribute from the Available list and click the Add button to add it to the list of selected attributes. This selection indicates that you want the user to see the department name, rather than the department number, in the list. Finally, click OK to close the UI Hints dialog box and OK again to close the List of Values dialog box.
6.	Run the AppModule again, and try to enter a salary ending in "1" for an employee in department 30 (SALES) or 40 (OPERATIONS). Then commit the change. Because these department names end with an s and the employee's salary is not a multiple of 5, the application will raise a validation error.

Back to Topic

Back to Topic List

Creating a Named Query

In this section you create a named query.

A named query you define lets you specify filter information for the rows of a view object collection. The named query object is a row set of one or more named query rows, whose attributes mirror those in the view object. The named query definition comprises query conditions that augment the WHERE clause of the target view object. Query conditions that you specify apply to the individual attributes of the target view object.

The key difference between a view object row of query results and a named query row is that the data type of each attribute in the view criteria row is String. This key difference supports query-by-example operators and therefore allows the user to enter conditions such as "OrderId > 304", for example.

Back to Topic

Back to Topic List

Examining Business Component Features in a JavaServer Faces Page

Now that you've configured and tested Business Component features on the EmpView view object, you can see how simple it is to use them in an Ajax-enabled Web page using JavaServer Faces (JSF).

1.	In the Application Navigator, expand the ViewController project and its Web Content folder to display the project's Page Flows folder. Inside the WEB-INF folder, double-click the adfc-config node to open the page flow diagram.
2.	Next, go to the Component Palette and find the Activities section. In this section, drag a View component and drop it onto the page flow diagram. When the new view appears on the diagram, rename the component Employees and click Enter. To create the JSF page for this view, double-click the icon representing the new view. When the Create JSF JSP dialog box appears, click OK to create the Employees.jspx page, using the default settings. The new Web page appears in the visual page designer.
3.	The next step is to drop a data collection onto the page. First, take a look at the Application Navigator and note that the frame is grouped into several sections, each containing a titled heading bar and an arrow to enable you to expand or collapse the section contents. Below the Projects section of the Application Navigator is the Data Controls section. Expand that section, and then expand AppModuleDataControl to reveal the EmpView1 and DeptView1 data collections it contains. Drag the EmpView1 data collection, and drop it onto the center of the visual JSF page editor.