02_extendadfbc

2Copyright © 2008, Oracle. All rights reserved.

Advanced ADF Business Components

Copyright © 2008, Oracle. All rights reserved.2 - 2

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


Agenda

• General Considerations

• Extending the Framework

• Using PL/SQL for DML Operations

• Avoiding Database Constraint Violations


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.


Business Components: Naming Conventions

Determine the following before you build the application:

• Adopt simple naming conventions.

• Partition your code into different packages.


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 style–named 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.


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.


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.


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.


Testing Java Code with JUnit

• JUnit is an open source regression-testing framework.

• It is useful for creating tests to verify Java code.

• JDeveloper’s 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


Agenda






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?


ADF Business Components Framework Extension Classes

An ADF Business Components framework extension class is a Java class you write that extends one of the framework’s 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


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 project’s 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.


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.


XML-Only Component on a Framework Extension Class

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


Custom Java Component on a Framework Extension Class

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


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.


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.


Agenda






ADF Business Rules in PL/SQL

Key

• Process validation• Cross table processing

• Table-specific validation• Attribute validation• DML: INSERT, UPDATE,

DELETE, and LOCK

• Other code or object

Database tier

Middle tier

Application Module (AM)

View Object (VO)

Entity Object B

Entity Object C

Table A Table B Table C

Entity Object A

PL/SQL for Table A

PL/SQL for Table B

PL/SQL for Table C


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;


Creating a Database View-Based Entity Object

1. Select the Entity Object database view.

2. Select the Primary Key attribute or attributes.


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().


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.


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.


Leveraging the Helper Method to Invoke Insert, Update, and Delete Procedures

• In the ProductsVImpl.java file, add code to invoke the PL/SQL procedures:

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

// 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()});

}


Agenda






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.


DB Constraints, Compositions, and Associations

CompositionAssociation

Database diagram

Business

Components

diagram


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.


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.


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.


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.


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.


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);

}


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.


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.


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();

} }


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


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

02_extendadfbc

Documents