Oracle Application Framework

By Sridhar Yerram

2/18/2014

Outline
Introduction to OA Framework
Definitions General Principles Understanding the basics of Model
View Objects View Links Entity Objects Entity Experts Validation AM Validation VO

MVC Architecture

Understanding the basics of View Understanding the basics of Controller

Jdeveloper Structure and configuration in your desktop Fundamental OA Framework UI Objects

Checkboxes Pop Lists Simple List of Values Exception Handling Advanced Tables Partial Page Refresh Dialog Pages Passive Criteria List of Values

2/18/2014

Outline
Implementing Server Side Features Debugging OA Framework Applications
Calling PL/SQL procedures and functions Error Handling

Debugging OA Framework Applications using Jdeveloper Logging Infrastructure in OA Framework

Finding out the right version of Jdeveloper IDE List of OAF Files Generated and their importance Directory Structure of Application Server Deploying OA Framework Applications OA Framework Personalization Concepts
Personalization Extension Substitution

SPEL JDR(Table/Packages)
2/18/2014 3

Overview
Oracle Application Framework(OA Framework) is a proprietary framework developed by Oracle Corporation for application development within the Oracle E-Business Suite. Available to customers for personalization, customizations and customapplication development. The OA Framework is a Model-view-controller (MVC) framework built using J2EE (Java 2 Platform, Enterprise Edition)technologies. Historical Perspective
Very first HTML screen in oracle apps was created using PLSQL code, using PL/SQL toolkit. AK Developer, repository for storing structure and definition of the WebPages.

Current Technology OAF with MDS

2/18/2014

Overview (Cont)
OA Framework is based on JSP technology, which executes in a servlet engine. When the browser issues an OA.jsp request for one of the Self-Service pages, page processing takes place within a servlet engine which, in turn, can access the application data as well as user interface metadata from the database.

2/18/2014

Overview (Cont)
Browser Support
Firefox IE

Session
ICX:Session Timeout ICX:Limit Time

2/18/2014

Overview(Cont)
User selects a responsibility and a function MDS Tables(JDR_*) XML representation cached in memory Web Bean hierarchy is instantiated, top level bean is pageLayoutBean and then for each component of the page there is a webbean
2/18/2014 7

OA Framework Features
Advantages Enterprise-Grade Performance and Scalability Improved End User Productivity Highly extensible architecture Browser Look and Feel (BLAF terminology) for all applications Open industry Standards such as XML, HTML, Java, JSP, SQL and Web Services.
2/18/2014 8

OA Framework Architecture
OA Framework architecture is based on Model-View-Controller (MVC)design pattern.

2/18/2014

2/18/2014

10

Components of MVC Architecture

Model: Data Implemented using Oracle Business Components for Java (BC4J). 1.EO (Entity Object) 2.VO (View Object) 3.AM (Application Module) AM is a container for EO, VO, viewLink and entityAssociation. AM retention Get request not retained by default Multipage transactions have same rootAM, Use retainAM=Y Post request by default, it is retained Originally Bc4j was named jbo(Java Business Objects) View: User Interface. Implemented using an Oracle technology called UIX. (UIX = User Interface XML). Controller: Code User actions are handled by the OA Controller. (Ex: Clicking SUBMIT button)
11

2/18/2014

Components of MVC Architecture(Cont)

2/18/2014

12

Interaction between model, view and controller

2/18/2014

13

Entity Object (EO)

Entity Object is based on database table or other data source. Entity Object contains attributes which represent database columns. All insert/update/delete (DML Operations) transactions go through EO to database.

2/18/2014

14

View Object (VO)

Two types
1. SQL based 2. EO based

Represents a query result. Is used for joining, filtering, projecting, and sorting your business data. Can be based on any number of entity objects (EOs) and provides access to EOs.
2/18/2014 15

View Links
View link defines a relationship between two view objects that BC4J uses to automatically query and coordinate the destination view object based on the current source view object.
View links can be based on an association or a declarative join relationship between two view objects.
For example, suppose two tables have a master-detail relationship based on a foreign key. The corresponding entity objects are related via an association, and view objects based on those entity objects can be related by a view link based on the association.
2/18/2014 16

Application Module (AM)

Container for VOs. Every page must have a root application module. Handles transactions.

2/18/2014

17

Web Bean Architecture

Each OA Framework web bean also implements a group of interfaces whose implementations collectively define the behaviors that the OA Framework adds to the base UIX beans. oracle.appps.fnd.framework.webui.beans.OAWebBean - defines core behavior common to all web beans (for example, among other key behaviors, this defines the processRequest, processFormData and processFormRequest methods that individual beans implement for themselves) oracle.apps.fnd.framework.webui.OAWebBeanConstants - a collection of constants used in the view/controller modules oracle.apps.fnd.framework.webui.beans.OAWebBeanData - defines common personalization definition and data source management behavior oracle.apps.fnd.framework.webui.beans.OAWebBeanContainer - defines the characteristics of all web beans that can act as containers for other web beans. For instance, all the layout web beans implement this interface. Only beans which implement this interface can have associated controllers. OAWebBean<Type> - defines a bean's inherent behaviors within the context of the OA Framework. For example, the OATableBean implements the oracle.apps.fnd.framework.webui.beans.OAWebBeanTable interface.

2/18/2014

18

Web Bean Architecture

2/18/2014

19

MDS Meta Data Service

Meta:- In technical world, meta work symbolizes dictionary. Think of a web page broken into small units which are fields, buttons, list boxes. These small individual units[fields, buttons etc] are stored in a dictionary, in the database. These units when combined together, they become a webpage that gets rendered on the browser. Data:- Those meta pieces are not stored as binary files, but as data in tables. Those tables begin with jdr, for example JDR_ATTRIBUTES, JDR_ATTRIBUTES_TRANS, JDR_COMPONENTS & JDR_PATHS. The definition and relationship of each field/region/component is stored in these JDR tables. OA framework reads that data when you request a page. The page structure is then built based on MetaData. Service:- Meta Data is available as a service(plain service not webservice). The data is there in JDR tables, but all such data has to be co-related, all fields, regions,buttons etc have to be clubbed into a meaningful manner to make a web page. You can say that MDS provides service to store & return page definitions. MDS collates those definitions in components/fields in a meaningful manner to build a page.

2/18/2014

20

View in MVC Architecture

2/18/2014

21

Controller (CO) in MVC Architecture

Responds to user actions and directs application flow. Model objects like EO and VO can't be accessed directly from theController Class, except AM. Contains methods such as
processRequest(OAPageContext, OAWebBean):
Fires when OAF page loads for the first time. Can create all UI components

processFormData(OAPageContext, OAWebBean):

processFormRequest(OAPageContext, OAWebBean):

User makes changes on the pages and posts back the page Does validations and moves changed values to VO/EO cache Calls validation methods Fires when user submits the page.(Ex: clicking SUBMIT button) Gets called after PFD returns without raising any exceptions place to do database commits

2/18/2014

22

Controller Class

2/18/2014

23

Onion Architecture of OA Framework

OA Framework can be extracted into a series of concentric layers, like an onion. Each layer only knows about the layers below it.

2/18/2014

24

MVC Architecture

2/18/2014

25

Key Terms
Installation
Setting up E-BS from distribution media to the host OS

Configuration
Process of setting proper parameters, needs SME from various business domains

Personalization
Process of declaratively altering page's UI to meet business needs

Extension
Process of altering page's functionality programmatically(using PL/SQL, java)

Customization
Process of creating new pages

Deployment
Process of moving personalization/extension/customization from development instance to test/prod instance.

2/18/2014

26

JDeveloper Structure (Cont.)

2/18/2014

27

Finding out the right version of Jdeveloper IDE

ATG Release 12.1 Version JDeveloper 10g Patch Patch 7315332 10G Jdev with OA 12.1 (Controlled Release - only included Extension ARU for R12.1 (Controlled for completeness) Release) Patch 8431482 10G Jdeveloper with OA 12.1.1 (rapidInstall or patch 7303030) Extension ARU for R12.1.1 12.1.2 (patch 7303033 or patch Patch 9172975 10G JDEVELOPER WITH 7651091) OA EXTENSION ARU FOR R12.1.2 12.1.3 (patch 9239090 or patch Patch 9879989 10G JDEVELOPER WITH 8919491) OA EXTENSION ARU FOR R12.1.3 Patch 9879989 10G JDEVELOPER WITH 12.1.3.1 (patch 11894708) OA EXTENSION ARU FOR R12.1.3

2/18/2014

28

OAF File Types & Extensions

File Types PG File CO File RN File AM Descript ion Java Package Structure Files File Stored in Generat DB/Middle ed Tier XML Java DB Middle tier Page File <clientName>.oracle.apps.fnd.<APPL_TOP>. webui Controll er File Region <clientName>.oracle.apps.fnd.<APPL_TOP>. webui <clientName>.oracle.apps.fnd.<APPL_TOP>. webui

XML

DB

Applicati <clientName>.oracle.apps.fnd.<APPL_TOP>. on server Module Entity Object View Object <clientName>.oracle.apps.fnd.<APPL_TOP>. schema.server <clientName>.oracle.apps.fnd.<APPL_TOP>. server

XML Java XML Java XML Java

Middle tier

EO VO

Middle tier Middle tier

29

2/18/2014

OAF File Types & Extensions(Cont)

File Descript Java Package Structure Types ion Jws Java Worksp ace Java Project NA Files File Stored in Generat DB/Middle ed Tier Jws NA

jpr

NA

jpr

NA

2/18/2014

30

OAF UI Objects
CheckBoxes Pop Lists Simple List of Values Exception Handling Advanced Tables

2/18/2014

35

OAF UI Objects- Checkbox

2/18/2014

36

OAF UI Objects- Pop Lists

Step 1: Create a view object to be used by your poplist. Per the OA Framework Package / File / Directory standards, you should create this object in a *.poplist.server package. Step 2: Create an item whose Item Style is messageChoice . Assign an ID in accordance with the OA Framework Package / File / Directory standards. Step 3: Apply an attribute set as required by the OA Framework View Coding Standards. Step 4: Specify the Prompt (if not specified by the attribute set). Step 5: Specify the view object that you created in Step 1.
set the Picklist View Instance property (for example, PoplistVO1). In this case, remember to add your poplist view object to the root UI application module for the page (or application module for the shared regions) that will include this poplist.

Step 7: (optional) If the poplist should read/write its selected value from an underlying data source, set the View Instance and View Attribute values accordingly as you would for any other data entry component. The View Instance value should not be same as the Picklist View Instance value.

Step 6: Map the poplist to its view object display and developer key attributes. Set the Picklist Display Attribute to the view object attribute whose value you want to display in the poplist. Set the Picklist Value Attribute to the view object attribute whose value you want to use as the internal developer key. To use our lookup code example above, we would set the Picklist Display Attribute to Meaning, and the Picklist Value Attribute to LookupCode.

2/18/2014

37

OAF UI Objects- Simple List of Values

2/18/2014

38

OAF UI Objects- Advanced Tables

2/18/2014

39

OAF UI Objects- Partial Page Rendering

example of PPR refresh behavior for the Hide/Show component.

2/18/2014

40

Dialog Pages
Messaging can be introduced into application flows when an Error, Information, Warning, Confirmation, or Processing Message needs to be displayed. There are two basic kinds of messaging flows:
Inline Message - The message appears inline on a page around the region item that requires attention. The inline message is also repeated in the message box on top of the page. Dialog Page - The message appears on it's own dialog page in the flow.

2/18/2014

41

Dialog Pages
Warning dialog page.

Example: Redirect to a Basic Warning Page You can include the following code example in your controller processFormRequest method to redirect to a basic warning page: OAException descMesg = new OAException("FND", "FND_CANCEL_WARNING"); OAException instrMesg = new OAException("FND", "FND_CANCEL_ALERT"); String okUrl = APPS_HTML_DIRECTORY + "OA.jsp?OAFunc=FND_REQUISITIONS_PAGE"; String noUrl = APPS_HTML_DIRECTORY + "OA.jsp?OAFunc=FND_REQUISITIONS_PAGE&retainAM=Y"; pageContext.redirectToDialogPage(OAException.WARNING, descMesg, instrMesg, okUrl, noUrl);

2/18/2014

42

Dialog Pages
The short hints render immediately below the item as shown in Figure 1 (see the Purchase Order field). The long hints render as a selectable information icon next to the item (see the Created poplist in Figure 1). When the user selects the information icon, a dialog window opens as shown in Figure 3 below.

43

Calling PL/SQL procedures and functions

According to Oracle Standards whenever it is possible we should use View Objects for Database operation but in some situations we have to call PL/SQL Procedures and Functions using JDBC
1. Create a JDBC CallableStatement with the PL/SQL block containing the stored procedure invocation 2. Register OUT Parameter if any 3. Bind any variables. 4. Execute the statement. 5. Retrieve the values of any OUT parameters if any 6. Close the statement

2/18/2014

44

Error Handling
The OA Framework handles three basic types of exceptions: general, validation and severe.
General Exception : Errors in the BC4J framework are handled by throwing an implicit (runtime) exception of the type oracle.jbo.JBOException. Validation Exceptions : Validation exceptions are thrown from entity objects and view objects for both row and attribute level validation failures.
oracle.apps.fnd.framework.OAAttrValException - specialization of OAException used for attribute level validation failures oracle.apps.fnd.framework.OARowValException - specialization of OAException used for row (entity) level validation failures

Severe Exceptions : Severe (or "fatal") exceptions include unexpected system-level errors (like a NullPointerException) and selected JBOExceptions like NoDefException. You can also deliberately throw a severe exception in your code.

2/18/2014

45

Directory Structure of Application Server

2/18/2014

46

Deploying OA Framework Applications

The Folder Structure for xml pages and respective Controllers are as below
D:\RUP6\jdevhome\jdev\myclasses\temp el\oracle\apps\xxtmg\pdms\msd\webui

D:\RUP6\jdevhome\jdev\myclas ses\tempel\oracle\apps\xxtmg\p dms\msd\server

2/18/2014

47

Deploying OA Framework Applications

This was the development of files in our localhost m/c. The next step will be to move the files into the JAVA_TOP. {/home/tempel10/cdev35appl/xxtmg/java/tempel/oracle/apps/xxtmg/pdms/msd} Just drag and dropped the msd folder from local m/c to Apps Java top path. Importing the XML files: Run the import scripts for the PG and LOVRn files. The import command is
import

D:\RUP6\jdevhome\jdev\myclasses\tempel\oracle\apps\xxtm g\pdms\msd\webui\MultiSpeedPG.xml
-username <DB user name> -password <DB password> -rootdir

D:\RUP6\jdevhome\jdev\myprojects\

-dbconnection " (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=<host IP>)(PORT=<port no.>))(CONNECT_DATA=(SID=<SIDNAME>)))"

2/18/2014

48

Deploying OA Framework Applications

Registering the Main Page as a function Enter the Function Name, User Function Name and Description. Enter Properties (Tab) Type as SSWA jsp function In Web HTML(tab) Enter the Main xml page path
OA.jsp?page=/tempel/oracle/apps/xxtmg/pdms/msd/webui/MultiSpee
dPG (Dont append .xml with the path, it results in error)

2/18/2014

Attach the function with a menu and then run from the respective responsibility.

49

OA Framework Personalization Concepts

Personalization : refers to the ability to declaratively alter the UI to suit user or business needs. Extension : refers to the ability to programmatically extend an application's functionality. Substitution: refers to add adding additional View Object Attributes, it is done by defining a substitution, so your new view object is used in place of the parent at runtime.
2/18/2014 50

Personalization

Profile options :
persnoalize Self-Service Defn FND:personalization region link enable Disable Self-Service personal

2/18/2014

51

Personalization(Cont)
How it is done
Personalize Page link Functional-Administration responsibility Import/Export

Common Types
Changing labels, prompts Hiding or adding table columns Re-ordering UI elements Adding buttons, labels, flexfields 2/18/2014 Adding regions

52

Personalization(Cont)
Involve Some Programming
Controller
Instantiate custom VO Add UI elements which cant be done via personalization

VO Extension
This is needed when value to displayed to the user on the screen is not available in underlying VO

2/18/2014

53

Partial Page Rendering and SPEL

PPR: Ability to partially render the page SPEL : Simplest Possible Expression Language ${oa.xxCustomerVO.isNameReadOnly} ${oa.FunctionSecurity.NAME_READ_ONLY}

2/18/2014

54

JDR Tables
JDR_PATHS Stores document paths, packages and there parent child relationship. Primary Key: PATH_DOCID

JDR_COMPONENTS

Stores components on documents and OA Framework pages. Primary Key: COMP_DOCID, COMP_SEQ
Stores attribute/properties of components on documents and OA Framework pages. Primary Key: ATT_COMP_DOCID, ATT_COMP_SEQ, ATT_SEQ

JDR_ATTRIBUTES

JDR_ATTRIBUTES_TRANS

Stores translated attribute values of document components or OA framework pages. Primary Key: ATL_COMP_DOCID, ATL_LANG, ATL_COMP_REF, ATL_NAME

2/18/2014

55

Query1: select distinct path_type from JDR_PATHS; / Result: DOCUMENT (for pages and regions) PACKAGE (for packages/directories path)

Query2: select * from JDR_PATHS where path_name = 'HelloWorldPG' ; / -- Get familiar with the table structure, path_type will be 'DOCUMENT' for this record.

Query3: select * from JDR_PATHS where path_docid = <path_owner_docid from query2>; / -- This record will point to the parent package/directory.
2/18/2014 56

Query4: select * from JDR_COMPONENTS where comp_docid = <path_doc_id>; / -- This will query components of the DOCUMENT. There are no records for a PACKAGE type.

Query5: select * from JDR_ATTRIBUTES where att_comp_docid = <path_doc_id> and att_comp_seq = <sequence id of component whose properties you wish to check>; /

2/18/2014

57

2/18/2014

58

jdr_utils.listdocuments('/learning/oracle/apps/', TRUE);

jdr_utils.printdocument(p_document => '/learning/oracle/apps/fnd/webui/DeptPG');

JDR Packages

JDR_CUSTOM_INTERNAL JDR_DOCBUILDER JDR_MDS_INTERNAL JDR_UTILS

SELECT * FROM ALL_OBJECTS WHERE object_name like 'JDR_%' AND OBJECT_TYPE IN ('PACKAGE') ;

2/18/2014

63