Advanced ADF Business Components

Copyright 2008, Oracle. All rights reserved.

Objectives
After completing this lesson, you should be able to do the following: Extend the ADF Business Components (ADF BC) framework to support your application Override entity object data manipulation language (DML) to use a PL/SQL procedure Avoid database constraint violations

2-2

Copyright 2008, Oracle. All rights reserved.

Agenda
General Considerations Extending the Framework Using PL/SQL for DML Operations Avoiding Database Constraint Violations

2-3

Copyright 2008, Oracle. All rights reserved.

Business Components: Preferences

Tools > Preferences > Business Components Define your own base classes. Set the default class and package naming. Create new properties. Use the default tuning values.

2-4

Copyright 2008, Oracle. All rights reserved.

Business Components: Naming Conventions

Determine the following before you build the application: Adopt simple naming conventions. Partition your code into different packages.

2-5

Copyright 2008, Oracle. All rights reserved.

Business Components: View Objects (VO)

General principles A one-to-one relationship with tables is rare. When you define VO, think in terms of screen designs and lists of values (LOV):
What is the shape of the data your user interface (UI) needs? ADF BC takes care of the hard bits; do not be afraid of joins.

You should use Oracle stylenamed bind variables in queries: Where ID = :CustId and Name like :CustName
It is easy to create Query Input forms based on this.

You should think about ExecuteWithParams rather than custom methods when you set the WHERE clause.

2-6

Copyright 2008, Oracle. All rights reserved.

Business Components: Read-Only VO

It is easy to create VO using the main wizards. The Create from Tables wizard also enables you to create read-only View Objects. You should use read-only or static VO for reference data.

2-7

Copyright 2008, Oracle. All rights reserved.

Business Components: VO Tuning

Based on the projected usage: Default values are taken from what is defined in Preferences. For entity object-based VO, by default all the rows are returned in batches of 1, as needed.

2-8

Copyright 2008, Oracle. All rights reserved.

Testing Business Components

You do not need to build a UI to test the data model. Isolate the business service layer to solve problems. Use the built-in tester to perform first-cut tests, including testing bind variables and viewing criteria and all business logic defined in the application module.

2 - 10

Copyright 2008, Oracle. All rights reserved.

Testing Java Code with JUnit

JUnit is an open source regression-testing framework. It is useful for creating tests to verify Java code. JDevelopers JUnit extension provides wizards to create test components. You can obtain the extension from JDeveloper: Help > Check for Updates. More information and examples:
SRDemo sample application Fusion Order Demo sample application JDeveloper online documentation http://www.junit.org

2 - 11

Copyright 2008, Oracle. All rights reserved.

Agenda
General Considerations Extending the Framework Using PL/SQL for DML Operations Avoiding Database Constraint Violations

2 - 12

Copyright 2008, Oracle. All rights reserved.

Globally Extending ADF Business Components Functionality

What are framework extension classes? How do you both create an extension class and base ADF components on it? How do you adopt the best practice of using a whole custom layer of framework extension classes for your component or specific project?

2 - 13

Copyright 2008, Oracle. All rights reserved.

ADF Business Components Framework Extension Classes

An ADF Business Components framework extension class is a Java class you write that extends one of the frameworks base classes to: Augment a built-in feature with additional, generic functionality Change how a built-in feature works Define a generic way to work around a problem you encounter

2 - 14

Copyright 2008, Oracle. All rights reserved.

Creating a Framework Extension Class

To create a framework extension class, perform the following steps: 1. Identify a project to contain the framework extension class. 2. Ensure that the ADF BC run-time library is in the projects libraries list. 3. Create the new class using the Create Java Class dialog box. 4. Specify the appropriate framework base class from the oracle.jbo.server package in the Extends field.

2 - 15

Copyright 2008, Oracle. All rights reserved.

Basing an ADF Component on a Framework Extension Class

You can either set the base classes for any ADF component using the Java page of any ADF Business Components wizard or editor or define your own defaults, which will appear in the dialog box.

2 - 16

Copyright 2008, Oracle. All rights reserved.

XML-Only Component on a Framework Extension Class

The ComponentClass attribute is read at run time to identify the Java class.

2 - 17

Copyright 2008, Oracle. All rights reserved.

Custom Java Component on a Framework Extension Class

The YourServiceImpl class inherits its base behavior from the CustomAppModuleImpl framework extension class.

2 - 18

Copyright 2008, Oracle. All rights reserved.

Considerations
Do not update the EXTENDS clause in custom component Java files manually. Set up project-level preferences for framework extension classes.
You can have multiple levels of framework extension classes, but keep it simple.

2 - 19

Copyright 2008, Oracle. All rights reserved.

Creating a Layer of Framework Extensions

Before you develop application-specific Business Components, perform the following tasks: 1. Create a complete layer of framework extension classes. 2. Set up your project-level preferences to use that layer by default.
You may have any custom code in mind but the first time you encounter a need, the framework is ready to accept it.

2 - 20

Copyright 2008, Oracle. All rights reserved.

Agenda
General Considerations Extending the Framework Using PL/SQL for DML Operations Avoiding Database Constraint Violations

2 - 21

Copyright 2008, Oracle. All rights reserved.

ADF Business Rules in PL/SQL

Application Module (AM) View Object (VO)
Entity Object A
Middle tier Database tier

Key

Entity Object B

Entity Object C

Process validation Cross table processing

PL/SQL for Table A PL/SQL for Table B PL/SQL for Table C

Table-specific validation Attribute validation DML: INSERT, UPDATE, DELETE, and LOCK

Table A

Table B

Table C

Other code or object

2 - 22

Copyright 2008, Oracle. All rights reserved.

Typical Environment
Background environment: A PL/SQL package that encapsulates insert, update, and delete access to an underlying table A companion database view for read access
create or replace package products_api is procedure insert_product(p_prod_id number, p_name varchar2, p_image varchar2, p_description varchar2); procedure update_product(p_prod_id number, p_name varchar2, p_image varchar2, p_description varchar2); procedure delete_product(p_prod_id number); end products_api; create or replace view products_v as select prod_id,name,image,description from products;

2 - 23

Copyright 2008, Oracle. All rights reserved.

Creating a Database View-Based Entity Object

1. Select the Entity Object database view. 2. Select the Primary Key attribute or attributes.

2 - 24

Copyright 2008, Oracle. All rights reserved.

What Is Created by Default?

By default, an Entity Object based on a database view performs all the following directly against the underlying database view:
The SELECT statement (for findByPrimaryKey()) The SELECT FOR UPDATE statement (for lock()) INSERT, UPDATE, and DELETE statements (for doDML())

All Entity Object implementations extend the EntityImpl.java class. You override the doDML() operations and when necessary, override lock() and findByPrimaryKey().

2 - 25

Copyright 2008, Oracle. All rights reserved.

Centralizing Details in the Base Class

Abstract the generic details into a base framework extension class, and then override the doDML() method. Add helper methods to perform the default processing.

// In PLSQLEntityImpl.java protected void doDML(int operation, TransactionEvent e) { if (operation == DML_INSERT) callInsertProcedure(e); else if (operation == DML_UPDATE) callUpdateProcedure(e); ... /* Override in a subclass to perform non-default processing */ protected void callInsertProcedure(TransactionEvent e) { super.doDML(DML_INSERT, e); ... }

The example shows how to call insert and update procedures. You can also add a call to a delete procedure.
2 - 26

Copyright 2008, Oracle. All rights reserved.

Implementing the Stored Procedure for DML Operations

When you generate the entity object class, click Classes Extend to use the PLSQLEntityImpl class as its base.

Enable a custom Java class for the entity object. Select Source > Override Methods to override callInsertProcedure() and other helper methods.

2 - 27

Copyright 2008, Oracle. All rights reserved.

Leveraging the Helper Method to Invoke Insert, Update, and Delete Procedures
In the ProductsVImpl.java file, add code to invoke the PL/SQL procedures:

// In ProductsVImpl.java protected void callInsertProcedure(TransactionEvent e) { callStoredProcedure("products_api.insert_product(?,?,?,?)", new Object[] { getProdId(), getName(), getImage(),getDescription()}); } protected void callUpdateProcedure(TransactionEvent e) { callStoredProcedure("products_api.update_product(?,?,?,?)", new Object[] { getProdId(), getName(), getImage(),getDescription()}); }

The example shows how to call insert and update procedures. You can also add a call to a delete procedure.

2 - 28

Copyright 2008, Oracle. All rights reserved.

Agenda
General Considerations Extending the Framework Using PL/SQL for DML Operations Avoiding Database Constraint Violations

2 - 29

Copyright 2008, Oracle. All rights reserved.

Controlling Entity Posting Order to Avoid Constraint Violations

Performing DML on more than one entity object can present problems. Because of database (DB) constraints, the order in which the operations are performed is important. Primary key values must be inserted before foreign key references to avoid DB violation. When you commit a transaction, entity object changes are processed in chronological order. When you insert a new Products row and then an associated new Suppliers row, the new product fails at the database level due to the Products_Suppliers_FK foreign key constraint.

2 - 30

Copyright 2008, Oracle. All rights reserved.

DB Constraints, Compositions, and Associations

Database diagram

Business Components diagram

Association
2 - 31

Composition

Copyright 2008, Oracle. All rights reserved.

Transactions with Compositions

A composition is a type of association in which the source object acts as a container for the destination object. It always handles posting order issues. For inserts, updates, and deletes, the destination Entity Object is considered part of the parent Entity Object. Because compositions need to have the FK field populated, create the children of compositions using a detail VO instance. By creating the children of compositions, the FK field gets populated automatically. JDeveloper enables you to perform Cascade Delete by using View Object.

2 - 32

Copyright 2008, Oracle. All rights reserved.

Transactions with Associations

If related entities are associated but not composed, you need code to ensure that the related entities get saved in the appropriate order. Sample method structure:
1. Create a new Products row (detail). 2. Create a new Suppliers row (master). 3. Set the foreign key in the master. 4. Commit the transaction.

2 - 33

Copyright 2008, Oracle. All rights reserved.

Violating a Database Constraint

The method structure in the previous slide raises an error at the database level because: The code created the Products row before the Suppliers row. Products and Suppliers Entity Objects are associated but not composed. The DML operations to save the new entity rows are performed in chronological order, so the new Products row gets inserted before the new Suppliers row.

2 - 34

Copyright 2008, Oracle. All rights reserved.

Forcing the Master to Post Before the Detail

One solution is to reorder the lines of code in the example to create the Suppliers row first, and then the Products row.
Other clients will then have to do the same. You can miss some instances.

A better solution is to make the entity objects handle the posting order:
Override the postChanges() method in the entity that contains the foreign key. Conditionally, force the new Suppliers row to post before the new Products row posts.

2 - 35

Copyright 2008, Oracle. All rights reserved.

Override postChanges() in ProductsImpl.java

If the Products row is new or modified, call the related Supplier association accessor. If the related Suppliers row is new, call postChanges() on the parent before you call super.postChanges() to perform its own DML.

2 - 36

Copyright 2008, Oracle. All rights reserved.

postChanges() Example
// In ProductsImpl.java public void postChanges(TransactionEvent e) { /* If current entity is new or modified */ if (getPostState() == STATUS_NEW || getPostState() == STATUS_MODIFIED) { /* Get the associated supplier for the product */ SuppliersImpl supplier = getSupplier(); /* If there is an associated supplier */ if (supplier != null) { /* And if it's post-status is NEW */ if (supplier.getPostState() == STATUS_NEW) { /* Post the supplier first, before posting this entity by calling super below*/ supplier.postChanges(e);}}} super.postChanges(e); }
2 - 37

Copyright 2008, Oracle. All rights reserved.

Trigger-Assigned Primary Key from the Database Sequence

If the primary key is assigned by a database sequence, its value is available at the posting of the entity, not the referencing one. During the transaction, a unique, temporary negative value is used until posting, and then refreshed with the database sequence value. All referencing entities are created pointing to the temporary value and need to be refreshed to prevent orphans. (Products Suppliers) For composed entity objects, the child foreign keys are automatically refreshed when the parent is posted with the database sequence value.
Copyright 2008, Oracle. All rights reserved.

2 - 38

Refreshing Reference to DB Sequence-Assigned Foreign Keys

If the detail entity is associated (but not composed) with the master, and the primary key is assigned by the database sequence, do the following: Add code to ensure that related entity rows (Products) that reference the temporary negative number (Suppliers) are updated to have the refreshed, database-assigned primary key value. Override the postChanges() method to save a reference to the row set of entity rows that reference it. Example: If the Suppliers row is new, store the RowSet value of association from Products.

2 - 39

Copyright 2008, Oracle. All rights reserved.

Refreshing Reference to DB Sequence-Assigned Foreign Keys

If the primary key is assigned by the database sequence, in the SuppliersImpl.java file, do the following: Override refreshFKInNewContainees. Refresh the saved RowSet.
protected void refreshFKInNewContainees() { if (newProductsBeforePost != null) { Number newSupplierId = getSupplierId().getSequenceNumber(); while (newProductsBeforePost.hasNext()) { ProductsBaseImpl product = (ProductsBaseImpl)newProductsBeforePost.next(); product.setSupplierId(newSupplierId); } closeNewProductsRowSet(); } }

2 - 40

Copyright 2008, Oracle. All rights reserved.

Summary
In this lesson, you should have learned how to: Extend the ADF BC framework to support your application Override entity object DML to use a PL/SQL procedure Avoid database constraint violations

2 - 41

Copyright 2008, Oracle. All rights reserved.

Practice 2 Overview: Advanced ADF Business Components

This practice covers the following topics: Extending the framework Basing an entity object on a PL/SQL package

2 - 42

Copyright 2008, Oracle. All rights reserved.