OA Framework Architecture Overview

• Development and Deployment Platform for Self Service Applications of Oracle eBusiness Suite

• 100% Java and XML based Middle Tier Application Framework• Metadata or Declarative oriented development• JDeveloper is used to develop and debug applications• Complex Business Logic either in Java or PL/SQL

MVC based Architecture

OA Framework follows Model, View and Controller Architecture

Typical J2EE MVC Architecture

• The browser communicates with back-end using HTTP (Hyper Text Transfer Protocol) used for both sending request and receiving response.

• Browser uses either “GET” or “POST” method to communicate with back-end.

• GET Method is used when user enters URL or clicks on a URL Link or Image. Parameters are sent as part of URL.

• POST Method is used when user presses Submit buttons. Parameters/data are sent as part of message body (not visible to users).

• A JSP is “View” component containing display logic.• A JSP contains some HTML and Java code. At runtime, it is compiled into a

Java class (“servlet”) and executed.• A servlet is a Java-based web application server program that implement’s the

functionality in the page either by itself of by calling other objects.• A servlet can either be “Controller” component which decides what needs to

be done next or could be “Model” component implementing the business logic.

• A JavaBean (or "bean" for short) is a reusable component that implements specific design patterns.

• JavaBeans are usually used as “Data Transfer Objects” (DTO) to transfer data from Model Layer to Controller and View Layers.

• Any objects in the middle tier use JDBC (Java Database Connectivity) drivers to communicate with database.

• J2EE Applications may employ many different “Design Patterns” (like MVC, DAO/DTO, Factory).

OA Framework Components

• MDS – Meta Data Service– Stores definition of OA Framework Pages and Regions– MDS stores the definition either in tables (JDR% tables) or in XML

files– MDS also holds the OA Framework Personalization information– UIX uses this information to dynamically generate HTML or JSP code

that is sent to browser– Formerly it was known as JRAD

• UIX – User Interface XML– Dynamically generates HTML and JSP code for displaying OA

Framework Pages on browser.– Makes use of “Web-beans” which have facility to store data received

from screen/model and also logic for rendering page components.

– UIX builds a hierarchy of “Web-beans” containing specification and data for each and every page component. The highest level will be “Page Level” Web-bean.

– BC4J – Business Components For Java• Primary Model Level Components• Consists of Application Modules (AM), Entity Objects (EO),

View Objects (VO), Entity Association (AO) and View Links (VL).

• JDeveloper is used to define these components.• Each of these consist of one XML file and one or more “Java”

programs, which are automatically generated that can be modified, if required.

– AOL/J – Application Object Library For Java• Provides facility for

– Authentication and authorization users against Oracle Applications

– Access/Use AOL components like Flexfields, Attachments etc.

• OA Framework

– Programmatic ‘glue’ integrating these technologies– Provides “OACore” (Core Controller) which first receives and

processes each request by instantiating and calling other objects as necessary

• iAS – Application Server– Contains Web-Server/Listener, embedded JVM and Java Servlet

Engine– Executes each and every Java program in JVM

• OC4J – Oracle Connect for Java– Light Weight Application Server running on PC/Server– JDeveloper has in-built OC4J to run OA Framework programs during

design and development time.

• Workflow– Used for customizable page and process flow

• JDeveloper – Integrated Development Environment (IDE)– Single tool to specify and code all components required by OA

Framework– Most of the times, components are designed and developed by

declaring/specifying properties instead of writing code.– Automatically generates XML files containing the object properties

and Java programs, which can be modified by developer to incorporate additional logic.

– JDeveloper allows testing of objects without deploying on backend server through in-built BC4J.

• OA Extension – Extension to JDeveloper– Allows to definition of BC4J Components, OA Components (i.e. Pages

and Regions) and Controller Classes.

OA Framework Internal working (High Level)

The View – Displayed Pages

The View – Rendering

The View – Designing

• Pages are made up of a hierarchy of regions and items.• Oracle 9i JDeveloper OA Extension used to create pages declaratively.

• Order of item control runtime positioning.• HTML is dynamically generated.

• A region is a reusable container that holds items• Region could be

– Stacked Layout Region, Query Region, Table Region, Notification Region, Message Component Layout etc.

• The top level of every page is a region with a 'pageLayout' style• A region can contain

– Buttons, Fields, Choice List, LOV– Images, Tabs, Other regions– Tables, HGrid, Tree, Train– Flexfields, Attachments– And other Widgets / UI Components for rich UI

• Each region can have special components called “<Region> Components” (e.g. PageLayout Components – Product Branding). OA Framework controls positioning of them at pre-specified locations.

• The “Style” of Region and Items control the way they are rendered on the browser.

• Each Widget, Region and Item corresponds to one or more Java Objects called “Web-Bean”.

The View – Display Process

The Model – Layered Architecture

• The Application Module – Container for related BC4J objects, which participate to perform same

tasks.– Provide transaction context and establish database connectivity.– Contains Java Code incorporating the “Business Logic” to handle each

request.– Majority of custom “Java Code” is written in this object.

• Entity objects (EO)– Encapsulate table level business rules and logic.– Contains logic for INSERT, UPDATE, DELETE and Validation of

data of single record at a time.– One Entity Object usually corresponds to a table.– Linked to other Entity objects by Entity Association objects.– Entity Objects can either be based on Java Classes or PL/SQL API

Procedures.• View objects (VO)

– Encapsulates a database query and presents data to the Framework page

– May be based on plain SQL if query only otherwise based on one or more Entity objects.

– View Objects is “Array” of records fetched from EOs or Query.– OA Framework Pages take data VOs to display on screens and also

populate it back with data entered/modified on screens.– Provides getter and setters for Entity Object values and facility to

create/add records, remove/delete records from array.– Linked together by View links.

The Controller – Request Handling

The Controller – Controller Class

• Class: OAControllerImpl - Implement it for– Intercept and handle user events like button clicks– Call appropriate Application Module method to execute the business

logic– Initialize the data items– Controlling Java Beans (Webbean) behavior– Manipulate UI data at run-time

• Method: processRequest– Called for each Page invoked in “GET” mode or Page that is not yet

initialized.– Extend this method to

• Customize page layout at runtime• Perform manual data initialization• Perform an auto-query

• Method: processFormData– Called for each Page invoked in “POST” mode.– Reads form field data (from PageContext) and transfers to underlying

View Objects– Extend this method to

• Update/Initialize the data appropriately• Method: processFormRequest

– Called for each page invoked in “GET” mode. – Called after processFormData– Extend this method for adding business logic

• Class: OAPageContext– Contains parameters from page along with form fields– Usually used to identify the user operations like pressing Button or

identify PPR event– Methods to perform JSP forwards and client redirects

• Class: WebAppContext– Tracks the application context (along with session-based cookie– Provides information like Current Responsibility, OrganizationId, User

Id etc.

– Can be accessed through OAPageContext (on the client) or OADBTransaction (on the server)

• Class: OADBTransaction– Encapsulates JDBC connection for the transaction– Use to build callable statements for executing PL/SQL procedures– Provides access to session-level Application context

OA Framework Personalization

• The Ability to Declaratively Tailor the OAF Formto suit a Business Need

• Administrative and User Level Personalization• We can make:

– Make fields Mandatory or Read Only– Show/Hide: Fields, Table, Table Columns, Regions, Tabs etc.– Change Text: Labels, Prompts, Tabs, Messages, Notifications– Changes to Font and Style– Alter Tables and Component Positions– Add New Items : Fields, Buttons, Links, Pick Lists, Images– Restrict Query Results etc.– Save Search Criteria, change sorting order etc.

• Prerequisite – Following profile options need to be set

• “Personalize Self Service Definitions” = Yes (FND_CUSTOM_OA_DEFINITION)

• “Disable Self Service Personal” = No (FND_DISABLE_OA_CUSTOMIZATIONS)

Press on ‘Personalize’ URLs

Expand and press Personalize Icon

Modify appropriate Properties and press Apply and Return to page

OA Framework Setting up Development Environment

• Prerequisites– Desktop with 1.5 GB RAM– Telnet and FTP access to apps and db server

– Database connectivity details: Apps username and password, SID, Host Name and port.

– Exact version of OA Framework on server, got from URL belowhttp://<Base Address>/OA_HTML/OAInfo.jsp

– Java DK version 1.4.2.16– Internet connection, Metalink access etc.

– References– Metalink Note: 416708.1 - How to find correct version of JDeveloper– Metalink Note: 330236.1- Configuring JDeveloper For Use With

Oracle Applications 11i and R12 – Metalink Note: 269138.1 - OAF Developer's Guide Release 11.5.10– http://oracle.anilpassi.com/apps-technology/3.html

– Download appropriate patch with ‘JDeveloper with OA Framework extension’ from Metalink, as specified by Metalink note 416708.1 and unzip it to directory d:\software\JDeveloper.

– Download and install Java 1.4.2.16 under directory D:\software\j2sdk1.4.2_16– Set Environment Variables ( Under My Computers -> Properties -> Advanced

-> Environment Variables) – JDEV_USER_HOME to d:\software\JDeveloper\jdevhome\jdev

– Using System Administrator responsibility, create Application User TESTnn and assign responsibilities:

– OA Framework Toolbox Tutorial– OA Framework Toolbox Tutorial Labs

– FTP(in ASCII mode) appropriate .dbc file (database connection file) from the server to desktop. Dbc files are available under $FND_TOP/secure directory. Copy this file to directory : d:\software\JDeveloper\jdevhome\jdev\dbc_files\secure.

– Create a desktop short-cut for d:\software\JDeveloper\jdevbin\jdev\bin\jdev.exe

– Launch JDeveloper either using short-cut and clicking on jdev.exe directly. This starts Oracle 9i JDeveloper.

– In System Navigator, Click on Connections and to Database. Right click on Database node and select New Connection. Enter appropriate details andtest the connection.

– In Tools -> Preferences -> Embedded OC4J, select ‘Default Local IP Address (recommended)’.

– In File -> Open , Select directory myprojects and open file ‘toolbox.jws’– Expand ‘toolbox.jws’ and select ‘tutorial.jpr’ and then select menu project ->

project settings. In ‘Run-time settings’, enter the name of application user and password created.

– Right click on ‘tutorial.jpr’ and select ‘Edit Business Component Project’– Repeat the above for all .jpr files– Select ‘toolbox.jws’ and then select menu option project -> rebuild

toolbox.jws– Select ‘tutorial.jpr’ and then select menu option project -> show categories.– Expand HTML Sources under tutorial.jpr and select test_fwktutorial.jsp and

then select menu option run -> run fwktutorial.jsp which displays the application.

OA Framework Build First Application

1. Verify database connectivityConnection -> Database -> <DB Name>

2. Create new OA WorkspaceNew -> General -> Projects -> Workspace Configured for OA FrameworkEnter Project Name ‘MyHelloWorld1WS.jws’

3. In Oracle Applications Project Wizard, Enter File Name ‘MyHelloWorld1OAProject.jpr’Default Package ‘oracle.apps.ak.hello’(Warning : Unselect Use Repository for Design Time (should be un-checked))

4. In Project Wizard, Runtime Connection, enterDBC File Name = select ../jdevhom/jdev/dbc_files/secure/<your>.dbcUser Name, Password = Enter Apps User Name and Password(User should have ‘OA Framework Toolbox Tutorial’ and ‘OA Framework Toolbox Tutorial Labs’ responsibilities)

5. In System Navigator -> Workspace, double click on ‘MyHelloWorld1OAProject.jpr’In Project Settings, Common -> Oracle Applications -> Runtime OptionsMove OADeveloperMode and OADiagnostic to ‘Selected Options’

6. Create OA Components Page FileIn System Navigator -> Workspace, right click on ‘MyHelloWorld1OAProject.jpr’Select New -> Web Tier -> OA Components -> Page, EnterName = MyHelloWorldPGPackage = oracle.apps.ak.hello.webui

7. In View, Enable ‘System Navigator’, ‘Structure Window’ and ‘Property Inspector’(Repeat this whenever required)

8. In ‘System-Navigator’, Select MyHelloWorldPG.xmlGoto Structure Window and Select( or Double Click) ‘region1’In Property Inspector (if not visible, try step 7), EnterID = PageLayoutRNWindow Title( under Visual) = My Hello World Window Title Title = My Hello World Page NameAM Definition=Oracle.apps.fnd.framework.server.OAApplicationModule

9. In Structure Window, Right Click on PageLayoutRNSelect New -> Region, system automatically creates region1 (visible in structure window)In Structure, select ‘region1’ and go to Property Palette and enterID = MainRN

10. In System Navigator, Right Click on ‘MyHelloWorld1OAProject.jpr’Select ‘Make’ or ‘Rebuild’RUN THE FORM NOW, by selecting Run -> Run MyHelloWorld1OAProject.jpr

11. In System Navigator -> Workspace, Select ‘MyHelloWorldPG.XML’Go to ‘Structure’ Window and Right Click MainRN Select New -> MessageTextInputGo to ‘Property Inspector’ and EnterID = HelloNameItem Style = messageTextInputPrompt = NameLength = 20

Maximum Length = 50(REBUILD AND RUN PAGE, if required)

12. In System Navigator -> Workspace, Select ‘MyHelloWorldPG.XML’Go to ‘Structure’ Window and Right Click MainRN Select New -> MessageLayoutGo to ‘Property Inspector’ and EnterID = ButtonLayout

13. In Structure, Right Click on ButtonLayoutSelect New -> Item and enterID = GoItem Style = SubmitButtonAttribute Set Property = /oracle/apps/fnd/attributesets/Buttons/GoPrompt = Go (should be inherited and defaulted from Attribute Sets)

14. Save work with File -> Save AllRUN THE PAGE

In System Navigator -> Workspace, Select ‘MyHelloWorldPG.XML’Go to ‘Structure’ Window and Right Click MainRN and Select Set New ControllerGo to ‘Property Inspector’ and Enterpackage Name = oracle.apps.ak.webuiClass Name = HelloWorldMainCO

16. In editor(for class), make following changes:Add line:import oracle.apps.fnd.framework.OAException;

public void processFormRequest(OAPageContext pageContext, OAWebBeanwebBean) { super.processFormRequest(pageContext, webBean); If (pageContext.getParameter("Go") != null) { String userContent = pageContext.getParameter("HelloName"); String message = "Hello, " userContent + "!"; throw new OAException(message, OAException.INFORMATION); } }

OA Framework Basic of Views

• BC4J Overview• Entity Object• Entity Association• View Object• View Link• Application Module• Transaction

View Layer Terminology• Page – the basic UI component created in OA Framework.• Region – A portion of a page defined in page or reused (extended) from

external region.• Property – Property of Items and Regions.• Attribute – An XML attribute in the UIX file. Roughly equivalent to a column

in a View Object. • BLAF – Oracle’s Browser Look-and-Feel Standard (available at:

http://otn.oracle.com/tech/blaf/)• Attribute set – a named set of properties applied to configure an item.• CSS Class – the cascading style sheet class applied to the item (see BLAF).• View Instance – the VO used for data binding• View Attribute – the VO’s specific attribute to which the item is bound• SPEL – Simplest Possible Expression Language

Creating Basic Page

• Create “Workspace Configured for Oracle Applications”– Default package should be type:

xx.oracle.apps.mmm.module.submodule.webui• Create “Project Configured for Oracle Applications”• Perform project settings

– Runtime Connections : DBC File, User Name and Password• Change Tools->Preferences->Embedded OC4J

• Compile and run the page• Add the Regions, Shared Regions and Items to Page of appropriate Style• Change properties of Regions and Items• Create/Modify “PageLayout Components” sub-regions and other similar

“<Region> Component” sub-regions.– Also called “Named children” of region (Other items are called

“Indexed children”)• Associate Pages, Regions and Items with BC4J components (AM, VO Object,

VO Attribute) and Controller.– These should have been pre-created

• Test pages progressively

Named and Indexed Children

• Named children of a Bean have a specific name, specific purpose, and a specific location in the UI.

• Indexed children of a Bean depend on their order under the Bean

Shared Regions

• Shared Regions improve reusability by including external region without re-defining it

• Shared Region can exist in own XML file or in another page.• Shared Region can be created using New->Web Tier -> OA Component ->

Region• Used extensively for LOVs• Public Shared regions should have own Controller and AM.

Attribute Sets

• Attribute sets are named, reusable collections of properties (prompt, max length, data type)

• Used by regions, items, and other attribute sets.• Improves reusability and reduce maintainance cost• Create Attribute Sets using

– Create using New->Web Tier -> OA Component -> Package– Select the ‘attribute set package’ in System-Navigator, Go to Structure

window.– Right-click on AttributeSets and select New – Give a useful name and choose properties – In Structure Window, select the attribute set and assign values

CSS Styles

• CSS Styles are used for consistent Look and Feel• Master List available in:

http://www.oracle.com/technology/tech/blaf/specs/index.html

• Common CSS Styles– OraFieldText: Updatable Fields– OraDataText: Display Only Fields– OraPromptText: Used for Prompts, Checkboxes– OraLinkText: For Links/URLs– OraInstructionText: For Plain Text Instructions

Region Styles

• advancedSearch• advancedTable• bulletedList• cellFormat• contentContainer• contentFooter• defaultDoubleColumn• defaultFormStack• defaultSingleColumn• defaultStack• flexibleLayout• gantt

• graphTable• hGrid• header• hideShow• hideShowHeader• labeledFieldLayout• navigationBar• pageButtonBar• query• rowLayout• Shuttle• messageComponentLayout

• stackLayout• subTabLayout• switcher• table• tableLayout• train• tree

Sub-Region Styles

• Some styles need to be combined to build a particular layout on your page, such as an arrangement of fields and buttons that use a tableLayout region to define their locations.

– tableLayout– rowLayout– cellFormat– spacer (this is an item type, not a region type)

Item Styles

• attachmentLink• attachmentTable• button• exportButton• flex• formParameter• formValue• formattedText• image• link• rawText• resetButton• richTextEditor• separator• servletInclude• spacer

• staticStyledText• submitButton• tip• urlInclude• messageCheckBox• messageDownload• messageFileUpload• messageLovChoice• messageLovInput• messageRadioButton• messageRadioGroup• messageStyledText• messageTextInput• messageChoice• messageRichTextEditor• messageInLineAttachment

• messageTextInput: input Field• messageChoice: Poplist/drop-down List of Values• messageLovInput: List of Values Field (external)• messageStyledText: Display only fields• staticStyledText: Plain boilerplate text• submitButton: Submit button with POST method• formValue: Hidden fields• flex: Descriptive or Key Flexfields• link: URL link (based on field value)

Region and Item Properties

• ID : Unique Identifier. Should be unique within a page, Case sensitive, Don’t change, Referred at many places

• Style (Region / Item) : Choose appropriate Style, Changing it can impact behavior and deletion of contents

• Extends: Used for Shared Regions and Reusability• Attribute Set: Specify full path of attribute set• Controller Class: Specify controller which processes the request. Controller

should be assigned to top-level region.• AM Definition : Specify the application module. Should be assigned to top-

level region (is called Root Application Module)• View Instance and View Attribute : View Object and column/attribute

associated with item/region.• DataType, Maximum Length : Mandatory• Prompt, Height, Additional Text, Length : Mandatory• Tip Type, Tip Message Apps Short Name, Tip Message Name: To provide tip

on the item, Maps to FND_MESSAGES tables

OA Framework:Basic BC4J Concepts

The “Reuse Onion”

• Each layer only “knows” about the layers below it.• This allows reuse of inner objects by outer objects at any of the layer

boundaries.

Entity Objects

• Map to a database table or other data source• Each entity object instance represents a single row• Contains attributes representing database columns• Fundamental BC4J object through which all inserts/updates/deletes interact

with the database

Entity Association

• Define a relationship between entity objects.• Facilitate access to data in related entity objects• May be based on database constraints• May be independent of database constraints• Consist of a source (master) and a destination (detail) entity• Similar to JOIN Conditions

Entity Association

• Two types of Entity Associations– Normal Association

• Used for Weak Association• E.g. Requisition to Supplier Association

– Composition Association• Used for composite objects with strong "owning" relationship• For parent-child/Master-Detail relationship where child cannot

exist without Master.• Example: RequisitionHeader - RequisitionLine association• Integrity and validity of data among master and detail will be

maintained.

View Objects

• Represent a query result and collection of data • Are used for joining, filtering, projecting, and sorting business data• Can be based on any number of entity objects• Can also be constructed from a SQL statement• Will have only those attributes required for a specific purpose

• View Object can be created in one of three ways based on:1. Generated SQL based on EOs

• Add ‘where clause’ at design-time, not run-time for best performance

• Can be based on one or more EOs joined using Entity Associations

2. ‘Expert’ custom SQL with no underlying EOs• Read-only Data

3. ‘Expert’ custom SQL based on mapped to EOs

• Create VO Java class (VOImpl) if needed– VOs should not contain business or validation logic, except transient

attribute and PL/SQL logic• Always create View Row Java class (ViewRowImpl) and accessors

(setters/getters)

View Links

• A view link is an active link between view objects.• You can create view links by providing the following:

– Source and destination views– Source and destination attributes

• Used for Master-Detail form

Application Module

• Defines the logical data model and business methods needed to support an application task

• Handles transactions

• Interacts with clients

• Encapsulates Server/Middle tier View Objects– Container for view objects and view links– View objects are defined by view instance names which are the names

referenced by UI framework– Allows definition of master/detail view links

• Encapsulates Server/Middle tier controller-like logic– Initialize and perform view object query– Custom functions to process view objects

– For example: copying data between VOs.– Custom functions to access entities.

• Root AM holds BC4J Transaction object– Nested AMs reference the root AM Transaction object

• OA Framework groups pages together by Root AM– Pages with same Root AM name, and RetainAM=Y URL flag, are

handled as one AM/Transaction instance shared for both pages– Useful for multi-page updates– Useful for sharing expensive queries across several pages

BC4J Packages

• There are two types of packages, directory paths and files. Directory path packages hold:

– EO-related (business logic) .java and .xml files in oracle.apps.<application shortname>. <module>.schema.server

– AM and VO (UI-related logic) .java and .xml files in oracle.apps.<application shortname>. <module>.server

– Poplist- and LOV-related VO and AM .java and .xml files in oracle.apps.<application shortname>.<module>.poplist.server and oracle.apps.<application shortname>. <module>.lov.server