You are on page 1of 276

OAF Workshop

Instructor Guide

Table of Contents
OAF Workshop - OAF Overview .................................................................................................................. 1-1
Oracle Applications Framework Workshop.................................................................................................. 1-2
Objectives ..................................................................................................................................................... 1-3
OA Framework Overview............................................................................................................................. 1-4
OA Framework Philosophy .......................................................................................................................... 1-5
Unified Platform for All Applications .......................................................................................................... 1-6
Physiology of an Application........................................................................................................................ 1-7
Technology Stack Overview ......................................................................................................................... 1-10
Functional Features ....................................................................................................................................... 1-11
Functional Features Core Services................................................................................................................ 1-12
Functional Features UI Services ................................................................................................................... 1-13
Functional Features Model Services ............................................................................................................. 1-18
Functional Features Standards Support......................................................................................................... 1-20
Functional Features Declarative MVC Architecture..................................................................................... 1-21
Business Benefits .......................................................................................................................................... 1-22
Schedule........................................................................................................................................................ 1-25
The Future..................................................................................................................................................... 1-27
The Future OAF Platform Available to Customers....................................................................................... 1-28
The Future Advanced Interactivity ............................................................................................................... 1-29
The Future Service Bean (EJB) Data Source ................................................................................................ 1-30
The Future Integration with BI Beans........................................................................................................... 1-31
Summary....................................................................................................................................................... 1-32
OAF Workshop - OAF Architecture............................................................................................................. 2-1
Oracle Applications Framework Workshop.................................................................................................. 2-2
Objectives ..................................................................................................................................................... 2-3
Objectives (continued) .................................................................................................................................. 2-4
Architectural Overview................................................................................................................................. 2-6
Architectural Overview Model ..................................................................................................................... 2-7
Architectural Overview View ....................................................................................................................... 2-8
Architectural Overview Controller ............................................................................................................... 2-9
Physiology of a Framework Application The Technology .......................................................................... 2-10
Physiology of a Framework Application The Technology ........................................................................... 2-14
Physiology of a Framework Application The Controller ............................................................................. 2-16
Physiology of a Framework Application The Model................................................................................... 2-21
Framework Technology ................................................................................................................................ 2-22
OA Framework Page..................................................................................................................................... 2-24
An Example of an OA Framework Page....................................................................................................... 2-25
An OA Framework Region ........................................................................................................................... 2-26
Controlling UI Behavior ............................................................................................................................... 2-28
Handling a GET Request .............................................................................................................................. 2-29
Handling a POST Request ............................................................................................................................ 2-30
The OAPageContext Object.......................................................................................................................... 2-31
Server Objects BC4J .................................................................................................................................. 2-33
Application Modules..................................................................................................................................... 2-34
Entity Objects................................................................................................................................................ 2-35
View Objects................................................................................................................................................. 2-36
Controlling Transactions............................................................................................................................... 2-37
Layered Re-use ............................................................................................................................................. 2-38
Applications Context .................................................................................................................................... 2-39
Handling a "GO" Button Press...................................................................................................................... 2-40
The Process ................................................................................................................................................... 2-41
The Controller............................................................................................................................................... 2-45
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop Table of Contents


i

View Object's initQuery() Method................................................................................................................ 2-46


Application Module Usage ........................................................................................................................... 2-47
State Management......................................................................................................................................... 2-48
Leveraging Key AOL Components .............................................................................................................. 2-49
Development vs. Deployment....................................................................................................................... 2-50
Resources ...................................................................................................................................................... 2-51
Summary....................................................................................................................................................... 2-52
Summary (continued).................................................................................................................................... 2-53
OAF Workshop - Early Adopter Program ................................................................................................... 3-1
Oracle Applications Framework Workshop.................................................................................................. 3-2
Objectives ..................................................................................................................................................... 3-3
EAP Background .......................................................................................................................................... 3-4
EAP Objectives............................................................................................................................................. 3-5
EAP Time and Delivery................................................................................................................................ 3-6
EAP Qualifications ....................................................................................................................................... 3-7
What Can You Do? ....................................................................................................................................... 3-8
OAF Workshop - Local Environment Setup ................................................................................................ 4-1
Oracle Applications Framework Workshop.................................................................................................. 4-2
Objectives ..................................................................................................................................................... 4-3
Pre-requisites................................................................................................................................................. 4-4
Extract Files .................................................................................................................................................. 4-5
Setup Windows Environment Variables ....................................................................................................... 4-6
Create JDeveloper Shortcut .......................................................................................................................... 4-8
Modify env.txt............................................................................................................................................... 4-9
Download the .dbc File ................................................................................................................................. 4-10
Test Your Installation.................................................................................................................................... 4-11
Starting on the Tutorial ................................................................................................................................. 4-12
Extensibility Tutorial .................................................................................................................................... 4-13
Summary....................................................................................................................................................... 4-14
OAF Workshop - Personalizations and Extensibility .................................................................................. 5-1
Oracle Applications Framework Workshop.................................................................................................. 5-2
Objectives ..................................................................................................................................................... 5-3
Taxonomy ..................................................................................................................................................... 5-4
Personalization.............................................................................................................................................. 5-5
User Interface Personalization ...................................................................................................................... 5-6
Examples of Personalization ......................................................................................................................... 5-7
Creating Admin Level Personalizations........................................................................................................ 5-8
Creating User Level Personalizations ........................................................................................................... 5-9
Benefits of Declarative Personalizations....................................................................................................... 5-10
Extensibility .................................................................................................................................................. 5-11
Adding a New Page ...................................................................................................................................... 5-12
Adding Persistent Attributes ......................................................................................................................... 5-13
Extend/Override Defaults & Validations ...................................................................................................... 5-14
Customize Page Flows .................................................................................................................................. 5-15
Standards for Extending Business Objects.................................................................................................... 5-16
Visual Illustration.......................................................................................................................................... 5-17
Upgradeable and Declarative ........................................................................................................................ 5-18
Interoperability.............................................................................................................................................. 5-19
Summary....................................................................................................................................................... 5-20
OAF Workshop - Deployment ....................................................................................................................... 6-1
Oracle Applications Framework Workshop.................................................................................................. 6-2
Objectives ..................................................................................................................................................... 6-3
Deployment Dependencies ........................................................................................................................... 6-4
Jserv Property Settings.................................................................................................................................. 6-5
Jserv Property Settings (continued) .............................................................................................................. 6-6
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop Table of Contents


ii

XDisplay ....................................................................................................................................................... 6-7


XDisplay (continued).................................................................................................................................... 6-8
SSL / HTTPS ................................................................................................................................................ 6-9
Apache Version............................................................................................................................................. 6-10
Apache Configuration ................................................................................................................................... 6-11
Apache .......................................................................................................................................................... 6-12
Load Balancing HTTP Servers / JVMs......................................................................................................... 6-13
Load Balancing HTTP Servers / JVMs (continued) ..................................................................................... 6-14
JVM / System Sizing .................................................................................................................................... 6-15
Diagnostics.................................................................................................................................................... 6-16
Moving to MDS in OAF 5.7 ......................................................................................................................... 6-17
Moving to MDS in OAF 5.7 (continued)...................................................................................................... 6-18
Summary....................................................................................................................................................... 6-19
OAF Workshop - Performance and Scalability............................................................................................ 7-1
Oracle Applications Framework Workshop.................................................................................................. 7-2
Objectives ..................................................................................................................................................... 7-3
Tuning OA Framework Applications............................................................................................................ 7-4
OA Framework Performance ........................................................................................................................ 7-16
Monitoring OA Framework Applications ..................................................................................................... 7-20
OA Framework Connection Pool.................................................................................................................. 7-23
Tracing OA Framework Applications........................................................................................................... 7-27
Summary....................................................................................................................................................... 7-29
OAF Workshops - Hands-on Lab.................................................................................................................. 8-1
OAF Workshop Hands-on Lab .................................................................................................................. 8-3
OAF Tutorial Solution ........................................................................................................................... 8-19
OAF Workshop - Extensibility Hands-on Lab ............................................................................................. 9-1
OAF Workshop Extensibility Hands-on Lab ............................................................................................. 9-2
OAF Tutorial - Lab ................................................................................................................................... 9-14
OAF Tutorial - Solution............................................................................................................................ 9-24

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop Table of Contents


iii

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop Table of Contents


iv

OAF Workshop
OAF Overview
Chapter 1

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 1

Oracle Applications Framework Workshop

Oracle Applications Framework


OAF Workshop

Overview

Schedule:

Timing
60 minutes

Topic
Lecture

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 2

Objectives

Objectives

After completing this lesson, you should be able to do


the following:
Give an overview of OA Framework
Describe the OA Framework philosophy
Describe the physiology of an application
Describe the OA Framework technology stack
Discuss the OA Framework functional features
Discuss the business benefits of OA Framework
Understand the proposed OA Framework schedule
Discuss the future directions for OA Framework

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 3

OA Framework Overview

OA Framework Overview

Oracle Applications self-service development and


deployment platform
100% Java & XML, middle-tier application
framework and services for the rapid development
& deployment of HTML based applications
JDeveloper extension

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 4

OA Framework Philosophy

OA Framework Philosophy

Declarative application development


Rapid development environment
Consistent & compelling UI
Built-in durable personalizations
Extensible UI and business logic
100% Java & XML on Oracle platform
Commitment to MVC architecture
Unified platform for all HTML based applications

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 5

Unified Platform for All Applications

Unified Platform for All Applications

Benefits, TCA - Dunn and Bradstreet,


AOL/Worklist, Student Registration
System, Project Resource
Management, Time and Labor,
iExpenses, Mobile Expenses,
iReceivables, iSupplier Portal,
Customer Portal, Quality, Customer
Portal, Training Administration,
Personnel, Payroll, Public Sector HR,
Performance Measurement FWK,
iRecruitment, Workflow, Asset
Management, iProcurement

CRM products are


migrating to OAF
Sales, Marketing,
Service, BIS,
Interaction Center,
E-Commerce

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 6

Physiology of an Application

Physiology of an Application

t
ha
W

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 7

do

u
yo

!
e!
se

Physiology of an Application

Physiology of an Application
ce
fa
r
s
Su n
e gio
h
t e
R
er of s
d
n hy em
U rc d It
a
ew er an
Vi Hi
A A

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 8

Physiology of an Application

Physiology of an Application

er ns
op gio
l
e e
ev f R
D
J o s
n h y te m
i
I
ith rc d
W ie r a a n
H
A

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 9

Technology Stack Overview

Technology Stack Overview


Browser

Web Server

Data Server

Oracle9iAS
HTTP Server and J2EE Container
Apache

OC4J

UI
Meta Data
Repository

Common Services
Portal

SSO

LDAP

BC4J:
UIX:
Application
Development
XML
& Java
XML
& Java
for data modelFramework
&
for user interface
Business Logic
OA Controller:
Oracle9i
JDeveloper
Java for flow and action events

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 10

Applications
Schema

Functional Features

Functional Features

Core Services
UI Services
Model Services
Standards Support
Declarative MVC Architecture

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 11

Functional Features Core Services

Functional Features
Core Services

Session Management
Authentication
Security
Logging & Auditing
Diagnostics

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 12

Functional Features UI Services

Functional Features
UI Services

Reusable UI Widgets

LOV
Table
HGrid
Tree
Train

Shuttle
Button
Tab
Choice list
Tip

Attachment
Hide/Show
Flex Field
etc.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 13

Functional Features UI Services

Functional Features
UI Services

Reusable Standard UI Templates


Various region layouts, such as:
Single Default Column
Double Default Column
Stacked Layout

Common navigation components


Query region
Advanced Search region
Workflow Notifications region
Catalog region
Master Detail

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 14

Functional Features UI Services

Functional Features
UI Services

Advanced UI Interactivity
Hide / Show
Smart Personalized Poplist
Partial Page Refresh (PPR)
Table Navigation, Sorting, Totaling, Row Insertion,
Detail Disclosure (row-level and cell-level)
Hide/Show Toggling
Populating LOV input

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 15

Functional Features UI Services

Functional Features
UI Services

Personalization Services
Multi-tiered personalizations:
Admin level:
Site, Organization and Responsibility
Single view at each level
User level
Several views per User
Just one click away personalization UI
Durable ~ survives upgrades
Portal integration / interoperability

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 16

Functional Features UI Services

Functional Features
UI Services

Others
Data Formatting
Dynamic date, currency and number formatting
Smart date interpretation
Printable view of a page
Export to Excel (csv format)
File upload / Attachments

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 17

Functional Features Model Services

Functional Features
Model Services

BC4J

Middle-tier object oriented data model


Fine tuned DML operations
Reusable objects
Reusable business logic
Extensible!

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 18

Functional Features Model Services

Functional Features
Model Services

Passivation Services
Scalability (reclaim idle connections)
Save current state for later
Recover from failures

E
S!
UR ENT
T
FU CEM
N
HA
EN

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 19

Functional Features Standards Support

Functional Features
Standards Support

Standards based middle-tier


Multilingual and BiDi support

Various browsers on different platforms


Meeting the standards of Section 508

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 20

Functional Features Declarative MVC Architecture

Functional Features
Declarative MVC Architecture

Meta-data driven UI components, flows and


business logic
World class IDE
Productivity wizards
Weathers technology shifts
Easier & Faster product maintenance and
customizations
J2EE based implementation

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 21

Business Benefits

Business Benefits

Lower cost of ownership


Durable Personalization & Extensibility
Quicker & cheaper implementation/upgrade cycles
Multilingual global deployments
Tab economy of scale gains
Manageability features (e.g. built-in diagnostics)
Much easier and cheaper to maintain a robust
deployment
Standards based technology and interfaces
Much cheaper to interoperate with
Declarative architecture
An insurance policy against disruptive
technologies

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 22

Business Benefits

Business Benefits

Improved business performance


Consistent and interactive UI boost user
productivity
Charting capabilities facilitate timely business
decisions
Passivation guards against data loss and enhances
user experience

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 23

Business Benefits

Business Benefits

Boost business competitiveness


In addition to lower cost of ownership & improved
business performance
State of the art self-service UI and end-user
personalization
Enhances customer/partner experience and loyalty
Easy and fast admin level personalizations
Makes it possible to react swiftly to changing
business requirements and conditions

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 24

Schedule

Schedule

OAF 5.7 January 2003


Partial Page Refresh (Table Navigation - Add Row,
Hide/Show)
Auto validated LOVs
Charting
Smaller HTML page sizes
Subtab Navigation
Passivation
Integration between OAF / JTT / Forms
Integration between OAF Attachments / OFO
Advanced AOL security integration

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 25

Schedule

Schedule

OAF 5.8 Q1 CY2003


OAF early adopters
BC4J extensibility

OAF 5.9 Q3 CY2003

Advanced interactivity for professional users


Service Bean (EJB) data source
Integration with BI Beans
Web Cache integration

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 26

The Future

The Future

OAF platform available to customers


Advanced interactivity for professional users
Service Bean (EJB) data source
Integration with BI Beans

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 27

The Future OAF Platform Available to Customers

The Future
OAF Platform Available to Customers

Prepare customer documentation


Describe best practices to ensure upgrade
survivability
Provide infrastructure for extending BC4J
Deployment strategies

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 28

The Future Advanced Interactivity

The Future
Advanced Interactivity

Keyboard Interaction
Speed keys & mnemonic keys
Smart cursor placement **
PPR dependent fields (remove the Go button)

Data Interaction

Reduced white space


Auto calc in tables
Simple drag & drop (table columns)
Master-detail PPR implementation
Row Level Events for Validation
Standard Address component
hGrid with record set navigation built in

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 29

The Future Service Bean (EJB) Data Source

The Future
Service Bean (EJB) Data Source

Web Services using a message-based


request/response API model.
expressible as XML Schema and/or equivalent
Java objects
chunky - compound collection of parameters and
data for a UI page or post a transaction in one
network round trip.
extensible by developer - developer can build a
message containing extra context parameters,
data requests and data posts.
recognizable industry patterns

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 30

The Future Integration with BI Beans

The Future
Integration with BI Beans

Support Analytic Solutions


Utilize Advanced BI Components
Dynamic Cross Tab Reporting
Interactive Control Bar, Tables and Graphs

Integrate with OLAP and EUL data sources

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 31

Summary

Summary

In this lesson, you should have learned how to:


Give an overview of OA Framework.
Describe the OA Framework philosophy.
Describe the physiology of an application.
Describe the OA Framework technology stack.
Discuss the OA Framework functional features.
Discuss the business benefits of OA Framework.
Understand the proposed OA Framework
schedule.
Discuss the future directions for OA Framework.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Overview


Chapter 1 - Page 32

OAF Workshop
OAF Architecture
Chapter 2

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 1

Oracle Applications Framework Workshop

Oracle Applications Framework


Workshop

Architecture

Schedule:

Timing
90 minutes

Topic
Lecture

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 2

Objectives

Objectives

After completing this lesson, you should be able to do


the following:
Describe the architectural layout of OA Framework
Describe the physiology of an OA Framework
application
Define and understand key OA Framework
terminology
Understand and describe the basics of an OA
Framework Page and Region

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 3

Objectives (continued)

Objectives
(continued)

Describe how user interaction is handled


Describe what happens during a GET
Describe what happens during a POST
Describe the basics of the OAPageContext object
Describe the basics of BC4J, including AMs, EOs
and VOs
Describe how transaction control is done in OA
Framework
Describe the OA Framework Re-use Onion

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 4

Objectives (continued)

Objectives
(continued)

Describe what happens when a GO button is


pressed
Describe AM usage
Describe State Management on OA Framework
pages
Describe what key AOL features are leverages by
OA Framework
Describe the differences between Development
and Deployment of OA Framework pages
Know where to go for additional resources related
to OA Framework

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 5

Architectural Overview

Architectural Overview

Declarative, MVC architecture a componentbased design with clean interfaces between


model, view and controller objects.
MetaMeta-data
Flows
UI Objects
DB Objects

Controller

Model

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 6

View

Architectural Overview Model

Architectural Overview
Model

The model encapsulates the underlying data and


business logic of the application.

Model

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 7

Architectural Overview View

Architectural Overview
View

The view formats and presents data from a model


to a user.

MetaMeta-data
Flows
UI Objects
DB Objects
View

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 8

Architectural Overview Controller

Architectural Overview
Controller

The controllers responds to user actions and


directs application flow.

Controller

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 9

Physiology of a Framework Application The Technology

Physiology of a Framework Application


The Technology
OA Framework Design time
Page Hierarchy

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 10

Physiology of a Framework Application The Technology

Physiology of a Framework Application


The Technology
OA Framework Design time
Page Hierarchy

Cache

Meta Data

.XML

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 11

Physiology of a Framework Application The Technology

Physiology of a Framework Application


The Technology
OA Framework Design time
Page Hierarchy

UIX
Bean Hierarchy

Cache

Meta Data

.XML

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 12

Physiology of a Framework Application The Technology

Physiology of a Framework Application


The Technology
OA Framework Design time
Page Hierarchy

UIX
Bean Hierarchy

UIX
Renderers

Cache

Meta Data

.XML

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 13

Physiology of a Framework Application The Technology

Physiology of a Framework Application


The Technology
OA Framework Design time
Page Hierarchy

UIX
Bean Hierarchy

UIX
Renderers

Cache

Meta Data

.XML

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 14

JSP/HTML

Physiology of a Framework Application The Technology

Physiology of a Framework Application


The Technology
OA Framework Design time
Page Hierarchy

UIX
Bean Hierarchy

UIX
Renderers

Cache

Meta Data

JSP/HTML

Browser

.XML

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 15

Physiology of a Framework Application The Controller

Physiology of a Framework Application


The Controller
User takes an action

Apply

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 16

Physiology of a Framework Application The Controller

Physiology of a Framework Application


The Controller
User takes an action

Browser
sends
request
to
Controller

Controller

Apply

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 17

Physiology of a Framework Application The Controller

Physiology of a Framework Application


The Controller
User takes an action

Browser
sends
request
to
Controller

1.

Controller
delegates data
processing to
Model

Controller

Apply

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 18

Model

Physiology of a Framework Application The Controller

Physiology of a Framework Application


The Controller
User takes an action

Browser
sends
request
to
Controller

1.

Controller 2.

Controller
delegates data
processing to
Model
Determines next
page

Apply

Meta Data
Workflow

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 19

Model

Physiology of a Framework Application The Controller

Physiology of a Framework Application


The Controller
User takes an action

Browser
sends
request
to
Controller

1.

Controller 2.
3.

Controller
delegates data
processing to
Model
Determines next
page
Invokes view to
present next
page

Apply

Meta Data
Workflow

View

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 20

Model

Physiology of a Framework Application The Model

Physiology of a Framework Application


The Model
BC4J OBJECTS
Entity Objects (EO)

View Objects (VO)

Application Module
(AM)
DML
Validations
Defaulting

Application Module
(AM)

.XML

Database
Tables,Views
PL/SQL

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 21

View Side
UIX
Bean Hierarchy

Framework Technology

Framework Technology

BC4J Java components for representing


business logic
UIX Java components for representing the User
Interface
MDS Declarative data for UIX
Resides in database (old AK)
Resides in database or XML files (JRAD)

AOL/J Applications authentication, authorization


and java services

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 22

Framework Technology

Framework Technology

Portal Enterprise portal able to centralize critical


business information and services
OA Framework Programmatic glue which
integrates these technologies

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 23

OA Framework Page

OA Framework Page

Each UI widgets corresponds to 1 or more Java


objects (Beans)
The Java objects are assembled declarative with
the JDeveloper JRAD tool
The Java objects generate HTML at runtime
The Java objects are defined hierarchically

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 24

An Example of an OA Framework Page

An Example of an OA Framework Page

Header Bean

Submit button
Bean

Results table
Bean

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 25

An OA Framework Region

An OA Framework Region

A Region is a reusable container that holds items


A Region can contain

Buttons
Fields
Images
Other Regions
Headers and so on

Regions can inherit properties from other regions


The top level of every page is a region with a
'pageLayout' style

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 26

An OA Framework Region

An OA Framework Region

The Framework uses the


order of the items to
determine their position
within a region UI

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 27

Controlling UI Behavior

Controlling UI Behavior

Controller classes define how your JavaBeans


behave
You can override controller classes to:
Manipulate the UI at runtime
Manually initialize data items
Intercept and handle user events like button clicks

Controllers classes subclass OAControllerImpl

There are methods in the Controller class to


handle GET and POST requests

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 28

Handling a GET Request

Handling a GET Request

The Framework calls the processRequest() on a


GET request
The Framework uses this method to build the
Bean hierarchy
Called for each Bean in the page hierarchy where
a controller has been registered
You can override this method on any of the beans
in the hierarchy
Typically only used on containers

The processRequest() method can be used to


Customize page layout at runtime
Perform manual data initialization
Initialize a query

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 29

Handling a POST Request

Handling a POST Request

The Framework calls processRequest() for each


Bean in the hierarchy if not available in cache
(similar to a GET)
The Framework calls processFormData()
method to read form field data from request and
apply it to underlying View Object Attributes
The Framework calls the processFormRequest()
method next
Override this method to add special event
handling logic

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 30

The OAPageContext Object

The OAPageContext Object

The Framework creates an OAPageContext object


for each request received
The methods that handle GET and POST request
accept OAPageContext as an argument
This object contains parameters from the
requesting page
It also contains form fields if the request is a POST

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 31

The OAPageContext Object

The OAPageContext Object

The OAPageContext object provides:


Access to the server Application Module Class
Methods to perform JSP forwards and client
redirects
Access to session level Application context for
User name
Id
Current responsibility

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 32

Server Objects BC4J

Server Objects BC4J

There are three basic component classes


The Application Module a container for related
BC4J objects
Entity objects encapsulate business rules
View objects present data to the Framework
page

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 33

Application Modules

Application Modules

Application Modules serve as containers for


related BC4J objects
The objects are related by participating in the
same task ( for example, a multi page UI for
creating purchase orders)
Application Modules provide transaction context
Application Modules establish database
connections
Application Modules may be nested to provide
more complex application modules

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 34

Entity Objects

Entity Objects

Encapsulate business rules and logic


Are used by any program that inserts, updates, or
deletes data
Provide consistent data validation across all
applications
May be linked to other Entity objects by Entity
Association objects

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 35

View Objects

View Objects

Encapsulate a database query


Provide iteration over the query result set
May be based on plain SQL if the UI is not for
update
May be based on multiple Entity objects if the UI is
for update
Provide single point of contact for getting and
setting Entity object values
May be linked together by View links

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 36

Controlling Transactions

Controlling Transactions

The OADBTransaction class encapsulates the


JDBC connection for your transaction
You can use this object to:
Create a callable statement for executing PL/SQL
functions and procedures
Access session-level Applications context
information
Access OANLServices object for NLS operations

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 37

Layered Re-use

Layered Re-use

Each layer only knows


about the layers below it.
This allows reuse at any
of the layer boundaries.

OAControllers
Application
Modules
View
Objects

dataflow up stack (pull)


dataflow down stack (push)

Entity
Objects

DB

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 38

Applications Context

Applications Context

The Framework application keeps track of


applications context by:
Creating a WebAppContext object when a user logs
in to a Framework Application
Creating a session-based cookie

These two objects keep track of information like


Current responsibility
Organization id
User characteristics (username, userid, and so on)

This information is accessible from


OAPageContext (on the client) or
OADBTransaction (on the server)

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 39

Handling a GO Button Press

Handling a GO Button Press

A UI button does not inherently do anything


You must add code to make the button respond to
a user click event
There are 3 steps to make the a query button work
Add an initQuery() method to the View Object that
builds and executes a query
Add a query method to the Application Module that
finds the view object and executes the initQuery()
method
Add code to the processFormRequest() method in
the Controller that calls the Application Module
query method

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 40

The Process

The Process
Controller
The controllers processFormRequest()
method is invoked when the GO button is
pressed.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 41

The Process

The Process
Controller
processFormRequest() calls
initEmployeesQuery()

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 42

The Process

The Process
Controller
processFormRequest() calls
initEmployeesQuery()

Application Module
initEmployeesQuery()
Finds and instantiates
the view object
Calls the View Object
initQuery()

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 43

The Process

The Process
Controller
processFormRequest() calls
initEmployeesQuery()

Application Module

View Object

initEmployeesQuery()

initQuery()

Finds and instantiates


the view object
Calls the View Object
initQuery()

Initializes the query


executes the query

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 44

The Controller

The Controller

Custom code goes in the processFormRequest()


method
Checks the button object to make sure it has been
clicked
Gets the Root Application Module
Serializes the parameters
Calls the 'Initialize Query' method in the
Application Module
Redirects back to the current page

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 45

View Objects initQuery() Method

View Objects initQuery() Method

Located in the VOImpl.java file


Is called from the Application Modules query
method
Accepts arguments that will be bound into the
query
Assembles a query statement using Oracle-style
parameter binding
Executes the Query

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 46

Application Module Usage

Application Module Usage

Root AM per page or multi-page transaction


By default the rootAM gets released (checked in)
when going to a new page
retainAM=Y tells Framework to retain AMs

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 47

State Management

State Management

Passivation provides a mechanism for saving


middle tier state off to the database
In 5.7 this will be used to reclaim resources
(connections and memory)
Also will be used to continue a transaction after a
session timeout
In future versions this will be used for failover on
the middle tier

May not maintain the same database session


across requests
Middle tier state known to Framework or BC4J will
be passivated automatically

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 48

Leveraging Key AOL Components

Leveraging Key AOL Components

Menus / Functions / Responsibilities / Security


Descriptive and Key Flexfields
Messages
Attachments
Workflow
Session Management
Connection Pooling
Profiles
Logging
iHelp
PL*Sql Error Handling
Grants

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 49

Development vs. Deployment

Development vs. Deployment

Development

Deployment

OC4J

Apache / JServ

XDK 9i

XDK 2.0.2.9

JDBC 9.0.2

JDBC 8.1.7

JDK / JRE 1.3

JDK 1.1.8 / JRE 1.3

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 50

Resources

Resources

www-apps.us.oracle.com/fwk
Tools:
JDEV_US IDE and BC4J issues
JDEVAPPS_US JRAD issues

Apps:
OACTECH_US High volume forum for all issues
around OA Framework. See archives and follow
template when posting a message.
OACNEWS_US Dedicated to news and
announcements on the tech stack

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 51

Summary

Summary

In this lesson, you should have learned how to:


Describe the architectural layout of OA
Framework.
Describe the physiology of an OA Framework
application.
Define and understand key OA Framework
terminology.
Understand and describe the basics of an OA
Framework Page and Region.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 52

Summary (continued)

Summary
(continued)

Describe how user interaction is handled.


Describe what happens during a GET.
Describe what happens during a POST.
Describe the basics of the OAPageContext object.
Describe the basics of BC4J, including AMs, EOs
and VOs.
Describe how transaction control is done in OA
Framework.
Describe the OA Framework Re-use Onion.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 53

Summary (continued)

Summary
(continued)

Describe what happens when a GO button is


pressed.
Describe AM usage.
Describe State Management on OA Framework
pages.
Describe what key AOL features are leverages by
OA Framework.
Describe the differences between Development
and Deployment of OA Framework pages.
Know where to go for additional resources related
to OA Framework.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - OAF Architecture


Chapter 2 - Page 54

OAF Workshop
Early Adopter Program
Chapter 3

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Early Adopter Program


Chapter 3 - Page 1

Oracle Applications Framework Workshop

Oracle Applications Framework


Workshop

Early Adopter Program

Schedule:

Timing
15 minutes

Topic
Lecture

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Early Adopter Program


Chapter 3 - Page 2

Objectives

Objectives

After completing this lesson, you should be able to do


the following:
Discuss the EAP Background
Discuss the EAP Objectives
Discuss the EAP Time and Delivery
Discuss the EAP Qualifications
Know where to know for more information

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Early Adopter Program


Chapter 3 - Page 3

EAP Background

EAP Background

Several customers asked for an IDE that


enables them to:
Add new pages
Personalize Oracle Applications UI
Extend or override Oracle Applications business
logic

The OA Framework is being packaged as an


extension to JDeveloper
The EAP will give selected customers and the field
early access to the JDeveloper extension

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Early Adopter Program


Chapter 3 - Page 4

EAP Objectives

EAP Objectives

Work with model customers on defining and


refining the capabilities of the add-on
Ramp up training for Oracles consulting, support
and sales
Encourage some existing customers to upgrade to
latest technology and products
Aid with some sales opportunities [very selective]

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Early Adopter Program


Chapter 3 - Page 5

EAP Time and Delivery

EAP Time and Delivery

Q1 CY2003
Approved candidates will receive:

Special JDeveloper with the extension


ARU to be installed on top of an Apps 11i8
Documentation
Extensibility Tutorials

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Early Adopter Program


Chapter 3 - Page 6

EAP Qualifications

EAP Qualifications

Customer needs must match our offering


Maximize benefit to customer and Oracle

Customer is using or will use a product based on


OAF 5.7
Consulting involvement

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Early Adopter Program


Chapter 3 - Page 7

What Can You Do?

What Can You Do?

Recommend candidate customers


Send email to adam.naser@oracle.com

If in consulting, convince your practice to commit


resources and participate in the program
Questions?
Email adam.naser@oracle.com

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Early Adopter Program


Chapter 3 - Page 8

OAF Workshop
Local Environment Setup
Chapter 4

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 1

Oracle Applications Framework Workshop

Oracle Applications Framework


Workshop

Local Environment Setup

Schedule:

Timing
15 minutes

Topic
Lecture

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 2

Objectives

Objectives

After completing this lesson, you should be able to do


the following:
Identify the pre-requisites to a local install
Extract the files
Setup the Windows environment variables
Create a JDeveloper shortcut
Modify env.txt
Download a proper .dbc file
Test your installation
Find and begin your workshop exercises

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 3

Pre-requisites

Pre-requisites

Assumes that you have downloaded the following


files:

http://www-apps.us.oracle.com:1100/fwk/download/57/Jdev_57g_m36/
jdev903_debug.zip
Tutorial.zip

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 4

Extract Files

Extract Files

On your drive of choice (C: thereafter) create the


two directories:
c:\jdevbin
c:\jdevhome

Extract jdev903_debug.zip under c:\jdevbin


Extract Tutorial.zip under c:\jdevhome

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 5

Setup Windows Environment Variables

Setup Windows Environment Variables

On Windows NT:
Right-click on My Computer, and choose
Properties.
Click on Advanced, then on Environment variables,
and then under User variables on the New button.
Click inside the User Variables box. For the Variable
Name field type JDEV_USER_HOME, and for the
Value field type c:\jdevhome\jdev
Click on Set, and then click the OK button to add
the new user variable.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 6

Setup Windows Environment Variables

Setup Windows Environment Variables

On Windows 2000:
Right-click on My Computer, and choose Properties.
Click on Advanced, and then click on Environment
variables. Click the New button at the User
Variables box.
For the Variable Name field type
JDEV_USER_HOME. For the Variable Value field
type c:\jdevhome\jdev.
Click the OK button to add the new user variable.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 7

Create JDeveloper Shortcut

Create JDeveloper Shortcut

Create a desktop shortcut to


c:\jdevbin\jdev\bin\jdevw.exe

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 8

Modify env.txt

Modify env.txt

Modify c:\jdevhome\jdev\myhtml\OA_HTML\env.txt
From:
FND_TOP=T:\\users\\dbc_files
JRAD_XML_PATH=T:\\users\\<YourName>\\jdev\\my
projects
JRAD_APPS=ak;fnd;dem;icx

To:
FND_TOP=c:\\jdevhome\\dbc_files
JRAD_XML_PATH=c:\\jdevhome\\jdev\\myprojects
JRAD_APPS=ak;fnd;dem

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 9

Download the .dbc File

Download the .dbc File

Download
http://www-apps.us.oracle.com:1100/fwk/
download/xweek/ap513dbs_dev115.dbc

To:
c:\jdevhome\dbc_files\secure

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 10

Test Your Installation

Test Your Installation

Open the c:\jdevhome\jdev\myprojects\toolbox.jws


workspace using the (Menu) File > Open.
Navigate to Tutorial.jpr under Workspaces toolbox.jws, right mouse click and choose Rebuild
Tutorial.jpr
You should get 0 errors, warnings are okay.

Navigate to HelloWorldPG under the Tutorial.jpr


project, right mouse click and choose run

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 11

Starting on the Tutorial

Starting on the Tutorial

Point your browser to


http://www-apps.us.oracle.com/fwk/57/
lessons/TutorialLessonList.htm

Start with Lesson 3


NOTE: substitute T:\users\<your id> with
c:\jdevhome

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 12

Extensibility Tutorial

Extensibility Tutorial

Point your browser to


http://www-apps.us.oracle.com/fwk/tutorials/
oaext/OAExt%20Lesson.htm

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 13

Summary

Summary

In this lesson, you should have learned how to:


Identify the pre-requisites to a local install.
Extract the files.
Setup the Windows environment variables.
Create a JDeveloper shortcut.
Modify env.txt.
Download a proper .dbc file.
Test your installation.
Find and begin your workshop exercises.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Local Environment Setup


Chapter 4 - Page 14

OAF Workshop
Personalizations and
Extensibility
Chapter 5

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 1

Oracle Applications Framework Workshop

Oracle Applications Framework


Workshop

Personalizations and Extensibility

Schedule:

Timing
30 minutes

Topic
Lecture

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 2

Objectives

Objectives

After completing this lesson, you should be able to do


the following:
Describe the difference between personalizations
and extensibility
Understand the process of making a
personalization
Understand extensibility

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 3

Taxonomy

Taxonomy

Personalization
Declaratively tailoring UI look-and-feel, layout or
visibility of built-in content to suite a business
need or a user preference
Extensibility
Extending the functionality of an application:
Adding new content or business logic
Extending/overriding existing business logic

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 4

Personalization

Personalization

Menus and Responsibilities


Cascading Style Sheets (CSS)
FND Messages, Lookups, etc.
Personalization Framework
UI definition overlays
Saved views
Attribute sets

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 5

User Interface Personalization

User Interface Personalization


Personalization is added on top of
base
product meta data at runtime
Admin Level Personalization
Site
Organization
Responsibility

User Level Personalization


User Views

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 6

Personalization
Personalization
Definition
Personalization
Definition
Definition

Base Product
Page Definition

Examples of Personalization

Examples of Personalization

Change the prompt for a


field
and other text on a page
Set whether a field or
region
is visible
Reorder the fields or
components on a page
Restrict the data that a
user
can access
Add new buttons or links,
text items, images, etc.
Restrict query results

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 7

Creating Admin Level Personalizations

Creating Admin Level Personalizations

1. Administrator sets profile option:


(FND_CUSTOM_OA_DEFINTION = Y)
2. Run application
3. Click on Personalize Region link for region you
wish to modify
4. Execute and save personalizations
5. Review results

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 8

Creating User Level Personalizations

Creating User Level Personalizations

1. Run application
2. Enter search criteria and click on Go
3. Click on Save Search to save query
4. Create view definition
5. Execute and save personalizations
6. Review results

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 9

Benefits of Declarative Personalizations

Benefits of Declarative Personalizations

Personalizations survive upgrades and patches


Admin personalizations available on any
component
User personalizations on tables/inquires
Administrator can easily disable personalizations
for debugging:
FND_DISABLE_OA_CUSTOMIZATIONS = Y

Personalizations can be translated


Can implement personalizations on test system
Personalization feedback is immediate

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 10

Extensibility

Extensibility

Flexfields
Workflow
Business Events
Extending and Creating Business Objects

New page(s)
New attribute(s)
Extend/over-ride defaults and validations
Customize page flow(s)

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 11

Adding a New Page

Adding a New Page

Use JDeveloper
IDE to create a
new page
Pass
information
between pages
through URLs
or middle-tier
state objects

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 12

Adding Persistent Attributes

Adding Persistent Attributes

Use Descriptive
Flexfields in the
traditional manner
(a) Extend the
underlying View
Object to include
more columns or to
add an additional
table
(b) Use
Personalization
Framework to
expose into the UI

New information

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 13

Extend/Override Defaults & Validations

Extend/Override Defaults & Validations

Subclass the relevant Entity Object and


programmatically add logic to existing methods
or Use BC4J events

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 14

Customize Page Flows

Customize Page Flows

Use Workflow
Extend the OA Controller
Override Link Item definition
Override Function definition

Eventually workflow (and menus) will be used for navigation across transactions
while the JDev Controller will be used for navigation within a given transaction.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 15

Standards for Extending Business Objects

Standards for Extending Business Objects

Never start with a copy of . Always extend .


Use JDeveloper IDE wizards to extend and create
new Business Objects
All changes must be done in the definition of the
extended object
Entity Object ~ when overriding defaults or validations
View Object ~ when adding new attributes

Use the substitution mechanism to let the


framework start using the extended version of the
object
Dont change base objects references to object
subject to extension

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 16

Visual Illustration

Visual Illustration

Enity.xml
EntityEO.java

VAM.xml
VAM.java

VVO.xml
VVO.xml
VVO.java
VVO.java

EntityExpert.java

MyEnity.xml
MyEntityEO.java

MyVAM.xml
MyVAM.java

VVO.xml
MyVVO.xml
VVO.java
MyVVO.java

MyEntityExpert
.java

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 17

Upgradeable and Declarative

Upgradeable and Declarative

All extensions in Oracle Applications are designed


to be upgradeable through:
Declarative overlays Customer changes to
declarative data resides in another schema
Factory mechanisms Declarative mechanisms
allow subclasses of the objects within the
customers package to be instantiated

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 18

Interoperability

Interoperability

Use the Business Event System


When running in OC4J, Business Objects will be
exposed as:
Web Services
Enterprise Java Beans (EJBs)

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 19

Summary

Summary

In this lesson, you should have learned how to:


Describe the difference between personalizations
and extensibility.
Understand the process of making a
personalization.
Understand extensibility.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Personalizations and Extensibility


Chapter 5 - Page 20

OAF Workshop
Deployment
Chapter 6

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 1

Oracle Applications Framework Workshop

Oracle Applications Framework


Workshop

Deployment

Schedule:

Timing
30 minutes

Topic
Lecture

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 2

Objectives

Objectives

After completing this lesson, you should be able to do


the following:
Understand the BIG PICTURE of things to do to
deploy OA Framework
Know where to go to more more specific
instructions to deploy OA Framework

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 3

Deployment Dependencies

Deployment Dependencies

Apache / Jserv 1.3.19


JDK 1.3.1_06 MetaLink Note 130091.1
jdbc12.zip MetaLink Note 164317.1
Workflow 2.6
CRM Interop (2282715) if customer is at CRM
11.5.6 or above
Check for latest OAF Rollup Patch (OAF 5.6E +
2501333)

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 4

Jserv Property Settings

Jserv Property Settings

FND_TOP
defines the location of the dbc file

Disable some BC4J exceptions added in BC4J 9i


wrapper.bin.parameters=Djbo.323.compatible=true

New libraries in classpath


Confirm that you added these while upgrading to
JDK 1.3 :
wrapper.classpath=<JDK13_TOP>/lib/dt.jar
wrapper.classpath=<JDK13_TOP>/lib/tools.j
ar
wrapper.classpath=<JDK13_TOP>/jre/lib/rt.
jar

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 5

Jserv Property Settings (continued)

Jserv Property Settings


(continued)
Add these for OAF:
wrapper.classpath=<JAVA_TOP>/jbojdbcpatch
.zip
wrapper.classpath=<JAVA_TOP>/jdbc12.zip
wrapper.classpath=<JAVA_TOP>/sax2.zip

Confirm Library reference for [POSDUVHUY]LS


wrapper.classpath=<JAVA_TOP>/xmlparserv2.
zip

Add the following to zone.properties to improve


first access after bounce
servlets.startup=oracle.apps.fnd.framewor
k.OAStartupServlet

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 6

XDisplay

XDisplay

OAF dynamically generates and caches images


with embedded text at runtime
Creates buttons and tab menu bars
Uses standard Java component - AWT

AWT on Unix requires an X Server


If X server is not available use the software
alternatives XVFB (X Virtual Frame Buffer) or
XVNC (X-based VNC) Metalink Note 181244.1
Ensure the display server is accessible by the
Apache server that will call it. use "xhost +", or
"xauth

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 7

XDisplay (continued)

XDisplay
(continued)

In jserv.properties add the following:


wrapper.env=DISPLAY=<xserverhostname>:<xserver-displayport>

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 8

SSL / HTTPS

SSL / HTTPS

Generate the Certificate Signing Request (CSR).


Submit the CSR to the Certificate Authority (CA) of
your choice. (Verisign is a popular CA.)
Deploy the certificate sent to you by the CA. (You
can either buy a certificate or use a trial one.)
Configure Apache for SSL connections.
Use MetaLink note 123718.1 as a detailed guide.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 9

Apache Version

Apache Version

Get to highest Apache version available especially


on Windows platforms
Get Apache 1.3.12F via patch for Apps 11.5.6 or
below MetaLink Note 161779.1
11.5.7 and above has 1.3.19 as part of Rapid Install
Once iAS 1.0.2.2 generally available (sometime in
Jan 2003?) move all Apps customers to Apache
1.3.19 ASAP

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 10

Apache Configuration

Apache Configuration

Minimize levels of logging (httpds.conf):


LogLevel warn
SSLLogLevel warn

Enable Caching of non-HTML resources including


images, style sheets, and Java script.
Caches content in the browser cache.
Reduces network round-trips (non SSL)
Reduces network bandwidth utilization (SSL)

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 11

Apache

Apache

On UNIX, Apache is process based (httpd), and


mods such as mod jserv run within the httpd
processes so multiple httpd processes will exist
On Windows, Apache is multi-threaded
(Apache.exe) so youll only have one apache
process
Tune the number of processes and number of
clients (httpds.conf):

MinSpareServers 5
MaxSpareServers 5
StartServers 5
MaxClients 512

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 12

Load Balancing HTTP Servers / JVMs

Load Balancing HTTP Servers / JVMs

HTTP Load Balancing


Hardware driven
Big IP
Cisco Content Service Switcher
Switcher maintains connection persistence

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 13

Load Balancing HTTP Servers / JVMs (continued)

Load Balancing HTTP Servers / JVMs


(continued)

JVM Load Balancing


Software driven mod_jserv
iAS provides oProc manager to manage
starting/stopping
Bug fix needed to load balance across multiple
servers on ias 1.0.2.2
Auto Config is limited to a single server (Multi node
Auto Config comes in June)
Apache/Mod_jserv maintains connection
persistence
http://java.apache.org/jserv/howto.loadbalancing.html

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 14

JVM / System Sizing

JVM / System Sizing

Allocate sufficient heap size for each JVM


wrapper.bin.parameters=-Xms256m -Xmx512m

Initiate sufficient instances of JVMs for active


user community
One JVM per CPU without other forms of load on
box
100 simultaneous peak users per JVM (Number of
active application modules)
Typical box Dell 4600 2x4 < $20,000
Red Hat Linux OS
2 CPUs - 1.5 GHz clock speed or above
4 Gb of memory

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 15

Diagnostics

Diagnostics

Application Module Pool Monitor


SQL Trace Utility
Diagnostics Log Viewer Interacts with following
Profiles
FND: Debug Log Enabled
Enables/Disables Logging (Default = No)
FND: Debug Log Filename
File location for log file; undefined logs to database
(Default = null)
FND: Debug Log Module
Log all modules (package+classname) matching this
parameter (Default = %)
FND: Debug Log Level
Log messages with level equal to or greater than setting
(Default = Statement)

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 16

Moving to MDS in OAF 5.7

Moving to MDS in OAF 5.7

Migration of page metadata from AK to MDS


Controlled by an application level profile value:
FND: Migrated To JRAD

Profile is set per application and delivered with


MDS page definitions via ARU
OAF 5.7 can run off MDS database repository or
XML files on file system
Customers always run from database MDS
repository

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 17

Moving to MDS in OAF 5.7 (continued)

Moving to MDS in OAF 5.7


(continued)

Personalizations are stored with corresponding


repository
Customer personalizations are migrated from AK
to MDS when base application page XML is
delivered via ARU
&XVW0LJUDWLRQ7RRO 
     

Customer deployment of personalization metadata


requires corresponding export/import tool
akload
XMLExporter/XMLImporter

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 18

Summary

Summary

In this lesson, you should have learned how to:


Understand the BIG PICTURE of things to do to
deploy OA Framework.
Know where to go to more more specific
instructions to deploy OA Framework.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 19

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Deployment


Chapter 6 - Page 20

OAF Workshop
Performance and Scalability
Chapter 7

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 1

Oracle Applications Framework Workshop

Oracle Applications Framework


Workshop

Performance and Scalability

Schedule:

Timing
60 minutes

Topic
Lecture

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 2

Objectives

Objectives

After completing this lesson, you should be able to do


the following:
Understand how OA Framework applications are
tuned
Understand OA Framework performance
Monitor OA Framework applications
Understand the OA Framework connection pool
Trace OA Framework applications

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 3

Tuning OA Framework Applications

Tuning OA Framework Applications

Apache
On UNIX, Apache is process based (httpd), and
mods such as mod PL/SQL run within the process
address space of the httpd processes.
On Windows, Apache is multi-threaded
(Apache.exe).
Tune the number of processes and number of
clients (httpds.conf):
MinSpareServers 5
MaxSpareServers 10
StartServers 5
MaxClients 512

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 4

Tuning OA Framework Applications

Tuning OA Framework Applications

Minimize levels of logging (httpds.conf):

LogLevel warn
SSLLogLevel warn

Enable Caching of non-HTML resources including


images, style sheets, and Java script.

Caches content in the browser cache.


Reduces network round-trips (non SSL)
Reduces network bandwidth utilization (SSL)

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 5

Tuning OA Framework Applications

Tuning OA Framework Applications

Enable Caching of non-HTML resources (httpd.conf)

<Directory "<physical_path_corresponding_to_the_alias_/OA_HTML/>">
#enable the generation of the Expires header for files under /OA_HTML/
ExpiresActive On
#expire images one month after last client access
ExpiresByType image/gif "access plus 1 month"
#expire stylesheets one week after the last client access
ExpiresByType text/css "access plus 1 weeks"
#expire javascript libraries one day after the last client access
ExpiresByType text/javascript "access plus 1 days"
</Directory>

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 6

Tuning OA Framework Applications

Tuning OA Framework Applications

Review Apache Access Log file to ensure images


are being satisfied from the browser cache.

Http code 200 (request for document)


Http code 304 (request for time stamp)

130.35.127.106 - - [23/Oct/2002:19:00:21 -0700] "GET /OA_MEDIA/FNDINVDT.gif HTTP/1.1" 200 821


130.35.127.106 - - [25/Oct/2002:14:38:23 -0700] "GET /OA_MEDIA/FNDINVDT.gif HTTP/1.1" 304 130.35.127.106 - - [25/Oct/2002:14:38:23 -0700] "GET /OA_MEDIA/FNDWATHS.gif HTTP/1.1" 200 190
130.35.127.106 - - [25/Oct/2002:14:38:23 -0700] "GET /OA_MEDIA/FNDREDPT.gif HTTP/1.1" 200 70
130.35.127.106 - - [25/Oct/2002:14:39:23 -0700] "GET
/OA_HTML/OA.jsp?page=/oracle/apps/icx/por/rcv/pages/ReceivingHomePage&OAHP=ICXP
OR_MENU&OASF=ICXPOR_RCV_HOME_PAGE&dbc=ap107fam_ipdev11i&language_code=US&transactionid=70A5819F04C
0F411 HTTP/1.1" 200 14
130.35.127.106 - - [25/Oct/2002:14:39:34 -0700] "GET /servlets/PoolMonitor?jvm HTTP/1.1" 200 7954
130.35.127.106 - - [25/Oct/2002:14:41:03 -0700] "GET /OA_HTML/US/ICXINDEX_ipdev11i.htm HTTP/1.1"
304 130.35.127.106 - - [25/Oct/2002:14:41:03 -0700] "GET /OA_MEDIA/logo.gif HTTP/1.1" 304 130.35.127.106 - - [25/Oct/2002:14:41:03 -0700] "GET /OA_MEDIA/appslogo.gif HTTP/1.1" 304 130.35.127.106 - - [25/Oct/2002:14:41:03 -0700] "GET /OA_MEDIA/FNDJLFRL.gif HTTP/1.1" 304 130.35.127.106 - - [25/Oct/2002:14:41:03 -0700] "GET /OA_MEDIA/FNDINVDT.gif HTTP/1.1" 304 130.35.127.106 - - [25/Oct/2002:14:41:03 -0700] "GET /OA_MEDIA/FNDJLFRR.gif HTTP/1.1" 304 -

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 7

Tuning OA Framework Applications

Tuning OA Framework Applications

Configure a dedicated mod PL/SQL Listener

Improves performance and scalability


Reduces overall number of sessions/connections.
Reduces latency of web requests.
Improves cursor sharing.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 8

Tuning OA Framework Applications

Tuning OA Framework Applications

Apache Mod PL/SQL (dedicated listener)


1. For the main Listener running on Port 7000, edit the file
$IAS_HOME/Apache/modplsql/cfg/plsql.conf as follows:
Disable the mod PL/SQL service from the main listener by
commenting out the lines between the two Location parameters as
follows:
<Location /pls>
# SetHandler pls_handler
# Order deny,allow
# Allow from all
</Location>

Comment out the following line as follows:


# LoadModule plsql_module /d1/ias/Apache/modplsql/bin/modplsql.so

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 9

Tuning OA Framework Applications

Tuning OA Framework Applications

Apache Mod PL/SQL (dedicated listener)

2. Configure the main listener to forward all mod_plsql requests to


the dedicated mod PL/SQL listener by adding the following line:
ProxyPass /pls/ http://sechost.us.oracle.com:8888/pls/

For the dedicated mod PL/SQL Listener running on Port 8888,


configure each DAD to override the default CGI environment
variables in order to allow redirects. Edit the file
$IAS_HOME/Apache/modplsql/cfg/wdbsvr.app and add the following line
for each DAD:
cgi_env_list=SERVER_NAME=mainhost.us.oracle.com,SERVER_PORT=7000,HO
ST=mainhost.us.oracle.com:7000

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 10

Tuning OA Framework Applications

Tuning OA Framework Applications

Apache Jserv / JVM

Minimize Jserv logging


log=true
log.channel.warning=true
log.file=/d1/ias/Apache/Jserv/logs/jserv_7000.log
Disable auto reload in production environments:
autoreload.classes=false
autoreload.file=false
Use Jserv Auto Load Balancing
Configure Multiple Zones.
Provides higher availability and improves scalability.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 11

Tuning OA Framework Applications

Tuning OA Framework Applications

Apache Jserv / JVM

Upgrade to the latest JDK (1.3.1_06).


Do not disable hotspot or the JIT
(i.e. DCOMPILER=NONE or Xint).
Enable verbose GC in order to optimally tune the
heap sizes based on the GC traffic.
Minor Collections
Major Collections
Elapsed Time of GC

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 12

Tuning OA Framework Applications

Tuning OA Framework Applications

Apache Jserv / JVM

Enable Verbose GC Output


Overload wrapper.bin with a shell wrapper in order
to redirect stdout to a file.

Existing:
wrapper.bin=/d13/jdk/jdk1.3.1/bin/java
Change To:
Wrapper.bin=/d13/scripts/java.sh
java.sh:
=========
/d13/jdk/jdk1.3.1/bin/java -verbosegc $* >> /d2/logs/java.log

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 13

Tuning OA Framework Applications

Tuning OA Framework Applications

Apache Jserv / JVM (Verbose GC Output)


/d2/logs/java.log:
[GC 30460K->1369K(510848K), 0.1135695 secs]
[Full GC 15135K->1686K(510848K), 0.2700469 secs]
[GC 32123K->2131K(510848K), 0.0203634 secs]
[GC 32595K->2130K(510848K), 0.0113639 secs]
[GC 32593K->2171K(510848K), 0.0129179 secs]
[GC 32635K->2419K(510848K), 0.0567306 secs]
[GC 32881K->3157K(510848K), 0.2906981 secs]
[GC 33620K->3197K(510848K), 0.0320023 secs]
[GC 33661K->3218K(510848K), 0.0103013 secs]
[GC 33674K->3309K(510848K), 0.0487887 secs]
[GC 33769K->3532K(510848K), 0.0531514 secs]
[GC 33983K->3784K(510848K), 0.0552549 secs]
[GC 34248K->4056K(510848K), 0.0624969 secs]
[GC 34520K->4404K(510848K), 0.0555575 secs]
[GC 34868K->4828K(510848K), 0.0587044 secs]
[GC 35292K->5242K(510848K), 0.0945290 secs]

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 14

Tuning OA Framework Applications

Tuning OA Framework Applications

Apache Jserv / JVM

Utilize the verbose GC output to tune the JVM


heaps (-Xmx and Xms) accordingly.
Review the frequency of collections, especially
major collections (i.e. Full GC).
Start with:
-Xms256M and Xmx512M
-XX:NewSize=60M -XX:MaxNewSize=120M

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 15

OA Framework Performance

OA Framework Performance

iExpenses Scalability

Response Time

10
9
8
7
6
5
4
3
2
1
0

Single JVM
4 JVMs

10

50 100 150 200 250


Number of Users

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 16

OA Framework Performance

OA Framework Performance

Network Traffic

Transaction
Frames App.frames
Bytes
AppTurns
TCPTurns
===============================================================================
General_Info(p1)
49
31
25,710
8
7
cc_txn(p2)
104
62
51,170
19
15
cc_txn_verify(p3)
103
69
55,770
21
16
Cash_txn_10lines
141
92
99,796
16
27
Review(p5)
116
74
77,651
13
25
Submit(p6)
47
28
20,671
9
7
Confirm_Submit(p7) 121
77
73,224
17
23

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 17

OA Framework Performance

OA Framework Performance
Middle-Tier Scalability &
Utilization

5
CPU Utilization

Page Response Time


(seconds)

4
3
2
1
0
10

50

100
90
80
70
60
50
40
30
20

100 150 200 250

10

50

100 150 200 250


Users

Users

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 18

OA Framework Performance

OA Framework Performance

Network Traffic

Page
Frames App.frames Bytes AppTurns
TCPTurns
=================================================================
PHP (List of Apps)
100
94
39,344
48
2
Applications Portal
88
72
42,476
31
6

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 19

Monitoring OA Framework Applications

Monitoring OA Framework Applications

Pool Monitor can be used to monitor the resource


utilization

Application Module Pool


View Objects
Entity Objects
Memory Utilization
JVM Properties
https://<hostname>/servlet/OAAppModPoolMonitor

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 20

Monitoring OA Framework Applications

Monitoring OA Framework Applications

OA Framework Applications (Pool Monitor)

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 21

Monitoring OA Framework Applications

Monitoring OA Framework Applications

OA Framework Applications (Pool Monitor)

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 22

OA Framework Connection Pool

OA Framework Connection Pool

AOL/J Connection Pool (dbc configuration)


$FND_TOP/secure/<hostname_sid>.dbc

Number of DB connections used by the Java based


OA Framework Applications.
FND_JDBC_MAX_CONNECTIONS: 300
AOL/J automatically decays idle connections and
resizes the pool.
Disable sanity checks in production environments
FND_JDBC_USABLE_CHECK=false
FND_JDBC_PLSQL_RESET=false

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 23

OA Framework Connection Pool

OA Framework Connection Pool


AOL/J Connection Pool (dbc configuration)

Patch 2566387 allows the use of service names in


the configuration:
New dbc parameter APPS_JDBC_URL
Used in place of DB_HOST, DB_NAME,
DB_PORT
Useful for automatic connection load
balancing

APPS_JDBC_URL=jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(LOAD_BA
LANCE=ON)(ADDRESS=(PROTOCOL=TCP)(HOST=ap201ops)(PORT=1526))(ADDRESS
=(PROTOCOL=TCP)(HOST=ap202ops)(PORT=1526)))(CONNECT_DATA=(SERVICE_N
AME=opsperf)))

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 24

OA Framework Connection Pool

OA Framework Connection Pool

AOL/J Connection Pool (dbc configuration)

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 25

OA Framework Connection Pool

OA Framework Connection Pool

AOL/J Connection Pool (dbc configuration)

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 26

Tracing OA Framework Applications

Tracing OA Framework Applications

Set profile FND : Diagnostics to Yes at user


level
Login to Self Service as the above user
Click on Diagnostics icon at the top of page
Select Set Trace Level and click Go
Select the desired trace level and click Save
Perform the activity that you want to trace
Exit application

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 27

Tracing OA Framework Applications

Tracing OA Framework Applications

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 28

Summary

Summary

In this lesson, you should have learned how to:


Understand how OA Framework applications are
tuned.
Understand OA Framework performance.
Monitor OA Framework applications.
Understand the OA Framework connection pool.
Trace OA Framework applications.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 29

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Performance and Scalability


Chapter 7 - Page 30

OAF Workshop
Hands-on Lab
Chapter 8

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 1

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 2

OAF Workshop Hands-on Lab


Contents
This exercise is organized into a series of questions that revisit key concepts presented in the lesson followed by handson lab.

Hands-On Lab Overview


For this exercise, you'll be implementing a simple "Search" and "Results" page as shown in Figure 01 below. Although this is similar to the purchase order "Search" page we studied in Lesson 3, we'll be
using a simpler entity (employees) so we can easily build on this exercise as we proceed through
subsequent lessons. Eventually, we'll add the ability to view, create and update employees.
Figure 0-1: Lesson 3 Lab Finished Product

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 3

If You Need Help...

The LabSolutions.jpr project contains all the code, including BC4J components and
declarative JRAD definitions, that comprise our solution to the exercises. You can run and view
our solution by expanding that project.
The solution document for this lab exercise contains explicit instructions for each step listed
below. If you need help, look for the corresponding step in the solutions document (or, if you're
working through this lab online, simply click the lesson step in this document to view the
corresponding solution). You should never have to guess at the correct implementation of an
exercise task.
The Lesson 3 Troubleshooting Guide includes common mistakes that students make with this
lab and suggests possible solutions.
Since each lesson exercise builds on the previous one, if you get stuck on this exercise and want to proceed to
Lesson 4 without finishing this one first, you can install a completed Lesson 3 exercise in your working directory. <
FOR HQ CLASS: Contact Sara Woodhull if you need this >

Warning Installing the Lesson 3 completed exercise implementation will overwrite any work
that you've done. If you want to save your Lesson 3 exercise work so you can revisit it later, we
suggest that you simply copy your jdev directory and name it something like jdev_lesson3
before unzipping the completed Lesson 3 exercise. When you're ready to resume the lab,
rename this saved directory to jdev and proceed (remember that you can have only 1 "jdev"
directory at a time).

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 4

Task 1 Create / Run the Basic Page

TIP Save frequently! We remind you to do this at the end of each task, but suggest that you save
more often.
So we don't start with too big a job at once, we'll break the page construction into several discrete
tasks. For your first task, you'll build and run a page with just the "Employees" header and the
"Search" and "Results" subheaders as shown in Figure 1-1 below:
Figure 1-1: Task 1 Finished Product

Step 1.1 Create a project named TutorialLabs.jpr. This is where you'll be creating all of your work.

TIP Remember to select (Menu) Project > Show Categories for any projects you open. It is
far easier to manage and navigate a large project when the files are categorized.

Step 1.2 Modify the project settings for your TutorialLabs.jpr project as described in the Hello, World! exercise.

Step 1.3 Create an oracle.apps.dem.employee.server BC4J package for your UI-related objects.

TIP If a BC4J package already exists, you can add it to your project by opening the xml file
located at the end of the package path (for example, opening server.xml located in your
myprojects\oracle\apps\dem\employee\server directory).

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 5

Step 1.4 Create an oracle.apps.dem.schema.server BC4J package for your EO-related objects (you'll be adding
these in a later lesson).

Step 1.5 Add the predefined test_fwklabs.jsp file to your project. You'll find this file in your
jdev\myhtml\OA_HTML directory (for example if you're an Oracle Applications developer working off the central
NAP drives or Tarantella, this will be in T:\users\<your user id>\jdev\myhtml\OA_HTML).

Step 1.6 Create the root UI Application Module (AM) in the oracle.apps.dem.employee.server BC4J package
named EmployeeAM. Be sure to generate a Java file for this Application Module because we'll be adding code to
it in this exercise.

Step 1.7 Edit the root UI AM to specify the standard Applications passivation setting. Remember that the property
Name should be RETENTION_LEVEL, and the property Value should be MANAGE_STATE.

Step 1.8 Create the EmpSearchPG page and add it to the oracle.apps.dem.employee.webui package.

Warning You MUST use this name and package or your page will not run properly. In fact, if
any package, Java file or JRAD region, item names, etc. are specified in the exercise
instructions, you must match them exactly in your work.

Step 1.9 Modify the default page layout region for the EmpSearchPG page.
o
o
o
o
o

Per the naming standards, the region's name should be PageLayoutRN


The window title should be Framework ToolBox Tutorial: Labs
The page header title should be Employees
Set the root UI Application Module to the one you created above.
Don't forget to enable the footer!

TIP When you first open the JRAD Property Inspector, the properties are listed in
alphabetical order. To organize them into meaningful categories (which we find to be
much more user friendly), select the Category icon in the Property Inspector toolbar as
shown below:

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 6

Step 1.10 Add your branding image. Use branding_tutorialapp.gif for the image. Be sure to
specify the source correctly.
Step 1.11 Add a "Search" region with the region header text set to Search. To comply with the
naming standards, please assign this region the JRAD ID SearchRN.
Step 1.12 Add a "Results" region with the region header text set to Results: No Search
Conducted (this is the default value; we'll set the post-search value programmatically later).
To comply with the naming standards, please assign this region the JRAD ID ResultsRN.
Step 1.13 Save and test your work. To run your JSP, select test_fwklabs.jsp, right-click and
select Run test_fwklabs.jsp from the context menu.
Your results should appear as shown above in Figure 1-1. (Note that, depending on
your environment's profile option settings, you might see "Personalize Region" links
throughout your page layout. This is normal and expected when a page is run in a
customizable mode. We'll learn more about this in Lesson 6. IF YOU DO SEE
PERSONALIZE LINKS -- DON'T PLAY WITH THEM AS YOUR EFFORTS AFFECT
EVERYONE IN THE CLASS).

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 7

Task 2 - Add the "Search" Region Items

In this section, you're going to add some region-level instruction text, two search criteria fields and a
"Go" button to your "Search" subheader region. When you're finished with this part of the exercise,
your UI should appear as shown in Figure 2-1 below:
Figure 2-1: Task 2 Finished Product

Step 2.1 Create region-level instruction text as a static styled text item. Use the predefined message
FWK_TBX_T_REGION_GENERAL (Application Short Name ICX). To comply with the naming standards, please
assign this item the JRAD ID SearchHelp and don't forget to set your CSS Class name properly for instruction
text.

TIP In Steps 2.2 and 2.3, you will need to select an attribute set in the JRAD Property
Inspector. To do this, place your cursor into the Attribute Set item property and select
the list of values button [...] to open the attribute set selection window. Click the Browse
button. In the Browse window, navigate to
/oracle/apps/fnd/framework/toolbox/attributesets and select the OK button. Finally,
select the Search button. You should now see a list of available attribute sets from
which to choose. In some cases, the attribute set list of values will not display until at
least 1 attribute set has been loaded to your project. If this happens, type the complete
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 8

attribute set path as listed in the corresponding lab step for your first attribute set
reference. You should then be able to select additional attribute sets as described here.

Step 2.2 Create the Employee Name text input item (we'll change this to an LOV field in a later step; for now,
simply create a plain text input field). Use the attribute set
/oracle/apps/fnd/framework/toolbox/attributesets/FwkTbxEmployees/FullName and don't forget to set the
correct CSS Class name for a text field. Also, please assign this item the JRAD ID EmpName.

Step 2.3 Create the Employee Number text input item using the attribute set
/oracle/apps/fnd/framework/toolbox/attributesets/FwkTbxEmployees/EmployeeId, and don't forget to set the
correct CSS Class name for a text field. Also, please assign this item the JRAD ID EmpNum.

Step 2.4 Create the Go submit button item using the standard attribute set
/oracle/apps/fnd/attributesets/Buttons/Go. Verify that the prompt is set to Go, and set the JRAD ID to Go.

Step 2.5 Save and test your work. Your results should appear as shown above in Figure 2-1.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 9

Task 3 - Create the EmployeeSummaryVO View Object

Step 3.1 Create the View Object (VO) in the oracle.apps.dem.employee.server BC4J package using the
following query. Also, be sure to generate Java files for both the View Object (we'll be adding code to this a bit
later) and the View Row (remember, for performance reasons we generate a *RowImpl.java class for every single
View Object we create regardless of whether we need to add code or not).

SELECT
emp.employee_id AS EMPLOYEE_NUMBER,
emp.full_name AS EMPLOYEE_NAME,
emp.email_address,
emp.manager_id,
emp2.full_name AS MANAGER_NAME,
emp2.email_address AS MANAGER_EMAIL,
flkp.meaning AS POSITION_DISPLAY,
emp.start_date,
emp.end_date,
emp.salary
FROM
fwk_tbx_employees emp,
fwk_tbx_employees emp2,
fwk_tbx_lookup_codes_vl flkp
WHERE
emp.manager_id = emp2.employee_id (+)
and emp.position_code = flkp.lookup_code
and flkp.lookup_type = 'FWK_TBX_POSITIONS'

Step 3.2 Edit the VO to disable passivation.

Step 3.3 Add your VO to the root UI AM you created in Task 1, Step 1.6 above.

TIP Take careful note of the default View Usage name that BC4J creates when you add your
VO to the selected AM (BC4J creates this name by appending a "1" to your VO name). Leave
it or change it, your choice. In either case, know what the value is before creating your
"Results" table region in Task 4 below.

Step 3.4 Save your work. There is no need to test at this point since we haven't associated the View Object with
your UI.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 10

Task 4 - Add the "Results" Region Items

In this section, you'll create the data table for your "Results" region and associate it with the View
Object you just created for this purpose. The finished region should appear as shown in Figure 4-1
below:
Figure 4-1: Task 4 Finished Product

TIP If you examine the "Results" region definition in the LabSolutions.jpr project, you'll note that
its child is a tableLayout region, and not a table. Why? The region reflects changes made in Lesson
4's exercise. For now, add your table directly to the "Results" region as described here.

Step 4.1 Add a "Results" data table based on the EmployeeSummaryVO that you created in Task 3. To do this,
select the "Results" region in the structure hierarchy, right-click and select New > Region Using Wizard from the
context menu.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 11

TIP Whenever you need to create a new region whose items will bind to a View Object, the
"Region Using Wizard" tool is the fastest and most reliable way to do this since it ensures that
all your View Object bindings are correct.
Warning In JRAD M3.6, there is an issue that the region wizard gets confused if there are
multiple application modules with the same name, but in different packages, in a workspace
(bug #2524776). The symptom is that you may see more view objects than you have created
so far--these come from the LabSolutions project. The workaround is to remove
LabSolutions.jpr from your workspace temporarily while you use the region wizard.
o
o
o

Make absolutely sure that you DO NOT select the "Use this as Application Module Definition for this
region" checkbox in the wizard's Select a View Object for the Region page.
Set the JRAD ID to ResultsTable, and make sure you select the right item style for a data table.
Your table should include the items shown in the table below (the View Object Attribute names assume
you copied the SQL in Step 3.1 exactly). Note the JRAD IDs that you should use for these items which
include a qualifier to distinguish the "Results" employee name and number items from those we created in
SearchRN.
Finally, while you're in the Customize Properties page, change the Style of each attribute to
messageStyledText (all LOV table items should have this style).

TIP If you find the Customize Properties page in the wizard difficult to
use, you can change the attribute properties using the Property Inspector
pane after you leave the wizard.

View Object Attribute

JRAD ID

EmployeeNumber

ResultsEmpNum

EmployeeName

ResultsEmpName

PositionDisplay

PositionDisplay

ManagerName

ManagerName

Step 4.2 Set the Results Table region properties as follows:


o Width should be 100% (it's important that you set it exactly to "100%" and not "100" as this the
Framework interprets this as meaning "100 pixels" and not "100 percent.")
o Number of rows displayed should be 10
Step 4.3 Verify/set individual the following item properties:
o All items should have the Style set to messageStyledText
o The ManagerName value should display as a "mailto" link that references the ManagerEmail attribute in
your View Object
o Make the ResultsEmpNum item sortable. Also designate it as the default sort value in ascending order.
o Make sure the ResultsEmpNum item has a Number data type
o Check that each item has its View Usage Name property set to EmployeeSummaryVO1 (you may need
to add the 1).
o The ResultsEmpNum item Sortable property set to Ascending.
o The ResultsEmpNum item Initially Sort this Column property set to first.
o Change the Data Type property of the ResultsEmpNum item from VARCHAR2 to NUMBER.
o Please set the following prompts and attribute sets for each item:

Item

Prompt

Attribute Set

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 12

ResultsEmpNum

Number

/oracle/apps/fnd/framework/toolbox/FwkTbxEmployees/EmployeeId

ResultsEmpName

Name

/oracle/apps/fnd/framework/toolbox/FwkTbxEmployees/FullName

ManagerName

Manager

/oracle/apps/fnd/framework/toolbox/FwkTbxEmployees/FullName

PositionDisplay

Position

/oracle/apps/fnd/framework/toolbox/FwkTbxEmployees/Position

Step 4.4 Save and test your work. Your results should appear as shown in Figure 4-1 above, however, the LOV
icon will not display next to the Employee Name field until we configure the list of values in Task 5.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 13

Task 5 - Add a List of Values (LOV) to the Employee Name Field

In this section, you'll create a list of values for the Employee Name field. The finished LOV should
appear as shown in Figure 5-1 below:
Figure 5-1: Task 5 Finished LOV

Step 5.1 Create a BC4J package named oracle.apps.dem.lov.server for your LOV-related objects (you will add
all the server-related LOV objects that you create in the ToolBox Tutorial labs to this package).

Step 5.2 Create an LOV Application Module named LabsLOVAM in the oracle.apps.dem.lov.server package.
Please do not generate an associated Java class as we have no code to add.

Step 5.3 Edit the root UI AM to specify the standard Applications passivation setting. Remember that the property
Name should be RETENTION_LEVEL, and the property Value should be MANAGE_STATE.

Step 5.4 Create your LOV View Object in the oracle.apps.dem.lov.server package. Please name it
EmployeeNamesVO and use the following query. Remember to generate a View Row Java class to comply with
the performance guidelines (you don't need to generate the View Object class since you won't be adding any
code).

SELECT full_name AS EMPLOYEE_NAME,


employee_id AS EMPLOYEE_NUMBER,
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 14

email_address
FROM fwk_tbx_employees
WHERE end_date is null

Step 5.5 Edit the LOV VO to disable passivation.

Step 5.6 Add this LOV VO to the LOV AM you created in Step 5.2.

TIP Take careful note of the default View Usage name that BC4J creates when you add your
VO to the selected AM (BC4J creates this name by appending a "1" to your VO name). Leave
it or change it, your choice. In either case, know what the value is before proceeding.

Step 5.7 Create a standalone (reusable) list of values region in the


oracle.apps.dem.lov.webui package and name it EmployeesLovRN.
Step 5.8 Associate Application Module that you created in Step 5.2 with the list of values
region that you created in Step 5.7.
Step 5.9 Add a table region to your list of values region.
o Set the table's JRAD ID to EmpNamesTable.
o Create items for each of the attributes in the EmployeeNamesVO that you created in Step 5.4 with the
table. Please use the following JRAD IDs for these items:

View Object Attribute

JRAD ID

EmployeeNumber

EmpNum

EmployeeName

EmpName

EmailAddress

EmailAddress

o Make absolutely sure you don't associate an Application Module with the table region!
Step 5.10 Set the table region's item properties as follows:
o Each item should have the Style set to messageStyledText
o The user should be able to query on Employee Name and Employee Number in the LOV, but not the
Employee Email Address
o Make sure that the EmpNum item has a Number data type
o Please set the following prompts and attribute sets:

Item

Prompt

Attribute Set

EmpName

Name

/oracle/apps/fnd/framework/toolbox/FwkTbxEmployees/FullName

EmpNum

Number

/oracle/apps/fnd/framework/toolbox/FwkTbxEmployees/EmployeeId

EmailAddress

Email

/oracle/apps/fnd/framework/toolbox/FwkTbxEmployees/EmailAddress

Step 5.11 Modify the existing Employee Name item in SearchRN to make it an LOV text input field (you do this
by changing the Item Style to messageLovInput).

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 15

o
o

When you make this change, an inline LOV region (region style listOfValues) and a default LOV mapping
are created automatically for you.
Change the External List of Values property of this listOfValues region to
/oracle/apps/dem/lov/webui/EmployeesLovRN (again, be very careful to duplicate this text exactly
including the leading slash).
When you change this property, you will see a confirmation message asking if you want to remove the
default inline list of values. When you select the OK button to confirm the change, the inline LOV region is
removed and the new external LOV region appears in the structure hierarchy (grayed out because it is a
shared region).

Step 5.12 Define your LOV mappings to implement the following behavior: any value entered
in the Employee Name field should be used as criteria when the LOV displays (meaning it will
be used to automatically query the LOV) and it should return the LOV result to the same base
page item. Also, the Employee Number value should be returned as a result to the
Employee Number search field (this will be the second mapping).
Step 5.13 Save and test your work. Your base page (the "Employees" page) should appear as
shown in Figure 4-1 above. When you select the list of values icon, your LOV window should
appear as shown in Figure 5-1 above.
Warning You cannot run and test the LOV page directly. You must run your base page, and
then select the list of values icon to invoke the LOV.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 16

Task 6 - Implement the Search

Step 6.1 Edit the EmployeeSummaryVOImpl.java class to add an initQuery( ) method that takes the employee
name and employee number values as search criteria, determines what WHERE clause to build, binds the given
search criteria accordingly and executes a query.
o If you want to code this yourself but need an idea of how to proceed, please review
oracle/apps/fnd/framework/toolbox/tutorial/server/PoSummarySimpleExpVOImpl.java in the
Tutorial.jpr project. You can also look at our version of the lab solutions in
oracle/apps/fnd/framework/toolbox/labsolutions/server/EmployeeSummaryVOImpl.java.
o If you want to copy and paste the code without writing it yourself, please see Step 6.1 in the Lesson 3 Lab
Solution document.
o In any case, remember to add the appropriate import statements for the classes you

reference!
Warning Be particularly careful of classes like oracle.jbo.domain.Number that won't give
you a compile-time error if you fail to import the correct class because the compiler assumes
you're dealing with a java.lang.Number.

Step 6.2 Edit the EmployeeAMImpl.java class to add an initEmployeesQuery() method which will invoke the
initQuery() method in your EmployeeSummaryVOImpl.java class.
o Sample code: oracle/apps/fnd/framework/toolbox/tutorial/server/PoSummarySimpleExpVOImpl.java.
o ToolBox lab solutions code:
oracle/apps/fnd//framework/toolbox/labsolutions/server/EmployeeSummaryVOImpl.java.
o Also see Step 6.2 in the Lesson 3 Lab Solution document to copy/paste code.
Step 6.3 Create an EmployeeSearchCO controller in the oracle.apps.dem.employee.webui package and
associate it with the "Search" region.

TIP The fastest way to create a new controller and associate it with a region is to select the
region in the Structure panel, right-click and select "Set Controller > New Controller ..." from
the context menu.

Step 6.4 Edit the EmployeeSearchCO controller to override the processFormRequest() method so you can
handle the "Go" button press (which means passing the search criteria to the initEmployeesQuery() you created
in the root UI AM).
o Sample code: oracle/apps/fnd/framework/toolbox/tutorial/webui/Lesson3SearchCO.java
o ToolBox lab solutions code:
oracle/apps/fnd/framework/toolbox/labsolutions/webui/EmployeeSearchCO.java.
o Also see Step 6.4 in the Lesson 3 Lab Solution document to copy/paste.

Step 6.5 Save and test your work by selecting the "Go" button (note that your code will compile when you run it).
Your page should appear as shown in Figure 0-1 above, however, the "Results" region text will still display as
"Results: No Search Conducted."

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 17

Task 7 - Implement the Dynamic "Results" Text

For the final deliverable in this exercise, you'll change the default "Results: No Search Conducted"
subheader label to "Results: Employees" after a search has been performed.

Step 7.1 Edit the EmployeeAMImpl.java class to add a generic isVOQueried() method.
o Sample code: oracle/apps/fnd/framework/toolbox/tutorial/server/Lesson3AMImpl.java
o ToolBox lab solutions code:
oracle/apps/fnd/framework/toolbox/labsolutions/server/EmployeeAMImpl.java.
o Also see Step 7.1 in the Lesson 3 Lab Solution document to copy/paste.

Step 7.2 Create an EmployeeResultsCO controller in the oracle.apps.dem.employee.webui package and


associate it with the "Results" region.

Step 7.3 Edit the EmployeeResultsCO controller to change the "Results: No Search Conducted" default header
text to reflect the fact that a search has been conducted. We will do this by checking in the processRequest()
method whether the "Results" table's associated View Object has been queried (this will call the method we
added to our AM in Step 7.1)
o You can use the predefined message with the name name FWK_TBX_T_EMP_RESULTS_TEXT
(product short code is ICX) for the "Results: Employees" text.
o Sample code: oracle/apps/fnd/framework/toolbox/tutorial/webui/Lesson3ResultsCO.java
o ToolBox lab solutions code
oracle/apps/fnd/framework/toolbox/labsolutions/webui/EmployeeResultsCO.java.
o Also see Step 7.3 in the Lesson 3 Lab Solution document.
Step 7.4 Save and test your work by selecting the "Go" button to execute the search. Your page should appear as
shown in Figure 0-1 at the start of this lab.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 18

OAF Tutorial Solution


Lab Solution
The LabSolutions.jpr project contains all the code, including BC4J components and declarative
JRAD definitions, that comprise our solution to the exercises. You can view our solution by expanding
that project.
TIP Remember to select (Menu) Project > Show Categories for any projects you open. It is far
easier to manage and navigate a large project when the files are categorized.

Overview
For this exercise, you'll be implementing a simple "Search" and "Results" page as shown in Figure 01 below. Although this is similar to the purchase order "Search" page we studied in Lesson 3, we'll be
using a simpler entity (employees) so we can easily build on this exercise as we proceed through
subsequent lessons. Eventually, we'll add the ability to view, create and update employees.
Figure 0-1: Lesson 3 Lab Finished Product

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 19

Task 1 - Create / Run the Basic Page


TIP Save frequently! We remind you to do this at the end of each task, but suggest that you save
more often.
So we don't start with too big a job at once, we'll break the page construction into several discrete
tasks. For your first task, you'll build and run a page with just the "Employees" header and the
"Search" and "Results" subheaders as shown in Figure 1-1 below:
Figure 1-1: Task 1 Finished Product

Step 1.1 Create the TutorialLabs.jpr project. This is where you'll be creating all of your work.
o Right-click on the toolbox.jws workspace in the Navigator, and select "New Empty Project..." from the
context menu.
o Change the Directory Name field to your directory, T:\users\<your id>\jdev\myprojects
o Change the File Name field to TutorialLabs.jpr.
o Click the OK button to create your project and continue.

Step 1.2 Modify the project settings for your TutorialLabs.jpr project.
o Right-click on the TutorialLabs.jpr project in the Navigator, and select "Project Settings..." from the
context menu.
o In the Project Setting screen, choose Common > J2EE.
o Change the J2EE Web Application Name field to bb.
o Change the J2EE Web Context Root field to /.
o Click the OK button to exit Project Settings.

Step 1.3 Create the BC4J package for your UI-related objects.
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 20

o
o
o
o

Right-click on the TutorialLabs.jpr project in the Navigator, and select "New Business Components
Package..." from the context menu to open the Business Components Package Wizard.
If the Welcome page appears, click the Next button.
Step 1 of 3: In the Package Name field enter oracle.apps.dem.employee.server. This will be the BC4J
package that contains your UI-related BC4J objects.
Click the Finish button.

Step 1.4: Create the BC4J package for your EO-related objects.
o Right-click on the TutorialLabs.jpr project in the Navigator, and select "New Business Components
Package..." from the context menu to open the Business Components Package Wizard.
o If the Welcome page appears, click the Next button.
o Step 1 of 3: In the Package Name field enter oracle.apps.dem.schema.server. This will be the BC4J
package that contains your EO-related BC4J objects.
o Click the Finish button.

Step 1.5 Add the test_fwklabs.jsp file to your project.


o Click the TutorialLabs.jpr project in the Navigator, and select (Menu) File > Open. You'll find this file in
your jdev\myhtml\OA_HTML file (for example if you're an Oracle Applications developer working off the
central NAP drives or Tarantella, this will be in T:\users\<your user id>\jdev\myhtml\OA_HTML). Select
test_fwklabs.jsp.
o Click the Open button to add the jsp to your project.

Step 1.6 Create the root UI Application Module.

Right-click the oracle.apps.dem.employee.server BC4J package in the Navigator, and select "New
Application Module..." from the context menu to open the Application Module wizard.
If the Welcome page appears, click the Next button.
Step 1 of 4: In the Name field enter EmployeeAM.
Click the Next button until you get to Step 4 of 4.
Step 4 of 4: Select the Generate Java File(s) checkbox.
Click the Finish button to create the AM.

Step 1.7 Edit the root AM to enable passivation.

Right-click the EmployeeAM Application Module in the Navigator, and select "Edit EmployeeAM..." from the
context menu.
Select the Properties page.
In the Name field enter RETENTION_LEVEL.
In the Value field enter MANAGE_STATE.
Click the Add button.
Click the Apply button.
Click the OK button to finish editing your AM.

Step 1.8 Create the EmpSearchPG page.

Right-click on the TutorialLabs.jpr project in the Navigator, and select "New..." from the context menu.
From the New window, navigate down to Web Tier > JRAD Component > Page.
Click the OK button to continue.
In the Name field enter EmpSearchPG.
In the Package field enter oracle.apps.dem.employee.webui.

Click the OK button to create your JRAD page.


Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 21

Warning You MUST use this name and package or your page will not run properly. In fact, if any
package, Java file or JRAD region, item names, etc. are specified in the exercise instructions, you
must match them exactly in your work

Step 1.9 Modify the default pageLayout region for the EmpSearchPG page.
o In the Structure pane open your EmpSearchPG page. Note that it created a region named, region1.
o Select that region, and change its properties as follows:
Property

Value

ID

PageLayoutRN

Region Style

pageLayout

Form

True

AutoFooter

True

Add Indexed Children

True

Window Title

Framework ToolBox Tutorial: Labs

title

Employees

Application Module Definition


Name

oracle.apps.dem.employee.server.EmployeeAM

TIP When you first open the JRAD Property Inspector, the properties are listed in
alphabetical order. To organize them into meaningful categories (which we find to be
much more user friendly), select the Category icon in the Property Inspector toolbar as
shown below:

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 22

Step 1.10 Add your branding image.


o
o

Right-click the PageLayoutRN in the Structure pane, and select New ... productBranding from the
context menu.
Select the pageLayout Components item that was created, and change its properties as follows:
Property

Value

ID

ProdBrand

Source

/OA_MEDIA/branding_tutorialapp.gif

Step 1.11 Add a "Search" region.


o Right-click the PageLayoutRN in the Structure pane, and select New > Region from the context menu.
o Select that region, and change its properties as follows:
Property

Value

ID

SearchRN

Region Style

defaultSingleColumn

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 23

Add Indexed Children

True

Text

Search

Step 1.12 Add a "Results" region.


o Right-click the PageLayoutRN in the Structure pane, and select New > Region from the context menu.
o Select that region, and change its properties as follows:
Property

Value

ID

ResultsRN

Region Style

defaultSingleColumn

Add Indexed Children

True

Text

Results: No Search Conducted (this is the default value;


we'll set the post-search value programmatically later)

Step 1.13 Save and test your work.


o Save your work ... (Menu) File > Save.
o Right-click the test_fwklabs.jsp file, and choose Run test_fwklabs.jsp from the context menu.
o Your results should appear as shown above in Figure 1-1. (Note that, depending on your environment's
profile option settings, you might see "Personalize Region" links throughout your page layout. This is
normal and expected when a page is run in a customizable mode. We'll learn more about this in Lesson
6. IF YOU DO SEE PERSONALIZE LINKS -- DON'T PLAY WITH THEM AS YOUR EFFORTS AFFECT
EVERYONE IN THE CLASS).

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 24

Task 2 - Add the "Search" Region Items


In this section, you're going to add some region-level instruction text, two search criteria fields and a
"Go" button to your "Search" subheader region. When you're finished with this part of the exercise,
your UI should appear as shown in Figure 2-1 below:
Figure 2-1: Task 2 Finished Product

Step 2.1: Create the instruction text.


o Right-click the SearchRN in the Structure pane, and select New > Item from the context menu.
o Select that item, and change its properties as follows:
Property

Value

ID

SearchHelp

Item Style

staticStyledText

Data Type

VARCHAR2

Display

True

CSS Class Name

OraInstructionText

Message Application
Short Name

ICX

Message Name

FWK_TBX_T_REGION_GENERAL

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 25

TIP In Steps 2.2 and 2.3, you will need to select an attribute set in the JRAD Property
Inspector. To do this, place your cursor into the Attribute Set item property and select
the list of values button [...] to open the attribute set selection window. Click the Browse
button. In the Browse window, navigate to
/oracle/apps/fnd/framework/toolbox/attributesets and select the OK button. Finally,
select the Search button. You should now see a list of available attribute sets from
which to choose. In some cases, the attribute set list of values will not display until at
least 1 attribute set has been loaded to your project. If this happens, type the complete
attribute set path as listed in the corresponding lab step for your first attribute set
reference. You should then be able to select additional attribute sets as described here.

Step 2.2 Create the EmpName item using an attribute set.


o Right-click the SearchRN in the Structure pane, and select New > Item from the context menu.
o Select that item, and change its properties as follows:

Property

Value

ID

EmpName

Item Style

messageTextInput (later this will change to an LOV field)

Attribute Set

/oracle/apps/fnd/framework/toolbox/attributesets/
FwkTbxEmployees/FullName

Data Type

VARCHAR2

Read Only

False

Display Length

40

Required

no

Display

True

Prompt

Employee Name

CSS Class Name

OraFieldText

Step 2.3 Create the EmpNum item using an attribute set.


o Right-click the SearchRN in the Structure pane, and select New > Item from the context menu.
o Select that item, and change its properties as follows:
Property

Value

ID

EmpNum

Item Style

messageTextInput

Attribute Set

/oracle/apps/fnd/framework/toolbox/attributesets/
FwkTbxEmployees/EmployeeId

Data Type

NUMBER

Read Only

False

Display Length

15

Required

no

Display

True

Prompt

Employee Number
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 26

CSS Class Name

OraFieldText

Step 2.4 Create the Go button item.


o Right-click the SearchRN in the Structure pane, and select New > Item from the context menu.
o Select that item, and change its properties as follows:
Property

Value

ID

Go

Attribute Set

/oracle/apps/fnd/attributesets/Buttons/Go

Item Style

submitButton

Description Select to view search results


(this is meeting the standards of section 508,
specifically accessibility compliant bubble help)

Display

True

Prompt

Go

Step 2.5 Save and test your work.


o Save your work ... (Menu) File > Save.
o Right-click the test_fwklabs.jsp file, and choose Run test_fwklabs.jsp from the context menu.
o Your results should appear as shown above in Figure 2-1.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 27

Task 3 - Create the EmployeeSummaryVO View Object

Step 3.1 Create the VO.


o Right-click the oracle.apps.dem.employee.server BC4J package, and select "New View Object..." from
the context menu to open the View Object wizard.
o If the Welcome page appears, click the Next button.
o Step 1: In the Name: field enter EmployeeSummaryVO.
o Click the Next button until you get to Step 5.
o Step 5: In the Query Statement field enter the query shown below. When you have done that, click the
Test button to ensure your syntax is correct.
SELECT
emp.employee_id AS EMPLOYEE_NUMBER,
emp.full_name AS EMPLOYEE_NAME,
emp.email_address,
emp.manager_id,
emp2.full_name AS MANAGER_NAME,
emp2.email_address AS MANAGER_EMAIL,
flkp.meaning AS POSITION_DISPLAY,
emp.start_date,
emp.end_date,
emp.salary
FROM
fwk_tbx_employees emp,
fwk_tbx_employees emp2,
fwk_tbx_lookup_codes_vl flkp
WHERE
emp.manager_id = emp2.employee_id (+)
and emp.position_code = flkp.lookup_code
and flkp.lookup_type = 'FWK_TBX_POSITIONS'
o
o
o
o

Click the Next button until you get to Step 7.


Step 7: Select the Generate Java File for View Object Class: EmployeeSummaryVOImpl.
Select the Generate Java File for View Row Class: EmployeeSummaryVORowImpl.
Click the Finish button to create your VO.

Step 3.2 Edit the VO to disable passivation.


o Right-click the EmployeeSummaryVO in the Navigator pane, and select "Edit
EmployeeSummaryVO..." from the context menu to edit your VO.
o Navigate to the Tuning page.
o Deselect the Enable Passivation checkbox.
o Click the OK button to finish editing your VO.

Step 3.3 Add your VO to the root UI AM you created in Task 1, Step 1.6 above.
o Right-click the EmployeeAM in the Navigator pane, and select "Edit EmployeeAM..." from the context
menu to edit your root AM.
o Navigate to the Data Model page.
o Select the EmployeeSummaryVO View Object in the Available Objects list and shuttle it to the Data
Model list.
o Click the OK button to finish adding your VO to your root AM.

TIP Take careful note of the default View Usage name that BC4J creates when
you add your VO to the selected AM (BC4J creates this name by appending a "1"

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 28

to your VO name). Leave it or change it, your choice. In either case, know what
the value is before creating your "Results" table region in Task 4 below.

Step 3.4: Save your work.


o Save your work ... (Menu) File > Save.
o There is no need to test your work. There is no need to test at this point since we haven't associated the
View Object with your UI.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 29

Task 4 - Add the "Results" Region Items


In this section, you'll create the data table for your "Results" region and associate it with the View
Object you just created for this purpose. The finished region should appear as shown in Figure 4-1
below:
Figure 4-1: Task 4 Finished Product

TIP If you examine the "Results" region definition in the LabSolutions.jpr project, you'll note that
its child is a tableLayout region, and not a table. Why? The region reflects changes made in Lesson
4's exercise. For now, add your table directly to the "Results" region as described here.

Step 4.1 Add a "Results" data table.


o Right-click the ResultsRN in the Structure pane, and select New > Region Using Wizard from the
context menu.
Warning In JRAD M3.6, there is an issue that the region wizard gets confused if there are multiple
application modules with the same name, but in different packages, in a workspace (bug #2524776). The
symptom is that you may see more view objects than you have created so far--these come from the
LabSolutions project. The workaround is to remove LabSolutions.jpr from your workspace temporarily
while you use the region wizard.
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 30

o
o
o

o
o
o
o
o
o

If the Welcome page appears, click the Next button.


Step 1: Select your EmployeeAM (oracle.apps.dem.employee.server.EmployeeAM) which contains
your EmployeeSummaryVO1 View Object that you will reference.
Select the EmployeeSummaryVO1 from the Available View Objects: list. (Note: At this time, there is a
Bug in JDeveloper. You should actually select EmployeeSummaryVO1, but that VO won't be available in
the list. EmployeeSummaryVO will be in the list. Select that VO. We will make properties changes later,
in step 4.3, to point to the correct VO usage/instance.)
DO NOT select the "Use this as Application Module Definition for this region." checkbox.
Click the Next button.
Step 2: In the Region ID field enter ResultsTable.
In the Region Style field set the style to table.
Click the Next button.
Step 3: Select the following attributes from your Available View Attributes list and shuttle them to the
Selected View Attributes list.

View Object Attribute


EmployeeNumber
EmployeeName
PositionDisplay
ManagerName
o
o

Step 4: Change the Style of each attribute to messageStyledText.


Change the ID of the attribute currently called EmployeeNumber to ResultsEmpNum. (We are making
this change because the Naming Standards require it. In the SearchRN there is an item named
EmpNum. To avoid conflict, per standards, we must name this item ResultsEmpNum.)

Change the ID of the attribute currently called EmpName to ResultsEmpName. (We


are making this change because the Naming Standards require it. In the SearchRN
there is an item named EmpName. To avoid conflict, per standards, we must name this
item ResultsEmpName.)
TIP If you find the Customize Properties page in the wizard difficult to use, you
can change the attribute properties using the Property Inspector pane after you
leave the wizard.

Click the Finish button to create your data table.

Step 4.2 Set the ResultsTable region properties.


o Select the ResultsTable region in the Structure pane, and set the following properties for this region in
the Property Inspector:
Property

Value

ID

ResultsTable

Region Style

table

Application Module
Definition Name

Make absolutely sure that you have not inadvertently


associated an Application Module here. If you have, please
delete it.

Display

True

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 31

100%

Number of Rows
Displayed

10

Step 4.3 Verify/set individual item properties.

Item

Style

Display

Prompt

AttributeSet

ResultsEmpNum

messageStyledText

True

Number

/<base path>/EmployeeId

ResultsEmpName messageStyledText

True

Name

/<base path>/FullName

ManagerName

messageStyledText

True

Manager

/<base path>/FullName

Position

messageStyledText

True

Position

/<base path>/Position

o
o
o
o
o
o

Width

Please replace the <base path> variable in the table above with the following text:
oracle/apps/fnd/framework/toolbox/attributesets/FwkTbxEmployees. When you do this, be VERY
careful with the slashes. For example, if we had room in the table to be explicit, the first attribute set
would be: /oracle/apps/fnd/framework/toolbox/attributesets/FwkTbxEmployees/EmployeeId
The ManagerName item Destination property set to mailto:{@ManagerEmail}.
Check that each item has its View Usage Name property set to EmployeeSummaryVO1 (you may need
to add the 1).
Check that each item has its View Attribute Name property set to the proper VO attribute name.
The ResultsEmpNum item Sortable property set to Ascending.
The ResultsEmpNum item Initially Sort this Column property set to first.
Change the Data Type property of the ResultsEmpNum item from VARCHAR2 to NUMBER.

Step 4.4 Save and test your work.


o Save your work ... (Menu) File > Save.
o Right-click the test_fwklabs.jsp file, and choose Run test_fwklabs.jsp from the context menu.
o Your results should appear as shown in Figure 4-1 above, however, the LOV icon will not display next to
the Employee Name field until we configure the list of values in Task 5.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 32

Task 5 - Add a List of Values (LOV) to Employee Name Field


In this section, you'll create a list of values for the Employee Name field. The finished LOV should
appear as shown in Figure 5-1 below:
Figure 5-1: Task 5 Finished LOV

Step 5.1 Create the BC4J package for your LOV-related objects.
o Right-click on the TutorialLabs.jpr project and select "New Business Components Package..." to open
the Business Components Package Wizard.
o If the Welcome page appears, click the Next button.
o Step 1 of 3: In the Package Name field enter oracle.apps.dem.lov.server. This will be the BC4J
package that contains your LOV-related BC4J objects.
o Click the Finish button.

Step 5.2 Create your LOV Application Module.


o Right-click the oracle.apps.dem.lov.server BC4J package in the Navigator, and select "New
Application Module..." from the context menu to open the Application Module wizard.
o If the Welcome page appears, click the Next button.
o Step 1: In the Name field enter LabsLOVAM.
o Click the Next button until you get to Step 4 of 4.
o Step 4 of 4: Deselect the Generate Java File(s) checkbox.
o Click the Finish button to create the AM.

Step 5.3 Edit the AM to enable passivation.


o Right-click the LabsLOVAM Application Module in the Navigator, and select "Edit LabsLOVAM..." from
the context menu.
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 33

o
o
o
o
o
o

Select the Properties page.


In the Name field enter RETENTION_LEVEL.
In the Value field enter MANAGE_STATE.
Click the Add button.
Click the Apply button.
Click the OK button to finish editing your AM.

Step 5.4 Create your LOV VO.


o Right-click the oracle.apps.dem.lov.server package in the Navigator, and select "New View Object..."
from the context menu to open the View Object wizard.
o If the Welcome page appears, click the Next button.
o Step 1: In the Name field enter EmployeeNamesVO.
o Click the Next button until you get to Step 5.
o Step 5: In the Query Statement field enter the query shown below. When you have done that, click the
Test button to ensure your syntax is correct.
SELECT full_name AS EMPLOYEE_NAME,
employee_id AS EMPLOYEE_NUMBER,
email_address
FROM fwk_tbx_employees
WHERE end_date is null
o
o
o
o

Click the Next button until you get to Step 7.


Step 7: Deselect the Generate Java File for View Object Class: EmployeeNamesVOImpl.
Select the Generate Java File for View Row Class: EmployeeNamesVORowImpl.
Click the Finish button to create your VO.

Step 5.5 Edit the LOV VO.


o Right-click the EmployeeNamesVO in the Navigator, and select "Edit EmployeeNamesVO..." from the
context menu.
o Navigate to the Tuning page.
o Deselect the Enable Passivation checkbox.
o Click the OK button to finish editing your VO.

Step 5.6 Add this LOV VO to the LOV AM.


o Right-click the LabsLOVAM in the Navigator pane, and select "Edit LabsLOVAM..." from the context
menu to edit your LOV AM.
o Navigate to the Data Model page.
o Select the EmpNamesVO View Object in the Available Objects list and shuttle it to the Data Model list.
o Click the OK button to finish adding your VO to your root AM.

TIP Take careful note of the default View Usage name that BC4J creates when
you add your VO to the selected AM (BC4J creates this name by appending a "1"
to your VO name). Leave it or change it, your choice. In either case, know what
the value is before proceeding.

Step 5.7 Create the LOV region.


o Right-click on the TutorialLabs.jpr project in the Navigator, and select "New..." from the context menu.
o From the New window, navigate down to Web Tier > JRAD Component > Region.
o Click the OK button to continue.
o In the Name field enter EmployeesLovRN.
o In the Package field enter oracle.apps.dem.lov.webui.
o In the Style field select listOfValues.
o Click the OK button to create your JRAD region.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 34

Step 5.8 Edit the LOV region.


o Select the EmployeesLovRN in the Structure pane.
o Change the Application Module Definition Name property to
oracle.apps.dem.lov.server.LabsLOVAM.

Step 5.9 Create a table region.


o Right-click the EmployeesLovRN in the Structure pane, and select New > table Using Wizard from the
context menu.
o If the Welcome page appears, click the Next button.
o Step 1: Select your LabsLOVAM (oracle.apps.dem.lov.server.LabsLOVAM) which contains your
EmployeeNamesVO1 View Object that you will reference.
o Select the EmpNamesVO1 from the Available View Objects: list.
o DO NOT select the "Use this as Application Module Definition for this region." checkbox.
o Click the Next button.
o Step 2: In the Region ID field enter EmpNamesTable.
o In the Region Style field set the style to table.
o Click the Next button.
o Step 3: Add all the VO attributes from the EmployeeNamesVO1.
o Step 4: Change the Style of each attribute to messageStyledText.

Step 5.10 Edit the table region.


o Select the EmpNamesTable in the Structure pane.
o Verify/set individual item properties.

Item

Style

EmpName

messageStyledText True

Name

/<base path>/ FullName

EmpNum

messageStyledText True

Number

/<base path>/ EmployeeId

Email

/<base path>/ EmailAddress

Query Prompt

EmailAddress messageStyledText False


o

AttributeSet

Please replace the <base path> variable in the table below with the following text:
oracle/apps/fnd/framework/toolbox/FwkTbxEmployees. When you do this, be VERY careful with the
slashes. For example, if we had room in the table to be explicit, the first attribute set would be:
/oracle/apps/fnd/framework/toolbox/FwkTbxEmployees/FullName
Change the Data Type property of the EmpNum item from VARCHAR2 to NUMBER.

Step 5.11 Modify the existing EmpName item in SearchRN.


o Select the EmpName item in the SearchRN region.
o Change its Item Style property to messageLovInput.
o When you set the Item Style property to messageLovInput, an inline LOV region (region style
listOfValues) and a default LOV mapping is created automatically.
o Change the External List of Values property to /oracle/apps/dem/lov/webui/EmployeesLovRN.
o When you change this property, you see a confirmation message. You see the message because objects
that are children of your base field, such as the inline LOV region, will be removed by the change.
Confirm the change (click the OK button). Once you confirm, the inline LOV region is removed and the
new external LOV region appears in the hierarchy (grayed out).
Step 5.12: Set the LOV mappings.
o Select the default LOV mapping, ID'ed as lovMap1, and set the following properties:
 Change the Result to property by selecting EmpName field from the poplist.
 Change the Criteria from property by selecting EmpName field from the poplist.
 Change the LOV Item property by selecting EmpName field from the poplist.
o Right-click lovMappings in the Structure panel, and select New > lovMap from the context menu.
o Select the default LOV mapping, ID'ed as lovMap2, and set the following properties:
 Change the Result to property by selecting EmpNum field from the poplist.
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 35

 Change the LOV Item property by selecting EmpNum field from the poplist.
Step 5.13 Save and test your work.
o Save your work ... (Menu) File > Save.
o Right-click the test_fwklabs.jsp file, and choose Run test_fwklabs.jsp from the context menu.
o Your base page (the "Employees" page) should appear as shown in Figure 4-1 above.

When you select the list of values icon, your LOV window should appear as shown in
Figure 5-1 above.
Warning You cannot run and test the LOV page directly. You must run your base
page, and then select the list of values icon to invoke the LOV.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 36

Task 6 - Implement the Search

Step 6.1 Edit the EmployeeSummaryVOImpl.java code.


o Select the EmployeeSummaryVOImpl.java code in the Navigator, and open it for editing.
o Add the following procedure to your EmployeeSummaryVOImpl.java code:

// Initialize and execute the query.


public void initQuery(String employeeName, String employeeNumber)
{
// Note that the use of oracle-style bindings, while requiring a bit
// more effort than the java-style binding, is REQUIRED of framework
// code.
StringBuffer whereClause = new StringBuffer(100);
Vector parameters = new Vector(2);
int clauseCount = 0;
int bindCount = 0;
setWhereClauseParams(null); // Always reset
setWhereClause(null);
if ((employeeNumber != null) &&
(!("".equals(employeeNumber.trim()))))
{
// Do the following converion for type consistency.
Number empNum = null;
try
{
empNum = new Number(employeeNumber);
}
catch(Exception e)
{
throw new OAException("ICX", "FWK_TBX_INVALID_EMP_NUMBER");
}
whereClause.append(" EMPLOYEE_NUMBER = :");
whereClause.append(++bindCount);
parameters.addElement(employeeNumber);
clauseCount++;
}
if ((employeeName != null) && (!("".equals(employeeName.trim()))))
{
if (clauseCount > 0)
{
whereClause.append(" AND ");
}
whereClause.append(" EMPLOYEE_NAME LIKE :");
whereClause.append(++bindCount);
parameters.addElement(employeeName+"%");
clauseCount++;
}
setWhereClause(whereClause.toString());
if (bindCount > 0)
{
Object[] params = new Object[bindCount];
// the copyInto() is 1.1.8 compliant which, as of 7/02, is required
// by ARU

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 37

parameters.copyInto(params);
setWhereClauseParams(params);
}
executeQuery();
} // end initQuery()
o

Add the following three(3) imports to your EmployeeSummaryVOImpl.java code:


 import java.util.Vector;
 import oracle.jbo.domain.Number;
 import oracle.apps.fnd.framework.OAException;

Step 6.2 Edit the EmployeeAMImpl.java code.


o Select the EmployeeAMImpl.java code in the Navigator, and open it for editing.
o Add the following procedure to your EmployeeAMImpl.java code:
public void initEmployeesQuery(String employeeName, String employeeNumber)
{
EmployeeSummaryVOImpl vo = getEmployeeSummaryVO1();
if (vo == null)
{
MessageToken[] tokens = { new MessageToken("OBJECT_NAME",
"EmployeeSummaryVO1")};
throw new OAException("ICX", "FWK_TBX_OBJECT_NOT_FOUND", tokens);
}
vo.initQuery(employeeName, employeeNumber);
} // end initEmployeesQuery()
o

Add the following two (2) imports to your EmployeeAMImpl.java code:


 import oracle.apps.fnd.common.MessageToken;
 import oracle.apps.fnd.framework.OAException;

Step 6.3 Create/associate the EmployeeSearchCO controller.


o Right-click the SearchRN in the Structure panel, and select "Set Controller > New Controller ..." from
the context menu.
o In the Package Name field enter oracle.apps.dem.employee.webui.
o In the Name field enter EmployeeSearchCO.
o Click the OK button to create your controller.

Step 6.4 Edit the EmployeeSearchCO controller.


o After you created/associated the controller in Step 6.1, it then opened the controller in a window for
editing. Add the following code to the processFormRequest() procedure in your controller:

/*
** The following code is part of Lesson 3's exercise solution.
*/
// Pressing the Go button causes the search to be executed.
if (pageContext.getParameter("Go") != null)
{
String employeeName = pageContext.getParameter("EmpName");
String employeeNumber = pageContext.getParameter("EmpNum");
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 38

OAApplicationModule am = pageContext.getRootApplicationModule();
Serializable[] parameters = { employeeName, employeeNumber };
am.invokeMethod("initEmployeesQuery", parameters);
// Now redirect back to this page so we can implement UI changes as a
// consequence of the query in processRequest(). NEVER make UI changes
in
// processFormRequest().
pageContext.setForwardURLToCurrentPage(null,
true, // retain the AM
ADD_BREAD_CRUMB_NO,
IGNORE_MESSAGES);
}
o

Add the following two (2) imports to your EmployeeSearchCO code:


 import java.io.Serializable;
 import oracle.apps.fnd.framework.OAApplicationModule;

Step 6.5 Save and test your work by selecting the "Go" button (note that your code will compile when you run it).
Your page should appear as shown in Figure 0-1 above, however, the "Results" region text will still display as
"Results: No Search Conducted."

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 39

Task 7 - Implement the Results

Step 7.1 Edit the EmployeeAMImpl.java code.


o Select the EmployeeAMImpl.java code in the Navigator, and open it for editing.
o Add the following procedure to your EmployeeAMImpl.java code:
public String isVOQueried(String viewUsageName)
{
OAViewObject vo = (OAViewObject)findViewObject(viewUsageName);
if (vo == null)
{
MessageToken[] tokens = { new MessageToken("OBJECT_NAME",
viewUsageName) };
throw new OAException("ICX", "FWK_TBX_OBJECT_NOT_FOUND", tokens);
}
return (vo.isPreparedForExecution()) ? "Y" : "N";
} // end isVOQueried()
o

Add the following import to your EmployeeAMImpl.java code:


 import oracle.apps.fnd.framework.OAViewObject;

Step 7.2 Create/associate the EmployeeResultsCO controller.


o Right-click the ResultsRN in the Structure panel, and select "Set Controller > New Controller ..." from
the context menu.
o In the Package Name field enter oracle.apps.dem.employee.webui.
o In the Name field enter EmployeeResultsCO.
o Click the OK button to create your controller.

Step 7.3 Edit the EmployeeResultsCO controller.


o After you created/associated the controller in Step 7.1, it then opened the controller in a window for
editing. Add the following code to the processRequest() procedure in your controller:

// We need to change the "Results: No Search Conducted" default header


// text to reflect the fact that a search has been conducted.
// Always use a translated value from Message Dictionary when setting
// strings in your controllers.
String afterSearchText = pageContext.getMessage("ICX",
"FWK_TBX_T_PO_RESULTS_TEXT", null);
// Now check to see if our "Results" VO has been queried so we can set
the
// region header text accordingly.
OAApplicationModule am = pageContext.getRootApplicationModule();
Serializable[] params = { "EmployeeSummaryVO1" };
if ("Y".equals(am.invokeMethod("isVOQueried", params)))
{
((OADefaultSingleColumnBean)webBean).setText(pageContext,
afterSearchText);
}
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 40

OATableBean table = (OATableBean)webBean.findIndexedChildRecursive


("ResultsTable");
if (table == null)
{
MessageToken[] tokens = { new MessageToken("OBJECT_NAME",
"ResultsTable") };
throw new OAException("ICX", "FWK_TBX_OBJECT_NOT_FOUND", tokens);
}
o

Add the following six(6) imports to your EmployeeResultsCO code:


 import java.io.Serializable;
 import oracle.apps.fnd.common.MessageToken;
 import oracle.apps.fnd.framework.OAApplicationModule;
 import oracle.apps.fnd.framework.OAException;
 import oracle.apps.fnd.framework.webui.beans.layout.OADefaultSingleColumnBean;
 import oracle.apps.fnd.framework.webui.beans.table.OATableBean;

Step 7.4 Save and test your work by selecting the "Go" button to execute the search. Your page should appear
as shown in Figure 0-1 at the start of this lab.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 41

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshops - Hands-on Lab


Chapter 8 - Page 42

OAF Workshop
Extensibility Hands-on Lab
Chapter 9

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 1

OAF Workshop Extensibility Hands-on Lab


Introduction
The Oracle Applications Self-Service Framework (OAF) provides a rich architecture for adding to the
user interface (UI) and the business logic (BC4J). The capabilities are largely the result of 2 things,
OAF's declarative architecture and the object-oriented features of Java.
To be precise, we must make a clear distinction between personalization and extensibility.
Personalization refers to the ability to declaratively alter the UI to suit the user or business needs.
Extensibility refers to the ability to add to the functionality of an application, beyond those things that
can be done with personalization.
If you need to make changes to the UI that can be accomplished through personalization, those tasks
are beyond the scope of this tutorial. Look to the OA Framework Personalization and Extensibility
Guide (NOTE: Need the Link to this document from Siu.)
Extensibility allows us to add to business logic by extending BC4J objects. Like the UI, we can
accomplish a great deal of extensibility through declarative alterations. Unlike the UI, we also add the
capability to edit BC4J object's Java classes.

Lesson Goals
By the end of this tutorial, you should be able to the following:

Add additional attributes to the BC4J object that serves as the data source.
Add or change the attribute default values.
Extend (add or modify) the BC4J validation logic.
Substitute the extended BC4J object for the parent BC4J object to be used throughout the
application.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 2

Adding additional attributes to the BC4J object that serves as the data source
In order to add additional attributes to the BC4J objects, follow these steps:
1. Analyze the page (PG) and the regions (RN's) associated with the page, to determine which
View Objects (VO's) are used. In the property inspector for the PG or RN, look at the View
Usage Name property. Also, look at the Application Module Definition Name property to
identify which Application Module (AM) the VO is contained in.
2. Once you analysis is complete, you will have the name of the VO you will extend. We will call
this the parent VO.
3. Create a new empty BC4J package to hold your Custom BC4J objects. (Note: This is created
like any other BC4J package, but we recommend putting custom into the directory path for this
package.)
4. Create an extended BC4J VO. The VO should be in the same package as the existing VO, and
you should preface the existing VO's name with CustomExistingVO. This VO is created the
same as any other VO, with the following exception. On the 1st screen of creating the VO,
there is a field labeled "Extends View Object". You will put the name of the parent VO from
which you are basing your extension.
5. After extending the new object from the parent, you can then add the new EO's that your
extended VO wishes to use.
6. Add the attribute(s) from the EO(s) to your extended VO.
7. Because this is an extended VO you set it as expert mode, and enter the SQL SELECT
statement directly. Make certain you TEST your new SELECT statement before moving to the
next step.
8. In the Java section of your VO creation, uncheck "View Object Class - Generate Java File"
checkbox. But! check the "View Row Class - Generate Java File" and "Generate
Accessors" checkboxes. (see Notes below)
9. Finish the generation of your VO.
Notes:

There is no need to have a redundant View Object Class Java file because there is no
business logic to add for this case. By default, BC4J framework will use the base View Object's
Java class. However, it is better to generate the View Row Class Java file because this class
allows BC4J framework to optimize the performance for attibute name lookup.
The Extends button in the Java section allows you to specify the super classes for the Java
files. When you extend the XML of the base View Object, the extended View Object Java
classes would extend the Java classes of the base View Object by default -- that is, the new
VOImpl would extend the parent VOImpl, and the new VORowImpl would extend the parent
VORowImpl. If you do not generate the Java files for the extended View Object, the Java files
of the base View Object will be used. However, if you press the Extends button upon View
Object creation, the super classes may not show the base View Object Java classes. But if you
see the auto-generated extended View Object Java classes after completing the View Object
creation wizard steps, you will notice that they correctly extend the base View Object Java
classes. If you then edit the View Object wizard for the extended View Object that was created,
the Java Extends button will show the correct super classes at that time. This is bug 2723937
(APPS: VO XML EXTENDS - JAVA CLASS DOES NOT SHOW CORRECT PARENT).
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 3

In your new VORowImpl, check that there is a limited number of constants (i.e., protected
static final int variables). This number should be 1 more than the number of additional
attributes you added to your new VO. There should be 1 MAXATTRCONST and constants for
the VO attributes you added. If you see more than these three constants and if you are seeing
the parent VO' constants, you are encountering bug 2723934 (APPS: VO XML EXTENDS
PUTS IN REDUNDANT BASE VO ATTRIBUTES IN SUBCLASS ROWIMPL). The symptom of
this bug is that you get java.lang.ArrayIndexOutOfBoundsException when you later run the
page and when the page logic tries to get the attribute value. To correct this, simply remove
the redundant lines.

10. Substitute the new VO for the parent VO. We discuss the process for doing this in the section
titled, Substitute the extended BC4J object for the parent BC4J object to be used throughout
the application.
11. We have made the BC4J changes, now we need to connect this to its UI component.
UI Changes
Note: For this lesson, we create copies of the existing page XML files and modify the
copies. However, note that this mechanism does not work with upgrades. In other
words, if the original page XML files get upgraded, you will end up having to create
copies again and redo the modifications. In OA Framework 5.8 version, we plan to
introduce durable solution to this problem.
12. As we analyzed the BC4J object in Step 1, we also identified the PG and RN(s) used, and
where the XML definitions of those PG and RN(s) were stored.
13. Create a new directory for the files. For example, assume that the existing XML files are stored
in the ./myprojects/oracle/apps/fnd/framework/toolbox/tutorial/webui directory. You would then
create a ./myprojects/oracle/apps/fnd/custom/framework/toolbox/tutorial/webui for the new
XML files.
14. Copy the ..PG.xml file from the existing directory into the new directory, and rename it adding
Custom to the first part of the name. Also, copy the ..RN.xml file(s) from the existing directory
into the new directory, and rename it adding Custom to the first part of the name. We need to
modify both XML files because once we modify the shared region (RN), we need to have the
page (PG) use that new shared region (RN).
15. Add these two new XML files into your project.
16. Now click on the Custom..RN.xml. Add the new items to your UI. Set the View Usage Name
property to the parent VO. The BC4J substitution will take care of properly creating a
Custom..VO instance at runtime in place of the parent VO.
17. Custom..PG contains an RN region under the PageLayoutRN region. Change the Extends
value of the region to the path of the new Custom..RN.
18. Run the new Custom..PG.xml to test it (see the Notes below).
Notes:

If you see the exception, "oracle.apps.fnd.framework.OAException:


oracle.jbo.NoDefException: JBO-25002: Definition
oracle.apps.fnd.custom.framework.toolbox.tutorial.server.Custom..VO of type View
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 4

Definition not found" or if the page renders a blank and incomplete table region with no
column header and data, you are hitting the substitution bug 2723829 (APPS: SUBSTITUTION
THROWS NOXMLFILEEXCEPTION DUE TO CLASS LOADING). See the Workaround for
bug 2723829.
When you rerun the page multiple times, you may get "Unable to Recover Previous State"
error page. This is due to an OC4J rerun bug 2653643 (SESSION CHANGED IN THE
MIDDLE OF A SESSION-RUN WHEN RE-RUN JSP OR JRAD XML). Workaround: Select
Run - Terminate from the JDeveloper menu to explicitly terminate the former process before
each rerun.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 5

Adding or changing the attribute default values


In order to add or change attribute default values to the BC4J objects, follow these steps:
1. Analyze the PG and RN that contains the item you wish to modify its default value. Look at the
item's View Usage Name property to identify the VO.
2. Edit the VO identified in Step 1, and note the EO that this VO uses.
3. Once you analysis is complete, you will have the name of the EO you will extend. We will call
this the parent EO.
Note: We will extend the XML and the Java classes to make use of the BC4J substitution instead of
just extending the Java classes. BC4J substitution works on the XML.
4. We will create an extended BC4J EO, Custom..EO that extends the parent EO. This EO will
modify the defaulting logic for the identified attribute in the Java class.

5.
6.
7.

8.

Note: We will place all our extended objects in oracle.apps.fnd.custom directory for this
lesson. You can replace the word "custom" with your own company name like "ford". Note that
all the Entity Objects (xxxEO) are packaged in oracle.apps.fnd....schema.server package, and
hence the extended Entity Objects will be placed under
oracle.apps.fnd.custom...schema.server.
Create a new empty BC4J package. We will add the new Custom EO to this package.
Create a new Entity Object, Custom..EO. In the "Extends Entity" field, select the parent EO.
For the rest of the steps, accept all the defaults and proceed until you get to Generate Default
View Object step. In Generate Default View Object step, uncheck the "Generate Default
View Object" checkbox as we do not need any new View Object for our extension. Then click
Finish.
Add the new defaulting logic by editing the Custom..EOImpl Java class. First, make sure that
it extends the parent EOImpl Java class. Then add the following code (create(AttributeList)
method) and compile the project:
/**
* Initializes a new purchase order header.
*/
public void create(AttributeList attributeList)
{
super.create(attributeList);
// Add or change the default values here.
// EXAMPLE: setPaymentTermsCode("NET_60");
}

You would also need to include the following import statement to make this class compile
successfully:
import oracle.jbo.AttributeList;
Note: The create(AttributeList) method is invoked when the Entity Object is created. We set
the default values in this method.
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 6

9. Substitute the new EO for the parent EO. We discuss the process for doing this in the section
titled, Substitute the extended BC4J object for the parent BC4J object to be used throughout
the application.
10. Run the PG to test.
Note:

If you see oracle.jbo.RowCreateException (due to an underlying


Java.lang.ClassCastException) error message in the message box of the rendered page,
you may be hitting bug 2723881 (APPS: XML EXTENDS - EXTENDED OBJECT DOES NOT
INHERIT CUSTOM PROPERTIES). This exception is thrown because the base business
object properties (added through the Properties section in the wizard) did not get inherited to
the extended business objects. Workaround: Add all the properties defined in the base
business object into the extended business object. This applies to both Entity Object and View
Object extensions.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 7

Extending (adding or modifying) the BC4J validation logic


In order to extend (add or modify) BC4J validation login, follow these steps:
1. Identify the EO to be modified. Follow Steps 1 and 2 of Adding or changing the attribute default
values.
2. Once you analysis is complete, you will have the name of the EO you will extend. We will call
this the parent EO.
3. Create a new empty BC4J package. We will add the new Custom EO to this package.
4. Create an extended BC4J EO, Custom..EO that extends parent EO. This EO will add the
validation logic for the identified attribute in the Java class. Set the "Extends Entity" field to
the parent EO.
5. For the rest of the steps, accept all the defaults and proceed until you get to Generate Default
View Object step. In Generate Default View Object step, uncheck the "Generate Default
View Object" checkbox as we do not need any new View Object for our extension. Then click
Finish.
6. Edit the new Custom..EOImpl Java class. First, make sure that it extends the parent EOImpl
Java class. Then add the following code and compile the project: (Note: We are using an
example of setting the UnitPrice attribute. Since we have getters and setters for all our
attributes, you would use the appropriate setter for your attribute.)
public void setUnitPrice(Number value)
{
// Add validation before calling the super class method call.
// The super class method will perform some validation and set the attribute
// and hence, additional validation needs to be added before the super class
// method call.
if (value != null)
{
// Verify value is <= 10000.
// Proper message with the message name should be seeded.
if (value.compareTo(10000) > 0)
{
throw new OAAttrValException(OAException.TYP_ENTITY_OBJECT,
getEntityDef().getFullName(), // EO name
getPrimaryKey(), // EO PK
" UnitPrice", // Attribute Name
value, // Attribute value
" ICX", // Message product short name
" FWK_TBX_T_PO_PRICE_EXCEEDED"); // Message name
}
}
super.setUnitPrice(value);
}

You would also need to include the following import statements to make this class compile
successfully:

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 8

import oracle.jbo.domain.Number;
import oracle.apps.fnd.framework.OAAttrValException;
import oracle.apps.fnd.framework.OAException;

Notes:
o

Attribute Level Validation: The attribute setter methods (e.g., setUnitPrice) are
invoked when the user-entered values are set in the EO. We overrode the attribute
setter method for the UnitPrice attribute present in the super class in the subclass.

Entity Level Validation: For a single attribute validation, you can override the attribute
setter method as illustrated in this lesson. If you want to perform cross-attribute
validation, then you need to override the validateEntity() method.

Attribute Level Exception vs. Entity Level Exception: For attribute level exceptions,
use OAAttrValException as illustrated in this lesson. For entity level exceptions, use
OARowValException.

Translated Messages for Exceptions: As pointed out in the comment of the code
above, a proper translated message with the message name should be seeded in the
message repository for the exception. Once, you seed the message with message
name = XXX, you should use that name (XXX) as the last parameter to the
OAAttrValException constructor call. OA Self-Service Framework will retrieve the
message text for the message name and display that. For this lesson, you can upload
the message for the message name, FWK_TBX_T_PO_PRICE_EXCEEDED to the
message repository using the files in the Lesson Solutions section.

7. Substitute the new EO for the parent EO. We discuss the process for doing this in the section
titled, Substitute the extended BC4J object for the parent BC4J object to be used throughout
the application.
8. Run the PG to test.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 9

Substituting the extended BC4J object for the parent BC4J object
Once you finish creating the extended business objects, you would want those extended objects to be
used in place of the original base objects. This means that the BC4J framework should create an
instance out of the extended object definition rather than out of the base object definition. BC4J
framework uses factory methods with substitution rules to accomplish this. The existing
application code uses the factory method APIs provided by BC4J to construct business object
instances. The application code passes in the fully qualified XML file name to the factory method, and
then the BC4J framework returns the appropriate Java object at runtime. With the factory method,
BC4J framework can flexibily change the type of the object that gets returned to some other subclass
object types. But a set of rules must be specified to the BC4J framework to perform this swapping.
The BC4J Substitution feature allows you to specify these rules. You use Substitution to substitute
the extended business object for the base object to be used throughout the application. Here is how:
1. Right click on your project in the Navigator pane, and select Edit Business Components
Project (or right click on the project's .jpx and select Edit <project>).
2. Select the Substitutions section.
From the Available list, select the base object (e.g., PoSimpleSummaryVO) that you want to
replace.
From the Substitute list, select the extended object (e.g., CustomPoSimpleSummaryVO) that
you want as the substitute.
Then click Add. A new substitution rule will be added in the Substitutions list box.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 10

This indicates that the extended object will be used in place of the parent object. You can also
update and remove the substitution rules with the Update and Remove buttons. Click OK to
apply the changes and exit.
3. After using the wizards to define the substitutions you want to make, the BC4J framework
enters this information in the project's .jpx file. The BC4J runtime does not typically read the
project's .jpx file. To make the runtime read the .jpx file, you must do the following:
i.
Make sure that the classpath contains the .jpx file.
ii.
Use the runtime system property -Djbo.project=Name where Name is the JPX file
name without the .jpx extension.

In JDeveloper, the classpath already contains the .jpx file when you compile the project.
Hence, you just need to specify the runtime system property.
Right click on your project and select Project Settings.
Then in Configurations | Development | Runner, add -Djbo.project=TutorialCustom to the
Java Options.
Give a space between the existing options like -mx256m and the new option, Djbo.project=TutorialCustom.
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 11

Note: If you forget to add this jbo.project Java option, you will get exceptions like
"oracle.apps.fnd.framework.OAException: oracle.jbo.NoDefException: JBO-25002: Definition
SiteName of type Attribute not found". The reason is that the runtime environment does not pick up
substitution rules, and hence BC4J tries to find the new attribute from the base object and not the
extended object.
Known Bugs:
2723829 (APPS: SUBSTITUTION THROWS NOXMLFILEEXCEPTION DUE TO CLASS LOADING):
You may get oracle.jbo.NoXMLFileException if your JDeveloper deployed the BC4J classes in the
global application space and the local classes in the web application space. OA Self-Service
Framework typically recommends and uses this deployment strategy to optimize the JSP run
performance, which ends up uncovering this bug.
Workaround: Open the Project Settings for the project.
In Configurations | Development | Paths, set the Output Directory to
< your jdeveloper user home>\myglobalclasses

In Configurations | Development | Runner, set the Run Directory to


Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 12

<your jdeveloper user home>\myglobalclasses

Note: JDeveloper 9i requires that all the projects in the workspace (.jws) to have the same output
directories. Hence, make the same changes for other projects in the workspace. For this lesson, we
need to make all the projects in toolbox.jws have the same output directories and then rebuild
Tutorial.jpr and TutorialCustom.jpr. When you try to change the paths, you may get the following
warnings.

Click OK.

Click Yes.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 13

OAF Tutorial - Lab


1. Create a JDeveloper project
We will create a new project called TutorialCustom.jpr under toolbox.jws.
TutorialCustom.jpr will contain the extended BC4J objects and the extended page XML files.
1. Create a new project. Put the project into the <your jdeveloper user home>\myprojects
directory, and call the project TutorialCustom.jpr.
2. Once the TutorialCustom.jpr is created, right click on the jpr and select Project Settings.
Then make the following changes to the project settings.
o In Common | J2EE, set the J2EE Web Application Name to "bb" and J2EE Web
Context Root to "/". This will later allow you to run your JSP programs in the project.
o In Configurations | Development | Libraries, add "BC4J Tester" library from the
Available Libraries to the Selected Libraries. This step is necessary because
JDeveloper 9i requires that all the projects in the workspace contain the same libraries.
3. To create extended BC4J objects in the new project, the base BC4J objects must be available
in the new project as well. Hence, we will add the BC4J objects in Tutorial.jpr to
TutorialCustom.jpr. Add the following files (one at a time) to the project:
oracle\apps\fnd\framework\toolbox\schema\server\server.xml
oracle\apps\fnd\framework\toolbox\lov\server\server.xml
oracle\apps\fnd\framework\toolbox\poplist\server\server.xml
oracle\apps\fnd\framework\toolbox\tutorial\server\server.xml

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 14

2. Adding additional attributes to the BC4J object that serves as the data source
We will extend lesson 7's Purchase Orders summary page to display the Supplier Site Name
information as well in the table display. See the extended lesson 7's Purchase Orders summary page
for the expected outcome of this extension.
BC4J Changes
1. Analyze what to change:
o The XML file for the Purchase Orders summary page is
myprojects\oracle\apps\fnd\framework\toolbox\tutorial\webui\PoSummaryL7PG.xml in
the Tutorial.jpr. Examine its page structure and properties in the Property Inspector.
Identify the following:
o The Page (PG) name and file.
o The Region (RN) name and file.
o The View Object (VO) name associated with the RN.
o The Application Module (AM) name associated to the VO.
2. Based on this analysis, we know that we need to extend the
oracle.apps.fnd.framework.toolbox.tutorial.server.PoSimpleSummaryVO to add
additional attributes.
3. Create an new empty BC4J package called,
oracle.apps.fnd.custom.framework.toolbox.tutorial.server.
4. Create an extended BC4J View Object, CustomPoSimpleSummaryVO that extends
PoSimpleSummaryVO in TutorialCustom.jpr. This View Object will add the SiteName
attribute in the oracle.apps.fnd.framework.toolbox.schema.server.SupplierSiteEO. Create
this VO beneath the BC4J package created in Step 3. Add the SupplierSiteEO to this
extended View Object to get the SiteName (supplier site name) attribute. Leave the Read Only
and Reference checkboxes checked as we are going to use this EO for read purpose only.
Add the SiteName attribute from the SupplierSiteEO to the View Object. In this step, we are
going to add the following two attributes from the SupplierSiteEO to this extended View Object:
SupplierSiteId -- we need this attribute because BC4J framework performs operations based
on the primary key of the Entity Object. Accept the default attribute settings. When you try to
move out of the Attribute Settings either upon View Object creation or edit time, you may get
the following popup dialog message:

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 15

Just press Yes. You get this message because the View Object contains some transient
attributes like SelectFlag that are not based on database columns or calculated attributes like
OrderTotal that are derived from the View Object SQL in the base View Object. Specify the
View Object query.
SELECT PurchaseOrderHeaderEO.HEADER_ID,
PurchaseOrderHeaderEO.DESCRIPTION,
PurchaseOrderHeaderEO.STATUS_CODE,
PurchaseOrderHeaderEO.SUPPLIER_ID,
PurchaseOrderHeaderEO.CURRENCY_CODE,
PurchaseOrderHeaderEO.CREATION_DATE,
SupplierEO.NAME AS SUPPLIER_NAME,
SupplierEO.SUPPLIER_ID AS SUPPLIER_ID1,
EmployeeEO.FULL_NAME AS BUYER_NAME,
EmployeeEO.EMPLOYEE_ID,
PurchaseOrderHeaderEO.BUYER_ID,
EmployeeEO.EMAIL_ADDRESS AS BUYER_EMAIL,
(select sum(nvl(line.quantity, 0) * nvl(line.unit_price, 0))
from fwk_tbx_po_lines line
where line.header_id = PurchaseOrderHeaderEO.HEADER_ID) AS ORDER_TOTAL,
decode(PurchaseOrderHeaderEO.STATUS_CODE,
'APPROVED', 'okind_status.gif',
'COMPLETE', 'completeind_status.gif',
'REJECTED', 'criticalind_status.gif', 'inprogressind_status.gif')
AS STATUS_IMAGE,
LookupCodeEO.MEANING AS STATUS_DISPLAY,
LookupCodeEO.ROW_ID,
decode(PurchaseOrderHeaderEO.STATUS_CODE,
'COMPLETE', 'DeleteDisabled',
'APPROVED', 'DeleteDisabled', 'DeleteEnabled') AS DELETE_IMAGE,
decode(PurchaseOrderHeaderEO.STATUS_CODE,
'COMPLETE', 'UpdateDisabled',
'APPROVED', 'UpdateDisabled', 'UpdateEnabled') AS UPDATE_IMAGE,
decode(PurchaseOrderHeaderEO.STATUS_CODE,
'COMPLETE', 'Y',
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 16

'APPROVED', 'Y', 'N') AS APPROVE_DISABLED,


SupplierSiteEO.SUPPLIER_SITE_ID,
SupplierSiteEO.SITE_NAME
FROM FWK_TBX_PO_HEADERS PurchaseOrderHeaderEO,
FWK_TBX_SUPPLIERS SupplierEO,
FWK_TBX_EMPLOYEES EmployeeEO,
FWK_TBX_LOOKUP_CODES_VL LookupCodeEO,
FWK_TBX_SUPPLIER_SITES SupplierSiteEO
WHERE PurchaseOrderHeaderEO.SUPPLIER_ID = SupplierEO.SUPPLIER_ID
AND PurchaseOrderHeaderEO.BUYER_ID = EmployeeEO.EMPLOYEE_ID
AND PurchaseOrderHeaderEO.STATUS_CODE = LookupCodeEO.LOOKUP_CODE
AND LookupCodeEO.LOOKUP_TYPE = 'FWK_TBX_ORDER_STATUS'
AND SupplierEO.SUPPLIER_ID = SupplierSiteEO.SUPPLIER_ID

(The texts in bold style indicate the modifications to the base View Object SQL.) Before you
move to the next step, test the query. In the Java section, uncheck View Object Class Generate Java File checkbox. But check View Row Class - Generate Java File and
Generate Accessors checkboxes. Go through the rest of the steps and click Finish at the
end. Just accept the defaults for the rest of the steps.
5. Save all your work.
6. Make sure the CustomPoSimpleSummaryVORowImpl extends
PoSimpleSummaryVORowImpl class.
7. In the CustomPoSimpleVORowImpl class, check if there are only three constants (protected
static final int) at the beginning as follows:
protected static final int MAXATTRCONST =
oracle.jbo.server.ViewDefImpl.getMaxAttrConst("oracle.apps.fnd.framework.toolbox.tu
torial.server.PoSimpleSummaryVO");;
protected static final int SUPPLIERSITEID = MAXATTRCONST;
protected static final int SITENAME = MAXATTRCONST + 1;

8. Substitute the new VO for the parent VO. We discuss the process for doing this in the section
titled, Substitute the extended BC4J object for the parent BC4J object to be used throughout
the application.
9. We have made the BC4J changes, now we need to connect this to its UI component.
10. Create a directory myprojects\oracle\apps\fnd\custom\framework\toolbox\tutorial\webui.
11. Copy PoSummaryL7PG.xml from myprojects\oracle\apps\fnd\framework\toolbox\tutorial\webui
into this directory and rename the file to CustomPoSummaryL7PG.xml.
12. Copy PoSummaryRN.xml from myprojects\oracle\apps\fnd\framework\toolbox\tutorial\webui
into this directory and rename the file to CustomPoSummaryRN.xml.
13. We need to modify both XML files because once we modify the shared region
(CustomPoSummaryRN), we need to have the page XML (CustomPoSummaryL7PG) use that
new shared region.
14. Add these two new XML files into the project, TutorialCustom.jpr.
15. Modify the CustomPoSummaryRN.xml. Add a new item with ID, SupplierSiteName. Set the
Attribute Set to
/oracle/apps/fnd/framework/toolbox/attributesets/FwkTbxSupplierSites/SiteName. Set the View
Usage Name to PoSimpleSummaryVO as in the other table region items. Set the View
Attribute Name to SiteName.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 17

16. Change the Extends property of OrderRN to


/oracle/apps/fnd/custom/framework/toolbox/tutorial/webui/CustomPoSummaryRN.
17. Configure the JRAD Framework Connections. Set the following properties:
User Name: fwktester
Password: fwkdev
Application: ICX
Responsibility Key: FWK_TBX_TUTORIAL
18. Rebuild TutorialCustom.jpr.
19. Run CustomPoSummaryL7PG. Your results should look as follows:

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 18

3. Adding or changing the attribute default values


We will extend lesson 7's Purchase Orders create page - step 1 to default the Payment Terms field
to Net 60. See the extended lesson 7's Purchase Orders create page - step 1 for the expected
outcome of this extension.
1. Analyze what to change:
o The XML file for the Purchase Orders create page - step 1 is
myprojects\oracle\apps\fnd\framework\toolbox\tutorial\webui\PoDescPG.xml in the
Tutorial.jpr.
o The Page (PG) name and file.
o The Region (RN) name and file.
o The View Object (VO) name associated with the RN.
o The Application Module (AM) name associated to the VO.
o The Entity Object (EO) used by the VO.
2. Based on this analysis, we know that we need to extend the
oracle.apps.fnd.framework.toolbox.schema.server.PurchaseOrderHeaderEO to change
the default value for the PaymentTermsCode.
3. If you haven't done so already, create a new empty BC4J package as detailed in Step 3 in Add
additional attributes to the BC4J object that serves as the data source. If you did this already,
skip this step.
4. Create an extended BC4J Entity Object, CustomPurchaseOrderHeaderEO that extends
PurchaseOrderHeaderEO in TutorialCustom.jpr. This Entity Object will modify the defaulting
logic for the PaymentTermsCode attribute in the Java class. Set the Extends Entity field to
PurchaseOrderHeaderEO under oracle.apps.fnd.framework.toolbox.schema.server. For
the rest of the steps, accept all the defaults and proceed until you get to Generate Default
View Object step. In Generate Default View Object step, uncheck the Generate Default View
Object checkbox as we do not need any new View Object for our extension. Then click Finish.
5. Edit the CustomPurchaseOrderHeaderEOImpl Java class. First, make sure that it extends
PurchaseOrderHeaderEOImpl Java class. Add code in the create(AttributeList) method to set
the default value of PaymentTermsCode to "NET_60".
6. Recompile the project.
7. Substitute the new EO for the parent EO. We discuss the process for doing this in the section
titled, Substitute the extended BC4J object for the parent BC4J object to be used throughout
the application.
8. Run the PG to test. Your results should look as follows:

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 19

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 20

4. Extending the BC4J validation logic

We will extend lesson 7's Purchase Orders create page - step 2 to throw a validation error when the
Unit Price exceeds 10000. See the extended lesson 7's Purchase Orders create page - step 2 for
the expected outcome of this extension.
1. Analyze what to change:
o The XML file for the Purchase Orders create page - step 2 is
myprojects\oracle\apps\fnd\framework\toolbox\tutorial\webui\PoLinesPG.xml in the
Tutorial.jpr.
o The Page (PG) name and file.
o The Region (RN) name and file.
o The View Object (VO) name associated with the RN.
o The Application Module (AM) name associated to the VO.
o The Entity Object (EO) used by the VO.
2. Based on this analysis, we know that we need to extend the
oracle.apps.fnd.framework.toolbox.schema.server.PurchaseOrderLineEO to add the
validation logic for UnitPrice.
3. If you haven't done so already, create a new empty BC4J package as detailed in Step 3 in Add
additional attributes to the BC4J object that serves as the data source. If you did this already,
skip this step.
4. Create an extended BC4J Entity Object, CustomPurchaseOrderLineEO that extends
PurchaseOrderLineEO in TutorialCustom.jpr. This Entity Object will add the validation logic
for the UnitPrice attribute in the Java class. Set the Extends Entity field to
PurchaseOrderLineEO under oracle.apps.fnd.framework.toolbox.schema.server. For the
rest of the steps, accept all the defaults and proceed until you get to Generate Default View
Object step. In Generate Default View Object step, uncheck the Generate Default View Object
checkbox as we do not need any new View Object for our extension. Then click Finish.
5. Edit the CustomPurchaseOrderLineEOImpl Java class. First, make sure that it extends
PurchaseOrderLineEOImpl Java class. Add code to UnitPrice's setter method to throw a
validation error when it exceeds 10000.
6. Recompile your project.
7. Substitute the new EO for the parent EO. We discuss the process for doing this in the section
titled, Substitute the extended BC4J object for the parent BC4J object to be used throughout
the application.
8. Run the PG to test. Your results should look as follows:

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 21

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 22

5. Substituting the extended BC4J object for the parent object


1. Edit your project's Business Components.
2. In the Substitutions section, add the parent VO to the Available list, and add the new VO to
the Substitute list.
3. After using the wizards to define the substitutions you want to make, the BC4J framework
enters this information in the project's .jpx file. The BC4J runtime does not typically read the
project's .jpx file. To make the runtime read the .jpx file, you must do the following:
i.
Make sure that the classpath contains the .jpx file.
ii.
Use the runtime system property -Djbo.project=Name where Name is the JPX file
name without the .jpx extension

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 23

OAF Tutorial - Solution


1. Create a JDeveloper project
We will create a new project called TutorialCustom.jpr under toolbox.jws.
TutorialCustom.jpr will contain the extended BC4J objects and the extended page XML files.
1. To create a new project, select File | New from the JDeveloper menu.
Then select Empty Project. This will pop up a dialog window.
2. For Directory Name, type in
<your jdeveloper user home>\myprojects
(that is, remove "\Project1" at the end so that the project file is created directly under
myprojects directory.)
For File Name, type in
TutorialCustom.jpr

3. Then press OK. This will add TutorialCustom.jpr under toolbox.jws. Select File | Save All to
frequently save your changes.
4. Once the TutorialCustom.jpr is created, right click on the jpr and select Project Settings.
Then make the following changes to the project settings.
o In Common | J2EE, set the J2EE Web Application Name to "bb" and J2EE Web
Context Root to "/". This will later allow you to run your JSP programs in the project.
o In Configurations | Development | Libraries, add "BC4J Tester" library from the
Available Libraries to the Selected Libraries. This step is necessary because
JDeveloper 9i requires that all the projects in the workspace contain the same libraries.
5. To create extended BC4J objects in the new project, the base BC4J objects must be available
in the new project as well.
Hence, we will add the BC4J objects in Tutorial.jpr to TutorialCustom.jpr.
Select File | Open from the JDeveloper menu and add the following files to TutorialCustom.jpr.
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 24

(Add one file at a time.)


oracle\apps\fnd\framework\toolbox\schema\server\server.xml
oracle\apps\fnd\framework\toolbox\lov\server\server.xml
oracle\apps\fnd\framework\toolbox\poplist\server\server.xml
oracle\apps\fnd\framework\toolbox\tutorial\server\server.xml

Whenever you add a BC4J package by including the server.xml file, you will get the following
popup dialog message:

Press Yes to add the BC4J package. This will create a new jpx file called TutorialCustom.jpx.
This jpx file contains information on the BC4J packages in the project.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 25

2. Adding additional attributes to the BC4J object that serves as the data source
We will extend lesson 7's Purchase Orders summary page to display the Supplier Site Name
information as well in the table display. See the extended lesson 7's Purchase Orders summary page
for the expected outcome of this extension.
BC4J Changes
1. Analyze what to change:
o The XML file for the Purchase Orders summary page is
myprojects\oracle\apps\fnd\framework\toolbox\tutorial\webui\PoSummaryL7PG.xml in
the Tutorial.jpr.
In Tutorial.jpr, click on PoSummaryL7PG.xml and examine its page structure and
properties in the Property Inspector.
o

PoSummaryL7PG contains an OrdersRN region under the PageLayoutRN region. The


OrdersRN region extends
/oracle/apps/fnd/framework/toolbox/tutorial/webui/PoSummaryRN as indicated in the
Extends property in the Property Inspector. The items under the OrdersRN are greyed
out because the inherited properties from the base region cannot be modified.

Now click on the PoSummaryRN.xml.


The PoSummaryRN region is a shared region that can be extended and reused by
other pages and regions.
PoSummaryRN contains an OrdersTable region under the TableLayout - TableRow TableCell region hierarchy.
Note that all the items under this region have the View Usage Name property set to
PoSimpleSummaryVO. Also note that the Application Module Definition Name
property is set only at the top level (PoSummaryRN) to
oracle.apps.fnd.framework.toolbox.tutorial.server.OrderSummaryAM.

Expand the oracle.apps.fnd.framework.toolbox.tutorial.server BC4J package and select


OrderSummaryAM. Right click and select Edit OrderSummaryAM. You will see that
the OrderSummaryAM contains the PoSimpleSummaryVO instance with the matching
instance name in the Data Model list box. If you also edit the
OrderSummaryAMImpl.java file, you will notice that there is a
getPoSimpleSummaryVO() method which returns PoSimpleSummaryVOImpl in the
same package.

Based on this analysis, we know that we need to extend the


oracle.apps.fnd.framework.toolbox.tutorial.server.PoSimpleSummaryVO to add
additional attributes.
2. Create oracle.apps.fnd.custom.framework.toolbox.tutorial.server.CustomPoSimpleSummaryVO:
We will create an extended BC4J View Object, CustomPoSimpleSummaryVO that extends
PoSimpleSummaryVO in TutorialCustom.jpr. This View Object will add the SiteName
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 26

attribute in the oracle.apps.fnd.framework.toolbox.schema.server.SupplierSiteEO.


Note: We will place all our extended objects in oracle.apps.fnd.custom directory for this
lesson. You can replace the word "custom" with your own company name like "ford". Note that
all the Entity Objects (xxxEO) are packaged in oracle.apps.fnd....schema.server package, and
hence the extended Entity Objects will be placed under
oracle.apps.fnd.custom...schema.server.
i.
We first need to create a new BC4J package called
oracle.apps.fnd.custom.framework.toolbox.tutorial.server. We will add
CustomPoSimpleSummaryVO into this package.
Right click on TutorialCustom.jpr and select New Business Components Package.
For the package name, type in
oracle.apps.fnd.custom.framework.toolbox.tutorial.server

Then in the next step, unclick all the checkboxes so that an empty package gets
created. Click Next and then Finish.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 27

ii.

To create CustomPoSimpleSummaryVO under the newly created package, right click


on the new package and select New View Object.
For the Extends View Object field, click on the Browse button and select
PoSimpleSummaryVO under oracle.apps.fnd.framework.toolbox.tutorial.server.
This will auto-fill the Extends View Object field and default the View Object Name to
PoSimpleSummaryVOEx. Change the default name to CustomPoSimpleSummaryVO.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 28

This step tells the BC4J framework to create a View Object named
CustomPoSimpleSummaryVO that extends PoSimpleSummaryVO. This feature is often
called "XML Extends" in BC4J. Filling out the Extends View Object field allows the
extended View Object to inherit the XML and the Java classes of the base View Object.
iii.

The next step specifies the Entity Objects that the View Object will include. We will add
SupplierSiteEO to this extended View Object to get the SiteName (supplier site name)
attribute. Select the SupplierSiteEO in
oracle.apps.fnd.framework.toolbox.schema.server package from the Available list and
then use the righ arrow button to add it to the Selected list. Leave the Read Only and
Reference checkboxes checked as we are going to use this Entity Object for read
purpose only.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 29

iv.

Next, we need to add the SiteName attribute from the SupplierSiteEO to the View
Object. In this step, we are going to add the following two attributes from the
SupplierSiteEO to this extended View Object:
SupplierSiteId -- we need this attribute because BC4J framework performs operations
based on the primary key of the Entity Object.
SiteName
Hold down the control key in the keyboard and select both SupplierSiteId and SiteName
from the SupplierSiteEO in the Available list. Then use the right arrow button to add
these attributes to the Selected list.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 30

v.

The next step shows you the default attribute settings. Just accept the defaults and
move to the next step. When you try to move out of the Attribute Settings either upon
View Object creation or edit time, you may get the following popup dialog message:

Just press Yes. You get this message because the View Object contains some transient
attributes like SelectFlag that are not based on database columns or calculated

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 31

attributes like OrderTotal that are derived from the View Object SQL in the base View
Object.
vi.

Now, you need to specify the View Object query. For this particular View Object that we
are creating, you will notice that the Query Statement field is initially left blank and the
Expert Mode checkbox is checked and disabled by default. The reason is that this new
View Object extends a View Object (PoSimpleSummaryVO) that was created in expert
mode. Checking the Expert Mode checkbox upon View Object creation allows you to
alter the query statement with more database columns in the SELECT clause and extra
WHERE clause. The extra database columns added in the SELECT clause become
what is called "Calculated" View Object attributes. The View Object attribute name is
derived from the database column alias.
If the original base View Object was created in non-Expert Mode (that is, with the Expert
Mode check box cleared), then the View Object wizard for the extended object will open
with Expert Mode disabled. In this case, the Query Statement area of the Query page
will display the default SQL query in a read-only list box.
If the original View Object was created in Expert Mode, then the Query page for the
extended object will open in Expert Mode. In this case, the Query Statement area of the
Query page will display an empty, editable list box. Again, the SQL query from the
original View Object is a reasonable starting point for your edits. You can copy the
query from the original View Object and paste it into the Query Statement area of the
extended View Object that you are creating.
You can examine the SQL of the base View Object, PoSimpleSummaryVO by selecting
and right clicking on the PoSimpleSummaryVO node in JDeveloper and choosing the
Edit PoSimpleSummaryVO option. Then in the wizard, you can go to the Query
section to get the SQL.
For CustomPoSimpleSummaryVO, we will use the following SQL. Copy this SQL and
paste it into the Query Statement list box:
SELECT PurchaseOrderHeaderEO.HEADER_ID,
PurchaseOrderHeaderEO.DESCRIPTION,
PurchaseOrderHeaderEO.STATUS_CODE,
PurchaseOrderHeaderEO.SUPPLIER_ID,
PurchaseOrderHeaderEO.CURRENCY_CODE,
PurchaseOrderHeaderEO.CREATION_DATE,
SupplierEO.NAME AS SUPPLIER_NAME,
SupplierEO.SUPPLIER_ID AS SUPPLIER_ID1,
EmployeeEO.FULL_NAME AS BUYER_NAME,
EmployeeEO.EMPLOYEE_ID,
PurchaseOrderHeaderEO.BUYER_ID,
EmployeeEO.EMAIL_ADDRESS AS BUYER_EMAIL,
(select sum(nvl(line.quantity, 0) * nvl(line.unit_price, 0))
from fwk_tbx_po_lines line
where line.header_id = PurchaseOrderHeaderEO.HEADER_ID) AS
ORDER_TOTAL,
decode(PurchaseOrderHeaderEO.STATUS_CODE,
'APPROVED', 'okind_status.gif',
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 32

'COMPLETE', 'completeind_status.gif',
'REJECTED', 'criticalind_status.gif',
'inprogressind_status.gif') AS STATUS_IMAGE,
LookupCodeEO.MEANING AS STATUS_DISPLAY,
LookupCodeEO.ROW_ID,
decode(PurchaseOrderHeaderEO.STATUS_CODE,
'COMPLETE', 'DeleteDisabled',
'APPROVED', 'DeleteDisabled', 'DeleteEnabled') AS
DELETE_IMAGE,
decode(PurchaseOrderHeaderEO.STATUS_CODE,
'COMPLETE', 'UpdateDisabled',
'APPROVED', 'UpdateDisabled', 'UpdateEnabled') AS
UPDATE_IMAGE,
decode(PurchaseOrderHeaderEO.STATUS_CODE,
'COMPLETE', 'Y',
'APPROVED', 'Y', 'N') AS APPROVE_DISABLED,
SupplierSiteEO.SUPPLIER_SITE_ID,
SupplierSiteEO.SITE_NAME
FROM FWK_TBX_PO_HEADERS PurchaseOrderHeaderEO,
FWK_TBX_SUPPLIERS SupplierEO,
FWK_TBX_EMPLOYEES EmployeeEO,
FWK_TBX_LOOKUP_CODES_VL LookupCodeEO,
FWK_TBX_SUPPLIER_SITES SupplierSiteEO
WHERE PurchaseOrderHeaderEO.SUPPLIER_ID = SupplierEO.SUPPLIER_ID
AND PurchaseOrderHeaderEO.BUYER_ID = EmployeeEO.EMPLOYEE_ID
AND PurchaseOrderHeaderEO.STATUS_CODE = LookupCodeEO.LOOKUP_CODE
AND LookupCodeEO.LOOKUP_TYPE = 'FWK_TBX_ORDER_STATUS'
AND SupplierEO.SUPPLIER_ID = SupplierSiteEO.SUPPLIER_ID

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 33

(The texts in bold style indicate the modifications to the base View Object SQL.)

vii.

Before you move to the next step, test the query you entered by pressing the Test
button. If the query is valid, then click Next.

viii.

In the Java section, uncheck View Object Class - Generate Java File checkbox. But
check View Row Class - Generate Java File and Generate Accessors checkboxes.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 34

This will auto-generate the Java file, CustomPoSimpleSummaryVORowImpl.


Notes:
 There is no need to have a redundant View Object Class Java file
(CustomPoSimpleSummaryVOImpl) because there is no business logic to add
for this case. By default, BC4J framework will use the base View Object's Java
class (PoSimpleSummaryVOImpl). However, it is better to generate the View
Row Class Java file (CustomPoSimpleSummaryVORowImpl) because this class
allows BC4J framework to optimize the performance for attibute name lookup.


The Extends button in the Java section allows you to specify the super classes
for the Java files. When you extend the XML of the base View Object, the
extended View Object Java classes would extend the Java classes of the base
View Object by default -- that is, CustomPoSimpleSummaryVOImpl would extend
PoSimpleSummaryVOImpl, and CustomPoSimpleSummaryVORowImpl would
extend PoSimpleSummaryVORowImpl. If you do not generate the Java files for
the extended View Object, the Java files of the base View Object
(PoSimpleSummaryVOImpl and PoSimpleSummaryVORowImpl) will be used.
However, if you press the Extends button upon View Object creation, the super
classes may not show the base View Object Java classes. But if you see the
auto-generated extended View Object Java classes after completing the View
Object creation wizard steps, you will notice that they correctly extend the base
View Object Java classes. If you then edit the View Object wizard for the
extended View Object that was created, the Java Extends button will show the
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 35

correct super classes at that time. This is bug 2723937 (APPS: VO XML
EXTENDS - JAVA CLASS DOES NOT SHOW CORRECT PARENT).
ix.

Go through the rest of the steps and click Finish at the end. Just accept the defaults for
the rest of the steps.

x.

Now you will see the CustomPoSimpleSummaryVO node under the


oracle.apps.fnd.custom.framework.toolbox.tutorial.server package. Save all your work.

xi.

Open the CustomPoSimpleSummaryVORowImpl class and make sure that it extends


PoSimpleSummaryVORowImpl class.

xii.

In CustomPoSimpleVORowImpl class, check if there are only three constants (protected


static final int) at the beginning as follows:
protected static final int MAXATTRCONST =
oracle.jbo.server.ViewDefImpl.getMaxAttrConst("oracle.apps.fnd.framework.tool
box.tutorial.server.PoSimpleSummaryVO");;
protected static final int SUPPLIERSITEID = MAXATTRCONST;
protected static final int SITENAME = MAXATTRCONST + 1;

There should be MAXATTRCONST and the constants for the new View Object
attributes (SUPPLIERSITEID and SITENAME) that we added.

3.

Substitute CustomPoSimpleSummaryVO for PoSimpleSummaryVO:


Please visit Substitute the extended business object for the base object section on how to do
this task. After you complete the substitution step, continue with the UI Changes in the next
section below.

UI Changes
Note: For this lesson, we create copies of the existing page XML files and modify the
copies. However, note that this mechanism does not work with upgrades. In other
words, if the original page XML files get upgraded, you will end up having to create
copies again and redo the modifications. In OA Framework 5.8 version, we plan to
introduce a substitution feature for the UI pages that is equivalent to the BC4J
substitution to support extensibility in UI.
1. Analyze what to change:
As we analyzed (above), we need to modify the shared region,
myprojects\oracle\apps\fnd\framework\toolbox\tutorial\webui\PoSummaryRN to include an
extra table region item for the supplier site name.
2. Create a directory myprojects\oracle\apps\fnd\custom\framework\toolbox\tutorial\webui.
Copy PoSummaryL7PG.xml from myprojects\oracle\apps\fnd\framework\toolbox\tutorial\webui
into this directory and rename the file to CustomPoSummaryL7PG.xml.
Copy PoSummaryRN.xml from myprojects\oracle\apps\fnd\framework\toolbox\tutorial\webui
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 36

into this directory and rename the file to CustomPoSummaryRN.xml.


We need to modify both XML files because once we modify the shared region
(CustomPoSummaryRN), we need to have the page XML (CustomPoSummaryL7PG) use that
new shared region.
3. Add these two new XML files in TutorialCustom.jpr with File | Open JDeveloper menu option.
4. Now click on the CustomPoSummaryRN.xml.
CustomPoSummaryRN contains an OrdersTable region under the TableLayout - TableRow TableCell region hierarchy.
o Add a new item with ID, SupplierSiteName
o Make sure that the item style is messageStyledText
o Set the Attribute Set to
/oracle/apps/fnd/framework/toolbox/attributesets/FwkTbxSupplierSites/SiteName

Note: If the Property Inspector complains about this attribute set not being found, then
just set the following property values instead:
Display Length: 20
Prompt: Site Name
o
o
o

Set the View Usage Name to PoSimpleSummaryVO as in the other table region
items.
Set the View Attribute Name to SiteName
Then drag the item above Currency and below Supplier.

Note: Note that we set the View Usage Name to PoSimpleSummaryVO and not
CustomPoSimpleSummaryVO. The BC4J substitution will take care of properly creating a
CustomPoSimpleSummaryVO instance at runtime in place of the PoSimpleSummaryVO.
5.

CustomPoSummaryL7PG contains an OrdersRN region under the PageLayoutRN region.


Change the Extends value of the OrdersRN region to
/oracle/apps/fnd/custom/framework/toolbox/tutorial/webui/CustomPoSummaryRN

Note: We will skip the part of associating this new extended page with a menu funtion for this
lesson.
Run Page
1.

We are now almost ready to test our BC4J extensions. Before we run the page, we need to
configure the JRAD Framework Connections.
Select Tools | Preferences from the JDeveloper menu.
In the Preferences window, select JRAD | Framework Connections. Then set the following
properties:
User Name: fwktester
Password: fwkdev
Application: ICX
Responsibility Key: FWK_TBX_TUTORIAL
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 37

2. Rebuild Tutorial.jpr and TutorialCustom.jpr.


Rebuild Tutorial.jpr first just in case some of the BC4J objects in the TutorialCustom.jpr
depend on some utility classes in Tutorial.jpr. Then rebuild TutorialCustom.jpr. (You need to
rebuild the Tutorial.jpr only once.)
3. Now run the CustomPoSummaryL7PG.xml by right clicking on the XML and selecting Run
CustomPoSummaryL7PG. The extended page should render with the extra Site Name
column in the table region as shown in extended lesson 7's Purchase Orders summary page.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 38

3. Adding or changing the attribute default values


We will extend lesson 7's Purchase Orders create page - step 1 to default the Payment Terms field
to Net 60. See the extended lesson 7's Purchase Orders create page - step 1 for the expected
outcome of this extension.
BC4J Changes
1. Analyze what to change:
o The XML file for the Purchase Orders create page - step 1 is
myprojects\oracle\apps\fnd\framework\toolbox\tutorial\webui\PoDescPG.xml in the
Tutorial.jpr.
In Tutorial.jpr, click on PoDescPG.xml and examine its page structure and properties
in the Property Inspector.
o

PoDescPG contains a MainRN region under the PageLayoutRN region. Note that all
the items under this region have the View Usage Name property set to
PoDetailsFullVO. Also note that the Application Module Definition Name property is
set only at the top level (PageLayoutRN) to
oracle.apps.fnd.framework.toolbox.tutorial.server.Lesson7AM.

Expand the oracle.apps.fnd.framework.toolbox.tutorial.server BC4J package and select


Lesson7AM. Right click and select Edit Lesson7AM. You will see that the Lesson7AM
contains the PoDetailsFullVO instance with the matching instance name in the Data
Model list box. If you also edit the Lesson7AMImpl.java file, you will notice that there is
a getPoDetailsFullVO() method which returns PoDetailsFullVOImpl in the same
package.

If you edit PoDetailsFullVO, it contains PurchaseOrderHeaderEO (in


oracle.apps.fnd.framework.toolbox.schema.server package) which includes the attribute
PaymentTermsCode. Defaulting or validation logic goes into the Entity Object Java
class instead of into the View Object Java class. Centralizing the defaulting/validation
logic in the Entity Object layer promotes reuse and sharing of the business logic.

Based on this analysis, we know that we need to extend the


oracle.apps.fnd.framework.toolbox.schema.server.PurchaseOrderHeaderEO to change
the default value for the PaymentTermsCode.
Note: We will extend the XML and the Java classes to make use of the BC4J substitution
instead of just extending the Java classes. BC4J substitution works on the XML.
2. Create
oracle.apps.fnd.custom.framework.toolbox.schema.server.CustomPurchaseOrderHeade
rEO:
We will create an extended BC4J Entity Object, CustomPurchaseOrderHeaderEO that
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 39

extends PurchaseOrderHeaderEO in TutorialCustom.jpr. This Entity Object will modify the


defaulting logic for the PaymentTermsCode attribute in the Java class.
Note: We will place all our extended objects in oracle.apps.fnd.custom directory for this
lesson. You can replace the word "custom" with your own company name like "ford". Note that
all the Entity Objects (xxxEO) are packaged in oracle.apps.fnd....schema.server package, and
hence the extended Entity Objects will be placed under
oracle.apps.fnd.custom...schema.server.
i.
First, create a new BC4J package called
oracle.apps.fnd.custom.framework.toolbox.schema.server as in the section (above). We
will add CustomPurchaseOrderHeaderEO into this package.
ii.

iii.

Then create a new Entity Object, CustomPurchaseOrderHeaderEO, by right clicking


on the oracle.apps.fnd.custom.framework.toolbox.schema.server package and selecting
New Entity Object.


As in the Add additional attributes to the business object section, click on the
Browse button next to the Extends Entity text input field and select
PurchaseOrderHeaderEO under
oracle.apps.fnd.framework.toolbox.schema.server. This will auto-fill the
Extends Entity field and default the Entity Object Name to
PurchaseOrderHeaderEOEx. Change the default name to
CustomPurchaseOrderHeaderEO.

For the rest of the steps, accept all the defaults and proceed until you get to
Generate Default View Object step. In Generate Default View Object step,
uncheck the Generate Default View Object checkbox as we do not need any new
View Object for our extension. Then click Finish.

Now, we need to add our defaulting logic. Edit CustomPurchaseOrderHeaderEOImpl


Java class. First, make sure that it extends PurchaseOrderHeaderEOImpl Java class.
Then add the following code (create(AttributeList) method) and compile the project:
/**
* Initializes a new purchase order header.
*/
public void create(AttributeList attributeList)
{
super.create(attributeList);
// Add or change the default values here.
setPaymentTermsCode("NET_60");
}

You would also need to include the following import statement to make this class
compile successfully:
import oracle.jbo.AttributeList;

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 40

Note: The create(AttributeList) method is invoked when the Entity Object is created. We
set the default values in this method.
3. Substitute CustomPurchaseOrderHeaderEO for PurchaseOrderHeaderEO:
Right click on the TutorialCustom.jpr and select Edit Business Components Project. Then
select Substitutions.
Select PurchaseOrderHeaderEO in the Available list, and select
CustomPurchaseOrderHeaderEO in the Substitute list.
Click Add. Then click OK to apply the changes and exit.
See Substitute the extended business object for the base object section for more information.
UI Changes
No page XML change is needed.
Run Page
1.

Run CustomPoSummaryL7PG. Once the page is rendered, press the "Create Purchase Order" button.

2.

The extended page should render with the Payment Terms field correctly defaulted to Net 60 as shown in
extended lesson 7's Purchase Orders create page - step 1.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 41

4. Extending the BC4J validation logic

We will extend lesson 7's Purchase Orders create page - step 2 to throw a validation error when the
Unit Price exceeds 10000. See the extended lesson 7's Purchase Orders create page - step 2 for
the expected outcome of this extension.
BC4J Changes
1. Analyze what to change:
o The XML file for the Purchase Orders create page - step 2 is
myprojects\oracle\apps\fnd\framework\toolbox\tutorial\webui\PoLinesPG.xml in the
Tutorial.jpr.
In Tutorial.jpr, click on PoLinesPG.xml and examine its page structure and properties
in the Property Inspector.
o

PoLinesPG contains a LinesTable region under the PageLayoutRN - MainRN region


hierarchy. Note that all the items under this region have the View Usage Name property
set to PoLineShipFullVO. Also note that the Application Module Definition Name
property is set only at the top level (PageLayoutRN) to
oracle.apps.fnd.framework.toolbox.tutorial.server.Lesson7AM.

Expand the oracle.apps.fnd.framework.toolbox.tutorial.server BC4J package and select


Lesson7AM. Right click and select Edit Lesson7AM. You will see that the Lesson7AM
contains the PoLineShipFullVO instance with the matching instance name in the Data
Model list box. If you also edit the Lesson7AMImpl.java file, you will notice that there is
a getPoLineShipFullVO() method which returns PoLineShipFullVOImpl in the same
package.

If you edit PoLineShipFullVO, it contains PurchaseOrderLineEO (in


oracle.apps.fnd.framework.toolbox.schema.server package) which includes the attribute
UnitPrice. Defaulting or validation logic goes into the Entity Object Java class instead of
into the View Object Java class. Centralizing the defaulting/validation logic in the Entity
Object layer promotes reuse and sharing of the business logic.

Based on this analysis, we know that we need to extend the


oracle.apps.fnd.framework.toolbox.schema.server.PurchaseOrderLineEO to add the
validation logic for UnitPrice.
2. Create oracle.apps.fnd.custom.framework.toolbox.schema.server.CustomPurchaseOrderLineEO:
We will create an extended BC4J Entity Object, CustomPurchaseOrderLineEO that extends
PurchaseOrderLineEO in TutorialCustom.jpr. This Entity Object will add the validation logic
for the UnitPrice attribute in the Java class.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 42

i.

ii.

Create a new Entity Object, CustomPurchaseOrderLineEO, by right clicking on the


oracle.apps.fnd.custom.framework.toolbox.schema.server package and selecting New
Entity Object.


As in the Add additional attributes to the business object section, click on the
Browse button next to the Extends Entity text input field and select
PurchaseOrderLineEO under
oracle.apps.fnd.framework.toolbox.schema.server. This will auto-fill the
Extends Entity field and default the Entity Object Name to
PurchaseOrderLineEOEx. Change the default name to
CustomPurchaseOrderLineEO.

For the rest of the steps, accept all the defaults and proceed until you get to
Generate Default View Object step. In Generate Default View Object step,
uncheck the Generate Default View Object checkbox as we do not need any new
View Object for our extension. Then click Finish.

Now, we need to add our validation logic. Edit CustomPurchaseOrderLineEOImpl


Java class. First, make sure that it extends PurchaseOrderLineEOImpl Java class.
Then add the following code and compile the project:
public void setUnitPrice(Number value)
{
// Add validation before calling the super class method call.
// The super class method will perform some validation and set the
attribute
// and hence, additional validation needs to be added before the super
class
// method call.
if (value != null)
{
// Verify value is <= 10000.
// Proper message with the message name should be seeded.
if (value.compareTo(10000) > 0)
{
throw new OAAttrValException(OAException.TYP_ENTITY_OBJECT,
getEntityDef().getFullName(), // EO name
getPrimaryKey(), // EO PK
"UnitPrice", // Attribute Name
value, // Attribute value
"ICX", // Message product short name
"FWK_TBX_T_PO_PRICE_EXCEEDED"); // Message name
}
}
super.setUnitPrice(value);
}

You would also need to include the following import statements to make this class
compile successfully:
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 43

import oracle.jbo.domain.Number;
import oracle.apps.fnd.framework.OAAttrValException;
import oracle.apps.fnd.framework.OAException;

Notes:


Attribute Level Validation: The attribute setter methods (setUnitPrice) are


invoked when the user-entered values are set in the Entity Object. We overrode
the attribute setter method for the UnitPrice attribute present in the super class
(PurchaseOrderLineEOImpl has setUnitPrice method) in the subclass.

Entity Level Validation: For a single attribute validation, you can override the
attribute setter method as illustrated in this lesson. If you want to perform crossattribute validation, then you need to override the validateEntity() method. For
an example, see
oracle.apps.fnd.framework.toolbox.tutorial.server.PurchaseOrderHeaderEOImpl
validateEntity() method.

Attribute Level Exception vs. Entity Level Exception: For attribute level
exceptions, use OAAttrValException as illustrated in this lesson. For entity level
exceptions, use OARowValException. For an example of an
OARowValException, see
oracle.apps.fnd.framework.toolbox.tutorial.server.PurchaseOrderHeaderEOImpl
remove() method.

Translated Messages for Exceptions: As pointed out in the comment of the


code above, a proper translated message with the message name should be
seeded in the message repository for the exception. Once, you seed the
message with message name = XXX, you should use that name (XXX) as the
last parameter to the OAAttrValException constructor call. OA Self-Service
Framework will retrieve the message text for the message name and display that.
For this lesson, you can upload the message for the message name,
FWK_TBX_T_PO_PRICE_EXCEEDED to the message repository using the files
in the Lesson Solution Files section.

3. Substitute CustomPurchaseOrderLineEO for PurchaseOrderLineEO:


Right click on the TutorialCustom.jpr and select Edit Business Components Project. Then
select Substitutions.
Select PurchaseOrderLineEO in the Available list, and select
CustomPurchaseOrderLineEO in the Substitute list.
Click Add. Then click OK to apply the changes and exit.
See Substitute the extended business object for the base object section for more information.
UI Changes
No page XML change is needed.
Run Page
Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 44

1.

Run CustomPoSummaryL7PG. Once the page is rendered, press the "Create Purchase Order" button. Fill out all
the required fields for the purchase order header. For the Supplier LOV, you may select "Hot Chip
Semiconnductors" from the LOV window. And then you can select "HQ" for the Site Name LOV. Then in the next
train step (purchase order lines page), press the "Add Another Item" button. Enter all the required fields and a unit
price that is larger than 10000. Then press the "Next" button.

2.

The extended page should throw a validation error when a unit price that is larger than 10000 was entered in
extended as shown lesson 7's Purchase Orders create page - step 2.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 45

5. Substituting the extended BC4J object for the parent object


The BC4J Substitution feature allows you to specify these rules. You use Substitution to substitute
the extended business object for the base object to be used throughout the application. Here is how:
1. Right click on the TutorialCustom.jpr and select Edit Business Components Project (or
right click on the TutorialCustom.jpx and select Edit TutorialCustom).
2. Select the Substitutions section.
From the Available list, select the base object (for instance, PoSimpleSummaryVO) that you
want to replace.
From the Substitute list, select the extended object (for instance,
CustomPoSimpleSummaryVO) that you want as the substitute.
Then click Add. A new substitution rule will be added in the Substitutions list box.

This indicates that the extended object (CustomPoSimpleSummaryVO) should be used in


Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 46

place of the base object (PoSimpleSummaryVO). You can also update and remove the
substitution rules with the Update and Remove buttons.
Click OK to apply the changes and exit.
3. Applying the substitutions at runtime:
After using the wizards to define the substitutions you want to make, the BC4J framework
enters this information in the project's .jpx file. The BC4J runtime does not typically read the
project's .jpx file. To make the runtime read the .jpx file, you must do the following:
i.
Make sure that the classpath contains the .jpx file.
ii.
Use the runtime system property -Djbo.project=Name where Name is the JPX file
name without the .jpx extension.

In JDeveloper, the classpath already contains the .jpx file when you compile the project.
Hence, you just need to specify the runtime system property.
For TutorialCustom.jpr, right click on the project and select Project Settings.
Then in Configurations | Development | Runner, add -Djbo.project=TutorialCustom to the
Java Options.
Give a space between the existing options like -mx256m and the new option, Djbo.project=TutorialCustom.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 47

Note: JDeveloper 9i requires that all the projects in the workspace (.jws) to have the same output
directories. Hence, make the same changes for other projects in the workspace. For this lesson, we
need to make all the projects in toolbox.jws have the same output directories and then rebuild
Tutorial.jpr and TutorialCustom.jpr. When you try to change the paths, you may get the following
warnings.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 48

Click OK.

Click Yes.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 49

6. Lesson Solution Files

The messages used in this lesson can be uploaded to the message repository with
icxfwkmsg.lct and TutorialCustomMsg.ldt.
Download the lct and ldt files and run the following command to upload the messages.
FNDLOAD username/password@databaseSID 0 Y UPLOAD icxfwkmsg.lct
TutorialCustomMsg.ldt
Supply the proper database user name, password, and SID for this command.

All the lesson solutions are in TutorialCustom.zip. You can extract the files from this zip file into
your JDeveloper user home directory.

Copyright Oracle Corporation, 2002. All rights reserved.

OAF Workshop - Extensibility Hands-on Lab


Chapter 9 - Page 50