11i Extend Oracle Applications:

Building OA Framework Applications

Basics of the Controller

Copyright © 2005, Oracle. All rights reserved.

 Objectives

After completing this lesson, you should be able to do

the following:
• Understand how coding logic is handled in OA
Framework
• Enhance an OA Framework page using logic for
buttons, automatic queries, dynamic WHERE
clauses, JSP forwards, and the Message
Dictionary
• Understand the event flow within an OA
Framework page (GET and POST events)

6-2 Copyright © 2005, Oracle. All rights reserved.

 Common Logic to Code

There are several tasks you will do routinely in your

code.
• Handle button press and other events
• Automatic queries
• Dynamic WHERE clauses
• Commits
• JSP Forwards

6-3 Copyright © 2005, Oracle. All rights reserved.

 Typical Locations for Code

The most common locations for your code will be:

• Controllers for regions
– processRequest (code for page initialization such as
HTTP GET actions, after passivation, and so on)
– processFormData (typically no code)
– processFormRequest (code for HTTP POST actions)
• Application Modules
– Often called by controller
• View Objects
– Initialize and execute queries
• Entity Objects
– Validation (may also be in "Entity Expert")

6-4 Copyright © 2005, Oracle. All rights reserved.

 Handling Queries

Most view objects need a method on the VO to

initialize and execute the query.
• The VO should be able to "query itself"
• Set up dynamic WHERE clause if needed
– You must use Oracle Style binding (:1, :2,…, not ?)
• Naming convention: initQuery method
• Usually not needed for query bean or LOV VOs

6-5 Copyright © 2005, Oracle. All rights reserved.

 View Object initQuery Code

• Located in the VOImpl.java class file

• Is called from the application module query
method
• Usually accepts query arguments
• Assembles a query statement using Oracle-style
parameter binding
• Executes the query

6-6 Copyright © 2005, Oracle. All rights reserved.

 Dynamic WHERE Clauses

Generally you should avoid dynamic WHERE clauses.

• You usually get better performance with VOs and
WHERE clauses that are defined at design time
(using the VO wizard).
– Better to create multiple similar VOs with different
WHERE clauses than to modify WHERE clause at
runtime.
• Sometimes you need to use a dynamic WHERE
clause:
– User-driven query where you do not know what
columns will be in the WHERE clause.

6-7 Copyright © 2005, Oracle. All rights reserved.

 Using findByKey Instead of initQuery

BC4J caches entity objects. The same entity object

can be referenced by multiple view objects, even in
different pages (within the same root UI AM).
• Changes to an entity object in one page are
reflected in a view object that references it from
another page.
• For a VO based on entity objects, you can use the
view object's findByKey method to locate a row
without always making a database round trip.
– Can also be used for SQL-only VOs
• For a single entity object that was already queried,
using findByKey locates the data efficiently.

6-8 Copyright © 2005, Oracle. All rights reserved.

 Processing a Button Press

• A submit button in the UI does not inherently do

anything.
• You must add code to make the submit button
respond to a user click event.
– Add button-handling code to the
processFormRequest method in a controller for
the region.
– Check the button object to make sure it has been
clicked.

6-9 Copyright © 2005, Oracle. All rights reserved.

 Checking for Button Presses and Getting
Parameters from Requests

Request parameters are available from the

PageContext object.
• For example (check if a button has been pressed):
if (pageContext.getParameter("Go") != null)
…
• For example (get a parameter value into a buffer):
String employeeName =
pageContext.getParameter("employeeName");

6-10 Copyright © 2005, Oracle. All rights reserved.

 Example: Manually-built Search

• There are 3 steps to make a Go button work for a

manually-built Search region, for example:
1. Add initQuery code to the view object that builds
and executes a query
2. Add a query method to the application module that
finds the view object and executes the initQuery
method
3. Add code to the processFormRequest method in
the Controller that calls the application module
query method

6-11 Copyright © 2005, Oracle. All rights reserved.

 The Process

Region Controller
User presses processFormRequest() calls
Go button initEmployeesQuery()

Application Module
View Object
initEmployeesQuery() initQuery()
– Finds and instantiates – Initializes the query
the view object – executes the query
– Calls the view object
initQuery()

6-12 Copyright © 2005, Oracle. All rights reserved.

 Example Search: Controller

The controller for the manually-built Search in this

example:
• Checks the button object to make sure it has been
clicked
• Gets the Root Application Module
• Serializes the parameters
• Calls the appropriate 'Initialize Query' method in
the Application Module
• Redraws the current page as necessary

6-13 Copyright © 2005, Oracle. All rights reserved.

 Forwarding to Another Page

Often a button press requires JSP forwarding to another

page, either with a URL or a function name:

pageContext.setForwardURL(
"OA.jsp?page=<page URL>", …

See the OAPageContext Javadoc for more information on

these utility methods.

6-14 Copyright © 2005, Oracle. All rights reserved.

 Setting Titles with Message Dictionary

Always use Message Dictionary to get translated

strings and messages for code that displays text on a
page.
• Start by defining a message in Message
Dictionary.
• Set tokens:
MessageToken[] tokens = { new
MessageToken("EMP_NAME", employeeName)};
• Get the message and use it as a title:
String pageHeaderText =
pageContext.getMessage("ICX",
"FWK_TBX_T_EMP_HEADER_TEXT", tokens);

6-15 Copyright © 2005, Oracle. All rights reserved.

 Event Flow Overview

Understanding the common OA Framework event

flows is essential to aid:
• Coding
– Logic execution order
• Debugging
– Breakpoint placement

6-16 Copyright © 2005, Oracle. All rights reserved.

 Initial Setup Flow

Request
JSP OAPageBean OAPageContext
from Browser

When a user makes a request from the browser:

• Request is received by the JSP
• JSP invokes OAPageBean
• OAPageBean creates OAPageContext
– Provides access to the state of the page
– Provides hooks into OA Framework services

6-17 Copyright © 2005, Oracle. All rights reserved.

 Controller Event Flows in OA Framework

• Two main OAController event flows

– “Initialize page” used for HTTP GET (URL)
- primarily processRequest

– “Submit action” used for HTTP POST (Form

Submit)
- processFormData and processFormRequest
• Form submits (such as button presses) are
directed back to the original OAController

6-18 Copyright © 2005, Oracle. All rights reserved.

 GET Event Flow – Overview

1. Get session info and validate user

2. Fetch metadata
3. Get Root AM and validate user session
4. Instantiate BC4J and UIX objects
5. Walk UIX tree and call processRequest on
controllers
6. Perform post processing for complex beans
7. UIX renders page

6-19 Copyright © 2005, Oracle. All rights reserved.

 GET Event Flow
(1) Get info and validate user

Get ICX session

 URL provides:
cookie
– Database (DBC) information
– Page name
– Other parameters
(2)

6-20 Copyright © 2005, Oracle. All rights reserved.

 GET Event Flow
(2) Fetch Metadata
Metadata NO
in cache?

YES MDS
Fetch metadata Repository

Apply  Metadata fetched through separate

personalizations static connection
 At customer sites metadata will be
in the database
(3)  In JDeveloper you can work against
XML files, the repository, or both

6-21 Copyright © 2005, Oracle. All rights reserved.

 GET Event Flow
(3) Get Root AM, Validate Session

Get  AM associated with page

root BC4J AM
is root AM

Validate session
 Root AM holds the
on root AM database connection

Validate Function
associated w/ page

(4)

6-22 Copyright © 2005, Oracle. All rights reserved.

 GET Event Flow
(4) Instantiate BC4J and UIX Classes

Build OA bean Instantiate assoc. Place bean bound

hierarchy from BC4J objects values (if any)
metadata

Cache OA bean
hierarchy on root AM (5)

 At runtime, UI regions and items map to Web beans

 OA beans are extensions of UIX beans

6-23 Copyright © 2005, Oracle. All rights reserved.

 Example Bean Hierarchy Structure

Request
JSP OAPage Bean OAPageContext
from Browser

PageLayout Bean

Header Bean

Text Bean Text Bean

6-24 Copyright © 2005, Oracle. All rights reserved.

 GET Event Flow
(5) processRequest

Walk bean hierarchy

- Instantiate controller classes
- Call processRequest() on controllers
(6)

 In processRequest developers can query data (using

vo.executeQuery) and set bean properties
programmatically

6-25 Copyright © 2005, Oracle. All rights reserved.

 GET Event Flow
(6) Post-Processing

• Perform post-processing on complex beans

– OAPageLayoutBean and OATableBean for
example
– Post-processing can also be initiated from
processRequest by calling prepareForRendering
method
• Places data binding objects on rendering
context

6-26 Copyright © 2005, Oracle. All rights reserved.

 GET Event Flow
(7) UIX Renders the Page

• UIX generates page by calling UIX render

method recursively
• UIX uses DataObjects and BoundValue
interfaces to fill in values
– DataObjectList – View Object
– DataObject – View Row

6-27 Copyright © 2005, Oracle. All rights reserved.

 Structure of a Web Bean
Dictionary

BaseMutableUINode Key Value

OAStyledTextBean “text” “Hello World”
_indexedChildren “style” “OraTipText”

_namedChildren

_attributes

Hello World
getAttributeValue
setAttributeValue

6-28 Copyright © 2005, Oracle. All rights reserved.

 Data Binding
WebBean

_attributes Dictionary OADataBound

Value
viewUsage VO1

viewAttr Attr1
RenderingContext
getAttributeValue text
(context, “text”)
VO1

UIX

6-29 Copyright © 2005, Oracle. All rights reserved.

 POST Event Flow – Overview

1. User does something to cause a form submit

2. UIX performs client-side validation on the browser
3. Browser sends the POST request
4. Validate user
5. Retrieve AM and bean hierarchy if saved
6. Walk UIX tree and apply form data to data objects
in processFormData
7. Walk UIX tree and call processFormRequest on
controllers
8. If no redirect then refresh the page

6-30 Copyright © 2005, Oracle. All rights reserved.

 POST Event Flow
(1 - 3) Submit, Client-Side Validation

• User does something to cause a form submit

(such as button press or PPR event)
• UIX performs onSubmit Javascript client-side
validation on the browser
• Browser sends the POST request only if the client-
side validation succeeds

6-31 Copyright © 2005, Oracle. All rights reserved.

 POST Event Flow
(4 & 5) Validate User and Retrieve State

• Validate the user as in GET

• Retrieve AM and cached copy of bean hierarchy.
If the bean hierarchy is not found:
– Validate session and function as in GET
– Go through processRequest logic again to
recreate the bean hierarchy
Your code must be prepared to expect
this!

6-32 Copyright © 2005, Oracle. All rights reserved.

 POST Event Flow
(6) Apply Form Data

First pass through the bean hierarchy:

• The processFormData method applies form data
to the underlying objects. If a primary key is
defined for the object, it validates that the data is
being applied to the correct object.
– Throws state error if data is out of synch
• Within processFormData, OA Framework calls
setAttribute on the current row of the
underlying VO for each bean.
– Executes any attribute-level validation you've
written for the view object row (ViewRowImpl)

6-33 Copyright © 2005, Oracle. All rights reserved.

 POST Event Flow
(6) More of processFormData

Attribute-level validation:
• Within view row setAttribute, the view row
automatically calls the corresponding
set<AttributeName> in the underlying entity
object.
– This executes any associated attribute-level
validation in the entity object.

6-34 Copyright © 2005, Oracle. All rights reserved.

 POST Event Flow
(6) More of processFormData

Row-level validation:
• Once all the attribute values have been set, the OA
Framework calls the VO validate for each row it
modified to execute any associated row-level
validation.
– Within validate, the view row
calls validateEntity for the underlying EO,
which executes any entity-level validation.
Debugging Tip: Any declarative BC4J
validation (such as Update While New
specified in BC4J wizards) fires after
validation in your Impl.java files.

6-35 Copyright © 2005, Oracle. All rights reserved.

 POST Event Flow
(6) More of processFormData

• OA Framework automatically displays error

messages for any exceptions thrown by the model
layer during processFormData.
– Bad attribute values are maintained in the
OAAttrValException object
– If there are errors, code does not proceed to the
next phase of calling processFormRequest
Debugging Tip: If your code never gets
to a debugger breakpoint in
processFormRequest, it probably had
an error in processFormData.

6-36 Copyright © 2005, Oracle. All rights reserved.

 POST Event Flow
(7) processFormRequest

• Walk UIX tree and call processFormRequest on

controllers (second pass through the bean
hierarchy)
– Developers can respond to events or redirect to
another page
• If no redirect (or if errors are thrown) redraw the
page

6-37 Copyright © 2005, Oracle. All rights reserved.

 Summary

You should now be able to understand the following:

• Initial Setup Flow
• Controller Event Flows
• Request Flow (GET)
• Submit Flow (POST)
• Much of the event flow happens automatically
through OA Framework or BC4J.
• Understanding the flow helps greatly with coding
and debugging.

6-38 Copyright © 2005, Oracle. All rights reserved.

 Summary

In this lesson, you should have learned how to:

• Understand how coding logic is handled in OA
Framework.
• Enhance an OA Framework page using logic for
buttons, automatic queries, dynamic WHERE
clauses, JSP forwards, and the Message
Dictionary.
• Understand the event flow within an OA
Framework page (GET and POST events).

6-39 Copyright © 2005, Oracle. All rights reserved.