OA frame Work Students Guide

Copyright Oracle 2011, All rights Reserved

R12 Customized Course – Customizing & Building OA Framework

Page 1 of 545

R12 – Customized Course Customizing & Building O A Framework

- Student Guide Customized Content 2011 – Oracle Corporation – Dubai – UAE



Page 2 of 545

Contents

R12 Customizing OA FCW Applications Building OA FW Applications ................................................ 3

Concepts of the MVC Design Pattern ............................................................................................... 33

Basics of the Model ........................................................................................................................... 69

Basics of the View ........................................................................................................................... 119

Basics of the Controller ................................................................................................................... 154

Introduction to JDeveloper 10g with OA Extension ........................................................................ 195

Deploying OA Framework Applications .......................................................................................... 248

Implementing Query Page and Drill Down Page ............................................................................. 291

Implementing Create Page ............................................................................................................. 300

Introduction to Personalizations..................................................................................................... 367

Personalization Concepts ................................................................................................................ 385

Extending OA Framework Applications .......................................................................................... 413

Deploying OA Framework Applications .......................................................................................... 435

Introduction to Personalizations..................................................................................................... 478

Personalization Concepts ................................................................................................................ 496

Extending OA Framework Applications .......................................................................................... 524



Page 3 of 545

R12 Customizing OA FCW Applications Building OA FW Applications

1Copyright © 2007, Oracle . Al l rights reserved.

R12 Customizing OA Framework Applications

Building OA Framework Applications

1Copyright © 2007, Oracle . Al l rights reserved.


Building OA Framework Applications



Page 4 of 545

Copyright © 2007, Oracle. All rights reserved.1 - 2

Course Objectives

After completing this course, you should be able to do the following:

• Identify the concepts, architecture and components of OA Framework applications

• Debugging the OAF Page

• Implementing Advanced OAF Features

• Extend existing OA Framework pages

• Personalization of OA Framework pages

• Deploy OA Framework personalization's and extensions into an E-Business Suite instance

• Migration of Custom Built OA Page between instances



Page 5 of 545

Slide 3


Lesson Objectives

After completing this lesson, you should be able to:

• List the course objectives and agenda

• Identify the architecture and components of OA Framework applications



Page 6 of 545

Slide 4


Agenda – Day 1

• Introduction to OA Framework

• Introduction to Model-View-Controller design pattern

• Basics of the Model

• Basics of the View

• Basics of the Controller

• Debugging OA Framework Pages

• Implementing a Drill Down

• Lab : Implementing a Drill Down



Page 7 of 545

Slide 5


Agenda – Day 2

• Implementing a Create with validations

• Implementing Partial Page Rendering (PPR)

• Lab: Implementing a Create

• Lab: Implementing Partial Page Rendering (PPR)

• Lab: Implementing a Multi-page Update

• Deploying an OA Framework Page

• Understanding OA Framework State Management



Page 8 of 545

Slide 6


Agenda – Day 3

• Implementing Master Detail OA Page

• Implementing LOV in OA Page

• Lab: Implementing Master Detail

• Lab: Implementing LOV in OA Page

• Extending OA Framework Pages

• Introduction to Personalization

• Personalization Concepts

• Migration of Custom built OA pages from DEV to PROD



Page 9 of 545

Slide 7


Important Terminology

• Installation

• Deployment

• Configuration

• Personalization

• Extension

• Customization

• Customizing

In any development, customization, extension, configuration, or installation process, there are a lot of words that can be used interchangeably, and are defined by the context of the speakers. This is fine for conversation, but it doesn’t allow the needed clarity for learning. For this course, there are six critically important terms that you must understand and use properly: installation, deployment, configuration, personalization, extension, and customization. Installation is the process of moving E-Business Suite from the distribution media (i.e., CD or DVD) to the host system. The complexity of the process and the tasks to complete the move are based on the operating system (i.e., Windows, Linux, etc.) of the host system. Installation is only the first step of bringing up a fully functional E-Business Suite instance. The software still needs to be configured to the specific needs of the business or business unit for which it is installed. The software may also need to be installed on multiple servers if a multi-node installation is desired. Deployment is the process of moving personalizations, extensions, or customizations from the development systems or servers to testing/production servers. Configuration is the process of setting the proper parameters and customer-specific information for a fully functional E-Business Suite instance. The requirements of configuration are set by each of the product teams. This is the most time consuming part of the process of bringing an E-Business Suite instance to full production. This process is not trivial, and will involve a multiple of subject matter experts covering the gamut of your business.



Page 10 of 545

Personalizations, Extensions and Customizations are all supported. But, it is critical to understand the scope and limitations of that support. Oracle supports the mechanics of each of these techniques. It also provides the tools for accomplishing such actions along with documentation on the tool. The implementation specifics for any given personalization, extension, or customization as required by a specific customer installation are not support beyond the mechanics, tools, and documentation support. Personalization is the process of making changes to the User Interface (UI) from within an E-Business Suite form/page. It is possible to make personalizations to both Forms-based and OA Framework-based pages. Extension is the process of making changes to the programmatic (i.e., PL/SQL or Java) elements of an E-Business Suite form/page. It is possible to extend both Forms-based and OA Framework-based pages. Customization is the process of creating new forms/pages. While Oracle does provide tools to do this (i.e., Oracle Forms and JDeveloper 10g with OA Extension), this is the least supported option. Customizing, a similar word to customization, is the totality of all the above processes. When you are done, and your E-Business Suite instance is running in production, you will have an instance that is customized to your business needs. And, you will have used several of the methods listed to accomplish your customized instance.



Page 11 of 545

Slide 8


Personalization vs. Extension

• Personalization – the ability to declaratively alter (in XML) the page’s UI to meet the business or user needs.

• Extension – the ability to programmatically (in Java) extend the page’s functionality.

From this page forward, we will discuss Personalizations and Extensions within the context of OA Framework pages and applications. While it is possible to personalize and extend Forms-based pages and applications, it is well beyond the scope of this course.



Page 12 of 545

Slide 9


So, What Is In This Course?

To fully customize the E-Business Suite, you will make use of all of these technologies:

1. Configuration

2. Personalization

3. Extension

4. Customization

Rule #1: Whenever you are faced with adapting the E-Business Suite to your business needs, choose the method that accomplished your needs, and err on the side of methods most likely to survive patches and upgrades.

In almost every adaptation you will make to your E-Business Suite instance, there are multiple choices for the method to use. It is strongly recommended that you look to implement your adaptation in the order listed above. Always choose configuration over any method. Configurations are most likely to survive patching and upgrades. If configurations do not survive patching or upgrades, no method below it would have survived. The evolutionary nature of E-Business Suite requires an open mind. E-Business Suite continues to add products and functionality that was not in previous releases. Functionality that might have even required customizations on your part to implement is often found in new releases. So, in those new releases, you will most likely find yourself with a difficult decision. Do you eliminate your customization in favor of the new functionality? Or, do you keep your customization, and deal with the challenges of patching and upgrades? There are no easy answers. If possible, for the long-term health of your E-Business Suite instance, it is better to move that functionality up the ladder.



Page 13 of 545

Slide 10


Architectural Components of OA Framework

• Written in Java

• Uses JDeveloper 10g with OA Extension

• Uses the following components

– Business Components for Java (BC4J)

– User Interface XML (UIX)

– Application Object Library for Java (AOL/J)

– OA Framework

– Metadata Services (MDS)

The smaller contributors are: • Caching Framework • Oracle JDBC 10g

To establish a common understanding, here are some basic definitions of the components:

• Business Components for Java (BC4J) is a component that meshes SQL database concepts like views, tables, and transactions into the Java world via View Objects (VOs), Entity Objects (EOs), and Application Modules (AMs).

• User Interface XML (UIX) is the component that allows creation of user interface (UI) objects through use of XML. This removes the need for the programmer to know various implementation details, like HTML or WML. At run-time, the generic XML can be transformed into the necessary output. UIX is also component-based, with each UI element defined as a JavaBean.

• Application Object Library for Java (AOL/J) provides a number of E-Business Suite specific services, especially security. This means that OA Framework pages implement that same user security model used in E-Business Suite.

• Metadata Services (MDS) is the delivery of XML on demand. OA Framework page, personalizations, and BC4J substitutions are not stored in the file system of the server. These XML components are stored and managed in MDS (tables in the database).

• HTML is hypertext markup language, and is a standard maintained by the World Wide Web Consortium (W3C) (http://www.w3.org). It is the language supported by browsers.



Page 14 of 545

• WML is wireless markup language, and is supported by most cell phones and other wireless devices.

• XML is extensible markup language, and is the generic standard underneath technologies like HTML and WML.



Page 15 of 545

Slide 11


Why Java?

• Object-oriented

• Platform independent (Write Once – Run Many)

• Network ready

• Secure

• Robust

• Industry-standard

• Open source

Java is a programming language that shares numerous features with other programming languages, especially C and C++. This means that programmers won’t have a difficult learning curve with Java. It is also an industry standard, not a proprietary development language like PL/SQL or Oracle Forms. Most of Java is now open source, and Oracle has contributed many components, as open source, to the Java community. Object-oriented programming allows us to create the highly sophisticated, distributed, networked applications that are in demand today. And it allows us to do so by implementing 3 common pillars, encapsulation, inheritance, and polymorphism. Java is robust in that it includes numerous compile-time and run-time checks to ensure that the programmer followed good programming habits. The most common practical application of this is in Java’s memory management. Java provides all the benefits of C and C++ programmer-defined data types, while avoiding the programming errors that are common within C and C++. Security within Java is built-in at its core. As such, applications created in Java can’t be invaded from outside. Finally, Java code is portable. Java code is compiled into an intermediate bytecode. That bytecode is distributed, and it is the responsibility of an individual JVM (Java Virtual Machine) to run that bytecode. Because JVMs exist for numerous platforms, the bytecode can run on each of those platforms without any programmer intervention.



Page 16 of 545



Page 17 of 545

Slide 12


Foundations of Java Programming

• Encapsulation

• Inheritance

• Polymorphism

Encapsulation Encapsulation in Java is essentially a shield around the object. That shield protects the object from other objects looking directly into its code. In practice, this means that if someone wants to use an object they communicate to that object via its methods. What encapsulation does is to hide the implementation from the client who interacts with the object via its interface. In theory, this should allow implementations to change without adversely affecting the client. Encapsulation also allows the building of modular systems without a lot of tightly coupled interdependencies. As an example, in a business application we might allow customers to place orders for books. The customer doesn’t care how we get them their book. They only care that they get it. Internally, we might have our own warehouse, or we might drop-ship directly from the printer. What we’ve done is “encapsulate” the delivery mechanism of the book from the customer.

Inheritance Inheritance is the ability to extend a class so the new class inherits the behavior and data of its parent while adding its own differentiating characteristics. Inheritance is often described as an "is-a" relationship. Subclasses (child classes) are specialized implementations of their more generic superclasses (parent classes). For example, assume you have a generic base class called Mammal with two subclasses: LandMammal and MarineMammal. You then subclass LandMammal to create the new class Cat, and subclass MarineMammal to create the new subclass Whale. A cat "is a" mammal the same way that a whale "is a"



Page 18 of 545

mammal (so they share many behaviors and characteristics), but they also have their own behaviors and characteristics: cats purr and whales swim.

Polymorphism In general terms, "polymorphism" refers to a component's ability to take on many forms. In the inheritance hierarchy described above, we have a Whale class that extends MarineMammal, which in turn extends Mammal. The single class -- Whale -- is capable of assuming three forms: Whale, MarineMammal and Mammal. Similarly, the Cat class is a Cat, a LandMammal and a Mammal. If you were to create an array of Mammals, for example, you could include both Cat and Whale objects since they are both Mammals. Now, taking this one step farther, you can also send the same message to these related classes that may result in distinctive class-specific behavior. Suppose we were to define an abstract method on our Mammal base class called move( ) ("abstract" means there is no implementation for this method at this level; the implementation must be supplied by a subclass). Then, we implement this method for our Mammal subclasses as appropriate: cats are quadrupeds that run, trot and walk while whales swim. Finally, we access the array of Mammals that we created above, and call the method move( ) on each object. This moves the animal from point A to point B using its species-specific method of locomotion.



Page 19 of 545

Slide 13


The Java Tech Stack for OA Framework

OA Framework

Java Core Spec.

J2SE API

J2EE API

MVC Design Pattern

All Java programs share a basic platform. Within Java development, we call these shared basics the core specification. Java itself is a compact programming language. It is the APIs that account for the seemingly endless list of objects and methods. While there are other APIs within Java, these are the ones that are critical to us.

• The Java 2 Platform, Standard Edition (J2SE) 1.4 API. (You can learn more about this at: http://java.sun.com/j2se/corejava/index.jsp)

• The Java 2 Platform, Enterprise Edition (J2EE) 1.4 API (You can learn more about this at: http://java.sun.com/j2ee/index.jsp)

It is outside the scope of this course to teach you the fundamentals of Java. If you need additional exposure to Java, the New to Java center (new2java) is a free resource available at: http://java.sun.com/learning/new2java/index.html Java development puts together the methods and instance variables provided in the core specification APIs into common formats called J2EE Design Patterns. Note: Design Patterns are not specific to the language (Java, for example) used to implement them. Design Patterns can be implemented in numerous programming languages, but for OA Framework we choose to implement them in Java, and the primary pattern we use is the Model-View-Controller (MVC) pattern. MVC will be discussed in more detail later in the course. Why patterns?

• Patterns work. Since the core requirement of any application is that it works, having a pattern to follow that already works is a tremendous boost.



Page 20 of 545

• Patterns are reusable. Templates decrease the time it takes to type in large quantities of code. At best, it will reduce errors and cut the time it takes to develop new applications.

• Patterns are shared. Java development patterns allow a common shared understanding amongst various developers.

For examples of design patterns, see the book: Design Patterns -- Elements of Reusable Object-Oriented Software by Gamma, Helm, Johnson, and Vlissides (Addison-Wesley, 1995) You may have heard of Java frameworks like Struts or JFC/Swing. In E-Business Suite, we use a framework called OA Framework. OA Framework is a Java framework that excels at creating 3-tier web-based applications that link to an E-Business Suite instance while maintaining all the security features of that instance. A framework is a specialized set of related classes designed to make application development easier. In effect, a framework implements part of an application so developers don't have to write all of the application code from scratch. Developers use the framework as the basis for their work, so they can focus on the additional code required to implement their specific application requirements. Frameworks can also cooperate. For example, the OA Framework cooperates with the UIX and BC4J frameworks to provide a rich, comprehensive foundation for building web-based applications. BC4J handles database interaction, UIX handles web beans and HTML rendering, and the OA Framework "glues" these technologies together into a seamless technology stack including application security, personalization support and other Oracle E-Business Suite features. Without these frameworks, a web application developer would have to implement all of this functionality in addition to her application's behavior. Not only do frameworks make development more efficient, but they also improve product quality. Each module is designed, developed and tested by developers with specific areas of expertise and focus.



Page 21 of 545

Slide 14


Oracle JDeveloper 10g

Development

UML

ADF

XML

Source control

Debug

Exchange

Database

HTML

Deployment

EJB

JSF

Integrated Development Environment The add-in API architecture of the Oracle JDeveloper integrated development environment (IDE) means that all the tool components (for example, navigator, editor, and modeler) share memory models and event systems. In this way, an update in one tool is communicated to another tool so that the latter can refresh its image or take other appropriate actions. In Oracle 10g, the JDeveloper IDE is developed in pure Java. Synchronization between model and code can be set so that you can decide to work using one or the other user interface. Customizable Environment You can customize the JDeveloper IDE and arrange its look to better suit your project needs and programming style. To suit the JDeveloper IDE to your individual taste, you can:

• Change its look and feel • Create and manipulate custom navigators • Customize the Component Palette • Customize the IDE environment • Select JDeveloper’s embedded Java EE server • Arrange the windows in the IDE



Page 22 of 545

Slide 15


Oracle JDeveloper 10g Components

Applications Navigatorand Structure window Property Inspector

Component Palette

Code Editor

Oracle JDeveloper 10g Environment Oracle JDeveloper 10g contains four major user interface components. These components are what you use to edit code, design and manage the user interface, and navigate your program. Component Palette The Component Palette displays the components available to build user interfaces, models, navigation diagrams, and so on. Applications Navigator and Structure window The Applications Navigator displays a list of files or classes in a project. The files may be Java source files, .class files, graphics files, HTML, XML documents, and so on. The associated Structure window shows the detailed structure of the object selected in the Navigator. Code Editor The Code (Design) Editor is where most of the work takes place; this is where you write code and design user interfaces. Open the editor by double-clicking the name of the file in the Navigator that you want to edit or view. The appropriate editor, code or design, will open based on your selection.



Page 23 of 545

Slide 16


What’s in BC4J?

• BC4J is the M (Model) layer of the MVC pattern.

• Includes the following basic BC4J components.

– Application Modules (AMs)

– Entity Objects (EOs)

– View Objects (VOs)

• Includes additional capabilities.

– Data binding

– AM pooling and session management

– Database transactions

Note: In many of the error messages generated by BC4J, you will see a reference to oracle.jbo…. Why? Originally, BC4J was named JBO (Java Business Objects). To maintain code, those APIs have not been refactored into a newer BC4J naming structure.



Page 24 of 545

Slide 17


What’s in UIX?

• UIX is part of the V (View) layer of the MVC pattern.

• UIX underlies the OA Framework UI components.

• Using both OA Framework and UIX allows OA Framework applications to have a consistent E-Business Suite look and feel.

• Includes specific simple and complex UI components, like the following:

– Fields

– Buttons

– Tables

– LOVs

– and others

UIX is an Oracle standard. But, it allows a migration path to future technologies. For example, Java Server Faces (JSF) was chosen and developed as the standard over UIX. So, Oracle has taken UIX, implemented it as a JSF Implementation Library, and open sourced the code. So, all the UI components migrate very easily to JSF.



Page 25 of 545

Slide 18


What’s in AOL/J?

• AOL/J is the layer that implements the common features expected in an E-Business Suite application, like the following:

– Function security

– Connection pooling

– Flexfields

– Profile options

– Hierarchies

– Online Help

– Encryption

– Thin Client Framework (TCF)

AOL/J is also responsible for managing and maintaining the application context (state) as you navigate within and on OA Framework pages. Note: The Thin Client Framework (TCF) was a means to allow an older, Oracle Forms-based interface to run newer java-based components from within the Oracle Forms UI.



Page 26 of 545

Slide 19


What’s in OA Framework?

• It is the programmatic ‘glue’ which integrates these technologies.

• It provides consistent UI components to E-Business Suite applications.

• Additionally, it provides methods for the following components:

– Personalizations

– Safe interfaces for access from both the Model (server) and View (user interface) code.

– Implementation of LAFs (Look and Feel)

– Final rendering

Note: In many of the error messages generated by OA Framework, you will see a reference to jrad…. Why? Originally, this UI-level was called Java Rapid Application Development (JRAD). To maintain code, those APIs have not been refactored into a newer naming structure.



Page 27 of 545

Slide 20


What’s in the Metadata Services?

• OA Framework encourages the use of declarative objects.

• The declarative objects are stored in XML.

• XML has the advantage over Java in that it does not need to be compiled to be used.

• XML has limitations, and Java code is still needed to overcome those limitations.

• OA Framework stores most of the XML in the database. That database is called, the metadata services (MDS), and includes the following objects:

– OA Framework Pages and Regions (PGs and RNs)

– Personalizations

– BC4J substitutions

In can not be over emphasized, unlike most objects in E-Business Suite, the OA Framework declarative components are retrieved from the MDS. Even though the XML files may exist in the EBS file system, those are not the objects that are being executed.



Page 28 of 545

Slide 21


What is the MVC Design Pattern?

Controller

Model View

The view formats and presents data from amodel to the user

The controller responds touser actions and directs

application flow

The model encapsulates underlying data and

business logic of the application

The term "view" has several meanings for Oracle-based applications (such as database view). In the case of the Model-View-Controller architecture, it helps to think of the view as the "end user's view of the data".



Page 29 of 545

Slide 22


Why Do We Use MVC?

• Model – Business logic encapsulated in Business Components for Java view objects and entity objects

• View – Common UIX-based HTML components used throughout Applications

• Controller – OA Controller responds to user actions, directs application flow

BC4J

UIX /OA Extension

OA Controller

• It provides a flexible architecture for applications that is more easily programmed and managed over the complete lifecycle.

It is also the most popular and consistently used pattern for this type of development. While not a standard, it is still widely used and adopted, and Oracle followed with its own implementation of this pattern.



Page 30 of 545

Slide 23


The OA Framework Architecture

Application Server Data Server

Browser

11i Data

Client

UIX

Se

rvle

tEn

gin

e

OA Controller

BC4J

OA Extension (MDS)

MetadataRepository

Listener

In OA Framework, there is often a discussion of Client-Server. If you see this, it is not the same as the older client-server computing with which you might be familiar. The UIX and OA Extension components, on the middle-tier, are referred to as the Client. The BC4J components, on the middle-tier, are referred to as the Server. The OA Controller spans the two components, and provides communication between them.



Page 31 of 545

Slide 24


Additional Resources

Further reading:

• OA Framework Developer's Guide: Anatomy of an OA Framework Page

• OA Framework Javadoc



Page 32 of 545

Slide 25


Summary

In this lesson, you should have learned how to:

• List the course objectives and agenda.

• Identify the architecture and components of OA Framework applications.



Page 33 of 545

Concepts of the MVC Design Pattern

2Copyright © 2007, Oracle. All rights reserved.


Concepts of the MVC Design Pattern



Page 34 of 545

Slide 2


Lesson Objectives


• Discuss the key concepts of an OA Framework page

• Discuss the runtime process of an OA Framework page

• Discuss how the MVC design pattern is used in OA Framework pages



Page 35 of 545

Slide 3


What is a JSP Page?

JSPs, or JavaServer Pages, is a technology to generate dynamic HTML pages. JSPs are text documents, similar to HTML. JSPs consist of a mix of HTML elements and special JSP elements.

Typical JSP programming is plagued by two significant drawbacks. One, the UI is only as good as the programmer’s ability to generate the proper HTML to generate that UI. Two, as a follow-on, making global changes to the UI via JSPs is difficult and labor-intensive. Example: In typical JSP programming, you might have a global footer that is included on each page. If that footer is changed, all the pages that reference that footer must be changed. Typically, there are no tools for doing this globally. Programmers must update each page manually. OA Framework JSPs differ substantially from this model. The major difference is the use of UIX JavaBeans to implement the UI. Instructor Note: There are products and product families (example: the majority of the CRM product family) that still use older JSP technology. Students will often, but wrongly, assume that the OA Framework course covers such materials. These types of pages are well beyond the scope of this course. Additionally, there is no Oracle University course that covers such pages. And, as of the writing of this note, there is no intent to add such a course.



Page 36 of 545

Slide 4


Key JSP Application Components

A typical JSP application involves the following components: a browser for client access, a database for enterprise data and a web application server ("middle-tier") where the application objects live.

• The browser communicates with the middle-tier using HTTP (Hyper Text Transfer Protocol), which involves sending a request message to which the middle-tier replies with a response message.

• A JSP is a file with some HTML and Java code that executes top to bottom. At runtime, it is compiled into a Java class that is actually a servlet.

• A servlet is a Java-based web application server extension program that implements a standard API.

• A servlet session is a mechanism for maintaining state between HTTP requests during a period of continuous interaction between a browser and a web application. A session may be initiated at any time by the application and terminated by the application, by the user closing the browser, or by a period of user inactivity. A session usually corresponds to an application login/logout cycle

• A JavaBean (or "bean" for short) is simply a reusable component that implements specific design patterns to make it easy for programmers and development tools to discover the object's properties and behavior.

• Any objects in the middle-tier that communicate with the database use a JDBC (Java Database Connectivity) driver.



Page 37 of 545

Slide 5


What Happens at Runtime?

• Step 1: Browser sends an HTTP request

– HTTP GET

– HTTP POST

• Step 2: Request routed to JSP by Application Server

• Step 3: JSP delegates to one or more JavaBeans.

• Step 4: Browser displays the HTML it receives.

Step 1 When the user selects a link, a button or an active image, the browser sends an HTTP request to the web application server for processing. For the purposes of this introduction, we will focus on the two primary HTTP request methods (POST and GET) that are relevant for an OA Framework application. HTTP GET Whenever the user clicks a link or an image with an associated URL (like http://www.yahoo.com) the browser submits a GET request. You can think of a GET as a postcard: both the address (URL) and any information the sender wants to convey (URL parameters) are written on the card itself (which is inherently space-constrained; how much can you write on a postcard?). This means that all the information for the communication is visible externally (and in an HTTP GET, all the data sent to the server is visible as parameters on the URL). HTTP POST Whenever the user clicks a button, image or link that performs a form submit in an OA Framework application (see What is a Form? below), the browser submits a POST request to the server (technically, a form can be submitted with a GET, but for the purposes of working with the OA Framework, you can assume a form submit is a POST). You can think of a POST as an envelope: the address (URL) is written on the outside, but the content within has the information the sender wants to convey. There's no limit to the amount of information that can be stored inside the envelope. Furthermore, the submitted data is not visible on the URL -- just as the



Page 38 of 545

contents of an envelope are not externally visible (although the metaphor isn't absolutely accurate: a developer could also add some parameters to the URL when doing a form submit). What is a "Form?" In simple terms, a "form" lets you collect data entered by users into "form fields," and send that data to the server for processing. A form is an HTML construct that groups data entry controls like fields (both hidden and visible), poplists and so on with action controls (like buttons) that are capable of "submitting the form." When the user selects a submit button, for example, the browser issues a POST request which sends the form's data to the server. Tip: People often use the terms "POST" and "submit form" interchangeably when talking about the OA Framework.

Step 2 The HTTP listener in the web application server routes the incoming request to the JSP. The developer's code does not know or care whether the browser issued a POST or a GET. All it does is read request values to determine what to do. So, for example, one of the request values might tell the JSP that a "Go" button had been pressed, which means it must execute a query.

Step 3 The JSP delegates to one or more JavaBeans that implement various behaviors including database interaction. Once they have completed their work, the JSP prepares the appropriate HTML content to send back to the browser in the response. Note: We included the JavaBeans in this example just to make the point that in an application of any complexity -- and modularity -- the JSP does not do the application work on its own since you should not combine model, view and controller code in the same file. However, there is no absolute technical requirement for the JSP to work with any other Java classes, and if it does, there is no requirement that these classes be JavaBeans.

Step 4 The browser displays the HTML it received in the response.



Page 39 of 545

Slide 6


What Happens from the Start?

While it may seem trivial, just seeing the Login page indicates a lot of very good information. If you see this page, it means the following:

• The database for your Applications instance is UP. • The TNS listener for your Applications instance is UP. • All of the critical Applications services, especially middle-tier services like

HTTP Listeners, OC4J Servers, and other processes are UP. • Most importantly, all of those processes listed above are properly

communicating with each other.



Page 40 of 545

Slide 7



Assuming you have correctly logged in to the Applications instance, a whole bunch of other things have now occurred. Those processes are as follows:

• When you logged in with your username and password, that username and password you entered was checked against valid users and passwords in the Applications instance. All of the communication of this sensitive data was encrypted. And, you would not see the Navigator (or Personal Home Page) if you did not enter a proper username and password.

• Once your username and password were checked and authorized, a SESSION was created for you in the database. And a special item, called a SESSION COOKIE, was passed to your browser. This SESSION and SESSION COOKIE combination ensure that you are who you say you are. Why is this important? It prohibits Applications users from cut-n-pasting URLs or bookmarking URLs to ensure proper security. From now on, every time you do something within Applications, the SESSION COOKIE on your browser will check itself against the SESSION in the database just to make sure your are secure.

• As an additional note on security, the SESSION and SESSION COOKIE have timeouts. What that means is that they are only valid for a specific period of time. In fact, there are two timeouts that should interest you. The first timeout controls how long you can remain IDLE. In other words, how long can you go between interactions with the server? This is important for performance of the servers, not security. The second timeout is a maximum limit, called a SESSION LIMIT. It simply says that after the session limit has expired (the



Page 41 of 545

default is 4 hours, but various systems can change this to longer or shorter periods of time), you MUST login again to the system. This timeout is important for security reasons.

• Now you see the Navigator (the Personal Home Page). What has happened to see this? The Application looked at the username you entered. And, it did the following:

• It read all the responsibilities that were assigned to your username. • For each responsibility, it looked at the Menu that was assigned to that

responsibility and any menu items that were specifically excluded from the menu assigned to you.

• For each menu, it read all of the individual submenus and functions that were assigned to that menu. A function is an individual Forms (traditional) page, a web-based (OA Framework) page, or a means of doing a security check (a securing function).

• After reading all of this data for your username, the Applications knows precisely what data and pages you can and can not see. In other words, it can enforce proper security to limit what you can do.

• Finally, now that it understands what you can and cannot do, it puts up a list of all the functionality to which you have access. The user, SYSADMIN, which is shown in the image above, has quite a broad range of functionality assigned to them.



Page 42 of 545

Slide 8



Let’s assume that you pick one of the items in the Navigator. In this example, assume you picked the System Administration responsibility. This responsibility has a complex menu made up of numerous submenus and individual pages.



Page 43 of 545

Slide 9



Some responsibilities have simple menus that include only one page. In this case, the example above assumes you selected the Functional Administrator responsibility. Whether the menu is simple or complex, the menu will eventually lead to an individual page.



Page 44 of 545

Slide 10



In some cases, the responsibility selected will utilize Oracle Forms-based pages. This is an older technology, and is beyond the scope of this course. It is also a technology that is being replaced with OA Framework-based pages.



Page 45 of 545

Slide 11



This is an OA Framework-based page. If you compare that with the Forms-based page on the previous slide, you will see that there are obvious visual differences in the two types of pages. While the visual differences are dramatic, the functionality that you can achieve with either is comparable.



Page 46 of 545

Slide 12


Behind the Scene

Just getting to the point that an OA Framework page is loaded and visible is a major accomplishment. The slides that follow outline what has occurred.



Page 47 of 545

Slide 13


Behind the Scene

• The user selected an item from the menu that pointed to a individual page to which that user was allowed to access. (Security first!)

• In the definition of that page (within Applications, this is called a Function), the function’s definition called a specific page (e.g., GrantSummaryPG)

• By default, OA Framework pages are named with PG on the end of the name. Sometimes individual objects on a page are used in multiple places, those items are called Regions and named (by default) with names ending in RN.



Page 48 of 545

Slide 14


Behind the Scene

• Application reads the definition for our page from the MDS (Metadata Service). The MDS is a set of tables in the database where XML-based items are kept. Pages (PG) and Regions (RN) are two common XML-based items.

• Application reads the personalizations from the MDS. Personalizations are XML-based entries stored in the MDS.

Personalizations add themselves like onion-layers to a page. The order in which those layers of personalization are applied is as follows:

• Base page • Function-level • Location-level • Site-level • Organization-level • Responsibility-level

Each progress layer up the hierarchy includes all the changes beneath it, plus any changes that it adds to the mix. Understanding this hierarchy is important to debugging unusual behavior.



Page 49 of 545

Slide 15


Behind the Scene

• After the page and all its personalizations is read from MDS, the AM (Application Module) of the page is determined.

• The AM is the means by which OA Framework pages retain a transaction, and by extension the connection to the database.

• If this page is part of a multi-page transaction, any AM for this page will be nested into an existing root AM.

• If this is a new part (not part of an existing transaction), the AM for this page will establish itself as the root AM.

• Root AMs maintain the transaction state and database connection for you page.

In order to read the AM, there are a couple of files the page will need to find. Those files will be stored on the server in a location referred to as $JAVA_TOP. In this case, the AM related files are:

• <AMName>AM.xml (this is the XML-based definition of the AM. While it is XML-based, it is not stored in the MDS.)

• <AMName>AMImpl.class (this is the Java-based programmatic capability of the AM. The XML-based capabilities are limited. In most cases, the needed capabilities of the AM have to be programmed in Java to accomplish their task.)



Page 50 of 545

Slide 16


Behind the Scene

• Once the AM is known, the AM knows all the View Objects (VOs) that are assigned to it.

• VOs are the mechanism by which data is queried from the database. A VO is essentially a SQL SELECT statement.

• Some pages will only need query (SELECT) capabilities, if so, there will likely be limited BC4J objects.

The VOs are, like the AM, stored in $JAVA_TOP. The VO related files are: • <VOName>VO.xml (this is the XML-based definition of the VO. While it is

XML-based, it is not stored in the MDS.) • <VOName>VOImpl.class (this is the Java-based programmatic capability of

the VO. The XML-based capabilities are limited. In most cases, the needed capabilities of the VO have to be programmed in Java to accomplish their task.)

• <VOName>VORowImpl.class (this is a pre-generated Java-based file. It needs to be present, but rarely, if ever, is anything actually done with this pre-generated file.)

There may be multiple VOs, each with their set of files. There are also view-level BC4J objects that may be referenced called View Links (VLs). VLs are the means by which VOs can be joined.



Page 51 of 545

Slide 17


Behind the Scene

• Some pages are more sophisticated that just query pages. These pages will actually be able to INSERT, UPDATE, and DELETE data from the database. In those cases, the VOs will know about the Entity Objects (EOs) they use.

• EOs are essentially BC4J representations of Tables in the database.

The EOs are stored in $JAVA_TOP. The EO related files are: • <EOName>EO.xml (this is the XML-based definition of the EO. While it is

XML-based, it is not stored in the MDS.) • <EOName>EOImpl.class (this is the Java-based programmatic capability of

the EO. The XML-based capabilities are limited. In most cases, the needed capabilities of the EO have to be programmed in Java to accomplish their task. Specifically, any data INSERTs, UPDATEs, DELETEs, or unique business logic validations (individual fields or multi-field) must be in this code.)

There may be multiple EOs, each with their set of files. There are also entity-level BC4J objects that may be referenced called Association Objects (AOs). AOs are the means by which EOs can be joined. There are also objects like Entity Experts, Validation AMs (VAMs), and Validation VOs (VVOs) to name some others.



Page 52 of 545

Slide 18


Behind the Scene

• Each time a new BC4J item is read, it is added to the root AM. Since the root AM is the transaction, it will ultimately be responsible for the commit or rollback of any data from the user’s interaction with the page.

There is a much more in-depth discussion on the details of page processing later in the course. Additionally, a detailed discussion of State Management (i.e., the overall management of the transaction) also occurs later.



Page 53 of 545

Slide 19


Behind the Scene

• Looking at the individual page, the Controllers (COs) are read.

• Some pages are simple enough that no controllers are needed. Most of these are query-only pages.

• Some pages, and their associated regions, have multiple controllers defined.

The COs are, like the AM, stored in $JAVA_TOP. The CO related file is: <COName>CO.class (this is the Java-based programmatic capability of the CO. For controllers, there is no XML-based definition. Any UI-capabilities beyond the things accomplishable by the Pages themselves will require the CO to accomplish the task. The most common such tasks are:)

• Generation of dynamic UI items (like dynamic window-titles). • Initiating data queries. • Responses to button-clicks and icon-clicks by the user. • Note: There are two methods in the CO. One method is run when the page is

loading (processRequest()). The other method is run when the page is responding to an event (processFormRequest()).

There may be multiple COs, each with a class file. While discussed in this course, COs are not extensible objects within OA Framework pages. Any deeper discussion of COs is beyond the scope of this course.



Page 54 of 545

Slide 20


Behind the Scene

• Any data needed by the page is associated to the individual UI objects.

• And finally, with everything for this page having been instantiated, run, and bound, the page is displayed … ALMOST …

• The individual UI objects are just that, generic objects. Those objects generate code that must be rendered to its final state. In most cases, this state is HTML and Javascript sent to a web browser. But, it could also be WML sent to a PDA or SmartPhone, and other special cases.



Page 55 of 545

Slide 21


Behind the Scene

• The following is a page without data associated with it:



Page 56 of 545

Slide 22


Behind the Scene

• The following is a page with data associated with it :



Page 57 of 545

Slide 23


Logical Components of an OA Framework Page

• The UI components that the user sees: Most of those objects are defined declaratively via XML, but some of them are programmatically defined via Java.

• The database components, the transaction, and the connections to database resources

• The event handling that responds to the user’s interactions on the page

Event Handling: In traditional client/server applications, you have the option of handling events ranging in granularity from very low-level mouse movements to field, region and finally, window-level scope. Furthermore, when you communicate from the client to the server, you can send a single value to be validated back to the server while expecting a single validation result back. You can then modify the user interface accordingly, which allows for a highly interactive experience for the user. In a web application, you essentially handle "page-level" events (unless you are using JavaScript extensively to create a more interactive experience, and since the OA Framework Coding Standards and Oracle Browser Look and Feel (BLAF) UI Guidelines prohibit this, we will not consider it here). In this case, as users navigate from field to field and enter data, there are no events for you as a developer to handle. When the browser finally sends a request as described above, all the page data is sent in that single communication -- including any user-entered values and information about what actions the user wants to perform. The developer reads request values to determine what happened (if the user pressed a button, which one was it?), does whatever work is required by the selected action, and then transmits a new HTML page back to the browser.



Page 58 of 545

Slide 24


What is the MVC Design Pattern?

Controller

Model View

The view formats and presents data from amodel to the user

The controller responds touser actions and directs

application flow

The model encapsulates underlying data and

business logic of the application

The term "view" has several meanings for Oracle-based applications (such as database view). In the case of the Model-View-Controller architecture, it helps to think of the view as the "end user's view of the data".



Page 59 of 545

Slide 25


Model: Business Components for Java

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

In general, the following definitions are useful as quick references to BC4J components.

• The AM is the transaction container. • EOs are the tables and the business rules. • VOs are the queries / SELECT statements.



Page 60 of 545

Slide 26


Model: 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

An AM must explicitly contain a VO. But, EOs and other objects are indirectly contained in the AM via their association to the VO and the objects the VO needs.



Page 61 of 545

Slide 27


Model: 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

There should be one EO per table, and that EO should be the means by which all business rules are implemented on that table.



Page 62 of 545

Slide 28


Model: View Objects

View Objects

• Encapsulate a database query

• Provide iteration over the query result set

• Primarily based on Eos.

• May be based on plain SQL for certain types of tasks

• 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

Here is a quick rule to remember. While code reuse for most objects is a desirable trait. It is far more important for VOs to run quickly and minimize their memory impact to the middle-tier. So, in general, you should develop specific VOs for specific needs, and avoid VO reuse.



Page 63 of 545

Slide 29


View: OA Framework-Based Page



Page 64 of 545

Slide 30


View: Java Objects in a Page

• Each UI widget corresponds to one or more Java objects (beans)

• The Java objects are assembled declaratively with the Oracle 10g JDeveloper OA Extension tool

– The Java beans are defined hierarchically

• The Java objects are used to create HTML at runtime

By referring to UI objects, instead of the code to create those UI objects, the UI objects can change in their underlying implementation without requiring changes to multiple pages of OA Framework code.



Page 65 of 545

Slide 31


View: A Framework Example

Table Bean

Header Bean

Submit Button Bean

Corporate and Product Branding Named Children

These are just examples of some of the JavaBeans that construct the UI for this page.



Page 66 of 545

Slide 32


View: Page Hierarchy

Unlike the previous pages, this page shows the UI from within JDeveloper. OA Framework pages use a hierarchical layout. The order in which an object appears in the hierarchy is the order in which it appears on the page.



Page 67 of 545

Slide 33


Controller: Controlling UI Behavior

• Controller classes define how your Java Beans behave.

• You can override controller classes to:

– Manipulate the UI at runtime

– Manually initialize data items

– Intercept and handle user events like button clicks

• Controller classes subclass OAControllerImpl.

• OAPageBean is the main OA Framework page processing class.

• There are methods in the Controller class to handle GET and POST requests.

In general, a controller does two things. • Responds to the drawing of the page (GET). • Responds to events (like button clicks) on the page (POST).



Page 68 of 545

Slide 34


Summary


• Discuss the key concepts of an OA Framework page.

• Discuss the runtime process of an OA Framework page.

• Discuss how the MVC design pattern is used in OA Framework pages.



Page 69 of 545

Basics of the Model



Basics of the Model

As you talk about each of the BC4J objects (EO, AO, VO, VL, and AM), you are encouraged (time permitting) to demonstrate the creation of one of each of those objects using the BC4J wizards in JDeveloper. If you don’t have time, this is one of the areas you can squeeze for time. Without the guided demonstration, you can easily save 30 minutes or more. There is no specific guided demo that has been created for this purpose. If you need a specific demonstration, the first lab, Query Page, creates most of the BC4J objects, and can be used for the purpose of this demo.



Page 70 of 545

Slide 2


Lesson Objectives


• Discuss BC4J and the Model layer of MVC

• Discuss Application Modules (AMs)

• Discuss Entity Objects (EOs)

• Discuss View Objects (VOs)

• Discuss how BC4J interacts with the database

• Discuss other Model-layer components



Page 71 of 545

Slide 3


Model-layer BC4J Objects

Remember two things: • The Root AM is just the first AM for a page. It contains the transaction and all

the connection objects. • The Root AM explicitly contains the VOs. All other objects are contained via

their association to the VOs.



Page 72 of 545

Slide 4


EncapsulationThe “Reuse Onion”

• Each layer only “knows” about the layers below it.

• This encapsulation promotes easier reuse of components.

'Client' / 'Server' Code Separation Within the Model-View-Controller architecture, OA Framework draws a clear distinction between client and server classes, a distinction that on the surface may seem to conflict with JSP application architecture. A typical JSP application has 3 physical tiers:

• The browser (the client where our HTML renders and users interact with the UI)

• The web application server (the middle tier where our UI web bean hierarchy is constructed and our application business logic executes)

• The database server Within the middle tier, OA Framework draws a further distinction between client and server classes as follows:

• Client classes (View and Controller code) drive the HTML user interface • Server classes (Model code) supports any client (not just OA Framework)

user interfaces This distinction is important because it preserves the ability to use server code with different clients.



Page 73 of 545

Slide 5


General Reuse Rules

• Model code should never reference controller code directly.

• Never reference/import any server-side implementation classes or interfaces on the client-side.

• If you need the server code to do work for you, always route your call through the root application module.

• Never include JDBC or other server-side processing directly in your client-side code.

Note about JDBC: It is not recommended or supported to included JDBC calls in OA Framework because of connection pooling. BC4J, through the Root AM, pools its connections to the database, and manages those connections to provide consistent performance on the middle tier. If you call JDBC directly, your code can cause memory and connection leaks, which will ultimately produce bad performance and server crashes. JDBC is the Java Database Connectivity API. It is a J2EE API that provides a way for Java programs to access one or more sources of data.



Page 74 of 545

Slide 6


Recommended Build Approach

1. Create any business components packages that you need for your BC4J model objects.

2. Implement declarative BC4J application modules, entity objects, view objects and others as needed for your page(s). Add view objects to your root application module(s) as appropriate.

3. Create the menu definition for your application.

4. Create the OA user interface components for your page(s).

5. Create and implement controller code.

6. Implement UI application module code supporting your pages.

7. Implement entity object business logic.

Steps 1, 2, 6, and 7 are the steps that deal directly with Model layer components.



Page 75 of 545

Slide 7


Business Component (BC4J) Packages

• While not formally a BC4J component, every BC4J component must belong to a BC4J package.

• BC4J packages contain the following:

– The naming/pathing structure for the BC4J components it stores.

– The database connection associated to the package for your development environment.

– Is mostly used for showing the relationship amongst related BC4J components by storing related components together, and then using a standardized naming structure to highlight the relationship.

The JDeveloper 10g process changed from the JDeveloper 9i process. In 9i, you explicitly created BC4J packages. In 10g, BC4J packages are create inherently from the BC4J object creation.



Page 76 of 545

Slide 8


BC4J Package Naming Standards

BC4J packages also correspond to directory paths.

• 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

Naming Standards are not enforced on customers. These standards are simply what Oracle uses. Like any standards, they evolve over time. If you encounter objects that don’t adhere to any given naming standard, chances are those are older objects adhering to an older naming standard that is no longer used.



Page 77 of 545

Slide 9


Application Modules

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

• Handles transactions

• Interacts with clients



Page 78 of 545

Slide 10


Application Modules

• 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.

AMs communicate with Controllers and VOs.



Page 79 of 545

Slide 11


Application Modules

• 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

Transactions then get connections from a connection pool, and those connections are reused and recycled to increase performance and reduce resource requirements on the middle tier.



Page 80 of 545

Slide 12


Transaction Object

• Holds Database Connections

• Holds all Entities centrally, separate from Application Modules and View Objects

• Holds list of EOs that require:

– Validation

– Posting to database

– Commit notification

While the AM holds all the EOs, the EO and EO-related objects are not explicitly declared as belonging to the AM, unlike VOs that are explicitly declared.



Page 81 of 545

Slide 13


Application Module Files

Each AM should have:

• <YourName>AM.xml

– Declarative information about AM

• <YourName>AMImpl.java

– Add methods to invoke assign VO’s initQuery methods if needed

Most BC4J objects follow this format, a declarative (XML) component with a programmatic (Java) component. It is worth stating that the XML component for BC4J objects is not stored in the MDS.



Page 82 of 545

Slide 14


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

The general rule is one EO per table. Although in some cases, one EO may represent several tables. But, those are unusual circumstances.



Page 83 of 545

Slide 15


Entity Objects

• Central point for business logic and validation related to a table

• Encapsulates attribute-level and entity-level validation logic

• Can contain custom business methods

No Oracle created object will contain custom methods. And, the preferred method of implementing custom methods is to extend an EO.



Page 84 of 545

Slide 16


Entity Object Creation Standards

• Include all table columns in the EO.

• Base your EOs on the _ALL tables rather than on organization-restricted views.

• Always generate accessors (setters/getters).

– Speeds up performance in attribute lookups because you can use named accessors

Why all columns? Simply because you only want one EO per table.



Page 85 of 545

Slide 17


Entity Object Automatic Features

• Validation, locking and posting order of children

– Handled by Composite Associations

• Who Columns (Record History)

– Set automatically during EO create() or doDML()

– EO should have following attributes:

— CreationDate

— CreatedBy

— LastUpdateDate

— LastUpdatedBy

— LastUpdateLogin

Composite associations control when validation business logic (declarative validation or program code in the entity objects) fires for the parent as opposed to the child.



Page 86 of 545

Slide 18


Entity Object Files

Each EO should have:

• <YourName>EO.xml

– Declarative information about EO

• <YourName>EOImpl.java (optional)

– Add create(), remove(), validateEntity(), and setter methods.




Page 87 of 545

Slide 19


View Objects

• Represent a query result.

• Are used for joining, filtering, projecting, and sorting your business data.

• Can be based on any number of entity objects.

• Can also be constructed from a SQL statement.

It is an oversimplification to state that a VO is a SELECT statement. A VO is an object. The object represents both the data (the SELECT), and the operations (methods) you can perform on that data (gets/sets/validations). Most VOs are defined declaratively, but there are even methods to programmatically create and alter VOs at run-time.



Page 88 of 545

Slide 20


View Objects

View Object is designed to:

• Manage collection of data

– Main collection interface into the database data

• Provide view-like shaping of data

– Leverage SQL to join tables and corresponding EOs

The VO allows us to do the action most often performed, a query, without the overhead of a full EO. This significantly increases the performance of OA Framework pages.



Page 89 of 545

Slide 21


View Objects

A View Object should:

• Always delegate to other objects such as the EO or PL/SQL for business logic

– ensures better reuse of business logic

• Contain only the attributes required for a specific purpose

– Do not select more attributes (columns) than required for a page/transaction UI

– View objects should be considered specific to a particular UI and are not expected to be reused

You should never put business logic in your view object.



Page 90 of 545

Slide 22


View Object Creation Methods

View Object can be created in one of three ways, based on:

• Generated SQL based on EOs

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

• ‘Expert Mode’ custom SQL with no underlying EOs

– Read-only Data

• ‘Expert Mode’ custom SQL manually mapped to EOs



Page 91 of 545

Slide 23


ExpertMode View Objects

Use ExpertMode custom SQL, manually mapped to EOs, for:

• Unions

• Complex SQL

• SQL is encapsulated within an inner view to support additional View Link bindings: ‘select * from (your-sql-here)’



Page 92 of 545

Slide 24


View Objects with Entity Objects

• VO can be mapped to multiple

– Updateable EOs, though often just the primary EO

– Reference EOs, used for additional ‘joined’ data including description lookups

EOs are the objects through which we insert, update, and delete data. VOs are the objects through which we query (select) data. This causes a natural disconnect of sorts. If you have a VO based on an EO, what is that VO capable of doing? A VO mapped to updateable EOs allows the actions on the EO to occur through the VO. VOs mapped to reference EOs are using those EOs just for query purposes, generally a foreign key of some sort.



Page 93 of 545

Slide 25


View Object Rows

• A view object controls many view rows.

• Each view row represents a row of the data that is queried from the database.

• An entity object gets instantiated for each view row.

Unlike the SELECT statement itself, VOs have a means by which to iterate through each returned row. But, there are performance implications, and your VO should be as precise as possible to return the fewest number of records. And, you should consider a limit beyond which you VO should not return any additional rows. The default in OA Framework is 200 records. This default behavior is controlled by a profile option, FND: View Object Max Fetch Size (VO_MAX_FETCH_SIZE). Changing this profile option should not be done lightly. If this value is increased, it will increase the memory requirements of the JVMs running on the middle tier, and it will impact the performance of the servers. The business requirements of your application may require you to increase the value. But, be aware of the consequences.



Page 94 of 545

Slide 26


Creating View Objects

• When you want aliases in the query, make sure that the attribute settings in the VO wizard include the alias names.

• When you create or modify an "Expert mode" VO using the View Object wizard, be careful to make sure that the attribute mappings match the expressions in the query.

Note: Also be aware that if you create a query in Expert Mode, and then toggle out of Expert Mode, all of your SQL changes are lost.



Page 95 of 545

Slide 27


View Object Java Files

• Create VO Java class (VOImpl) if needed

– VOs should not contain business or validation logic, except transient attribute logic

• Always create View Row Java class (ViewRowImpl) and accessors (setters/getters)

The ViewRowImpl class should always be created for two reasons. One, it is the iterator that allows you to step through the individual rows of the VO. Two, it generates the get/set methods for the VO. Merely creating the get/set methods doesn’t gain anything, but it does allow others to extend those methods should the need arise. Note: On this same page of the wizard, there is an Object Definition class (ViewObjDefImpl) that can also be selected (created). What is this? An Object Definition class allows for the run-time creation of the definition of a VO object. If this sounds indirect, it is. While it preserves a pure object-oriented model, it doesn’t perform or scale properly. These objects are not used in OA Framework pages. Even in non-OA Framework pages, they are seldom used because of their poor performance characteristics.



Page 96 of 545

Slide 28


View Object Files

Each VO should have:

• <YourName>VO.xml

– Declarative information about VO

• <YourName>VOImpl.java (optional)

– Add initQuery method if needed

• <YourName>ViewRowImpl.java (required)

– Contains accessors (setters and getters) for VO attributes

– Behind the scenes, these accessors call corresponding methods in your EOImpl.java




Page 97 of 545

Slide 29


Read-only Queries

Entity objects are not required for read-only queries. So, BC4J breaks the Entity encapsulation for View Objects. This is done for significant performance improvement reasons. Note: While the diagram shows one row, one VO can potentially fetch multiple rows during its query. Note: The difference between a read-only query and an initial query is nothing at this point. Underlying the process is the definition of the VO. If the VO has no associated EO, it is read-only. If the VO has been defined with an associated EO, then the first step is an initial query.



Page 98 of 545

Slide 30


Step 1: Initial Query

Note: The difference between a read-only query and an initial query is nothing at this point. Underlying the process is the definition of the VO. If the VO has no associated EO, it is read-only. If the VO has been defined with an associated EO, then the first step is an initial query.



Page 99 of 545

Slide 31


Step 2: Entity Object Population

Requisition Supplier

Entity

ViewObjectRow

Database

ReqIdPK4534

Number

123

SupplierIdFK456

CalcField1Entity-Derived

SupplierIdPK456

SupplierNum

1234

ClosedCode

MiscField1

MiscField2

ReqIdPK

Number SupplierIdFK

SupplierIdPK

SupplierNum CalcField2SQL-Derived

"CalcValue2"


Query data is used to instantiateand partially populate Entities

The query can bring back many view object rows (the result set or row set) in a single fetch from the database. Each view object row corresponds to an entity object (entity object instance). If the view object is based on an entity object, entity objects are found or instantiated by primary key (PK) for each VO row. No data is preserved in the VO-layer except for those columns that are SQL-derived or transient, because those objects are only found in the SELECT and/or VO definition.



Page 100 of 545

Slide 32


Step 3: Entity Object Reuse

RequisitionRequisition Supplier

Entity

2ndViewObjectRow

Database

ReqIdPK4554

Number

124

SupplierIdFK456


SupplierIdPK456

SupplierNum

1234

ClosedCode

MiscField1

MiscField2

ReqIdPK

SupplierIdFK

SupplierIdPK

SupplierNum CalcField2SQL-Derived"COMP"

CalcField2SQL-Derived

"CalcValue2"

Number CalcField1Entity-DerivedCalcField1

Entity-DerivedReqId

PKNumber SupplierId

FKSupplierId

PKSupplierNum

VO reuses sameSupplier EO for 2nd Row

The 2nd VO Row uses less memory since it references and reuses the same Supplier EO



Page 101 of 545

Slide 33


Step 4: Entity-derived Attributes

Entity-Derived attributes are useful for calculations owned by the Entity and shared by multiple VOs. But, entity-derived attributes are only calculated when demanded. When is that? When the VO attempts to bind the entity-derived attribute into the UI for rendering to the browser.



Page 102 of 545

Slide 34


Step 5: Entity Object Fault-in

Missing attributes are faulted-in on demand during EO validation.



Page 103 of 545

Slide 35


Step 6: Entity Object References

Here is the scenario. Assume you have an Association Object that connects the two Entity Objects. Initially, the VO queries the data, transfers it to the EO. Then, during interaction with the end-user, they assign a different SupplierId. This requires that a new Entity Object row in the cache that currently is not there. In these scenarios, the VO marks all reference EO (Supplier) attributes as read-only. And, you cannot change the primary key of the reference EO. You must change the foreign key attributes, which will result in the fault-in of the EO-layer data from the database.



Page 104 of 545

Slide 36


Requisition

Entity

Database

ReqIdPK4534

Number

123

Description

"NewDesc"

ClosedCode

"OPEN"

Modified entity already exists intransaction cache. Attribute is

marked as dirty

EO/VO Merge

An EO/VO merge occurs whenever an EO already exists in memory, containing original or modified values, and a new VO is queried containing data for the EO. The EO is the transaction cache, and the values need to be resolved before the VO can properly bind the correct value to the UI.



Page 105 of 545

Slide 37


Step 1: EO/VO Merge Resolution


Entity

ViewObjectRow

Database

ReqIdPK4534

Number

123

SupplierIdFK456

Description

"NewDesc"

SupplierIdPK456

SupplierNum

1234

ClosedCode

"OPEN"

MiscField1

MiscField2

Query brings in older values that don'tmatch new EO attributes

ReqIdPK4534

Number

123

SupplierIdFK456

SupplierIdPK456

SupplierNum

1234

Description

"OldDesc"

ClosedCode

"OPEN"

Note: Other users do not see the changed value until it is saved to the database. The EO/VO merge only applies to data within that user’s current session.



Page 106 of 545

Slide 38


Step 2: EO/VO Merge Resolution


Entity

ViewObjectRow

Database

ReqIdPK4534

Number

123

SupplierIdFK456

Description

"NewDesc"

SupplierIdPK456

SupplierNum

1234

ClosedCode

"OPEN"

MiscField1

MiscField2

Original Attribute values are notmerged with EO

ReqIdPK

Number SupplierIdFK

SupplierIdPK

SupplierNumDescription ClosedCode

VO will display new EO values"OldDesc"

After query and the EO/VO merge, the VO will then bind the correct value to the UI during rendering.



Page 107 of 545

Slide 39


Other Model-layer Objects

• Association Objects (AOs)

• View Links (VLs)

• Entity Experts

• Validation Application Modules (VAMs)

• Validation View Objects (VVOs)

We will cover Association Objects (AOs) and View Links (VL) in this lesson. Entity Experts, Validation Application Modules (VAMs), and Validation View Objects (VVOs) will be defined later in the course. At this point, it is sufficient to simply know that these objects exist.



Page 108 of 545

Slide 40


Association Objects

• 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

Source Destination

OrdersByAO

AssociationCustomerEO OrderEO

Association Objects are the way to implement foreign keys at the EO-layer.



Page 109 of 545

Slide 41


Association Objects

• Two types of Association Objects

– Reference

– Composition

• Both types can be referenced via ‘association attributes’ on Entity.

Composition - A strong association where the source entity object owns the destination entity object. In other words, the destination cannot exist independent of its source. For example, a purchase order header is comprised of purchase order lines, which have no meaning or life span outside the context of their header. Reference - A weak association where the source entity object only references the destination entity object. For example, a purchase order header references a supplier, but the supplier can still exist regardless of whether a purchase order references it or not.



Page 110 of 545

Slide 42


Reference Association Objects

Reference Association

• Used for weak associations between Entities, such as foreign keys for lookups

• No special runtime behavior

• Example: Requisition - Supplier association

This is the default behavior for AOs.



Page 111 of 545

Slide 43


Composition Association Objects

Composition Association

• Used for composite objects with strong "owning" relationship

– Use if: child entity cannot exist without parent; child is deleted when parent is deleted

– Example: RequisitionHeader - RequisitionLine association

• Create by checking the Composition check box in the BC4J association wizard

This has to be specifically indicated in the EO.



Page 112 of 545

Slide 44


Composition Association Object Behavior

Behavior of Composition Association

• When child is dirtied, parent is dirtied automatically

• When child is locked, parent is locked first automatically

• Parent is brought into memory automatically if not already in memory

• Validation order is child first, parent second - parent has final veto power on child modifications

• Insert/Update order is parent first, child second

• Delete order is child first, parent second



Page 113 of 545

Slide 45


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

Source view object

Destination view object

Order4ItemVL

Link

InvItemVO LineItemVO

Note: While it is possible to create View Links (VLs), they are seldom-used objects. Why? If you application is doing any data manipulation, you will be using Association Objects (AOs) instead of VLs. If you are doing read-only, it is far easier to either put the join into the SELECT statement that defines the VO. Or, create a database view that has your join, and base you VO on that database view.



Page 114 of 545

Slide 46


View Links

Use a View Link to create a Master-Detail relationship between view objects.

• Allows dynamic synchronization between parent and child VO

• Child rowset is refreshed when the current parent row changes

View Links Use view links sparingly. See the OA Framework Developer's Guide for more information.



Page 115 of 545

Slide 47


Entity Experts

Simple common code or, more commonly, validation routines that can be called by other EOs that avoids the overhead of instantiating an entire EO.

The entity expert is a singleton defined to be a special affiliate of a business object (either the top entity object in a composition, or a standalone entity object). It includes common code called by the owning business object, or simple validation routines called by other entity objects that don't want the cost of instantiating the entity object itself. For example, a PurchaseOrderHeaderEOImpl class doesn't want to instantiate a whole SupplierEOImpl class just to find out if the supplierId foreign key it's about to set is valid. Instead, it calls an isSupplierIdValue(Number supplierId) method on the supplier's entity expert singleton -- a much lighter weight operation.



Page 116 of 545

Slide 48


Validation AMs and Validation VOs

• Validation VOs (VVOs): Allows simple SQL statements to be executed at the entity-layer. Most commonly, these are SELECT statements done to validate data.

• Validation AMs (VAMs): VOs must be contained within AMs. VAMs are the containers for VVOs.

When you implement business logic in your entity objects, you will frequently find that you need to execute some simple SQL statements, and not just for pure validation purposes. For example, a purchase order header has many lines. Each line is assigned a unique line number. This number is defined as the current maximum line number for the entire purchase order + 1. At runtime, we need to query the database to find out what the maximum line number is for a given purchase order header:

SELECT MAX(LINE_NUMBER) FROM FWK_TBX_PO_LINES WHERE

HEADER_ID = :1;

Whenever you need to execute SQL like this, you can create a view object dynamically from a SQL statement, or you can predefine a declarative view object for it. That being said, OA Framework Coding Standards require that you use the declarative strategy in this case since it is more performant: a view object is cached in its respective application module, which allows entity object code to reuse it (and the underlying JDBC prepared statement) by simply rebinding and re-execute the query. This is an important performance benefit since validation routines are called repeatedly. Predefined view objects must be assigned to an application module so that they can be accessed at runtime. In other words, view objects do not exist outside the context of an application module. Since entity objects (and their associated validation view objects) can be shared by multiple UI clients (and the root application modules should be considered UI-specific), it is not appropriate to use the root application module for a particular



Page 117 of 545

page to hold your validation view objects. Instead, to group these utility view objects into meaningful, reusable units, create a validation application module per business object to hold them. A business object is defined the top-level entity object in a composition, or a single entity object if it stands alone.



Page 118 of 545

Slide 49


Summary


• Discuss BC4J and the Model layer of MVC.

• Discuss Application Modules (AMs).

• Discuss Entity Objects (EOs).

• Discuss View Objects (VOs).

• Discuss how BC4J interacts with the database.

• Discuss other Model-layer components.



Page 119 of 545

Basics of the View



Basics of the View



Page 120 of 545

Slide 2


Lesson Objectives


• Use the proper terminology when discussing OA Framework UI (View-layer) objects

• Discuss pages

• Discuss regions

• Discuss items

• Discuss attribute sets

• Discuss CSS styles

• Discuss other View-layer objects

• Discuss View-layer read and write data binding

• Identify and use View-layer naming standards



Page 121 of 545

Slide 3










Steps 4 deals directly with View layer components.



Page 122 of 545

Slide 4


View-layer Terminology

• Property – anything shown in the property inspector.

• Attribute – an XML attribute in the UIX file. Roughly equivalent to a column in a View Object.

• BLAF – Oracle’s Browser Look-and-Feel UI guidelines (available at: http://otn.oracle.com/tech/blaf/)

• Page – the basic UI component created in OA Framework, and referenced by E-Business Suite function security.

• Region – a portion of a page that can either be unique to the page, or reused (extended) from a previously build region.

• Attribute set – a named set of properties applied to configure an item.

Be careful with terminology, and always try to understand the context. As an example, a property in one context may or may not mean the same thing as a property in a differing context.



Page 123 of 545

Slide 5


View-layer Terminology

• 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

• Admin Personalization – indicates whether the item or region is system administrator personalizable

• User Personalization – indicates whether the query region is user level personalizable

• SPEL – Simplest Possible Expression Language

Simplest Possible Expression Language (SPEL) For selected properties, the OA Framework supports the use of SPEL expressions to quickly bind the property to an underlying data source that provides the property's value. For example, you could bind the Rendered property of a button to a view object attribute to ascertain whether it should be hidden or shown when the page renders. The SPEL syntax for this property looks like:

${oa.<ViewInstanceName>.<ViewAttributeName>}

${oa.FunctionSecurity.<FunctionName>}

Note: SPEL is defined in JSR-52, which is maintained by the JCP (Java Community Process). You can download more information on SPEL, and the types of expressions possible in SPEL at: http://jcp.org/aboutJava/communityprocess/final/jsr052/index2.html



Page 124 of 545

Slide 6


Workspaces and Projects

While not specifically an View-layer component, workspaces and projects are essential components of OA Framework development. Workspaces and Projects are containers that hold objects together for development purposes. You do not deploy workspaces and projects to a running E-Business Suite instance.

However, be careful to choose “Workspace Configured for Oracle Applications” and “Project Configured for Oracle Applications” rather than generic workspaces and projects.

Only OA projects allow you to create pages, regions, and attribute sets. And, only OA projects capture E-Business Suite related information such as run options and OA Framework connection information.

Workspaces and Projects are just containers for JDeveloper, and are not needed to run OA Framework pages.



Page 125 of 545

Slide 7


Step 1: Create a Page

(Menu) File > New > Web Tier > OA Components > Page



Page 126 of 545

Slide 8


Step 2: Name Your New Page

By E-Business Suite Development standards, all pages end in PG. While not mandatory for your pages, it is strongly recommended that you follow all of the E-Business Suite Development naming standards to ensure interoperability and maintainability of your pages.



Page 127 of 545

Slide 9


Step 3: View Page’s Initial Structure

The structure is shown in the Structure panel within JDeveloper. By default, the Structure panel is in the lower-left corner of the JDeveloper window.



Page 128 of 545

Slide 10


Step 4: Modify the Page’s Structure

By E-Business Suite Development standards, the first region, initially named region1, should be modified to set its properties as follows:

• ID must be PageLayoutRN. (This is an E-Business Suite Development naming standard.)

• Region Style must be pageLayout. • The pageLayout region must be the first region of a page. (The page is

created by default to adhere to this.) • AM Definition must be set to a defined AM. • Window Title must be set. • Title must be set. • Autofooter must be set to True. • Form must be set to True.

Note: Both XML and Java are case-sensitive.



Page 129 of 545

Slide 11


Running the New Page

Notice that with essentially nothing more than a blank page, you already have something that looks like an OA Framework page in an E-Business Suite instance. How? Since OA Framework is built in Java, and one of Java’s core principles is inheritance, the objects that you create already get certain added components. For example, in the page, note the following:

• The page has the R12 look and feel, especially the color scheme. • There is a corporate branding image, the Oracle logo in the upper left. • There is a header line with options, Home, Logout, and Preferences. • There is a footer link with options, Home, Logout, and Preferences. • There is a Privacy Statement link. • There is a Copyright statement

All of these come not from something you specifically did, but through inheritance.



Page 130 of 545

Slide 12


What Can You Add to the Page?

You can add the following to an OA Framework page:

• Regions

• Items

• Shared Regions

You should also know the difference between Named and Indexed children.

A Shared Region is simply a region with the Extends property set to the name of the Shared Region object.



Page 131 of 545

Slide 13


Region Styles

The region style in the Property Inspector determines the UI Bean for the region. Different Beans have very different behaviors. The region styles available are:

• 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

It is absolutely critical that you begin to familiarize yourself with the OA Framework Developer’s Guide (OAFDG). The OAFDG comes in the patch that contains the JDeveloper with OA Extension version that you are using for your development. In Chapter 4: Implementing Specific UI Features of the OAFDG, there is a detailed discussion of each of these region types, along with other UI features.



Page 132 of 545

Slide 14


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)



Page 133 of 545

Slide 15


Named Children vs. 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

The named children are as follows: • location • copyright • userInfo • inContextBranding • productBranding • returnNavigation • pageStatus • footnote • contentFooter • corporateBranding • quickSearch • privacy • flexibleContents

By default, the corporateBranding named child is set automatically when the page is created. The corporateBranding named child is set with default characteristics, but you can change this as desired.



Page 134 of 545

Slide 16


Item Styles

The item style in the Property Inspector determines the UI Bean for the item. Different Beans have very different behaviors. The item styles available are:

• attachmentLink

• attachmentTable

• button

• exportButton

• flex

• formParameter

• formValue

• formattedText

• image

• link

• rawText

• resetButton

• resetButton

• richTextEditor

• separator

• servletInclude

• spacer

• staticStyledText

• submitButton

• tip

• urlInclude

• messageCheckBox

• messageRichTextEditor

• messageInLineAttachment

• messageDownload

• messageFileUpload

• messageLovChoice

• messageLovInput

• messageRadioButton

• messageRadioGroup

• messageStyledText

• messageTextInput

• messageChoice

It is absolutely critical that you begin to familiarize yourself with the OA Framework Developer’s Guide (OAFDG). The OAFDG comes in the patch that contains the JDeveloper with OA Extension version that you are using for your development. In Chapter 4: Implementing Specific UI Features of the OAFDG, there is a detailed discussion of each of these item types, along with other UI features.



Page 135 of 545

Slide 17


Item Style Details

• Item styles that start with message (such as messageTextInput, messageStyledText, messageLovInput, and so on) create displayed data fields.

– Use messageTextInput for an input field.

– Use messageLovInput for an input field with an LOV.

– Use messageStyledText for a display-only field.

• The region style messageComponentLayout can be used to quickly and correctly position message* beans and related items into an n-column grid.

Message beans are components that are capable of displaying associated error, warning or information icon(s) with an explanatory message (for example, if a user enters the wrong value in a text input field an error icon renders next to its prompt). Typically message beans either display or accept data values (as opposed to boilerplate text, for example). If you use the region style messageComponentLayout to contain your message beans, and you want to add some other type of bean such as a submitButton item, you must insulate or encapsulate the non-message bean in a messageLayout region first. For example:

• messageComponentLayout - messageTextInput - messageStyledText - messageLovInput - messageLayout

submitButton - messageTextInput



Page 136 of 545

Slide 18


Item Style Details

• Use staticStyledText for plain boilerplate text on a page such as an instruction.

• Use submitButton for a button that does a POST (the button item style does not submit).



Page 137 of 545

Slide 19


Shared Regions

If you want to create a shared region, you must comply with the following standards.

• The top-level (shared) region must be saved in its own XML file.

• Shared region can accept values from a using region.

• Shared region must be implemented to fail gracefully. For example, if appropriate parameters are not passed from a using region, the shared region should set acceptable defaults or raise a meaningful (and documented) exception.

Shared Regions are an important tool to ensure a consistent look and feel, while minimizing the cost and time to make changes to a page.



Page 138 of 545

Slide 20


Shared Regions

• If the region scope is set to Public:

– The top-level region must have its own application module. The application module should include only those view objects that are relevant for the shared region.

– The top-level region must have its own controller. You may associate additional controllers with subregions as necessary.

• The shared region must be fully documented.

Shared Regions are an important tool to ensure a consistent look and feel, while minimizing the cost and time to make changes to a page.



Page 139 of 545

Slide 21


Lists of Values (LOVs)

• Two types of declarative LOV

– In-line LOV region

– External LOV region

• Dynamic query construction

– Add to either in-line or external LOV

– Define "Programmatic Criteria" in LOV mappings

– Requires an extra controller

Be aware of the limits of LOVs and other UI objects. Not every region type is capable of containing an LOV, even if you can add that LOV within JDeveloper. OA Framework may simply refuse to display the object. See the OA Framework Developer’s Guide for more information.



Page 140 of 545

Slide 22


Lists of Values (LOVs)

1A

Base Page

2B

C

4D

LOV Window

Search by 1

4

2 4

4

1

4

ResultsE F G H

E

F

Search

Go

Cancel Select

Criteria

Hidden Criteria

Return

Fields E, F, and H have their Search Allowed property set to True, so they appear in the poplist in the LOV window. Field A (with the search icon) on the base page is the LOV field. The LOV field must have both criteria item and return item LOV mappings. The other fields in the base page can only be either criteria or return items. If a field other than the LOV field provides criteria, that criteria must be an exact match to a column in the LOV results table. While the diagram shows the criteria field D and the results column H as hidden fields, they can be hidden or displayed fields.



Page 141 of 545

Slide 23


Defining an External LOV

• Build the LOV region in a region file:

– Create an LOV region of style ListofValues.

– Create a table region inside the LOV region.

– Items that users can choose for entering query criteria in LOV window must have Search Allowed property set to True.

• Attach the LOV region to the base page using External List of Values property on LOV field

– Set to qualified name of region file.

– Base page LOV field must have Item Style property set to messageLovInput.



Page 142 of 545

Slide 24


Defining an External LOV

Create the LOV mappings:

– LOV field on base page must be specified for both Criteria From and Return To properties.

– Other fields can only be used for one direction only (criteria item or return item).

– Other criteria fields provide hidden criteria that is always applied to the search in the LOV window.



Page 143 of 545

Slide 25


Reading Model Data

Assuming you have specified the appropriate data source bindings, the OA Framework automatically reads data from the model for display in the view, and writes user-entered data in the view back to the model. You don't need to write a single line of code (except for any validation you want to perform in the underlying entity objects, of course). In simple terms, every time the OA Framework renders a page, it calls the current view object row's get<AttributeName> method for each web bean's associated view object attribute. Consider an example page with a "Suppliers" table, which binds to a SuppliersVO view object. The SuppliersVO maps to an underlying SupplierEOImpl, although it also includes one "calculated" transient attribute ("OnHoldDisplay") that does not have a corresponding entity object attribute.

• The user selects the "Search" region's "Go" button to populate search results in the "Suppliers" table.

• The "Search" region's controller handles the button press by invoking a search method in the root application module, which in turn delegates to the SuppliersVOImpl class so it can query itself.

• Within the executeQuery method, the SuppliersVOImpl view object performs its SQL SELECT in the database.

• For each row returned in our example result set, the view object instantiates a SupplierEOImpl entity object and sets its attribute values with the query results.



Page 144 of 545

Note: Entity object-based attribute values aren't actually stored anywhere in the view object. They "live" in the entity object, and are retrieved as needed by the view object. "Calculated" (meaning the values are simply selected from a SQL statement and have no relationship to an entity object) or "Transient" view object attribute values are stored on the SuppliersVORowImpl object.

• During page rendering (after all the query processing), the OA Framework uses the view object data bindings defined for each web bean to call the corresponding SuppliersVORowImpl object's getAttribute("<attributeName">) which in turns calls its get<AttributeName> method.

• The SuppliersVORowImpl get<Attribute Name> method in turn calls the corresponding SupplierEOImpl get<AttributeName> method to retrieve the value. For the "calculated" OnHoldDisplay attribute, the view object row retrieves the value from its own cache.



Page 145 of 545

Slide 26


Writing Model Data

Whenever the browser issues a POST request, the OA Framework automatically writes any user-entered form values back to the underlying view objects, which in turn update any corresponding entity objects as shown below. Note: The following steps assume that the entity object for the row has already been successfully instantiated and initialized (such as in the create method on the underlying view object for the page when the user originally comes into a Create page. The VO create method calls the corresponding create method on the entity object behind the scenes).

• UIX performs onSubmit JavaScript validation (required fields, data types, formats) and issues the POST request only if this validation succeeds.

• The browser sends a POST request and the OA Framework calls the processFormData methods on all the web beans in the hierarchy.

• Within processFormData, the OA Framework automatically calls setAttribute(String name, Object value) on the current row of the underlying view object for each bean. This executes any attribute-level validation that you've written in the view object row.

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

• Once all the attribute values have been set, the OA Framework calls the view object validate for each row it modified to execute any associated row-level validation.



Page 146 of 545

• Finally, within the validate method, the view object row calls validateEntity for the underlying entity object which executes any associated entity-level validation.



Page 147 of 545

Slide 27


Binding Items to Data

In your declarative data, binding a specific item to data from an existing VO is simple.

• Add the VO instance to the root AM.

• Specify the root AM for the pageLayout.

• Specify the View Instance in the Property Inspector for each item.

– Also called view object instance or view usage

• Specify the View Attribute in the Property Inspector for that item.

– Also called view object attribute



Page 148 of 545

Slide 28


General Naming Rules

• File Name length

– File names are limited to 30.3 characters for OA Extension XML files (50.java for Java files).

• Object Name length (regions, items, and so on)

– For performance reasons, object names (internal ID’s) are limited to 30 characters.

– Use the shortest possible names that are readable.

– Consider abbreviating repeating object names.

These naming rules are guidelines, and are meant to show the standards to which Oracle’s E-Business Suite developers adhere.



Page 149 of 545

Slide 29



Object name abbreviations:

• Common abbreviations are acceptable to keep names as short as possible.

• Acceptable abbreviations can be instantly understood by a third party consultant.

• Examples of acceptable abbreviations are:

– Emp for employee

– Num for number

– Desc for description

– Industry terms such as PO

• If in doubt don’t abbreviate.

Short names are important because they reduce the size of the generated HTML file sent back to the browser. This have middle-tier and network performance issues.



Page 150 of 545

Slide 30



Object names in pages must be unique in the entire page.

• Convention is to name the object to match its label (shortened as appropriate).

• For duplicate names, prefix the second and higher instances with a short version of the parent object’s name. For example:

– EmpName

– SearchEmpName

– ResultsEmpName

• Most names follow Java naming convention (mixed case)

Because of OA Framework’s hierarchy, names must be unique within the entire page.



Page 151 of 545

Slide 31


Page and Object Naming Rules

• Page name ends in PG: EmpSearchPG, EmployeePG, SupplierPG

• Content regions have names ending with RN: MainRN, EmpSearchRN, PoHeaderRN

• Layout-only container region names reflect the layout: ContactsTableLayout, ButtonsRow

• BLAF Navigation-only regions use standard names: PageTopNavLinksRN, TrainRN

BLAF stands for Oracle's Browser-Look-And-Feel specification, and it specifies the appearance and behavior of OA Framework-based applications.



Page 152 of 545

Slide 32


Styles and Bean Names

• Region or item style names in the JDeveloper Property Inspector appear in the Java naming convention starting with lower case letter.

• The corresponding programmatic versions (web Bean names) usually prepend "OA", append "Bean" and capitalize the first letter.

– messageComponentLayout becomes OAMessageComponentLayoutBean

– table becomes OATableBean

• See the OA Framework Developer's Guide and OA Framework Javadoc

Exceptions to the rule: attachmentLink becomes OAMessageAttachmentLinkBean



Page 153 of 545

Slide 33


Summary


• Use the proper terminology when discussing OA Framework UI (View-layer) objects.

• Discuss pages.

• Discuss regions.

• Discuss items.

• Discuss CSS styles.

• Discuss other View-layer objects.

• Discuss View-layer read and write data binding.

• Identify and use View-layer naming standards.



Page 154 of 545

Basics of the Controller



Basics of the Controller



Page 155 of 545

Slide 2


Lesson Objectives


• Discuss how events are handled in OA Framework applications

• Create the controller for an OA Framework page that enables button handling, automatic queries, dynamic WHERE clauses, JSP forwards, and the messages from the Message Dictionary

• Identify the event flow within an OA Framework page (GET and POST events)



Page 156 of 545

Slide 3










Steps 5 deals directly with Controller layer components.



Page 157 of 545

Slide 4


Do You Need a Controller?

In general, before tackling the question of how to design your controller, it's important to consider whether you even need to create a controller.

As a rule, you should write controller code only if it is absolutely essential. If you can create your page declaratively, do not instantiate regions and items programmatically. Programmatically created web beans cannot be personalized, reused or extended. Furthermore, some hard-coded layouts may fall out of compliance with the standards as they evolve over time.

As required, all top-level regions in a shared component must have an associated controller.



Page 158 of 545

Slide 5


Controller Basics

• OA Controllers can be associated with any region. OA Controllers can not be associated with items.

• Never set properties on a parent/grandparent web bean from a child bean. Always define controllers so they control the regions with which they're associated, or set properties on children/grandchildren of this region. If you want a controller to manage multiple child/grandchild web beans, it should be associated with an appropriate parent/grandparent bean.

• For complex beans, you should associate a controller with the bean itself, or perhaps with a simple containing bean if it represents a logical unit of functionality.

• In general, you should create the fewest number of controllers per page that satisfies the rules and considerations outlined above.

A general rule is to minimize the number of controllers. While it is possible for every region object to have a controller, it is probably not advisable to do so. And, by minimizing regions with controllers, it can simplify the code for your OA Framework page, and make the page must more maintainable.



Page 159 of 545

Slide 6


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



Page 160 of 545

Slide 7


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)

– processFormRequest (code for HTTP POST actions)

• Application Modules

– Called by controllers

• View Objects

– Called by AMs to initialize and execute queries

• Entity Objects

– Validation, creation, deletion (may also be in "Entity Expert")

The code itself will typically be in the <AM/VO/EO>Impl.java file or a <controller name>CO.java file.



Page 161 of 545

Slide 8


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

This is the most common use of a controller.



Page 162 of 545

Slide 9


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

Remember to keep to the encapsulation. The controller should call the AM, and defer to the AM to call the necessary VO.



Page 163 of 545

Slide 10


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.

This is a good general rule. Where possible, keep things defined at design time (declarative) instead of at run time (programmatic). Declarative objects have much better performance.



Page 164 of 545

Slide 11


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.

The findByKey is useful when you are looking for a single row whose entity objects are likely to already be in the cache (BC4J will pluck them from the cache instead of doing a round trip to the database). This is a very useful tool for developers and we want to encourage them to use it. That doesn't mean that you won't still have cases when it is preferable to initialize a query.



Page 165 of 545

Slide 12


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.

Button presses and other events are part of the POST cycles spoken about earlier.



Page 166 of 545

Slide 13


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

Note: Java and XML are case sensitive. This is a common error in OA Framework pages.



Page 167 of 545

Slide 14


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 VOImpl.java class that

builds and executes a query

2. Add a query method to the AMImpl.java class that finds the view object and executes the initQuery

method

3. Add code to the processFormRequest method in

the CO.java (Controller) class that calls the application module query method

Manually-built Search regions are those that are individually constructed as individual pieces rather than using the Query Bean. For example, the Query Bean creates a Go button to execute the query, and it creates the associated controller-layer and model-layer code to make the query function. With manually-built search regions, you will have to create all the UI items, the controllers, and the model-layer code to implement the functionality. The drawback is that this is much more complex, and for the normal, simple cases is over complicated. The advantage is that it allows truly complicated cases to be constructed. The processFormRequest in the controller should never call methods on the VO directly; it should always delegate to the AM. This same code, added to the processRequest method instead of the processFormRequest method, can be used to do an automatic query when the user comes into the page.



Page 168 of 545

Slide 15


The Process

processFormRequest() calls initDetails()

initDetails()

– Finds and instantiates the view object

– Calls the view object initQuery()

initQuery()

– Initializes the query

– executes the query

Region Controller

View ObjectApplication Module

User presses

Go button



Page 169 of 545

Slide 16


Example VOImpl Code

public void initQuery(String employeeNumber)

{

if ((employeeNumber != null) &&

(!("".equals(employeeNumber.trim())))) {

Number empNum = null;

try

{ empNum = new Number(employeeNumber); }

catch(Exception e)

{ throw new OAException("AK",

"FWK_TBX_INVALID_EMP_NUMBER"); }

setWhereClause("EMPLOYEE_ID = :1");

setWhereClauseParams(null); // Always reset

setWhereClauseParam(0, empNum);

executeQuery();

}

This code gives an example of the code that would be put into the VOImpl.java class. Note the following characteristics:

• The method is named initQuery(). This is a naming standard. • The parameter passed to the method (employeeNumber) is not assumed to

be valid number. There is a try/catch to typecast the String object to a Number object.

• If the typecast fails, an OAException is thrown from the message dictionary. • The remainder of the code sets up the dynamic WHERE clause for the VO,

and then executes the query. • If you do not have the executeQuery(), the VO will not query your data. This is

a common error. Sometimes, you will, when creating the VO, accidentally or unintentionally check the generate VOImpl.java class. The VOImpl.java class file is just an empty stub. Without an initQuery method with a call to executeQuery, the data will not be retrieved.



Page 170 of 545

Slide 17


Example AMImpl Code

public void initDetails(String employeeNumber)

{

EmployeeFullVOImpl vo = getEmployeeFullVO1();

if (vo == null)

{

MessageToken[] errTokens = { new

MessageToken("OBJECT_NAME", "EmployeeFullVO1")};

throw new OAException("AK",

"FWK_TBX_OBJECT_NOT_FOUND", errTokens);

}

vo.initQuery(employeeNumber);

} // end initDetails()

This code gives an example of the code that would be put into the AMImpl.java class. Note the following characteristics:

• The method checks to see if the VO is assigned to the AM. • If the VO is not known to the AM, an OAException is thrown. • The AM then invokes the initQuery method on the VO passing any parameters

needed.



Page 171 of 545

Slide 18


Example Controller Code

public void processRequest(OAPageContext pageContext,

OAWebBean webBean)

{

// Always call this first.

super.processRequest(pageContext, webBean);

// Get the employeeNumber parameter from the URL

String employeeNumber =

pageContext.getParameter("employeeNumber");

// Now we want to initialize the query for our single

employee

// with all of its details.

OAApplicationModule am =

pageContext.getApplicationModule(webBean);

Serializable[] parameters = { employeeNumber };

am.invokeMethod("initDetails", parameters);

}

This code gives an example of the code that would be put into the CO.java (Controller) class. Note the following characteristics:

• The first line of the method is a call to super. • The controller knows the UI objects, and gets their values from the

pageContext. • The pageContext knows what its root AM is. So, the controller asks for the

root AM from the pageContext. • Parameters are serialized. For this example, this is simple. Serialization is the

process of converting an object into a string representation. Since the parameter is already a string, this is simple. In some cases, more complex objects may be passed as parameters to the method.

• Finally, the AM method is invoked. Since the AM can contain multiple VOs, it is not possible, like initQuery for VOs, to call a standard AM method.



Page 172 of 545

Slide 19


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

There are two methods of redrawing the page. • The primary way is now to use partial page rendering (PPR) to redraw

relevant sections of the page without redrawing the entire page. • The older method is to forward the current page back to itself if there is some

UI change that requires going back through the processRequest logic for the page.

The use of forwarding back to the current page to display UI changes, such as a data-dependent title, is no longer necessary for most pages, which now use partial page rendering (PPR) instead.



Page 173 of 545

Slide 20


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>", …

Forward is used to direct to a new page without having to interact with the browser. The redirection is done on the middle-tier server.



Page 174 of 545

Slide 21


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

Declarative values set in the pages (text, prompts, and so on, set in the Property Inspector) are also translatable, but do not use Message Dictionary. You should never hardcode text into your page logic. Use the Message Dictionary to ensure that the text can be translated and reused. Do not use tokens for single words, partial words, or sentence fragments because they do not translate into languages that have a different grammatical structure. For example:

• "This &DOCUMENT cannot be &ACTION." - DOCUMENT might be purchase order or invoice, and ACTION might be

approved, denied, and so on. These would not translate to a Romance language that uses gender, because there may be a mismatch between the noun and the verb.

- "&NUMBER of row&PLURAL saved." where the value of PLURAL can be either "s" or nothing, to result in "row" or "rows". This does not translate to any language that does not use "s" to designate a plural.



Page 175 of 545

Slide 22


Event Flow Overview

Understanding the common OA Framework event flows is essential to aid:

• Coding

– Logic execution order

• Debugging

– Breakpoint placement



Page 176 of 545

Slide 23


Initial Setup Flow

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

JSP OAPageBean OAPageContextRequest

from Browser

OAPageBean does many “housekeeping” tasks. OAPageContext is passed to all the web beans when they are called. It can be considered the beans communication link to the outside world. "OA Framework services" mostly refers to services from AOL/J, but also to convenience methods for common tasks.



Page 177 of 545

Slide 24


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

“Submit action” is an oversimplification. The flow for this action also includes drawing or redrawing a page.



Page 178 of 545

Slide 25


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



Page 179 of 545

Slide 26


GET Event Flow (1-3)

1. Get session info and validate user

2. Fetch metadata

3. Get Root AM and validate user session

• Get the ICX Session Cookie � The URL provides:

• Database (DBC) information • Page name • Other parameters

• Check to see if metadata is in the cache. • If metadata not in cache, fetch the metadata.

• Metadata fetched through separate static connection • At customer sites metadata will be in the database • In JDeveloper you can work against XML files, the repository, or both

Note: Separate static connection for fetching metadata means that: 1) It’s a different commit cycle so rollbacks in their own pages will not affect the metadata (though that would be read-only anyhow) and 2) there is a separate AM in the AM pool for fetching the metadata.

� Apply personalizations. � Get root AM for session. � Validate session on root AM. � Validate the function (function security) associated with the page, the user, and

the responsibility. The AM associated with page is the root AM. The root AM holds the database

connections. One connection is used for data. The other connection, the shadow, is used to fetch metadata and validate SQL.



Page 180 of 545

Note: “Validate function associated with page” refers to going through function security to see if user has access to the function. Function is (at least) associated with the page using a property at the pageLayout (top) region of a page.



Page 181 of 545

Slide 27


GET Event Flow (4) Instantiate BC4J and UIX Classes

1. Build OA web bean hierarchy from metadata of the page and any personalizations.

2. Instantiate any associated BC4J objects.

3. Place web bean bound values, if any.

4. Cache the web bean hierarchy on the root AM.

At runtime, UI regions and items map to web beans (JavaBeans). OABeans are extensions of UIX beans.



Page 182 of 545

Slide 28


Example Bean Hierarchy Structure

JSP OAPage Bean

PageLayout Bean

Header Bean

Text Bean Text Bean

OAPageContextRequest

from Browser



Page 183 of 545

Slide 29


GET Event Flow (5) processRequest

1. Walk the web bean hierarchy.

2. Instantiate any controller classes.

3. Invoke the processRequest() methods on any controllers in the hierarchy.

In the processRequest() method, developers can query data (using vo.executeQuery) and set bean properties programmatically. NOTE: Programmatically setting, and even creating, a UI object is possible, but is highly discouraged. Programmatic UI creation or manipulation has the following drawbacks:

• Adverse performance impact • Inability to apply personalizations • Difficult to maintain and debug • Programmatically created pages cannot use important OA Framework

abilities, like partial page refresh



Page 184 of 545

Slide 30


GET Event Flow (6) Post-Processing

1. Perform post-processing on complex beans

– OAPageLayoutBean and OATableBean for example

– Post-processing can also be initiated from processRequest by calling prepareForRendering method

2. Places data binding objects on rendering context



Page 185 of 545

Slide 31


GET Event Flow(7) UIX Renders the Page

1. UIX generates page by calling UIX render methods recursively

2. UIX uses DataObjects and BoundValue interfaces to fill in values

– DataObjectList – View Object

– DataObject – View Row



Page 186 of 545

Slide 32


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



Page 187 of 545

Slide 33


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

1. User does something to cause a form submit (such as button press or PPR event)

2. UIX performs onSubmit Javascript client-side validation on the browser

3. Browser sends the POST request only if the client-side validation succeeds

Note that while UIX performs browser-side validation using JavaScript, but OA Framework based pages and their related code must not use JavaScript.



Page 188 of 545

Slide 34


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

1. Validate the user as in GET

2. 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!

Cases where the bean hierarchy might not exist or might be out of synch include: Back button use, passivation, and failover to another JVM. Failover is not yet supported.



Page 189 of 545

Slide 35


POST Event Flow(6) Apply Form Data

First pass through the bean hierarchy:

1. 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

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



Page 190 of 545

Slide 36


POST Event Flow(6) More of processFormData

Attribute-level validation:

3. 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.



Page 191 of 545

Slide 37



Row-level validation:

4. 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.



Page 192 of 545

Slide 38



5. 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.



Page 193 of 545

Slide 39


POST Event Flow(7) processFormRequest

1. Walk UIX tree and call processFormRequest on

controllers (second pass through the bean hierarchy)

– Developers can respond to events or redirect to another page

2. If no redirect (or if errors are thrown) redraw the page



Page 194 of 545

Slide 40


Summary


• Discuss how events are handled in OA Framework applications.

• Create the controller for an OA Framework page that enables button handling, automatic queries, dynamic WHERE clauses, JSP forwards, and the messages from the Message Dictionary.

• Identify the event flow within an OA Framework page (GET and POST events).

Open the Course Labs book. Complete Lab 1 – Learning More About the Page



Page 195 of 545

Introduction to JDeveloper 10g with OA Extension

8Copyright © 2010, Oracle and/or its affiliates. All rights reserved.

Introduction to JDeveloper 10g with OA Extension

R12.x Extend Oracle Applications: Building OA Framework Applications



Page 196 of 545

Slide 2

8 - 2 Copyright © 2010, Oracle and/or its affiliates. All rights reserved.

Lesson Objectives


• Use JDeveloper 10g with OA Extension

• Use the JDeveloper 10g debugger

• Configure JDeveloper 10g with OA Extension to connect to an E-Business Suite instance to run OA Framework pages

The debugger section in this course is a very brief overview of what can be debugged in JDeveloper. There are many techniques and methods to debugging and the more advanced topics are beyond the scope of this class. Using the Debugger in the classroom is usually a very network intensive process and your instructor will probably opt to go over the debugging or demonstrate it for you, in lieu of every student using the debugger. If you use the debugger, you will cause performance to suffer for all of your classmates.



Page 197 of 545

Slide 3


Oracle JDeveloper 10g with OA Extension

• Oracle JDeveloper 10g with OA Extension provides an integrated development environment (IDE).

• It enables you to:

– Build, compile, and run Java applications

– Use wizards to help build source code

– View objects from many perspectives: code, structure, layout, and so on

Oracle JDeveloper You can use Oracle JDeveloper to build many different types of Java components. This lesson focuses on using the JDeveloper IDE for building OAF applications. Many of the components that you will create are Wizard driven. A Wizard is a graphical tool that provides step-by-step guidance through the process of defining a new element in the IDE. Oracle JDeveloper provides many contextual Wizards, including:

Application Wizard: Defines a new application and associated projects Applet Wizard: Defines a new Java applet and adds it to the specified

project EJB Wizard: Defines a new Enterprise JavaBean (EJB) and adds it to the

specified project JSP Wizard: Defines a new JavaServer Page (JSP) and adds it to the

specified project HTTP Servlet Wizard: Defines a new servlet and adds it to the specified

project OA Framework Contextual Wizards

Note: Some of the wizards above are not used when building OAF Applications.

They are part of JDeveloper. Oracle JDeveloper helps you specify the following features of your user interface:

Size and position of controls



Page 198 of 545

Properties for each control, such as labels, enabled or disabled status, font, etc.

Event-handler methods

Slide 4


Oracle JDeveloper 10g Components

Applications Navigatorand Structure window Property Inspector

Component Palette

Code Editor

Oracle JDeveloper 10g Environment Oracle JDeveloper 10g contains four major user interface components. These components are what you use to edit code, design and manage the user interface, and navigate your program. Component Palette The Component Palette displays the components available to build user interfaces, models, navigation diagrams, and so on. Applications Navigator and Structure window The Applications Navigator displays a list of files or classes in a project. The files may be Java source files, .class files, graphics files, HTML, XML documents, and so on. The associated Structure window shows the detailed structure of the object selected in the Navigator. Code Editor The Code (Design) Editor is where most of the work takes place; this is where you write code and modify user interfaces. You can open the editor by double-clicking the name of the file in the Navigator that you want to edit or view.



Page 199 of 545

Note: The interface components windows are movable and you have control over which ones are displayed.



Page 200 of 545

Slide 5


Applications and Workspaces

• May contain multiple projects

• Enable you to view currently used objects

Application node

Applications Navigator

pane

Structure pane

Application Organization Oracle JDeveloper 10g with OA Extension uses a well-defined structure to manage Java programming applications. The structure is hierarchical and supports applications, projects, images, .html files, and so on. Applications An Application is the highest level in the control structure. It is a view of all the objects you currently need while you are working. An application keeps track of the projects you use and the environment settings while you are developing your application. When you open JDeveloper, the last application used is opened by default so that you can resume your work. Applications are stored in files with the extension .jws. You do not edit an application file directly. Whenever you save your application, you are prompted to save all the files currently open. To save the open and modified files, click the Save option (or the Save All option) from the File menu. Note: You can view the content of an application file by using any text editor. Workspaces For E-Business Suite development, there is additional information and restrictions. For example, an OA Framework application needs to know the E-Business Suite user, password, application short name, and responsibility key in order to run. Additionally, unlike typical J2EE development, E-Business Suite doesn’t run Applications, it runs pages (XML files). So, in JDeveloper, an Application is used as the starting template that is modified to meet E-Business Suite needs, and is then renamed as a Workspace.



Page 201 of 545



Page 202 of 545

Slide 6


Creating a Workspace

In the General category, select Workspace Configured for Oracle Applications to invoke the Create Application dialog box.

Creating a Workspace - .jws files in the file system The first step is to create a new workspace that acts as a container for all the files that are going to be part of your project. Workspaces contain projects. When you create a workspace, you will enter a name for the workspace. When creating a Workspace you will designate the top-level directory for the application files that are going to be part of your project. The top level directory will be the physical location for your files. By default, the location is:

JDEV_USER_HOME/myprojects.

When you create a Workspace, you immediately can create a new OA Project



Page 203 of 545

Slide 7


Projects

• Contain related files

• Manage project and environment settings

• Manage compiler and debug options

Projectnode

Projectfiles

Projects - .jpr files in the file system JDeveloper projects organize the file elements that are used to create your program. A project file has the file extension .jpr and keeps track of the source files, packages, classes, images, and other elements that may be needed for your program. You can add multiple projects to your application and workspace to easily access, modify, and reuse your source code. You can view the content of a project file by using any text editor. Projects manage environment variables, such as the source and output paths used for compiling and running your program. Projects also maintain compiler, run-time, and debugging options so that you can customize the behavior of those tools for each project. In the Navigator pane, projects are displayed as the second level in the hierarchy under the application. When you select a .java or .html file in the Applications Navigator, the Structure pane displays the elements of the file in a tree format. For example, when you select a .java source file, the classes, interfaces, methods, and variables are displayed. To edit source code, double-click the file in the navigation list to display the contents in the appropriate editor. The Structure pane can be used to quickly locate specific areas of code in your Java source files and to browse the class hierarchy.



Page 204 of 545

When you are working with the visual designer, the Structure pane displays the components of your user interface and their associated event-handling methods in a hierarchical tree format. Note: Italic style is used to indicate file names that have not yet been saved.

Slide 8


Creating Project Wizard Start Screen



Page 205 of 545

Slide 9


Enter Project Informationand

Default Project Package

Default Package: This is simply a default starting point for future files. It is not a limit. You can change the package of any object you create to point to the appropriate path.



Page 206 of 545

Slide 10


Runtime settings for a Project

DBC File Name: You can either copy it to your own ./secure directory, or you can link to the directory where you instructor has stored the original. User Name: Default for this course is fwktester or FWKTESTER. Password: Default for this course is fwkdev. or FWKDEV Application Short Name: Default for this course is AK. Responsibility Key: Default for this course is FWK_TBX_TUTORIAL.



Page 207 of 545

Slide 11


Establish a Database Connection

Once you have a workspace and a project, most developers make sure there is a working connection to their test instance and define the required parameters. It is important to change the seeded values as you work through the setup wizards. The seeded values that appear will not work. The values you see are populated to give you an idea of what you need to know about your instance. From the Applications Navigator panel, you can click the Connections tab, and choose the Database folder to configure the correct setting based on what your instructor provides.



Page 208 of 545

Slide 12


Establish a Database Connection

Right-click the Database folder, and choose New Database Connection.



Page 209 of 545

Slide 13


Provide the SID for the Database Connection

Generally, it is recommended to give the connection the same name as the SID of the E-Business Suite database to which you are connecting. The slide above is NOT what you are supposed to fill in.



Page 210 of 545

Slide 14


Establishing a Database Connection

Username: Default for this course is apps. Password: Default for this course is apps.



Page 211 of 545

Slide 15


Database Connection Information

If you don’t know this information, you can ask your instructor, or you can examine the DBC file they provided. All of the connection information is contained in the DBC. Again, the slide above is NOT what you are supposed to fill in.



Page 212 of 545

Slide 16


Testing a Database Connection

Always test the connection.



Page 213 of 545

Slide 17


Project Properties

Project Properties: Specifying Project Details Once the database connection is working, most developers go ahead and set up other parameters as part of their project and workspace. If you need to change any of the connection information, or any other project setting, simply double-click the project in the Applications Navigator panel to open the Project Properties window.



Page 214 of 545

Slide 18


Project Properties – Oracle Applications

In order to see complete diagnostic errors and stack dumps, we will add OADiagnostic to the Run Options of every project.



Page 215 of 545

Slide 19


Directory Structure

JDeveloper creates and stores.java, .xml and.class

files by using the following conventions:

• JDEV_USER_HOME/myprojects

• JDEV_USER_HOME/myclasses

When JDeveloper was unzipped, it created a file structure on the local machine. myprojects: Holds .java and .xml files

myclasses: Holds .class and .xml files

myhtml: Holds deployed objects, like shared images, and .jsps

system: Holds JDeveloper configuration information dbc_files/secure: Holds DBC files



Page 216 of 545

Slide 20


Creating JDeveloper Items

• JDeveloper items areinvoked by selecting File > New.

• They are categorized by type:

– General

– Business Tier

– Client Tier

– Database Tier

– Integration Tier

– Web Tier

• Create any JDeveloper element.

Creating JDeveloper Items Once past JDeveloper set up, you can start to create objects. You can create any JDeveloper item from the New Gallery window. You can select new and work your way down the categories to create what you would like to create or use a contextual based creation mechanism. The contextual mechanism for creating an item is based on what was highlighted when you clicked the right mouse button or selected new. You must have the correct element selected in the category column to contextually create an appropriate item. The functionality to contextually create something is based on the OAF extension. Use the Filter By drop-down list to view specific types of elements.



Page 217 of 545

Slide 21


Exploring Java Files

You can edit the Java files that are part of your application.



Page 218 of 545

Slide 22


Exploring Other Objects - Wizards

Some objects, notably any BC4J objects (AM, EO, VO, AO, VL), have Wizards associated with them. When you double-click the object, it opens the object wizard by default.



Page 219 of 545

Slide 23


Exploring Other Objects – UI Objects

UI (View-layer) objects, like pages (PG) and regions (RN), aren’t written in Java and they don’t have object wizards. These objects are edited using the Property Inspector. The UI objects that you create are actually XML files that are used declaratively to render the pages. You can’t edit the XML files for your pages from within JDeveloper. There is an enforced hierarchy of the page structure via the OAF framework.



Page 220 of 545

Slide 24


Finding Methods and Fields

Find methods and fields using the Structure pane:

Finding Methods and Fields As projects evolve, classes can become quite large, containing several methods and fields. To help you find your way around complex classes, JDeveloper provides the Structure pane, which is the bottom pane in the Applications Navigator. The Structure pane lists all the methods and fields for the currently selected class. If you double-click an item in the Structure pane, JDeveloper takes you to the definition of that item in the source code, displaying and highlighting it in the Code Editor. For example, if you double-click a method in the Structure pane, the start of the method you clicked is highlighted in the Code Editor. You can also search the Navigator and Structure pane components for strings by using a [letter]. The search is a hierarchical search based on the first letter of each component. As you enter subsequent letters, the structure list highlights the first component that begins with that set of letters. If there is more than one occurrence, use the up and down arrow keys to scroll through the result set. Note: JDeveloper 10g with OA Extension provides some new features to facilitate navigation through your Java code. One of these is navigation between members, which allows you to quickly navigate between fields and methods in the Code Editor by using the Previous Member ([Alt] + [Up]) and Next Member ([Alt] + [Down]) accelerators.



Page 221 of 545

Slide 25


Supporting Code Development with Profiler and Code Coach

• Improve code quality with Code Coach.

• Evaluate execution stack with the Execution Sample profiler.

• Examine heap memory usage with the Memory profiler.

• Analyze event occurrence and duration with the Event profiler for:

– JVM events

– Business components for Java events

– Custom events

Supporting Code Development with Profiler and Code Coach Code Coach Code Coach creates more efficient Java programs by helping you write higher-quality, better-performing code. You run Code Coach on a class to obtain advice on how to make your code better. Profilers Profilers gather statistics on your program, enabling you to more easily diagnose performance issues. With profilers, you can examine and analyze your data. Code Editor When you pause momentarily while entering code in the Code Editor, JDeveloper automatically scans your code to look for syntax errors. If there are any, you see them represented in the Structure pane or in the Log window. Code Insight If you pause after entering a “.” (period), JDeveloper invokes Code Insight. Code Insight displays valid methods and members from which you can select. JDeveloper also provides Code Insight for parameters when you pause after entering a left parenthesis.

Instructor Note You may want to encourage students to explore these features. JVM is required to use the Code Coach and profiler features. To use a custom Java SE version (other than the one provided by JDeveloper), students can follow the installation guide provided by JDeveloper for installing OJVM on the custom Java SE.



Page 222 of 545



Page 223 of 545

Slide 26


New Code Editor Features

Code Assist

Overview margin

Implements and overrides navigation

Tasks list

Scope and code folding

New Code Editor Features Code Assist Code Assist is a new feature in JDeveloper 10g with OA Extension. It deals with adherence to coding standards rather than syntactical correctness. It examines your code in the Java Source Editor and offers suggestions to fix coding problems or breaches of coding standards. A light bulb icon appears in the margin beside a line where JDeveloper has a suggestion for a code change. You click the icon to display the suggestion. You can accept the suggestion by clicking it and amending the code; or you can reject the suggestion and suppress the light bulb by closing the suggestion. In many cases, if you accept the suggestion, JDeveloper makes the appropriate code modifications for you automatically. You can choose which rules you want Code Assist to use, or you can disable the feature altogether by selecting Tools > Preferences > Audit: Profiles. Code Folding Code folding allows you to shrink sections of code, making large programs more readable and more manageable. You use the + and – buttons in the blue vertical bar on the left of the code to expand or contract classes, respectively. Tasks List By using the Tasks list, you can create and keep track of tasks. The tasks can be of any nature, but the feature has been provided primarily for tasks connected with the process of software development. For this reason, a direct link has been provided between the Code Editor and the Tasks list: When writing code, a task is created whenever you enter



Page 224 of 545

//TODO. A check mark is displayed in the margin to the left of the line, indicating the presence of a task. Overview Margin The Overview margin is displayed vertically on the right side of the Code Editor. If there are no problems with the code, a small green marker appears at the top of the margin. An orange marker indicates a warning, and a red marker denotes an error. When you position the cursor over an orange or red marker, you see a brief displayed description of the error or warning. Overridden and Implemented Method Definitions When working in the Java Source Editor, you can identify methods that override superclass definitions or implement interface declarations. Overriding definitions are marked with an upward-pointing arrow and the letter o in the left margin; clicking this letter takes you to the overridden definition. Similarly, an upward-pointing arrow and the letter i in the margin identifies a method that implements an interface; clicking the letter takes you to the implemented method declaration.

Instructor Note Demonstration It may be useful to show students that these coding conventions can be customized to suit the user. Go to Tools > Preferences, and then choose the Code Editor node.



Page 225 of 545

Slide 27


Customizing JDeveloper 10g with OA Extension

Customize the IDE:

• Look and feel

• General environment

• Dockable windows

• Component Palette

• Preset keymaps

Customizing JDeveloper 10g with OA Extension Customizing the IDE You can customize JDeveloper’s default display options (for example, whether the splash screen is displayed at startup and whether dockable windows are always on top) as well as other general behavior (for example, whether JDeveloper automatically reloads externally modified files and whether output to the Log window is automatically saved to a file). You can do all of the following:

Customize the general environment for the IDE. Customize dockable windows for the IDE. Customize the Component Palette. Load preset keymaps and customize individual accelerators.You can take

advantage of the several existing keymap sets in JDeveloper or begin with an existing keymap and then customize it to suit your own coding style by changing which keyboard shortcuts, or accelerators, map to which actions.

Customize options for the Code Editor. Add external tools to JDeveloper.



Page 226 of 545

Slide 28


Refactoring Java Files

Modify the structure of code without changing its behavior (or breaking it).

Refactoring Refactoring is the process of improving an application by reorganizing its internal structure without changing its external behavior. In JDeveloper, you can make these changes without breaking any dependent files on which your project relies because these files are automatically updated for you. Oracle JDeveloper 10g with OA Extension provides an even more powerful refactoring framework; as a result, performing refactoring actions is faster and much smoother. You can now right-click a method or field in the Java Structure window (or in the Code Editor) to initiate refactoring. When refactoring, JDeveloper searches your entire project and any projects that are listed in Tools > Project Properties, Dependencies. Before proceeding with a refactoring action, you have the option of previewing the occurrences that will be updated (as the slide shows). You can then choose to continue with the refactoring action or cancel it. You can even undo refactoring if needed.



Page 227 of 545

Slide 29


Refactoring Java Files

• Drag-and-drop refactoring

• Refactor across entire application

• Refactor across source control

• More than 35 new refactoring operations, including:

- Rename Class

- Rename Field

- Rename Method

- Rename Package

- Rename Parameter

- Change Method Signature

- Introduce Variable

- Introduce Field

- Extract Interface

- Use Supertype Where Possible

- Move Class

- Duplicate Class

- Pull Members Up

- Safe Delete

Refactoring (continued) You can refactor across an entire application. In particular, you can refactor across multiple projects (via project dependencies). Some of the available refactoring operations are: Rename Class: Renames a class, its constructors, and its source file and updates all references to the class in the project Rename Field: Renames a field and updates all references to the field in the project Rename Method: Renames a method and updates all references to the method in the project Rename Package: Renames a package and updates all references to the package in the project (including organization of subpackages) Rename Local Variable: Renames a local variable and updates all references to the variable Rename Parameter: Renames a parameter and updates all references to the parameter Introduce Variable/Field/Constant/Parameter: Replaces the selected expression with a new expression of the same type Extract Method: Creates a new method from the selected code, setting up parameters for any variables that need to be passed to the new method Extract Interface: Creates a new interface from any of the public methods in the current type definition and implements that interface for the current type



Page 228 of 545

Use Supertype Where Possible: Replaces all occurrences of a type with one of its supertypes if applicable Pull Members Up: Promotes the declaration of methods or fields to the supertype and updates references accordingly Push Members Down: Moves the declaration of methods or fields to all the subtypes of the current type and updates references accordingly Delete Safely: Checks to make sure that the element you are attempting to delete is not actually being used in your code before allowing the delete operation to proceed. If references are found, you are warned and given the option to cancel the delete operation. Delete Safely can be used when deleting types, methods, and fields. You can also Reformat Java files so that the indents and spaces are compliant with standards. The Reformat command in on the same pop out window as Refactor. Reformat changes the immediate file and not the entire project.



Page 229 of 545

Slide 30


JDeveloper Help System

JDeveloper Help System To make the best use of JDeveloper tools and libraries, and of Java itself, you can use a comprehensive help system that covers all aspects of Java development. To access the help system:

1. Select Help > Table of Contents in the main menu. The help system appears. 2. Select one of the topics from the content navigator at the left of the window.

After you select a topic, the topic expands to display subtopics. 3. Select the topic you are interested in and right-click it to display the help text

in a window. Use hypertext links to navigate within a topic or to related topics.

Note: The JDeveloper 10g with OA Extension contains both the JDeveloper 10g help and the specific help for the additional components provided by OA Extension and OA Framework. Contained within the Help System, you will find several Tutorials. The Tutorials in the help system are legacy and may not work with the E-Business suite release 12.x. The Tutorials will contain obsolete examples or non functioning examples. Do not use any of the code snippets from the Tutorials for this class. Remember, portions of the Help system come from the generic 10g JDeveloper and do not contain or pertain to the OAF extensions. Note: The Oracle University course you are taking represents the most up-to-date version of the legacy based Tutorial and contains examples that are not within the legacy Tutorials.



Page 230 of 545



Page 231 of 545

Slide 31


Obtaining Help on a Topic

Use [F1] to invoke context-specific help.

Obtaining Help on a Topic Pressing the [F1] key invokes a context-sensitive Help topic window. Javadoc is a tool that parses the declarations and documentation comments in a set of source files and produces a set of HTML pages describing the classes, inner classes, interfaces, constructors, methods, and fields. When working in the Code Editor, you can quickly access the specific javadoc entry for any element in the source file. To browse the specific javadoc entry for a given class, member, or method, select the appropriate code element, right-click, and choose Quick Javadoc. A pop-up window with javadoc for just that element appears.

Instructor Note At this time, you may want to demonstrate Javadoc and show how to use it. If you have problems getting the java documentation on the Sun site, you can fix it with the following settings: Tools � Preferences; select the Web Browser and Proxy node. Select the Use HTTP Proxy Server check box and name the Host Name (that is, edu-proxy.us.oracle.com). Set the Port Number (80). Click OK.



Page 232 of 545

Slide 32


Oracle JDeveloper Debugger

• Helps find and fix program errors:

– Run-time errors

– Logic errors

• Allows control of execution

• Allows examination of variables

Oracle JDeveloper Debugger Debugging is the process of looking for program errors that prevent your program from doing what you intended. There are two basic types of program errors: run-time errors and logic errors. Remember that the compiler catches any syntax problems. If your program successfully compiles but gives run-time exceptions or hangs, then you have a run-time error. That is, your program contains valid statements but is encountering errors when they are executed. For example, you may be trying to open a file that does not exist or you may be trying to divide by zero. Logic errors are errors in the design and implementation of your program. That is, your program statements are valid and do something, but the results are not what you intended them to be. This type of error is usually the most difficult to find. The debugger enables you to control the execution of your program. It provides the ability to execute parts of the code step by step. You can also set breakpoints that pause the program execution when it reaches the line of code you want to examine. While the program is paused, you can inspect and even modify program variables. This helps you examine loops and other control structures to make sure that what is happening is what you intended. Breakpoints Breakpoints are a convenient way of tracing the cause of a problem in a program. When the debugger encounters a breakpoint, it pauses program execution. You can resume execution, stepping through the code line by line and examining



Page 233 of 545

variables and conditions. Or you can simply stop the program. You can set as many breakpoints as you want. Watchpoints A watchpoint is a new type of breakpoint in JDeveloper 10g with OA Extension. A watchpoint is a breakpoint that breaks on a value change. Watchpoints enable you to pause the debugger when the value of a specified field is accessed or modified. You set a watchpoint by right-clicking a variable in the Code Editor and choosing Toggle Watchpoint from the shortcut menu.



Page 234 of 545

Slide 33


Breakpoints

Setting breakpoints:

• Manage multiple breakpoints

• Manage conditional breakpoints

• Define columns displayed in window

– Description

– Type

– Status

• Control scope of action

– Global > Application > Project

Breakpoints Setting Breakpoints To set a breakpoint, you select a line of code in the source code window, right-click, and then select Toggle Breakpoint. You can click in the left margin to set a new breakpoint. After you start debugging, breakpoints that are known to be valid have a check mark in the breakpoint icon. A breakpoint without a check mark may mean that this line does not represent code where the debugger can stop. However, it might simply mean that the debugger does not yet know whether the breakpoint is valid or invalid. Viewing Breakpoints To view all the currently enabled breakpoints, select View > Breakpoints from the menu bar. A window appears showing all the breakpoints that are set in the program. To disable or remove a breakpoint, right-click the breakpoint and select an action from the shortcut menu. Conditional Breakpoints To set the conditions on which you want a breakpoint to be activated, right-click a breakpoint and select Edit Breakpoint. On the Breakpoint Conditions tab, you can specify information about how and when the breakpoint is activated (including valid Java conditional statements and thread-specific conditions). Display Settings To select the columns that are displayed in the breakpoints window, right-click in the breakpoints window and select Settings. In the dialog box, select Debugger > Breakpoints in the navigator tree on the left, and then select the columns to display.



Page 235 of 545

Scope Settings To select the scope for debugging, right-click in the breakpoints window, select Change Scope, and then select the appropriate value.



Page 236 of 545

Slide 34


Breaking on Exceptions

• When you get an exception, create a new breakpoint with the Exception breakpoint type.

• Copy your exception from the error message exception stack and paste it into your new breakpoint.



Page 237 of 545

Slide 35


Debugger Windows

View debugging information:

• Classes: Displays list of loaded classes and status

• Watch: Evaluates and displays expressions

• Monitors: Displays information about active monitors

• Threads: Displays the names and statuses of all threads

• Smart Data: Analyzes source code near execution point

• … and more

Debugger Windows Make sure that the project is selected, and then click the Debug icon. Alternatively, in the menu bar you can select Debug > Debug <Project Name>.jpr. This causes any required files to be compiled and then starts your program in debug mode. Debugging Windows As soon as you start the debugger, three tabs are added to a new window at the lower-right side of JDeveloper: the Smart Data tab, the Data tab, and the Watch tab. A new tab is added to the existing message window. You can use this tab to monitor the code as it executes. Fields for each window can be modified in the Tools > Preferences menu in the Debugger node. Smart Data tab: Displays only the data that appears to be relevant to the source code you are stepping through Data tab: Displays all the arguments, local variables, and static fields for the current method Watch tab: Displays the current value of an expression that you have flagged to appear during execution of the program Remote Debugging: You can manually launch the program you want to debug and then start the debugger. In the Host list, select the name of the machine where the program has started. After the debugger is attached to the running program, remote debugging is similar to local debugging.



Page 238 of 545



Page 239 of 545

Slide 36


Stepping Through a Program

Use the buttons on the debugger toolbar:

• Start the debugger.

• Resume the program.

• Step over a method call.

• Step into a method call.

• Step out of a method call.

• Step to the end of the method.

• Pause execution.

• Stop the debugger.

Stepping Through a Program Click the following buttons in the debugger toolbar: Start the debugger: Executes the program in debug mode. The program is paused when it encounters a breakpoint. If no breakpoints are set, you can pause the program by clicking the “Pause execution” button. Resume the program: Resumes the program after stopping at a breakpoint Step over a method call: Executes the method at the current position in the program at full speed rather than tracing the method line by line Step into a method call: Traces a method line by line. This is useful when you suspect that the method may be the one that is causing the problem. Step out of a method call: Enables you to step out of the current method and return to the next instruction of the calling method Step to the end of the method: Jumps to the end of the method Pause execution: Pauses a running program at its current position Stop the debugger:



Page 240 of 545

Stops the execution of a running program. This is a useful way of killing the program.

Slide 37


Watching Data and Variables

• The Smart Data tab displays analyzed variables and fields.

• The Data tab displays arguments, local variables, and static fields from the current context.

• To watch other variables:

1. Select a variable in the source window and right-click.

2. Select Watch... at Cursor from the shortcut menu.

3. View the variable in the Watch tab.

4. Right-click a data item to modify it.

Watching Data and Variables Viewing Analyzed Data on the Smart Data Tab The debugger analyzes the source code near the execution point, looking for variables and fields expressions that are used in the lines of code. By default, the debugger analyzes only one line of code for each location. Viewing Local Variables on the Data Tab The Data tab is the lower window that is displayed when you click the Debug tab at the bottom of the Applications Navigator. The Data tab automatically displays a list of local variables, static fields, and arguments that are in scope. As you jump from one method to the next, the list of variables displayed on the Data tab changes. Selecting Other Variables and Expressions to Watch Other variables and expressions can be viewed by following the steps described in the slide. Select a variable or expression such as age+10. Right-click the variable or expression and select “Watch… at Cursor” from the shortcut menu. A dialog box displays the selected variable or expression; click OK to accept it and add it to the Watch tab. View the variables that you have selected to monitor on the Watch tab. To modify a data value, right-click it and select Modify Value from the shortcut menu.



Page 241 of 545



Page 242 of 545

Slide 38


Debugging Declarative Applications

Pages built with the OA Framework are mostly made up of declarative data, so debugging often requires more than just the debugger.

• Read any error messages carefully.

– Look for spelling or other mistakes.

– The exception stack gives you information on what classes and lines of code to look at.

• Look at information in the log window of JDeveloper.

– Compiler messages often have useful warnings.

– The Embedded OC4J window shows runtime information.

For example, compiler messages can warn you that you forgot to provide a setting for important properties that would affect how the page runs. The Embedded OC4J window shows runtime information such as SQL statements being executed as well as their bind variables.



Page 243 of 545

Slide 39


More Debugging Tips

• Check the easy things first (spelling, capitalization, data).

• Check file locations by rolling over the filename in the Navigator.

• Look at page XML files to help locate bad declarative values within the page (do not edit them directly).

• Learn the common event flows such as commit cycles and button handling.

– See the OA Framework Developer's Guide for more information.



Page 244 of 545

Slide 40


Understand BC4J Interactions

• Follow BC4J interactions from an item (field) to the underlying BC4J objects.

– Root AM, View Instance, and View Attribute properties for a pageLayout region, tables, and items

— Are these set correctly?

– View object definitions and code

— Is the query correct? Does it return data?

— Are the attribute settings and mappings correct?

– Entity object definitions and code

– Entity associations and view links

– Application module definitions and code

— Are the view objects included correctly?



Page 245 of 545

Slide 41


Understand BC4J Interactions

• Check any redirections, links, and forwards to other pages or the same pages, either in Destination URI property or in code.

— Are view attribute names correct?

— Are you passing correct parameter names and values?

— Are page URL paths and function names correct?

• Check if a page is getting the AM state information it expects.

— Does the page have AM State Required set correctly?

— Is the RetainAM flag set correctly for the transition to the page?



Page 246 of 545

Slide 42


Debugging Validation and Commits

If you are using entity experts, validation VOs, and validation AMs and getting errors:

• Is the ExpertClass property set correctly on the owning entity object?

• Is the VAMDef property set correctly on the owning entity object?

• Are the validation VOs included in the VAM?

• Does the validation code reference objects such as VO instances correctly?

• If you are writing data back to the entity object (in processFormData, through the VO), was the entity object actually created properly?



Page 247 of 545

Slide 43


Summary


• Use JDeveloper 10g with OA Extension.

• Use the JDeveloper 10g debugger.

• Configure JDeveloper 10g with OA Extension to connect to an E-Business Suite instance to run OA Framework pages.



Page 248 of 545

Deploying OA Framework Applications






Page 249 of 545

Slide 2


Objectives

After completing this lesson you should be able to:

• Describe the personalization directory structure

• List the tools used for deploying personalizations

• Inspect the MDS repository for personalization documents

• Deploy personalizations

• Deploy a custom page

• Deploy business logic extensions

Instructor Note: Demonstrate a personalization to the students. Do the following: • Login to apps as SYSADMIN/SYSADMIN • Select the iProcurement responsibility, and go to the default page. • Click the “About this page” link. • Click the Personalizations tab. • Note the Oracle-seeded personalizations applied to the base page.



Page 250 of 545

Slide 3


Storing Personalizations

The personalization information (metadata) of a region / page is stored as a personalization document in the MDS repository, with a specific directory structure.

The directory structure for:

Original page Personalization file

+ <component> + <component>

+ webui + webui

file.xml + customizations

+ <layer type>

+ <layer value>

+ file.xml

MDS Repository Documents The MDS Repository is the database that stores the metadata of your OA Framework-based pages and regions, as well as information on any personalizations that have been created in your system. Each metadata definition of a region, page or personalization is called a document. This document is stored in JDR_PATHS, JDR_COMPONENTS and JDR_ATTRIBUTES tables. JDR_PATHS – has columns that store document path. JDR_COMPONENTS – has columns that store component information. JDR_ATTRIBUTES – has columns that store attribute information.



Page 251 of 545

Slide 4


Directory Structure

To understand the storage structure in the MDS let’s look at the following example:

If the following page is personalized at site level:/oracle/apps/fnd/wf/worklist/webui/AdvancWorklistRG

The page will be stored in the MDS repository with the following structure:/oracle/apps/fnd/wf/worklist/webui/customizations/

site/0/AdvancWorklistRG

site - customization layer type

0 – customization layer value



Page 252 of 545

Slide 5


Directory Structure - Layer Values

<layer type>

Function

Location

Site

Organization

Responsibility

User

<layer value>

Function Name

Location ID

0

Organization ID

Responsibility ID

User ID

Note: One quirk of interest. Please notice that the Location, Organization, Responsibility and User all use the ID. There may be cases where IDs exist on your Development system and not in Production, and vice-versa. You must test this carefully when deploying.



Page 253 of 545

Slide 6


Toolset

The personalizations are deployed from the:

• Functional Administrator responsibility page.

– Export to File System button

– Import from File System button

• Command line.

– Using .bat files (export.bat, import.bat, jpxImport.bat)

– Using command-line .java files

— XMLExporter

— XMLImporter

— JPXImporter

XMLExporter – exports personalization from MDS repository to .xml file. XMLImporter – imports personalizations into MDS repository. JPXImporter – imports substitutions specified in the .jpx file to the MDS repository. The export/import batch files are shipped along with OA Extension to JDeveloper. These batch files have the script to run the XMLExporter and XMLImporter java files.



Page 254 of 545

Slide 7


Functional Administrator Personalization UI

The Functional Administrator responsibility page provides an Import/Export tab that lets the user:

• Import the personalization documents into the MDS repository from the file system.

• Export the personalization documents from the MDS repository to the file system.

You can only work with Personalizations from this UI. It does not allow the import/export of OA Framework pages or BC4J substitutions.



Page 255 of 545

Slide 8


export.bat / import.bat- Syntax

export/import <Document_Name> <parameters>

<Document_Name > - full path to XML filename

Supported parameters:

-rootdir <output_dir/input_dir>

-username <database username>

-password <database password>

-dbconnection <database>

-rootdir = directory where the exported xml file needs to be stored -username = username for the database to export from -password = password for the database to export from -dbconnection = connection for the MDS



Page 256 of 545

Slide 9


export.bat/import.bat - Example

For example, to export the HelloWorldPG from MDS repository to the file system:

• Go to Windows Command Prompt.

• Change to <Jdev_Install_Dir>\Jdev\bin.

• Run the following command:

export /oracle/apps/ak/hello/webui/HelloWorldPG.xml

-rootdir d:\jdeveloper\jdev\myprojects

-username apps -password apps

-dbconnection es0006.oracle.com:1521:es0006

The –dbconnection information can actually be in one of two formats: Format 1: The long format You can put the entire TNS Names entry. For example, your entry might read as follows:

-dbconnection "(description = (address_list = (address =

(community = tcp.world)(protocol = tcp) (host

=es0006.oracle.com)(port = 1521))) (connect_data = (sid =

es0006)))“

Format 2: The short format (preferred) You can put an entry similar to the following:




Page 257 of 545

Slide 10


Command Line – XMLExporter/XMLImporter

• Exports/imports the personalizations from the MDS repository to an .xml file (same as export.bat).

• Is available along with the Oracle E-Business Suite runtime environment.

• Does not require JDeveloper with OA Extension.

java oracle.jrad.tools.xml.exporter.XMLExporter

<Document_Name> <params>

java oracle.jrad.tools.xml.importer.XMLImporter


This tool can be run from either the JDeveloper with OA Extension install, or it can be run on the Admin Server where the files will be stored.



Page 258 of 545

Slide 11


export.bat vs. XMLExporter

• Both have same usage and syntax.

• The export.bat batch file is available only with JDeveloper with OA Extension, whereas the XMLExporter.class file is available as part of Oracle E-Business Suite runtime environment.

• Same is true for import.bat vs. XMLImporter.



Page 259 of 545

Slide 12


Import Substitutions – JPXImport.bat

• JPXImport.bat is used to import the BC4J substitution documents into the MDS repository.

• Is available as part of JDeveloper with OA Extension and has the script that runs the JPXImporter.java file.

• JPXImport:

– Parses the .jpx file for each BC4J substitution defined in the file.

– Transforms each substitution into a separate site level customization document.

– Imports the customization document into the MDS repository.



Page 260 of 545

Slide 13


JPXImport.bat - Syntax

JPXImport <full_path_of_file> <parameters>

<full_path_of_file > - full path of the .jpx file to import





-username = username for the database to import to -password = password for the database to import to -dbconnection = connection for the database to import to, in tnsnames format



Page 261 of 545

Slide 14


Import Substitutions – JPXImporter

• JPXImporter is used to import the BC4J substitution documents into the MDS repository (same as the JPXImport.bat).

• Is available as part Oracle E-Business Suite runtime environment.




Page 262 of 545

Slide 15


Inspecting the MDS Repository

• Before deploying, the personalizations stored in the MDS repository can be inspected using JDR_UTILS PL/SQL package (optional step).

• The JDR_UTILS PL/SQL package provides procedures to:

– List the personalizations done on a page.

– Inspect the personalizations by extracting the required personalization document - site , function, user or responsibility level personalization documents.

Using JDR_UTILS in SQL*Plus You can use SQL*Plus to review all the personalizations for a given base document. JDR_UTILS is a PL/SQL package that allows you to evaluate the list of personalization documents that are in your MDS repository. Included in this package is a procedure called JDR_UTILS.listcustomizations( ); which allows you to see the personalization document path names that are currently defined in the MDS repository. See "Inspecting the MDS Repository Content" in the OA Framework Developer's Guide for more information on the JDR_UTILS package. This package should never be called from any program code.



Page 263 of 545

Slide 16


JDR_UTILS PL/SQL package APIs

The JDR_UTILS PL/SQL package contains the

following APIs to inspect the MDS repository:

• deleteDocument

• deletePackage

• exportDocument

• getComponentName

• getDocumentName

• getTranslations

• listContents

• listDocuments

• listLanguages

• printDocument

• printTranslations

• saveTranslations

• deleteEmptyCustomizations

PROCEDURE deleteDocument(p_document VARCHAR2); -- Deletes all empty customization documents from the repository. An empty -- customization document is a customization document that does not specify -- any modifications to the base metadata. -- -- Example 1: /oracle/apps/hr/customizations/localization/US/page1 -- <customization customizes="/oracle/apps/hr/page1" -- xmlns="http://xmlns.oracle.com/jrad" -- xmlns:ui="http://xmlns.oracle.com/uix/ui" -- xmlns:oa="http://xmlns.oracle.com/oa" -- xmlns:user="http://xmlns.oracle.com/jrad/user" -- file-version="$Header: JDRUTEXS.pls 120.3 2005/10/26 06:16:00 akbansal noship $" version="9.0.3.6.6_557" -- xml:lang="en-US"> -- <modifications/> -- </customization> -- -- Example 2: /oracle/apps/hr/customizations/user/100/page1 -- <customization customizes="/oracle/apps/hr/page1" -- xmlns="http://xmlns.oracle.com/jrad" -- xmlns:ui="http://xmlns.oracle.com/uix/ui" -- xmlns:oa="http://xmlns.oracle.com/oa" -- xmlns:user="http://xmlns.oracle.com/jrad/user"



Page 264 of 545

-- file-version="$Header: JDRUTEXS.pls 120.3 2005/10/26 06:16:00 akbansal noship $" version="9.0.3.6.6_557" -- xml:lang="en-US"> -- <views> -- <view name="MyTest10" description="my view" -- id="view1" element="Region1"> -- <modifications/> -- </view> -- <views/> -- <customization/> PROCEDURE deleteEmptyCustomizations; -- Deletes the package from the repository if the package is empty. If the -- package is not empty (i.e. it contains either documents or packages), then -- an error will be issued indicated that non-empty packages can not be -- deleted. -- -- Parameters: -- p_package - the fully qualified package name -- (i.e. '/oracle/apps') PROCEDURE deletePackage(p_package VARCHAR2); -- Export the XML for a document and pass it back in 32k chunks. This -- function will return XML chunks, with a maximum size of 32k. -- -- Specifying a document name will initiate the export. Thereafter, a NULL -- document name should be passed in until the export is complete. -- That is, to export an entire document, you should do: -- -- firstChunk := jdr_utils.exportDocument('/oracle/apps/fnd/mydoc', isDone); -- WHILE (NOT isDone) LOOP -- nextChunk := jdr_utils.exportDocument(NULL, isDone); -- END LOOP; -- -- Parameters: -- p_document - the fully qualified name of the document. However, -- after the first chunk of text is exported, a NULL -- value must be passed in to retrieve the next -- chunks. -- -- p_exportFinished - OUT parameter which indicates whether or not the export -- is complete. TRUE indicates the entire document is -- exported, FALSE indicates that there are more chunks -- remaining. -- -- p_formatted - TRUE indicates that the XML is formatted nicely -- (i.e. whether or not the elements are indented). -- This is defaulted to TRUE.



Page 265 of 545

-- -- -- Returns: -- The exported XML, in 32k chunks. -- -- Notes: -- As this function relies on package state, it is not possible to export -- multiple documents at the same time. A document must be finished -- exporting before a new document can be exported. FUNCTION exportDocument( p_document VARCHAR2, p_exportFinished OUT NOCOPY /* file.sql.39 change */ BOOLEAN, p_formatted BOOLEAN DEFAULT TRUE) RETURN VARCHAR2; -- Gets the fully qualified name of the component. -- -- Parameters: -- p_docid - the ID of the document which contains the component -- -- p_compid - the ID of the component (from comp_id in the -- jdr_components table FUNCTION getComponentName( p_docid jdr_paths.path_docid%TYPE, p_compid jdr_components.comp_id%TYPE) RETURN VARCHAR2; -- Gets the fully qualified name of the document. -- -- Parameters: -- p_docid - the ID of the document FUNCTION getDocumentName( p_docid jdr_paths.path_docid%TYPE) RETURN VARCHAR2; -- Gets all of the translations of the specified document. -- -- Parameters: -- p_document - the fully qualified document name -- -- Raises NO_SUCH_DOCUMENT exception if the document does not exist. FUNCTION getTranslations( p_document VARCHAR2) RETURN translationList; -- Prints the contents of a package. -- -- For the non-recursive case, this will list the documents, -- package files and package directories. -- -- For the recursive case, this will list the document, package files -- and empty package directories (i.e. packages which contain no documents



Page 266 of 545

-- or child packages). -- -- In order to diferentiate documents from package directories, package -- directories will end with a '/'. -- -- Parameters: -- p_path - The path in which to list the documents. To specify -- the root directory, use '/'. -- -- p_recursive - If TRUE, recursively lists the contents of -- sub-directories. Defaults to FALSE. -- -- To use this from SQL*Plus, do: -- -- (1) set serveroutput on -- execute jdr_utils.listContents('/oracle/apps/ak'); -- This will list the contents of the ak directory, without showing -- the contents of the sub-directories. -- -- (2) set serveroutput on -- execute jdr_utils.listContents('/', TRUE); -- This will list the contents of the entire repository. -- sub-directories. PROCEDURE listContents(p_path VARCHAR2, p_recursive BOOLEAN DEFAULT FALSE); -- List the customizations for the specified document. -- -- Parameters: -- p_document - the fully qualified document name, which can represent -- either a document or package file. -- (i.e. '/oracle/apps/ak/attributeSets') PROCEDURE listDocuments(p_path VARCHAR2, p_recursive BOOLEAN DEFAULT FALSE); -- Lists the supported languages for the specified document. -- -- Parameters: -- p_document - the fully qualified document name, which can represent -- either a document or package file. -- (i.e. '/oracle/apps/ak/attributeSets') PROCEDURE listLanguages(p_document VARCHAR2); -- Prints the contents of a JRAD document to the console. -- -- Parameters: -- p_document - the fully qualified document name, which can represent -- either a document or package file.



Page 267 of 545

-- (i.e. '/oracle/apps/ak/attributeSets') -- -- p_maxLineSize - the maximum size of line. This defaults to 255 which is -- the maximim allowable size of a line (the 255 limit is -- a limitation of the DBMS_OUPUT package). -- -- Limitations: -- Documents larger than 1000000 bytes will fail as DBMS_OUPUT's maximim -- buffer is 1000000 bytes. -- -- To use this from SQL*Plus, do: -- set serveroutput on format wrapped (this is needed for leading spaces) -- set linesize 100 -- execute jdr_utils.printDocument('/oracle/apps/ak/attributeSets', 100); -- -- To create an XML file, you can create the following SQL file: -- set feedback off -- set serveroutput on format wrapped -- set linesize 100 -- spool (parameter 1) -- execute jdr_utils.printDocument('(parameter 2)', 100); -- spool off -- -- and call the file with: -- sqlplus scott/tiger @export.sql myxml.xml /oracle/apps/ak/attributeSets PROCEDURE printDocument(p_document VARCHAR2, p_maxLineSize NUMBER DEFAULT MAX_LINE_SIZE); -- Prints the translations for the document in XLIFF format. -- -- Parameters: -- p_document - the fully qualified document name, which can represent -- either a document or package file. -- (i.e. '/oracle/apps/ak/attributeSets') -- -- p_language - the language to use for the translations -- -- p_maxLineSize - the maximum size of line. This defaults to 255 which is -- the maximim allowable size of a line (the 255 limit is -- a limitation of the DBMS_OUPUT package). -- -- To use this from SQL*Plus, do: -- set serveroutput on format wrapped (this is needed for leading spaces) -- set linesize 100 -- execute jdr_utils.printTranslations('/oracle/apps/ak/attributeSets', -- 'mylanguage', 100); PROCEDURE printTranslations(p_document VARCHAR2,



Page 268 of 545

p_language VARCHAR2, p_maxLineSize NUMBER DEFAULT MAX_LINE_SIZE); -- Saves the specified translations for the specified document. -- -- This procedure will do the following: -- (1) Lock the document so as to prevent multiple users attempting -- to modify translations at the same time -- (2) Delete all of the translations for the specified document -- (3) Insert the new translations -- (4) Commit the data unless p_commit set to FALSE -- -- Please use this with care as it will delete all of the -- translations for the specified document. -- -- Parameters: -- p_document - the fully qualified document name -- -- p_translations - the list of translations to insert -- -- p_commit - if TRUE, the data is committed. Default is TRUE -- -- NOTE: If p_commit is set to FALSE, then the document will remain locked -- after the call to saveTranslations. In order to prevent a deadlock, a -- commit (or rollback) must occur to unlock the document. -- -- Raises NO_SUCH_DOCUMENT exception if the document does not exist. PROCEDURE saveTranslations( p_document VARCHAR2, p_translations translationList, p_commit BOOLEAN := TRUE);



Page 269 of 545

Slide 17


List the Personalizations Done on a Page

Use the PL/SQL procedure JDR_UTILS.listContents to list the personalizations done on a page.

SQL> set serveroutput on;

SQL> execute JDR_UTILS.listContents('/acme',TRUE);

Printing contents of /acme recursively

/acme/oracle/apps/fnd/framework/toolbox/tutorial/

webui/customizations/site/0/AcmePoSummaryCreatePG


webui/acmePoSummaryCreatePG

PL/SQL procedure successfully completed.



Page 270 of 545

Slide 18


Inspect Personalizations

Use the PL/SQL procedure JDR_UTILS.printDocument to inspect the

personalizations done on a page.

SQL> execute

JDR_UTILS.printDocument('/acme/oracle/apps/

fnd/framework/toolbox/tutorial/webui/customizat

ions/site/0/AcmePoSummaryCreatePG');

The above mentioned command will produce the following output. <?xml version='1.0' encoding='UTF-8'?>

<customization xmlns="http://xmlns.oracle.com/jrad"

version="9.0.5.4.79_479" xml:lang="en-US"

customizes="/acme/oracle/apps/fnd/framework/toolbox/tutorial/

webui/AcmePoSummaryCreatePG"

xmlns:oa="http://xmlns.oracle.com/oa">

<modifications>

<move element="OrdersRN.Status" after="OrdersRN.OrderNum"/>

…

<move element="OrdersRN.Description"

after="OrdersRN.Status"/>

<move element="OrdersRN.Buyer" after="OrdersRN.Description"/>

<move element="OrdersRN.Supplier" after="OrdersRN.Buyer"/>

<move element="OrdersRN.Currency" after="OrdersRN.Supplier"/>

<insert before="OrdersRN.Currency">

<oa:messageStyledText id="SiteName" adminCustomizable="true"

cellNoWrapFormat="false"

dataType="VARCHAR2" initSortSeq="none" prompt="Supplier Site"

queryable="false" rendered="true"

required="no" scope="." selectiveSearchCriteria="false"

serverUnvalidated="false" sortState="no" tipType="none"

totalValue="false" userCustomizable="false"



Page 271 of 545

vAlign="middle" viewAttr="SiteName" viewName="PoSummaryVO1"

warnAboutChanges="true"/>

…

</insert>

<move element="OrdersRN.OrderTotal"

after="OrdersRN.Currency"/>

<move element="OrdersRN.DeleteSwitcher"

after="OrdersRN.OrderTotal"/>

<move

element="OrdersRN.UpdateSwitcher"

after="OrdersRN.DeleteSwitcher"/>

</modifications>

</customization>



Page 272 of 545

Slide 19


Deploying Personalizations

Personalizations are first done on a test instance, verified and then deployed into the production instance.

To deploy personalizations from a test instance into a

production instance :

• Extract the personalizations from the test instance.

• Upload the personalizations into the production instance.



Page 273 of 545

Slide 20


Extract the Personalizations – Functional Administrator Page

• Login to E-Business Suite under the Functional Administrator Responsibility.

• Set the Personalization Document Root Pathprofile value to a directory in your file system.



Page 274 of 545

Slide 21


Set Personalization Document Root Path

The full Internal Profile Code is FND_PERZ_DOC_ROOT_PATH.



Page 275 of 545

Slide 22


Import/Export Personalizations

• From the Personalizations tab, select the Import/Export subtab.



Page 276 of 545

Slide 23


Extract the Personalizations – Select the Page

• Expand the Personalization Repository view

and select the page that needs to be exported to the file system.



Page 277 of 545

Slide 24


Extract the Personalizations – Export to File System

• Click on Export to File System button.



Page 278 of 545

Slide 25


Upload Personalizations into Production Instance – Functional Administrator Page

• Set the FND_PERZ_DOC_ROOT_PATH profile value to a

directory in your file system that has the personalization documents to be uploaded.

• Login to E-Business Suite under the Functional Administrator responsibility.


The profile option should be set at the User level to ensure security.



Page 279 of 545

Slide 26


Upload Personalizations into Production Instance – Exported Personalizations

• Select Exported Personalizations from the side

navigation menu.



Page 280 of 545

Slide 27


Upload Personalizations into Production Instance – Import from File System

• Expand the Exported Personalizations and select the page that needs to be imported from the file system.

• Click on Import from File System button.



Page 281 of 545

Slide 28


Extensions

OA Framework applications are extended by:

• Adding new content or business logic (OA page extensions).

• Extending/overriding existing business logic (BC4J extensions).

Extensions require either changes to Java code or changes to XML files that cannot be done via personalizations. Since personalizations deal with the UI objects, the XML files needed by extensions are BC4J-based XML files.



Page 282 of 545

Slide 29


OA Page Extensions

Custom (new) OA pages that are added to an existing application consist of:

• XML files that define the OA components and declarative properties specified for the pages

• One or more controller Java files

• BC4J XML and java files



Page 283 of 545

Slide 30


Deployment of Page Extensions

To deploy the page extensions:

1. Copy the corresponding controller and BC4J classes to the file system $JAVA_TOP.

2. Import the BC4J substitutions (if any) into the MDS repository.

3. Import the OA component definitions (in XML files) into the MDS repository.



Page 284 of 545

Slide 31


1.Copy .java Classes

• Copy the controller and BC4J classes to $JAVA_TOP:

– Compile the java files in JDeveloper and zip the class files.

– The zip file should contain all the custom BC4J java classes and the controller classes. Pick up the classes from -<JDEV_USER_HOME>\myclasses.

– Preserve the directory structure while zipping these files.

– Extract the zip to $JAVA_TOP.



Page 285 of 545

Slide 32


2. Import Substitutions

Run the jpximport utility to import the substitutions specified in the .jpx definition file into the MDS.

Example:<jdev_install_dir>\jdev\bin\jpximport

<JDEV_USER_HOME>\myprojects\ExtendLabSolutions.jpx



Instructor Note: Demonstrate a JPX file. Open the JPX file of your choice, and show the students how it is simply the substitutions area that you are uploading into the MDS.



Page 286 of 545

Slide 33


3. Import OA Component Definitions

Import the OA component definitions into the MDS using either:

• The Functional Administrator Responsibility page

• The import.bat/XMLImporter tool



Page 287 of 545

Slide 34


View The Deployed Extensions

• Bounce the web server.

• Review your deployed extensions.



Page 288 of 545

Slide 35


BC4J Extensions

Business components you extend consist of:

• XML files that provide the declarative properties for your extended business component.

• Extended Java files with the overridden methods that provide custom business logic programmatically.

Note: Extending BC4J objects is supported. Extending Controllers (CO) is not. Any work done to extend an Oracle-supplied Controller is by definition unsupported.



Page 289 of 545

Slide 36


Deployment of Business Logic Extensions

To deploy business logic extensions:

1. Compile your Java in JDeveloper and zip up your Java classes.

2. Extract the .zip to $JAVA_TOP.

3. Run the jpx import utility to import substitutions specified in the .jpx definition file to the MDS repository.

4. Bounce the web server (if required).

5. Review your deployed extensions.



Page 290 of 545

Slide 37


Summary

In this lessons, you should have learned to:

• Describe the personalization directory structure.

• List the tools used for deploying Personalizations.

• Inspect the MDS repository for personalization documents.

• Deploy Personalizations.

• Deploy a custom page.

• Deploy business logic extensions.

Open the Course Labs book. Complete Lab 10 – Deploying Personalizations Complete Lab 11 – Deploying Extensions



Page 291 of 545

Implementing Query Page and Drill Down Page


Implementing a Query Page and Drill Down Page




Page 292 of 545

Slide 2


Lesson Objectives


• Create a typical OA Framework query page

• Create a typical OA Framework drill-down to details page



Page 293 of 545

Slide 3


Course Method

For the remainder of the course, until Day 5, the focus is on programming. The lectures to follow are intentionally kept as short as possible to allow you as much time with hands-on programming labs.

OA Framework pages and applications can be incredibly complex. The labs are designed to remove as much complexity as possible, but there are subtle interactions between labs that can not be simplified.

Things to remember. • Java is case sensitive • SPEL is case sensitive • Select the correct attributes from your attribute sets. • Save your project and workspace frequently. • The labs are sequential and cumulative. • Do not change order or skip sections unless your instructors say you can. • Take your time and take frequent breaks. • Sometimes have another set of eyes to review your work. Looking at the same

error over and over will hide something that is apparent to another set of eyes. • This is a programming course, so give the instructor a little time to come up to

speed on exactly where you are in your steps and process. There is no magic code snippet that the instructor can use to correct days of incorrect steps.

• The initial labs and setting up the BC4J objects are the backbone for all that is to come.



Page 294 of 545

Slide 4


Course Method

It is critical that you follow the labs precisely. Your likelihood of success increases when you follow the labs. It also increases the likelihood of your instructor being able to assist you should you encounter unexpected behavior.

You can also improve your likelihood of success by improving your debugging skills. The debugging skills learned and practiced in this course will apply directly to real world OA Framework pages back in your work environment.

We want to convey, that if you understand the steps to make the error, your success in finding out what is not working when you get back to your company will be much greater. Remember that OAF is a J2EE framework. The Model, View, Controller are all components that make of your application. When you have something that doesn’t work right, think about the component that is directly responsible and how the linkage to the MVC creates pages and how they are interrelated. Think about what you see and don’t see in both the errors, and what is displayed when you run your test pages.



Page 295 of 545

Slide 5


Finished Page Before Search

Once you complete the lab, your Search page should look similar to the following before a search:

The actual labs will have the most up-to-date screen captures. The above screen capture is only an example.



Page 296 of 545

Slide 6


Finished Page After Search

Once you complete the lab, your Search page should look similar to the following after a search:




Page 297 of 545

Slide 7


Finished List of Values Page

Once you complete the lab, your LOV page should look similar to the following:




Page 298 of 545

Slide 8


Finished Drilldown-to-Details Page

Once you complete the lab, your Details page should look similar to the following:




Page 299 of 545

Slide 9


Summary


• Create a typical OA Framework query page.

• Create a typical OA Framework drill-down to details page.



Page 300 of 545

Implementing Create Page


Implementing a Create Page




Page 301 of 545

Slide 2


Lesson Objectives


• Create a typical OA Framework insert page

• Create a poplist on an OA Framework page

• Extend a shared region on an OA Framework page

• Write the programmatic code to respond to a button press on an OA Framework page



Page 302 of 545

Slide 3


Implementing a Poplist

Poplists use two view objects:

• VO for the base page item

– View Instance

– View Attribute

• VO for the values in the list

– Definition

– Value

– Meaning



Page 303 of 545

Slide 4


Extending a Shared Region

Use the Extends property to incorporate standard and other regions into your pages.

• Create a new region.

• Set the new region’s Extends property to the fully-qualified name of the region you want to include.

– For example, /oracle/apps/fnd/framework/webui/OAReqFieldDescRG

Whenever you need a BLAF-standard "Indicates Required Field" key in your page, you can simply extend the common OA Framework region by extending /oracle/apps/fnd/framework/webui/OAReqFieldDescRG. Note: For the Extends property, you may need to deselect the "Show Components With Valid Scope Only" check box in the dialog window if the shared region is outside your application packages or otherwise restricted in scope. In other cases you may want to restrict the choices to components with a valid scope, such as in your particular application.



Page 304 of 545

Slide 5


Creating a New Row

Before the user can enter a new row, the middle tier must be prepared to accept the data (usually during page initialization):

• Get and initialize the view object.

• Create an empty view object row, and corresponding entity object if any, on the middle tier.



Page 305 of 545

Slide 6


Initializing a View Object

OAViewObject vo = (OAViewObject)getDetailsVO1();

// This is the standards-compliant

// way to initialize a VO that is used

// for both inserts and queries.

if (!vo.isPreparedForExecution())

{

vo.executeQuery();

}

. . .

This code would typically be in a create() method in the application module for the page (such as a createEmployee() method in an EmployeeAMImpl.java file). The method would be invoked from the client-side controller code, either from processRequest() or processFormRequest().



Page 306 of 545

Slide 7


Creating and Initializing a VO Row

import oracle.jbo.Row;

. . .

Row row = vo.createRow();

vo.insertRow(row);

// OA Framework Model Coding Standard M69

row.setNewRowState(Row.STATUS_INITIALIZED);

. . .

This code would be right after the view object initialization in the create() method on the application module. The view object internally delegates to the entity object, if there is one, to execute entity object methods such as create(). The create() method provides any default values for the new row.



Page 307 of 545

Slide 8


Getting the Data

• The user enters values and does an action, such as pressing an Apply button, to cause a form submit.

• The processFormData method writes the user's data to the middle tier into the view object row and triggers validation.

• If the validation is successful, commit the row to the database.



Page 308 of 545

Slide 9


Saving a Row to the Database

import oracle.jbo.Transaction;

. . .

getTransaction().commit();



Page 309 of 545

Slide 10


Lab – After Create Basics

After the first part of the Lab, Create Basics, your progress should look similar to the following:




Page 310 of 545

Slide 11


Lab – After Validations

After the second part of the Lab, Validations, your progress should look similar to the following:




Page 311 of 545

Slide 12


Lab – After Validations

After the second part of the Lab, Validations, your progress should look similar to the following:




Page 312 of 545

Slide 13


Lab – After Partial Page Rendering

After the third part of the Lab, Partial Page Rendering, your progress should look similar to the following:

Note: This sample shows the Position field set to President. Notice that when the Position is President, there is no Manager field presented in the UI. The actual labs will have the most up-to-date screen captures. The above screen capture is only an example.



Page 313 of 545

Slide 14


Lab – After Partial Page Rendering

After the third part of the Lab, Partial Page Rendering, your progress should look similar to the following:

Note: This sample shows the Position field set to something other than President (Buyer in this case). Notice that when the Position is not President, there is a Manager field presented in the UI. The actual labs will have the most up-to-date screen captures. The above screen capture is only an example.



Page 314 of 545

Slide 15


Summary


• Create a typical OA Framework insert page.

• Create a poplist on an OA Framework page.

• Extend a shared region on an OA Framework page.

• Write the programmatic code to respond to a button press on an OA Framework page.

Slide 1


OA Framework State Management




Page 315 of 545

Schedule: Timing Topic 90 minutes Lecture 90 minutes Total



Page 316 of 545

Slide 2


Lesson Objectives


• Discuss OA Framework state management

• Discuss OA Framework state caches

• Discuss Passivation

• Discuss Back-button support

• Discuss Application Module pooling



Page 317 of 545

Slide 3


Architectural Overview – Session and Cookies

Everything starts with the browser. When the user enters the URL for the E-Business Suite instance, and they log in, a session is created in the database, and a session cookie is stored on the browser for that session. This is a security mechanism to prevent a cut-n-paste of URLs, and subsequent passage of those URLs to other users who may not have the proper security rights to that part of the application.



Page 318 of 545

Slide 4


Architectural Overview – JVM

Everything in Java runs inside a Java Virtual Machine (JVM), and OA Framework pages are no exception to that rule.



Page 319 of 545

Slide 5


State Caches in OA Framework

An OA Framework application has a number of state management caches. Data can be carried and passed through these caches, each with a different life span and usage scenario. The caches are as follows:

• Root Application Modules

• Servlet Session

• E-Business Suite User Session

• Page Context

• Request

Additionally, as all pages are run from within OA.jsp, there is a JSP cache that is part of the caching mechanism. However, the JSP cache is outside the scope of an OA Framework page and is outside the scope of this course.



Page 320 of 545

Slide 6


Root Application Modules

Each OA Framework page is associated with a root application module that provides its transaction context and JDBC database connection.

• One Root AM per transaction, be that a single page or multi-page transaction.

• The Root AM controls the transaction.

– Root AM contains OADBTransaction object.

– The OADBTransaction object is the primary means for keeping transaction data saved on view objects and entity objects.

• The Root AM persists as long as it is retained (such as across page transitions).

The Root AM is simply the first AM that is loaded. Initially, the Root AM is without connections or a transaction context. Once instantiated, the Root AM establishes the connections and creates the transaction context. The Root AM, shares the connection and context through the OA Framework transaction context for that user on that page (or set of pages).



Page 321 of 545

Slide 7


Root Application Modules

• The use of the browser Back button can cause the loss of application module state.

• Any data stored on the transaction is accessible to all pages that share the same root application module instance (assuming that navigation between them involves retaining this application module as described below).

• A single transaction can be accessed from both controller (client) and model (server) code, these utilities are provided in both.

Example: Imagine a typical multi-page ordering flow common to most e-Commerce sites. At the end of the transaction, the user is given a confirmation page and a summary page finalizing the transaction. The final page is the summary. In the transition from the confirmation page to the summary page, the user record is committed to the database as the transaction is final at that point. Whatever order/transaction the user has been performing is now finished. At the summary page, if the Back button were allowed, what would be the desired behavior? Should the transaction be uncommitted (rolled back)? The nature of web applications and the browser in which those applications run, makes it difficult to anticipate user behavior. The back button within the browser was originally created as a “Window History – 1” and was designed around static HTML pages. Transactional contexts were never built into Web Browsers and because of that, the back button’s use is sometimes problematic.



Page 322 of 545

Slide 8


Default Root Application Module Retention

By default, when the user navigates from one page to the next (such as with a GET request or a JSP forward), and OA Framework renders the new page, the application module instance associated with the previous page is "released," and a new instance is requested from an application module pool. Note: OA Framework never releases application modules during form submit (POST) requests unless you explicitly release the application module in a controller. For example, if a user sorts a table or navigates the result set within a table -- two actions that implicitly submit the page form -- the page's root application module instance is automatically retained.



Page 323 of 545

Slide 9


Retaining the Root Application Module

The default behavior as described above is desirable for individual pages that comprise an isolated, complete task. However, it is not appropriate for a multi-page flow that implements a single task, or a series of related pages participating in a virtual transaction. In these cases, the different pages should be associated with the same root application module instance. To achieve this, you must do the following:

Declaratively associate the same root application module type with each page in the multi-page flow.

Set the application module retention flag for a page by specifying the URL parameter retainAM=Y. For GET requests. This flag is evaluated when a new page is rendered (as mentioned above, OA Framework always retains the application module for POST requests regardless of the retainAM parameter value). If set to "Y," the previous page's application module instance will be retained. If set to "N" (or not specified, which implies "N"), OA Framework releases all application modules -- including any that might have been explicitly retained before reaching this point. You also set this parameter when calling JSP forward OAPageContext methods

Warning: It is not enough to simply associate the same root application module with each page. If you forget to set the retainAM flag, each page will have a different application module instance -- and transaction -- even though they are associated with the same application module type. Note: Technically, depending on the state of the application module pool, Page B could get a reference to the same physical application module instance that Page A



Page 324 of 545

used. However, the object's state will be completely reset as if created anew. For the purposes of this discussion, consider it a "new instance."



Page 325 of 545

Slide 10


Recommendation: Multipage Flow

A flow of related pages (query, update, insert, delete pages in the same virtual transaction):

• Retain the AM

– Everything hanging off the same menu item should usually use and retain the same AM (includes navigation through trains, links, and so on, but not another tab). These would be considered the same virtual transaction.

– Be careful to test for and handle back button problems.



Page 326 of 545

Slide 11


Recommendation: Multipage Flow with Side Trip

A multipage flow with a side trip to an unrelated page (which is in a separate transaction), such as creating a missing supplier during a requisition flow:

• Retain the AM to facilitate the multipage flow.

• Avoid carrying additional application modules with the main flow AM.



Page 327 of 545

Slide 12


Recommendation: Side Trip with Extended Page

• Incorporate the side-trip flow into the main flow by using an "extended page" with the same retained AM as the main flow.

– Create a new page with the main AM.

– At the pageLayout region, extend the pageLayout region of the side-trip page into the new page. The side-trip page AM will be nested under the main AM.



Page 328 of 545

Slide 13


Recommendation: Unrelated Pages Flow

A series of unrelated pages, each in a separate transaction, such as a setup flow:

• Do not retain the application modules.



Page 329 of 545

Slide 14


Servlet Session

A servlet session is a mechanism for maintaining state between HTTP requests during a period of continuous interaction between a browser and a web application. A session usually corresponds to an application login/logout cycle, but that is not strictly true in the case of OA Framework applications.

• Servlet Session persists until it times out or user logout.

• It is used for the following:

– Expensive-to-fetch data that is used across pages and transactions

– Only small serializable objects of Number, String and Date data types allowed

– Accessed through the OAPageContext

There are two hard-coded timeouts, based on idle-time and total connection time, which the user cannot override. These are done for security reasons.



Page 330 of 545

Slide 15


Applications User Session (ICX Session)

When the user logs in to an OA Framework application, the OA Framework creates WebAppsContext object and a browser session-based cookie that track key E-Business Suite context, responsibility, organization id, user name, user id, employee id and so on.

• The cookie contains an encrypted key identifier for a session row stored in the Applications database.

• User session times out based on profile settings.

– Typically lasts longer than the Servlet Session.

– An E-Business Suite user session might be associated with multiple servlet sessions. For example, the servlet session times out while the user takes a phone call, then resumes work before the E-Business Suite user session times out.

Since cookies are used, the user’s browser must be set to allow cookies, or at the very least allow cookies from the EBS servers.



Page 331 of 545

Slide 16


Page Context

• Each time a request is received for a page, the OA Framework creates an OAPageContext object

• OAPageContext persists until a new page finishes processing

• OAPageContext keeps references to Request Object and Root AM



Page 332 of 545

Slide 17


Request and Page Boundaries

A web application's unit of work is a request/response pair. The browser submits a request; the servlet processes the request and returns a response. The transmission of a response signifies the end of a single request, or the "boundary" between the completed request and a new one. Similarly, when the OAPageBean finishes processing a page, this is the "boundary" between the current page and a new one. So, in the following simple scenario where a user navigates from Page X to Page A and then to Page B, there are two request boundaries: the first is between Page X and Page A, the second is between Page A and Page B. There are also two page boundaries in the same conceptual location between Page X and Page A, and Page A and Page B.



Page 333 of 545

Slide 18


Request and Page Boundaries

In some situations, however, the request and page boundaries are not the same. Consider the following JSP Forward case: The user navigates from Page X to Page A as illustrated on the previous slide. While on Page A, the user selects a control that Page A code must evaluate before deciding which page to display in response. The browser issues a request to Page A, which OA Framework processes, including creating an OAPageContext for the page. Once Page A finishes processing, the first page boundary is reached as illustrated above. Within the Page A code, the developer evaluates which control the user selected and issues a JSP Forward to Page B. Instead of providing an HTTP response at this point , since we don't want to redisplay Page A, OA Framework begins processing for Page B, including creating a new OAPageContext for this page. Once Page B finishes processing, the second page boundary is reached. Since Page B must now be displayed to the user, an HTTP response it sent to the browser. The request boundary is now reached.



Page 334 of 545

It is important to understand this distinction for several reasons: Request parameters exist throughout the life span of the request -- which can span multiple page boundaries. This can be somewhat surprising for new OA Framework developers who simply assume that a request and a page are the same thing, and therefore do not account for request parameters "hanging around" after performing a JSP Forward. Consider the following example: A user selects a link in Page X that navigates to Page A. The Page A URL includes the parameter foo=bar. Page A issues a JSP Forward to Page B. Now, even though we are in a new page, the request still includes the value foo=bar. If you don't want a parameter value on the request after doing a JSP Forward, you must explicitly replace it. For example, in this case, simply reset the value to something like foo=X when you call the OAPageContext's setForward*() method. Note: You cannot actually remove parameters from a request. Tip: It is preferable to replace the unwanted parameter value with a new one that your code can use as an "ignore" value. Do not simply set the value to "". Since there isn't a one-to-one mapping between the page context and the request, some people find it a bit confusing that you access request parameters from the OAPageContext. Just remember that each page is a distinct entity, and from its "point of view," the OAPageContext represents the request. When you get into the details of passivation in Chapter 6, you'll see that page and request boundaries are distinct event points with different passivation implications.



Page 335 of 545

Slide 19


Request

Although short-lived, an object is created for each HTTP request. This object contains the following application state:

• Any URL parameters, regardless of whether the browser issued a POST or a GET request

• Assuming the browser issues a POST request: any form field data values.

• Assuming the browser issues a POST request: the web bean and event names associated with a user's selection of action/control components.

To access any of these request values, use OAPageContext getParameter*() methods. You will not interact directly with the request itself.



Page 336 of 545

Slide 20


Ways to Pass Parameters

• Append them to the URL

– Declaratively through JDeveloper or Personalization

– Programmatically by setting URI properties on some beans

• OAPageContext.putParameter

• OAPageContext.setForwardURL

• Hidden form fields are passed on the request during a POST (submit)

To put values on the request (the preferred way of communicating between pages) you can do any supported method listed below. Note: The following is a general description of the request-passing mechanisms; there are browser Back button considerations related to each of these techniques that you should fully understand before building your pages. Use Hidden Fields A "hidden" field is a tool for developers to get/set values on a form that can't be accessed by the user. Just as the user's field values are added to the request during a form submit, so are the developer's field values -- assuming your page issues a POST. You can create hidden fields declaratively in JDeveloper by selecting the formValue item style. At runtime, these are instantiated as an oracle.apps.fnd.framework.webui.beans.form.OAFormValueBean. Specify Values During JSP Forward/Client Redirect When you explicitly forward to a new page using the OAPageContext setForward*() methods or issue a client redirect by calling OAPageContext.sendRedirect(), you can optionally set request parameter values.



Page 337 of 545

For example, Page A includes a submit button. When this button is selected, the user navigates to Page B using a JSP Forward. Page A needs to pass a "mode" value to Page B, which can be accessed several different ways so it knows how to behave. The user selects the submit button. In the Page A controller that handles this button press, we call OAPageContext.setForwardURL() in the processFormRequest() method. As part of this method call, we pass a request parameter named queryMode with a value of automatic. In a Page B controller we check for the queryMode parameter value in the processRequest() method by calling getParameter("queryMode"). Page B's controller then responds to the fact that the queryMode value is automatic by immediately querying the data the page should display. Specify Values by Calling OAPageContext.putParameter() OAPageContext includes a putParameter() method that is used for passing values down the web bean hierarchy during page processing. Values specified with a call to putParameter() are not technically added to the request, but are stored in a special page cache. Tip: For those familiar with the HttpServletRequest.setAttribute() method in the Java servlet 2.1 API, which is simply a way of stashing some information on the HTTP request, consider this its equivalent. Set URL Parameters Declaratively Specify request parameter values when defining URLs declaratively in JDeveloper or by setting the URL programmatically on web beans that have associated URLs. Warning: The URL is space-constrained; be cautious about adding numerous URL parameters, particularly if they are lengthy. Since the URL is visible to users, encrypt any sensitive values.



Page 338 of 545

Slide 21


URL Parameters: Tokens, Encryption, Encoding

Declarative URL parameters in your page can specify both literal and token-substituted values The token types are as follows:

• {!Attr} - encrypts the attribute value while leaving the {!} in the URL.

• {@Attr} - encodes the attribute value while leaving the {@} in the URL.

• {$Attr} - plain token substitution (no encoding or encryption).

• {@@RETURN_TO_MENU} – As Destination URI property to return the user to the E-Business Suite Personal Home Page.

• {@@RETURN_TO_PORTAL} -- As Destination URI to return user to their launching Portal page.

Token Substitution Example (using the view object attribute name "OrderNum"): OA.jsp?OAFunc=FWK_TBX_T_PO_PAGE&order={@OrderNum} Literal Example: OA.jsp?OAFunc=FWK_TBX_T_PO_PAGE&order=123 Token Types Tokens use a special character prefix to tell the OA Framework how to resolve the value at runtime (note that the concepts of "encoding " and "encryption " are described below): {!Attr} - encrypts the attribute value while leaving the {!} in the URL {@Attr} - encodes the attribute value while leaving the {@} in the URL {$Attr} - plain token substitution (no encoding or encryption) {@@RETURN_TO_MENU} - Can be used exactly as shown to specify the Destination URI property of an application component if you want it to return the user to the E-Business Suite Personal Home Page. If you need to specify this when performing a JSP forward, the corresponding constant for this is OAWebBeanValues.RETURN_TO_MENU_URL.



Page 339 of 545

{@@RETURN_TO_PORTAL} -- Can be used exactly as shown to specify the Destination URI property of an application component if you want it to return the user to a launching Portal page. If you need to specify this when performing a JSP forward, the corresponding constant for this is OAWebBeanValues.RETURN_TO_PORTAL_URL. Encoding Any value that you specify for a request parameter must conform to HTTP syntax rules. For example, you can't pass a URL parameter value with a blank space ; the following parameter value would cause a runtime error when the corresponding URL is accessed:buyerName=John Doe. To fix this, we encode these values, meaning that the encoding routine replaces problematic characters with standard substitutions as shown in this example:buyerName=John%20Doe. When the OA Framework adds parameters to the request (form field values, for example), it automatically encodes them. When you put parameters on the request during a call to a setForward* method, the OA Framework automatically encodes these values. When you put parameters on a URL that you assemble yourself (if, for example, you set a bean's URL by calling its setDestination method), you must encode any part of the String that could include invalid characters. To do this, you pass the String to an encode method on the oracle.apps.fnd.framework.webui.OAUrl utility class. Tip: If you manually set a URL parameter value that can't include invalid characters (for example, "value=Y") then you don't need to bother with the encoding step. When you put values on the request using OAPageContext.putParameter, you must encode the String if necessary. The OA Framework automatically decodes parameter values when you call the OAPageContext.getParameter* methods, except for the following cases: When you use the "#" character for Javascript function tokens, the OA Framework encodes the token values, but it does NOT automatically decode them when you call pageContext.getParameter("<tokenName>"). To do this yourself, you'll need to use the OAUrl decode method on the value that getParameter returns. When you call putParameter with an encoded value, the OA Framework does not decode it. You must also use the OAUrl decode method in this case on the value the getParameter returns. Encryption



Page 340 of 545

Encryption is the process of obfuscating data to make it illegible. Since URL request parameter values may be visible to the user (and hidden form field values if the user opts to view the HTML page source), you should always encrypt sensitive data if stored in a URL parameter or a hidden field. In addition to the declarative, token-based encryption described above, the OA Framework also provides methods in oracle.apps.fnd.framework.webui.OAPageContext for manually encrypting and decrypting any parameter values that you put on the request programmatically.



Page 341 of 545

Slide 22


Passivation

• Passivation provides a mechanism for saving middle tier state off to the database

– Reclaim resources (connections and memory)

– Continue a transaction after a session timeout (future)

– Failover on the middle tier (future)

• Middle tier state known to Framework or BC4J will be passivated automatically if passivation is enabled.

Note: Passivation is not being released in R12, but there are already actions that you can take to allow passivation (such as setting the RETENTION_LEVEL property on your AMs to MANAGE_STATE) and the Transaction Undo feature, which leverages passivation and is supported.



Page 342 of 545

Slide 23


Passivation

• A passivated page flow may not keep the same database session across requests

– Avoid using PL/SQL package variables

• Enable by creating RETENTION_LEVEL property on AM and setting to MANAGE_STATE

– Not setting, or setting to RESERVE_FULL, disables passivation for that application module and can create a resource problem

– Follow all passivation-related standards in the Oracle Application Framework Developer's Guide.

Passivation is not fully implemented in most systems due to the significant resources requirements. However, such common features as “Save for Later” are artifacts of the Passivation technology.



Page 343 of 545

Slide 24


Application Module Pooling

To improve performance and scalability, OA Framework pools (caches and reuses) application modules. Reuse is much more efficient than re-creation. In simple terms:

• Each JVM has an AM pool manager that contains and manages individual AMs.

• Each AM pool contains multiple instances of the same AM. In other words, a pool is created for each root AM type in your product.

• AM instances within the pool are designated as being available for use, or unavailable (currently "checked out").

• Only root AMs are pooled; nested AMs are pooled as children of the root AM.

Without connection pooling, it would be both possible and probable for there to be connection leaks. Given that opening and closing connections are expensive instructions, it significantly impacts middle-tier performance if there is no AM pooling.



Page 344 of 545

Slide 25


Application Module Pooling



Page 345 of 545

Slide 26


Application Module and Connection Pooling

Pooling is a mechanism where cached objects kept in a runtime object pool can be used and reused as needed by an application. Instead of creating an object when requested by an application and destroying it when released by the application, you can pool these objects and reuse them when required. This saves the creation time associated with the object and improves performance and scalability. A pool manager manages the objects in the pool. When an object is requested, it looks for an available object in the pool. If there isn't any, it creates one, up to the maximum allowable objects. If it can't create an object, it waits for one to be released and depending on the implementation may eventually display an error indicating that it was unable to retrieve the object. The OA Framework pools the application modules and the connections used by application modules. This chapter describes these two pools and the various options that configure each pool. You will also learn how to diagnose and troubleshoot performance and scalability issues associated with pooling in your application. The Application Module (AM) instances are pooled in an Application Module Pool (also known as AM Pool). Each JVM has an application module pool manager that contains and manages individual application module pools. Each application module pool contains multiple instances of the same application module definition. In other words, a pool is created for each root application module definition (type) in your product. Application module instances within the pool are designated as being available for use, or unavailable (currently "checked out"). Only root application modules are pooled. Nested application modules are pooled as children



Page 346 of 545

of the root application module; they cannot be checked out or checked in independently of the parent. In addition to pooling the AMs, the OA Framework relies upon AOL/J to pool the connections used by them. The AMs reuse a pool of connections instead of creating a JDBC connection for every new instance and destroying it when the instance disconnects. A connection pool is assigned for each JDBC connection URL; currently in OA Framework, only one DBC file (and hence, only one JDBC connection URL) is allowed per JVM.



Page 347 of 545

Slide 27


Application Module Pooling Process

Checkout: When a page requires a root AM.

1. OA Framework retrieves the AM pool manager for the JVM. If the AM pool manager doesn't exist, it is created.

2. OA Framework then retrieves the AM pool from the AM pool manager. If the AM pool doesn't exist, it is created.

3. If the AM pool contains an available AM instance, it is checked out (meaning it is marked as being unavailable (locked) so others can't use it). If the AM pool doesn't have any available AM instances, a new AM instance is created and checked out.



Page 348 of 545

Slide 28



Checkout: When a page requires a root AM.

4. Upon checkout, BC4J ensures the connection associated with an AM is in a usable state. If the connection is not usable, BC4J disconnects and reconnects the AM to request another connection from the Connection pool.



Page 349 of 545

Slide 29



Checkin: AM released without state.

1. VO data is cleared.

2. The database transaction is rolled back.

3. Any cached data on the transaction for the root AM is cleared (note that product-specific AM member variables are NOT automatically cleared by OA Framework and should be avoided for this reason. The product-specific AM member variables should be cleared by overriding OAApplicationModuleImpl beforeRelease() method. See the OAApplicationModuleImpl beforeRelease() javadoc for more information.)

4. The AM is marked as being available for use.



Page 350 of 545

Slide 30



Checkin: AM released with state managed.

• All AM state (VO data, database transaction state, and so on) is managed without being cleared.

• The AM is marked as being available for use.



Page 351 of 545

Slide 31


Monitoring the AM Pool

The AM pool monitor shows the active AM pools in the JVM.

The new version of pool monitor is now accessible from the Diagnostics global button. To gain access, you need to set the FND: Diagnostics profile to Y for the user.

Once you log in, the Diagnostics button "Show Pool Monitor" option gives you access to the pool monitor functionality. The pool monitor interrogates iAS to get a list of load-balanced JVMs and if successful gives you the opportunity to access the different JVM pools.

The functionality to access all JVMs is only available with iAS 1.0.2.2.2 or higher. If you are using an earlier version or the JVM list can not be obtained, then you are only able to inspect the pool in the current JVM you are connected to.



Page 352 of 545

Slide 32


JDBC Connection Pooling Process

Checkout:

1. Every active AM has a dedicated JDBC connection. When the AM is created, it requests a JDBC connection from the JDBC Connection pool.

2. The JDBC Connection Pool Manager tries to select a usable connection from the list of available connections and returns one if found.

3. If the selected connection is not usable, or if there are no available connections, then the pool checks to see if it has already reached its maximum size. If the pool is not at maximum size, it tries to create a new connection for the client.



Page 353 of 545

Slide 33



Checkout:

4. If the pool is already at maximum size, the JDBC connections are detached (harvested) from the inactive AMs and released back to the pool for reuse. If it cannot create a new connection, it records an error and returns null.



Page 354 of 545

Slide 34



Checkin:

Once a connection is checked out by the AM, it remains locked. Note that checking an AM into the AM pool does not check in the connection back to the connection pool by default. Instead, connections are lazily checked back into the connection pool in cases as below:

1. When the AM is destroyed by the AM Pool Monitor cleanup thread.

2. When the AM needs to disconnect and reconnect upon checkout to acquire a usable connection in place of an unusable (closed or timed out) connection.



Page 355 of 545

Slide 35



Checkin:

3. When the profile option FND: Application Module Connection Pool Enabled is set to Yes.

4. When the AOL/J connection harvester requests a connection from the AM.



Page 356 of 545

Slide 36



Cleanup:

The connection pool tries to maintain a number of available connections between the buffer min and buffer max values. When the usage is high, the pool size may grow considerably, and hence, the cleanup thread removes (destroys) connections. When the usage is low, the pool shrinks down below the buffer max size, and hence, the cleanup thread creates connections.

The cleanup happens over a period of time controlled by the decay interval and the decay size. The decay size is set to 1 by default, and you can increase this to 5 to speed up the decaying process. You should however leave the decay interval at its default 60 seconds.



Page 357 of 545

Slide 37


Monitoring the JDBC Connection Pooling

The connection pool status can be viewed using:

http://<hostname:port>/OA_HTML/jsp/fnd/AoljDbcPoolStatus.jsp



Page 358 of 545

Slide 38


Monitoring the JDBC Connection Pooling

Inspecting the Connection Pool Monitor

You can inspect the connection pool monitor for the following:

• Available Connections: The number of connections that are available for checking out.

• Locked Connections: The number of connections that were checked out by clients that use the JDBC Connection Pool. This includes the OA Framework AMs, other JSPs, servlets and so on. By clicking on locked connections, you can get a list of all users and the connections held by them.

• Pool Size Counter: Total number of available and used connections in the pool.



Page 359 of 545

Slide 39


Determining User Load

How do you find out how many users are accessing my system at any given time?

There is no way to accurately determine the number of active OA Framework users on a system. The best you can do is determine the number of active E-Business Suite users. You can do that by querying the ICX_SESSIONStable where disabled_flag = 'N'.

Note: for one user entry in the ICX_SESSIONS table there could be many active AMs.



Page 360 of 545

Slide 40


Back Button Usage Goals

Usability tests show that users rely heavily on the browser Back button. Unfortunately, this navigation preference introduces a series of potential failure points in transactional applications. The goals are as follows:

1. Provide consistent behavior in handling the browser back button.

2. Avoid severe, unexpected exceptions from state change.



Page 361 of 545

Slide 41


Back Button Scenario #1

The user deletes a row from a table and the page redraws with a confirmation message indicating that the row has been deleted (the row no longer appears in the table). The user then presses the browser Back button, and the page renders with the row still present in the table. The user then tries to delete the row a second time.

Problem The browser caches page contents. If the user performs an action that changes data state, and then uses the browser Back button, the browser's page cache doesn't reflect the correct middle tier state (in this case, that a row no longer exists). An attempt by the user to delete, or otherwise transact, this deleted row in the cached page would likely result in an ugly runtime application error. A Back button compliant page would detect the attempt to transact a deleted row and fail gracefully by displaying a user-friendly message indicating that the row has already been deleted.



Page 362 of 545

Slide 42



At the end of a shopping cart checkout process, the user selects a "Submit Order" button to purchase items. For whatever reason, the user navigates from the confirmation page back to order submission page using the browser Back button and selects the "Submit Order" button a second time (perhaps she thinks she can make a change to an order quantity and have it properly reflected on the original order).

Problem This scenario is similar to the one described above, however, the unguarded action could result in "successful" duplicate transaction (the order might be created twice, which is unlikely to be the user's expectation). A Back button compliant page would detect an attempt to submit the same order twice and fail gracefully by displaying a user-friendly error message indicating that the order had already been placed.



Page 363 of 545

Slide 43



The user navigates from Page 1 to Page 2, and then back to Page 1 using the browser Back button. The user presses a form submit component in Page 1, and an unhandled exception (NullPointerException, IndexOutOfBoundsException and the like) is thrown.

Problem The OA Framework "Page 1" expects the web bean hierarchy to be in a certain state, and/or it expects transaction, session or BC4J object state values to be present. When navigating with the browser Back button, this state may be lost. If the page doesn't anticipate this, unhandled exceptions may display to the user. A Back button compliant page would anticipate the potential loss of state behind the scenes, and would either be capable of recreating the state so it can continue functioning normally, or fail gracefully by displaying a user-friendly error message indicating that the page cannot be accessed after navigating with the browser Back button.



Page 364 of 545

Slide 44


Addressing Consistent Behavior

It is important that the application pages handle the browser Back button in a consistent manner. Use the following list of subgoals as a guide to achieve this consistency:

• Allow basic, straightforward operations to be repeated unless technical limitations are present.

• Allow transactions to be repeated as long as the logical transaction is active.

• Avoid ambiguous transactions, transactions on already deleted data, or transactions that could result in unintended user operations.



Page 365 of 545

Slide 45


Further Study of Back Button

Chapter 6: Advanced OA Framework Development Topics in the OA Framework Developer’s Guide is absolutely essential reading for this issue. Back button support is not trivial, and should be carefully studied.



Page 366 of 545

Slide 46


Summary


• Discuss OA Framework state management.

• Discuss OA Framework state caches.

• Discuss Passivation.

• Discuss Back-button support.

• Discuss Application Module pooling.



Page 367 of 545

Introduction to Personalizations






Page 368 of 545

Slide 2


Course Objectives

After completing this lesson, you should be able to do the following:

• Discuss personalizations

• Describe the benefits of personalizations

• Describe the benefits of extensions



Page 369 of 545

Slide 3


Concepts: Pages

A page is a location a user can navigate to from a menu, tab, or another page.

• A page provides a specific piece of functionality.

• A page is also called a form.

• An administrator can create personalizations at the page level.



Page 370 of 545

Slide 4


Concepts: Regions

A region is a specific part of a page.

• Arranged hierarchically (regions within a region, within a region, and so on).

• An administrator can create personalizations at the region level.

• An end user can create personalizations for specific regions (for inquiry pages if enabled).



Page 371 of 545

Slide 5


Concepts: Region Hierarchy

Item

Item

RegionRegion

Region

Region Hierarchy This picture shows how regions and items in a page correspond to the hierarchy you would see in the Personalization Structure page for administrators. The hierarchical grid is an abstraction of the OA Framework-based page. Each indent level in the hierarchy represents a container region. Each leaf node is an item (field or widget). Note that Personalize… region links are shown in the displayed page. Whether these region-level links appear is determined by the FND: Personalization Region Link Enabled (FND_PERSONALIZATION_REGION_LINK_ENABLED) profile option. Some objects listed in the Personalization Structure page may not appear in the same order as they do in the displayed page. For example, the Page Button Bar, which display the “Create Expense Report”, “Import Spreadsheet”, and “Export Spreadsheet” buttons on the top of the page, appear after the “Track Submitted Expense Reports” and “Update Expense Reports” headers in the page hierarchy. Use Expand All on the hierarchy to see the entire hierarchy of regions and items.



Page 372 of 545

Slide 6


Concepts: Items

An item is a field, button, poplist, or other user interface widget.

• Items must be contained in a region.

• An administrator can personalize almost all items.

• An end user can personalize items in specific regions (for inquiry pages if enabled).



Page 373 of 545

Slide 7


Examples of Personalizations

• User-level personalizations (stored queries)

• Administrator-seeded personalizations (site-wide user-level)

• Administrator-level personalization like reordering regions, adding items, adding buttons, changing common items (privacy statements, etc.), and adding columns

• Configurable pages that allow for region-level additions and rearrangements

• Advanced personalizations like adding flexfields to pages

• Customizable Look and Feel (CLAF)



Page 374 of 545

Slide 8


User Personalizations

Once you create a user personalization, the page displays a Views button. This allows you to call up any user-created or administrator-seeded user personalizations.



Page 375 of 545

Slide 9



Once you click on the Views button, you now have an additional UI where you can call up your predefined user-level personalizations, including administrator-seeded user-level personalizations.



Page 376 of 545

Slide 10


Administrator-seeded Personalizations

Other than being broadly available, administrator-seeded personalizations are no different from any other user personalization.



Page 377 of 545

Slide 11


Administrator Personalization (After)

1

2 & 3

4

5

The following changes have been made on this page: • The regions have been reordered. Note that the Notifications region is first. • A new tip has been created and put at the bottom of the page. • A new button has been created and put below the new tip. • The privacy statement link has had its TEXT changed. While not visible on this

slide, the privacy statement points to a new URI as well. • A new column (Currency Code) has been added to the Track Submitted

Expenses Reports table, and data has been mapped into that new column.



Page 378 of 545

Slide 12


Configurable Pages (After)



Page 379 of 545

Slide 13


Add a Flexfield (After)

This is the page with the added flexfield. If the flexfield has not been defined, the region would not appear. So, adding a flexfield is a multi-part process involving both E-Business Suite and OA Framework-based capabilities.



Page 380 of 545

Slide 14


Customizing the Look-and-Feel (After)



Page 381 of 545

Slide 15


Personalizations vs. Extensions

Personalization Extension

Done in Page? Yes No

Special Tool? No Yes

Programming? No Yes

Likely to Survive an

Upgrade?

Yes No



Page 382 of 545

Slide 16


Benefits of Personalizations

• Personalizations survive upgrades and patches.

• Administrator-level personalizations are available on any component.

• User-level personalizations are available on queries.

• Administrators can easily disable personalizations for debugging.

• Personalizations can be translated.

• Personalizations can be implemented on a test system, and they allow for immediate feedback.



Page 383 of 545

Slide 17


Benefits of Extensions

• Much more powerful that personalizations.

• Allows changes to business logic.

• Performed in Java.

• Easily deployed to existing servers.

• Capable of changes not possible with mere personalizations.

Limitations of Personalizations • Modifying business logic requires creating an extension to the application

using JDeveloper with OA Extension. Extensions are covered in another section of this class.

• The ability to change page flows depends on how the page flow was implemented. In some cases, URLs in functions may be modified, or destination URIs on navigational elements may be personalized. However, in any case of changing page flows, transaction flows may be affected, and such changes should be thoroughly tested. Page flow changes are generally beyond the scope of the system administrator.

• If you are trying to create a button or link that goes to another page with parameters, the destination page must already be built to accept parameters and do something with them. Usually these would be drilldown pages. If the source page uses nested application modules, it may not be possible to implement passing parameters.

• You cannot replace a List of Values (LOV) with a poplist.



Page 384 of 545

Slide 18


Summary

You should now be able to understand the following:

• The objectives of this course

• The kinds of labs in this course

• The basics of Personalizations vs. Extensions

• The basic architectural components of OA Framework



Page 385 of 545

Personalization Concepts






Page 386 of 545

Slide 2


Objectives


• List the capabilities of personalizations

• Discuss the benefits of personalizations

This lesson covers the personalization features available in the E-Business Suite Release 12.



Page 387 of 545

Slide 3


System Personalization Capabilities

• Menus and responsibilities

• FND messages, lookups, etc.

• Display Preferences

– Colors and fonts

– Branding

– Icons and images

• Page Personalization

– Business preferences

– End user preferences

Menus and responsibilities are system personalizations, as are messages and lookups. These types of personalization apply to both OA Framework-based products and Oracle Forms-based products. Display Preferences are personalizations that apply across OA Framework-based applications and do not affect product functionality. For example, changing the FND: Branding profile option changes the appearance of the product logo in all OA Framework-based pages in the installation of the E-Business Suite, but it does not affect how the pages behave. Page Personalization can affect both the appearance and functionality of an OA Framework-based page.



Page 388 of 545

Slide 4


Menus and Responsibilities

• Menus and responsibilities give a user access to a particular set of functionality, such as pages and sections of pages.

• An administrator usually personalizes shipped menus and responsibilities or creates new ones, often using parts of shipped menus.

System administrators often create new responsibilities for different classes of users. System administrators can also create new menus, modify existing menus, and remove (exclude) portions of existing menus for different responsibilities. This type of personalization applies both to OA Framework-based products and Oracle Forms-based products. Creating menus and responsibilities, as well as setting up other security features, is covered in the System Administrator Fundamentals class offered by Oracle University.



Page 389 of 545

Slide 5


Creating Menus and Responsibilities

• Create menus using:

– Menus page in Functional Administrator responsibility (preferred)

– Oracle Forms-based Menus form in the System Administrator responsibility

• Create responsibilities using:

– Oracle Forms-based Responsibilities forms in the System Administrator responsibility



Page 390 of 545

Slide 6


Functional Administrator Menus Page

Create new menus or search for existing menus.

This is an OA Framework-based menus page available to the Functional Administrator. Menus you define in this page can be used for both OA Framework-based pages and Oracle Forms-based forms. Select the link on the menu name to drill down to see its menu entries. Use the Create Navigation Menu button to enter a new menu. Responsibility: Functional Administrator (or UMX: Functional Security Administration) Navigation: Core Services > Menus It is worth noting that the old Oracle E-Business Suite security system has been superceded by a newer security mechanism called, UMX (User Management). Products now leverage this new and more powerful security model. If you want to know more, please visit the Oracle User Management FAQ at: http://www.oracle.com/technology/products/applications/security/oracleusermanagementfaq.htm#Q35



Page 391 of 545

Slide 7



You can copy or update menus.

This is the page you drill down to from the Menus page. You can use this page to examine, update, and duplicate existing menus. Responsibility: Functional Administrator Navigation: Core Services > Menus > link on menu name



Page 392 of 545

Slide 8


Menus Form

Responsibility: System Administrator Navigation: Application > Menu



Page 393 of 545

Slide 9


Responsibilities Form

Responsibility: System Administrator Navigation: Security > Responsibility > Define



Page 394 of 545

Slide 10


Messages

Applications messages are stored in Message Dictionary tables in the E-Business Suite database.

• An administrator often creates new messages or personalizes shipped messages.

• Administrators create or modify messages

– OA Framework-based Messages page in the Functional Administrator responsibility (preferred).

– Oracle Forms-based Messages form in the Application Developer responsibility.

Messages and lookups are system personalizations. System administrators often create new application messages and lookups. This type of personalization applies both to OA Framework-based (web-based) products and Oracle Forms-based (traditional) products. Creating or modifying Oracle Applications messages is covered in the Oracle Applications Developer’s Guide, as well as in some product-specific documentation.



Page 395 of 545

Slide 11


Functional Administrator Messages Page

Create new messages or modify existing messages using the Messages page.

This is an OA Framework-based messages page available to the Functional Administrator. Messages you define in this page can be used for both OA Framework-based (Web-based) pages and Oracle Forms-based (Traditional forms) pages. Select the Create Message button to create a new message. Responsibility: Functional Administrator (or UMX: Functional Security Administration) Navigation: Core Services > Messages



Page 396 of 545

Slide 12


Messages Form

Responsibility: Application Developer Navigation: Application > Messages



Page 397 of 545

Slide 13


Lookups

• Application lookup values are stored in tables in the E-Business Suite database.

• An administrator often personalizes shipped lookup values or creates new ones.

• Lookups are created or modified using:

– Lookup Types page in the Functional Administrator responsibility

– Application Object Library Lookups and Application Utility Lookups forms in the Application Developer responsibility

– Application-specific forms and pages

See the Oracle Applications System Administrator’s Guide, the Oracle Applications Developer’s Guide, and product-specific documentation for further information on lookups.



Page 398 of 545

Slide 14


Functional Administrator Lookup Types Page

Lookup types and codes you define in this page can be used for both OA Framework-based (web-based) pages and Oracle Forms-based (traditional) forms. Select the link on the lookup type name to drill down to see the lookup codes and meanings. Responsibility: Functional Administrator (or UMX: Functional Security Administration) Navigation: Core Services > Lookups



Page 399 of 545

Slide 15


Drill Down to Lookup Codes Page

For those lookup types that are updatable, you can edit existing lookup codes and add new codes with meanings and descriptions by selecting the Update button.



Page 400 of 545

Slide 16


Application Object Library Lookups

This is one of several lookups forms in the E-Business Suite. Responsibility: Application Developer Navigation: Application > Lookups > Application Object Library Note: For clarity, the above screenshot is a traditional Forms 6i based page, not an OA Framework web-based page.



Page 401 of 545

Slide 17


Custom Colors and Fonts

Modify the appearance of the E-Business Suite.

• Custom style sheets

• Custom icons

• Custom Look and Feel (CLAF)

Custom Look-and-Feel (CLAF, or Custom Skin) In Release 12, OA Framework provides pages to declaratively define new a look-and-feel in a convenient HTML user interface.

• A style sheet controls colors and fonts. • Named icons can be replaced with custom icons.

The E-Business Suite includes several skins that you can use or extend. You can apply different skins at the site, responsibility, application, organization, or user level. Creating a new look-and-feel is described in another section of this class.



Page 402 of 545

Slide 18


Branding

Branding includes the display of:

• Corporate ("Oracle") brand name

• Product brand name as text drawn from one of several possible sources

• Global links shown as text at the top of the page



Page 403 of 545

Slide 19


Corporate Branding Image

Change the corporate branding image (“Oracle”) branding in one of two ways:

• Globally across all applications

– Set the profile option “Corporate Branding Image for Oracle Applications”.

• For an individual page, responsibility, and so on

– Use page personalization to replace the corporate branding image with your own.

To set a Global image to be used across all products, set the profile option “Corporate Branding Image for Oracle Applications” (FND_CORPORATE_BRANDING_IMAGE) to the full path name of an image file (GIF) that contains your corporate image. This profile option should be set at the Site level and does not have a default value. To change just a single page’s image, create an administrator personalization for a specific page by setting the Image URI property on the corporateBranding page element to a different image file. This updates the image only for the specific usage on that page. Branding is covered in more detail in the Oracle Applications Framework Personalization Guide Release 12.



Page 404 of 545

Slide 20


Product Branding Image

Product branding is determined in one of three ways:

• Defaults from the current responsibility and page link

• Administrator can declaratively override the default value with a personalization that sets the Text property on the productBranding: formattedText page element to a new value.

• Developer can override the first two values by defining a Form Function and programmatically calling it using the OAPB URL parameter with the page to specify the product branding text.

Personalizing product branding is covered in more detail in the Oracle Applications Framework Personalization Guide Release 12.



Page 405 of 545

Slide 21


Concepts: Page Personalizations

• Personalizations modify the user interface of a page.

• Personalizations are layered on top of the base page at runtime.

– Base product pages are not changed.

• Personalizations survive upgrades. Base Product

Page Definition

PersonalizationDefinitionPersonalization

DefinitionPersonalizationDefinition

Layered Page Personalizations OA Framework-based pages are saved as metadata in the database (page definitions). Each page personalization represents just the change (i.e., the delta change) from the base page definition. Page personalizations are also stored as metadata definitions. At runtime, the personalization definitions are layered over the base page definitions.

Page Personalizations Survive Upgrades Because page personalizations are saved as metadata documents in the database, and that data is not affected by an upgrade, personalizations survive upgrades unchanged. You should test and evaluate each personalization after an upgrade, however. In some cases, your personalizations may no longer be valid. Reasons personalizations might become invalid include:

• Functionality you created or modified for a specific product now may be incorporated into the base product pages, making your personalization no longer necessary after the upgrade.

• A page in a product may have been modified by development to remove fields or regions, in which case personalizations based on those fields would no longer be valid. This scenario is unlikely.

• A page in a product may have been modified by development to add fields or regions, in which case you may want to create additional personalizations after the upgrade.



Page 406 of 545

• A page in a product may have been completely rewritten by development, in which case most or all of the personalizations on that page may be invalid. This scenario is unlikely.



Page 407 of 545

Slide 22


Concepts: User Personalizations

There are two types of personalizations:

• End User personalizations

– No special authority needed

– Available on inquiry pages built to allow saved searches

– Can modify query criteria, display of results

• Administrator personalizations

– Administrator must have profile options set to access the administrator personalization UI.

– Can add fields, make changes for all OA Framework-based pages

Administrator Personalizations and User Personalizations Administrators can personalize most pages, regions, and items in the OA Framework-based parts of the E-Business Suite. Administrators can do personalizations that affect the behavior and functionality of the pages, such as adding new fields and connecting them to data in tables. The changes made by administrators can affect the applications across the entire installation, or at more restricted levels. End users are much more limited in what they can do. Users can only make personalizations to inquiry pages where personalization has been specifically enabled by the application developer. User personalizations affect only the user who creates them. Users can hide some columns, and they can change prompts, order of table columns, query criteria, and sort order of columns, but they cannot add new columns or other items to the page.



Page 408 of 545

Slide 23


Concepts: Personalization Levels

• Administrator Personalization

– Function

– Industry

– Location

– Site

– Organization

– Responsibility

• End User Personalization

– User Views

Base ProductPage Definition



Personalization Levels The various personalization levels are layered. For example, a responsibility-level personalization would take effect above and beyond any personalizations at the site level for a user in the specified responsibility, but any other users at the site not using that responsibility would see only the site-level changes.

Levels • Function Level - the customer administrator can define functions and use

them as context for granular level personalizations. For example, you can create a function-level personalization to "hide the salary field, if the user is updating an employee record, but not when the user is creating a new employee".

• Industry Level – the customer administrator can introduce personalizations that affect all users of a particular industry such as using the term “business unit” rather than “store”, “location”, or “franchise”. Industry level includes a predefined list of vertical market categories, such as Healthcare - Provider and Utilities – Electricity.

• Localization Level - the customer administrator can use locales as context for personalizations such as "showing a different address field label based on country settings".

• Site Level - the customer administrator can introduce global personalizations that affect all users with access to the given application component, such as "setting the number of rows shown in a table".



Page 409 of 545

• Organization Level - the customer administrator can introduce personalizations that affect all users belonging to a particular organization or business unit with access to the application component. Example: "sort notifications by age for one organization and by urgency for another".

• Responsibility Level - the customer administrator can introduce personalizations that affect all users of a particular responsibility with access to the application component. Example: "show a trend graph for the sales manager responsibility".

• Seeded User Level - like the User Level available to End Users, but personalizations made at this level are visible to all users and can only be changed or deleted by the customer administrator. (Also referred to as "Admin-seeded user-level" personalizations.)

Oracle-Seeded Levels Oracle E-Business Suite developers can also seed personalizations as part of the product:

• Seeded Function Level - like the Function Level available to Administrators, but personalizations made at this level can only be changed or deleted by Oracle.

• Seeded User Level - like the User Level available to End Users, but personalizations made at this level can only be changed or deleted by Oracle. (Also referred to as "Oracle-seeded user-level" personalizations.)

• Oracle Applications Developers can create and ship personalizations at any of the Administrator personalization levels discussed above, but these are not protected against change and deletion by Administrators at the customer site.



Page 410 of 545

Slide 24


Personalization Levels and Layers

Add personalization layers to get to a particular personalization level.

• Layer is the definition of a particular personalization that is placed on top of a previous layer.

• Level is the net result of personalization layers to that point in the personalizations stack.



Page 411 of 545

Slide 25


Layers and Levels

Organization Layer

Responsibility Layer

Site Layer

Location Layer

Function Layer

Base Page Layer

Base Page Level (no personalization)

Function Level = Base Page + field

Location Level = Function level + new prompt

Site Level = Location level + hidden field

Org Level = Site level + required field

Resp Level = Org level + reordered fields

Add field

Change prompt

Hide different field

No personalization

Reorder fields

Make field required

Personalizations add themselves like onion-layers to a page. This hierarchy shows the order in which those layers of personalization are applied. Each progress layer up the hierarchy includes all the changes beneath it, plus any changes that it adds to the mix. Understanding this hierarchy is important to debugging unusual behavior. Let’s offer an example. Function Layer: add a field Site Layer: hide the field added at the function layer. In this example, you might think that your new field would appear on the page, but since the field was hidden at a layer above where it was added, the field will not appear on the page. Diagnosing issues like this can be time-consuming to track down all the possible culprits.



Page 412 of 545

Slide 26


Summary


• List the capabilities of personalizations.

• Discuss the benefits of personalizations.



Page 413 of 545

Extending OA Framework Applications






Page 414 of 545

Slide 2


Objectives


• Discuss the basic types of OA Framework extensions

• Describe the basic methodology for OA Framework extensions

• Discuss common extension tasks

• Add a new attribute to an OA Framework page

• Set a default attribute value

• Validate an attribute value



Page 415 of 545

Slide 3


4 Basic Types of Extensions

• Add a new attribute and expose it to the UI.

• Set default attribute values.

– Simple & local method

– Simple & global method

– Method for calculated values

• Validate attribute values.

– Attribute level

– Calculated attribute level

– Cross-attribute level

– Cross-entity level

• Develop a supplemental module (customization).



Page 416 of 545

Slide 4


Adding New Attributes

• Analyze the existing OA Framework page.

• Identify and reuse an existing table.

• Assemble a new JDeveloper with OA Extension project.

• Identify and reuse existing EOs.

• Identify and extend existing VO.

• Create and deploy a BC4J substitution.

• Use Admin Personalization to expose the new attribute on the UI.

Note: The assumption is that the tables, EOs, VOs, and other BC4J object currently exist. If they don’t, the additional steps of creating those objects will need to be done.



Page 417 of 545

Slide 5


Defaulting Attribute Values

• Simple & local method

– Analyze the existing OA Framework page.

– Use Admin Personalization to set the default value.



Page 418 of 545

Slide 6



• Simple & global method


– Assemble a new JDeveloper with OA Extension project.

– Identify and extend existing EO.

– Set the default value using the BC4J Wizard.

– Create and deploy a BC4J substitution.



Page 419 of 545

Slide 7



• Method for calculated values




– Add code to the EO Create() method to set the default value.

– Create and deploy a BC4J Substitution.



Page 420 of 545

Slide 8


Validate Attribute Values

• Attribute Level




– Set the attribute validation using the BC4J Wizard.




Page 421 of 545

Slide 9



• Calculated Attribute Level




– Add code to the EO set<attribute>() method to validate the value.




Page 422 of 545

Slide 10



• Cross Attribute Level




– Add code to the EO validateEntity() method to validate the value(s).




Page 423 of 545

Slide 11



• Cross Entity Level



– Identify and extend existing VO.

– Add code to the VO Validate() method to validate the value(s).




Page 424 of 545

Slide 12


New Development

• Create a new APP ID.


• Create or reuse the database table.

• Create or reuse the EO(s).

• Create or reuse the VO(s).

• Create or reuse the AM(s).

• Create a page or flow of pages.

• Link the new page to an existing application or a new menu.



Page 425 of 545

Slide 13


Common Extension Tasks



• Create and deploy a BC4J Substitution.



Page 426 of 545

Slide 14


Deploying an Extension

BC4J components that are extended consist of the following:

• XML file(s) that provide declarative properties for your extended component(s).

• Java file(s) that provide overridden methods from the base class for the component.

• JPX file(s) that deploy the corresponding BC4J substitutions.

A complete discussion of deployment will occur later. At this point, the common task we are observing is the creation and deployment of a BC4J substitution.



Page 427 of 545

Slide 15


Creating a BC4J Substitution

• Open the Project Properties window.

• Navigate to Business Components > Substitutions.

• From the Available list, select the base BC4J object (e.g., PoSummaryVO) that you want to be substituted.

• From the Substitute list, select the extended object (e.g., MyCompanyPoSummaryVO) that you want to substitute.

• Choose Add to create a new substitution rule.

• Select OK to save your changes.



Page 428 of 545

Slide 16





Page 429 of 545

Slide 17



When you save your changes to the project, the BC4J framework updates the project’s .jpx file. The .jpx file is an XML document that includes a “<Substitutes>” section as shown below.

<Substitutes>

<Substitute OldName

=“oracle.apps.fnd.framework.toolbox.tutorial.

server.PoSummaryVO”

NewName

=“mycompany.oracle.apps.fnd.framework.toolbox

.tutorial.server.MyCompanyPoSummaryVO”/>

</Substitutes>



Page 430 of 545

Slide 18


Deploying a BC4J Substitution

There are 2 methods by which you can deploy a BC4J substitution.

• Deploy from within JDeveloper with OA Extension.

• Deploy from the middle-tier server.



Page 431 of 545

Slide 19


Deploy from within JDeveloper with OA Extension

Open your Project Properties window. Select Run/Debug. Select the Default Run Configuration, and click the Edit button.



Page 432 of 545

Slide 20



Add –Djbo.project=<NAME> to the Java Options field. Note: The <NAME> value is the .jpx file name without the .jpx extension (e.g., ExtendLabSolution). Be sure to include a space between any existing options and the new option.



Page 433 of 545

Slide 21


Deploy on the Middle-Tier Server

You must load any <ExtensionProject>.jpx files of BC4J substitutions into the MDS Repository

• Use the jpx import utility jpximport.bat

– Located under the jdev\bin directory of your JDeveloper with OA Extension installation.

– Run from the command line

– Running the utility without any parameters displays usage options and format information

• The import utility transforms each substitution into a separate site-level customization document which is then imported into the MDS Repository.

The .jpx files contain information on any BC4J substitutions you made when extending Oracle Applications BC4J objects. To have a .jpx file of BC4J substitutions take effect at runtime in a deployed environment, you must import your substitution information into the MDS Repository. You can load multiple .jpx files into the MDS Repository, but if multiple substitutions apply to the same object, the substitution loaded latest will override previously-loaded substitutions.



Page 434 of 545

Slide 22


Summary


• Discuss the basic types of OA Framework extensions.

• Describe the basic methodology for OA Framework extensions.

• Discuss common extension tasks.

• Add a new attribute to an OA Framework page.

• Set a default attribute value.

• Validate an attribute value.

Open the Course Labs book. Complete Lab X – Adding Attributes Complete Lab X – Setting Default Values Complete Lab X – Adding Validations



Page 435 of 545







Page 436 of 545

Slide 2


Objectives

After completing this lesson you should be able to:

• Describe the personalization directory structure

• List the tools used for deploying personalizations

• Inspect the MDS repository for personalization documents

• Deploy personalizations

• Deploy a custom page

• Deploy business logic extensions

Instructor Note: Demonstrate a personalization to the students. Do the following: • Login to apps as SYSADMIN/SYSADMIN • Select the iProcurement responsibility, and go to the default page. • Click the “About this page” link. • Click the Personalizations tab. • Note the Oracle-seeded personalizations applied to the base page.



Page 437 of 545

Slide 3


Storing Personalizations

The personalization information (metadata) of a region / page is stored as a personalization document in the MDS repository, with a specific directory structure.

The directory structure for:

Original page Personalization file

+ <component> + <component>

+ webui + webui

file.xml + customizations

+ <layer type>

+ <layer value>

+ file.xml

MDS Repository Documents The MDS Repository is the database that stores the metadata of your OA Framework-based pages and regions, as well as information on any personalizations that have been created in your system. Each metadata definition of a region, page or personalization is called a document. This document is stored in JDR_PATHS, JDR_COMPONENTS and JDR_ATTRIBUTES tables. JDR_PATHS – has columns that store document path. JDR_COMPONENTS – has columns that store component information. JDR_ATTRIBUTES – has columns that store attribute information.



Page 438 of 545

Slide 4


Directory Structure

To understand the storage structure in the MDS let’s look at the following example:

If the following page is personalized at site level:/oracle/apps/fnd/wf/worklist/webui/AdvancWorklistRG

The page will be stored in the MDS repository with the following structure:/oracle/apps/fnd/wf/worklist/webui/customizations/

site/0/AdvancWorklistRG

site - customization layer type

0 – customization layer value



Page 439 of 545

Slide 5


Directory Structure - Layer Values

<layer type>

Function

Location

Site

Organization

Responsibility

User

<layer value>

Function Name

Location ID

0

Organization ID

Responsibility ID

User ID

Note: One quirk of interest. Please notice that the Location, Organization, Responsibility and User all use the ID. There may be cases where IDs exist on your Development system and not in Production, and vice-versa. You must test this carefully when deploying.



Page 440 of 545

Slide 6


Toolset

The personalizations are deployed from the:

• Functional Administrator responsibility page.

– Export to File System button

– Import from File System button

• Command line.

– Using .bat files (export.bat, import.bat, jpxImport.bat)

– Using command-line .java files

— XMLExporter

— XMLImporter

— JPXImporter

XMLExporter – exports personalization from MDS repository to .xml file. XMLImporter – imports personalizations into MDS repository. JPXImporter – imports substitutions specified in the .jpx file to the MDS repository. The export/import batch files are shipped along with OA Extension to JDeveloper. These batch files have the script to run the XMLExporter and XMLImporter java files.



Page 441 of 545

Slide 7


Functional Administrator Personalization UI

The Functional Administrator responsibility page provides an Import/Export tab that lets the user:

• Import the personalization documents into the MDS repository from the file system.

• Export the personalization documents from the MDS repository to the file system.

You can only work with Personalizations from this UI. It does not allow the import/export of OA Framework pages or BC4J substitutions.



Page 442 of 545

Slide 8


export.bat / import.bat- Syntax

export/import <Document_Name> <parameters>

<Document_Name > - full path to XML filename


-rootdir <output_dir/input_dir>




-rootdir = directory where the exported xml file needs to be stored -username = username for the database to export from -password = password for the database to export from -dbconnection = connection for the MDS



Page 443 of 545

Slide 9


export.bat/import.bat - Example

For example, to export the HelloWorldPG from MDS repository to the file system:

• Go to Windows Command Prompt.

• Change to <Jdev_Install_Dir>\Jdev\bin.

• Run the following command:

export /oracle/apps/ak/hello/webui/HelloWorldPG.xml

-rootdir d:\jdeveloper\jdev\myprojects



The –dbconnection information can actually be in one of two formats: Format 1: The long format You can put the entire TNS Names entry. For example, your entry might read as follows:

-dbconnection "(description = (address_list = (address =

(community = tcp.world)(protocol = tcp) (host

=es0006.oracle.com)(port = 1521))) (connect_data = (sid =

es0006)))“

Format 2: The short format (preferred) You can put an entry similar to the following:




Page 444 of 545

Slide 10


Command Line – XMLExporter/XMLImporter

• Exports/imports the personalizations from the MDS repository to an .xml file (same as export.bat).

• Is available along with the Oracle E-Business Suite runtime environment.


java oracle.jrad.tools.xml.exporter.XMLExporter


java oracle.jrad.tools.xml.importer.XMLImporter


This tool can be run from either the JDeveloper with OA Extension install, or it can be run on the Admin Server where the files will be stored.



Page 445 of 545

Slide 11


export.bat vs. XMLExporter

• Both have same usage and syntax.

• The export.bat batch file is available only with JDeveloper with OA Extension, whereas the XMLExporter.class file is available as part of Oracle E-Business Suite runtime environment.

• Same is true for import.bat vs. XMLImporter.



Page 446 of 545

Slide 12


Import Substitutions – JPXImport.bat

• JPXImport.bat is used to import the BC4J substitution documents into the MDS repository.

• Is available as part of JDeveloper with OA Extension and has the script that runs the JPXImporter.java file.

• JPXImport:

– Parses the .jpx file for each BC4J substitution defined in the file.

– Transforms each substitution into a separate site level customization document.

– Imports the customization document into the MDS repository.



Page 447 of 545

Slide 13


JPXImport.bat - Syntax

JPXImport <full_path_of_file> <parameters>

<full_path_of_file > - full path of the .jpx file to import





-username = username for the database to import to -password = password for the database to import to -dbconnection = connection for the database to import to, in tnsnames format



Page 448 of 545

Slide 14


Import Substitutions – JPXImporter

• JPXImporter is used to import the BC4J substitution documents into the MDS repository (same as the JPXImport.bat).

• Is available as part Oracle E-Business Suite runtime environment.




Page 449 of 545

Slide 15


Inspecting the MDS Repository

• Before deploying, the personalizations stored in the MDS repository can be inspected using JDR_UTILS PL/SQL package (optional step).

• The JDR_UTILS PL/SQL package provides procedures to:

– List the personalizations done on a page.

– Inspect the personalizations by extracting the required personalization document - site , function, user or responsibility level personalization documents.

Using JDR_UTILS in SQL*Plus You can use SQL*Plus to review all the personalizations for a given base document. JDR_UTILS is a PL/SQL package that allows you to evaluate the list of personalization documents that are in your MDS repository. Included in this package is a procedure called JDR_UTILS.listcustomizations( ); which allows you to see the personalization document path names that are currently defined in the MDS repository. See "Inspecting the MDS Repository Content" in the OA Framework Developer's Guide for more information on the JDR_UTILS package. This package should never be called from any program code.



Page 450 of 545

Slide 16


JDR_UTILS PL/SQL package APIs

The JDR_UTILS PL/SQL package contains the

following APIs to inspect the MDS repository:

• deleteDocument

• deletePackage

• exportDocument

• getComponentName

• getDocumentName

• getTranslations

• listContents

• listDocuments

• listLanguages

• printDocument

• printTranslations

• saveTranslations

• deleteEmptyCustomizations

PROCEDURE deleteDocument(p_document VARCHAR2); -- Deletes all empty customization documents from the repository. An empty -- customization document is a customization document that does not specify -- any modifications to the base metadata. -- -- Example 1: /oracle/apps/hr/customizations/localization/US/page1 -- <customization customizes="/oracle/apps/hr/page1" -- xmlns="http://xmlns.oracle.com/jrad" -- xmlns:ui="http://xmlns.oracle.com/uix/ui" -- xmlns:oa="http://xmlns.oracle.com/oa" -- xmlns:user="http://xmlns.oracle.com/jrad/user" -- file-version="$Header: JDRUTEXS.pls 120.3 2005/10/26 06:16:00 akbansal noship $" version="9.0.3.6.6_557" -- xml:lang="en-US"> -- <modifications/> -- </customization> -- -- Example 2: /oracle/apps/hr/customizations/user/100/page1 -- <customization customizes="/oracle/apps/hr/page1" -- xmlns="http://xmlns.oracle.com/jrad" -- xmlns:ui="http://xmlns.oracle.com/uix/ui" -- xmlns:oa="http://xmlns.oracle.com/oa" -- xmlns:user="http://xmlns.oracle.com/jrad/user"



Page 451 of 545

-- file-version="$Header: JDRUTEXS.pls 120.3 2005/10/26 06:16:00 akbansal noship $" version="9.0.3.6.6_557" -- xml:lang="en-US"> -- <views> -- <view name="MyTest10" description="my view" -- id="view1" element="Region1"> -- <modifications/> -- </view> -- <views/> -- <customization/> PROCEDURE deleteEmptyCustomizations; -- Deletes the package from the repository if the package is empty. If the -- package is not empty (i.e. it contains either documents or packages), then -- an error will be issued indicated that non-empty packages can not be -- deleted. -- -- Parameters: -- p_package - the fully qualified package name -- (i.e. '/oracle/apps') PROCEDURE deletePackage(p_package VARCHAR2); -- Export the XML for a document and pass it back in 32k chunks. This -- function will return XML chunks, with a maximum size of 32k. -- -- Specifying a document name will initiate the export. Thereafter, a NULL -- document name should be passed in until the export is complete. -- That is, to export an entire document, you should do: -- -- firstChunk := jdr_utils.exportDocument('/oracle/apps/fnd/mydoc', isDone); -- WHILE (NOT isDone) LOOP -- nextChunk := jdr_utils.exportDocument(NULL, isDone); -- END LOOP; -- -- Parameters: -- p_document - the fully qualified name of the document. However, -- after the first chunk of text is exported, a NULL -- value must be passed in to retrieve the next -- chunks. -- -- p_exportFinished - OUT parameter which indicates whether or not the export -- is complete. TRUE indicates the entire document is -- exported, FALSE indicates that there are more chunks -- remaining. -- -- p_formatted - TRUE indicates that the XML is formatted nicely -- (i.e. whether or not the elements are indented). -- This is defaulted to TRUE.



Page 452 of 545

-- -- -- Returns: -- The exported XML, in 32k chunks. -- -- Notes: -- As this function relies on package state, it is not possible to export -- multiple documents at the same time. A document must be finished -- exporting before a new document can be exported. FUNCTION exportDocument( p_document VARCHAR2, p_exportFinished OUT NOCOPY /* file.sql.39 change */ BOOLEAN, p_formatted BOOLEAN DEFAULT TRUE) RETURN VARCHAR2; -- Gets the fully qualified name of the component. -- -- Parameters: -- p_docid - the ID of the document which contains the component -- -- p_compid - the ID of the component (from comp_id in the -- jdr_components table FUNCTION getComponentName( p_docid jdr_paths.path_docid%TYPE, p_compid jdr_components.comp_id%TYPE) RETURN VARCHAR2; -- Gets the fully qualified name of the document. -- -- Parameters: -- p_docid - the ID of the document FUNCTION getDocumentName( p_docid jdr_paths.path_docid%TYPE) RETURN VARCHAR2; -- Gets all of the translations of the specified document. -- -- Parameters: -- p_document - the fully qualified document name -- -- Raises NO_SUCH_DOCUMENT exception if the document does not exist. FUNCTION getTranslations( p_document VARCHAR2) RETURN translationList; -- Prints the contents of a package. -- -- For the non-recursive case, this will list the documents, -- package files and package directories. -- -- For the recursive case, this will list the document, package files -- and empty package directories (i.e. packages which contain no documents



Page 453 of 545

-- or child packages). -- -- In order to diferentiate documents from package directories, package -- directories will end with a '/'. -- -- Parameters: -- p_path - The path in which to list the documents. To specify -- the root directory, use '/'. -- -- p_recursive - If TRUE, recursively lists the contents of -- sub-directories. Defaults to FALSE. -- -- To use this from SQL*Plus, do: -- -- (1) set serveroutput on -- execute jdr_utils.listContents('/oracle/apps/ak'); -- This will list the contents of the ak directory, without showing -- the contents of the sub-directories. -- -- (2) set serveroutput on -- execute jdr_utils.listContents('/', TRUE); -- This will list the contents of the entire repository. -- sub-directories. PROCEDURE listContents(p_path VARCHAR2, p_recursive BOOLEAN DEFAULT FALSE); -- List the customizations for the specified document. -- -- Parameters: -- p_document - the fully qualified document name, which can represent -- either a document or package file. -- (i.e. '/oracle/apps/ak/attributeSets') PROCEDURE listDocuments(p_path VARCHAR2, p_recursive BOOLEAN DEFAULT FALSE); -- Lists the supported languages for the specified document. -- -- Parameters: -- p_document - the fully qualified document name, which can represent -- either a document or package file. -- (i.e. '/oracle/apps/ak/attributeSets') PROCEDURE listLanguages(p_document VARCHAR2); -- Prints the contents of a JRAD document to the console. -- -- Parameters: -- p_document - the fully qualified document name, which can represent -- either a document or package file.



Page 454 of 545

-- (i.e. '/oracle/apps/ak/attributeSets') -- -- p_maxLineSize - the maximum size of line. This defaults to 255 which is -- the maximim allowable size of a line (the 255 limit is -- a limitation of the DBMS_OUPUT package). -- -- Limitations: -- Documents larger than 1000000 bytes will fail as DBMS_OUPUT's maximim -- buffer is 1000000 bytes. -- -- To use this from SQL*Plus, do: -- set serveroutput on format wrapped (this is needed for leading spaces) -- set linesize 100 -- execute jdr_utils.printDocument('/oracle/apps/ak/attributeSets', 100); -- -- To create an XML file, you can create the following SQL file: -- set feedback off -- set serveroutput on format wrapped -- set linesize 100 -- spool (parameter 1) -- execute jdr_utils.printDocument('(parameter 2)', 100); -- spool off -- -- and call the file with: -- sqlplus scott/tiger @export.sql myxml.xml /oracle/apps/ak/attributeSets PROCEDURE printDocument(p_document VARCHAR2, p_maxLineSize NUMBER DEFAULT MAX_LINE_SIZE); -- Prints the translations for the document in XLIFF format. -- -- Parameters: -- p_document - the fully qualified document name, which can represent -- either a document or package file. -- (i.e. '/oracle/apps/ak/attributeSets') -- -- p_language - the language to use for the translations -- -- p_maxLineSize - the maximum size of line. This defaults to 255 which is -- the maximim allowable size of a line (the 255 limit is -- a limitation of the DBMS_OUPUT package). -- -- To use this from SQL*Plus, do: -- set serveroutput on format wrapped (this is needed for leading spaces) -- set linesize 100 -- execute jdr_utils.printTranslations('/oracle/apps/ak/attributeSets', -- 'mylanguage', 100); PROCEDURE printTranslations(p_document VARCHAR2,



Page 455 of 545

p_language VARCHAR2, p_maxLineSize NUMBER DEFAULT MAX_LINE_SIZE); -- Saves the specified translations for the specified document. -- -- This procedure will do the following: -- (1) Lock the document so as to prevent multiple users attempting -- to modify translations at the same time -- (2) Delete all of the translations for the specified document -- (3) Insert the new translations -- (4) Commit the data unless p_commit set to FALSE -- -- Please use this with care as it will delete all of the -- translations for the specified document. -- -- Parameters: -- p_document - the fully qualified document name -- -- p_translations - the list of translations to insert -- -- p_commit - if TRUE, the data is committed. Default is TRUE -- -- NOTE: If p_commit is set to FALSE, then the document will remain locked -- after the call to saveTranslations. In order to prevent a deadlock, a -- commit (or rollback) must occur to unlock the document. -- -- Raises NO_SUCH_DOCUMENT exception if the document does not exist. PROCEDURE saveTranslations( p_document VARCHAR2, p_translations translationList, p_commit BOOLEAN := TRUE);



Page 456 of 545

Slide 17


List the Personalizations Done on a Page

Use the PL/SQL procedure JDR_UTILS.listContents to list the personalizations done on a page.

SQL> set serveroutput on;

SQL> execute JDR_UTILS.listContents('/acme',TRUE);

Printing contents of /acme recursively


webui/customizations/site/0/AcmePoSummaryCreatePG


webui/acmePoSummaryCreatePG

PL/SQL procedure successfully completed.



Page 457 of 545

Slide 18


Inspect Personalizations

Use the PL/SQL procedure JDR_UTILS.printDocument to inspect the

personalizations done on a page.

SQL> execute

JDR_UTILS.printDocument('/acme/oracle/apps/

fnd/framework/toolbox/tutorial/webui/customizat

ions/site/0/AcmePoSummaryCreatePG');

The above mentioned command will produce the following output. <?xml version='1.0' encoding='UTF-8'?>

<customization xmlns="http://xmlns.oracle.com/jrad"

version="9.0.5.4.79_479" xml:lang="en-US"

customizes="/acme/oracle/apps/fnd/framework/toolbox/tutorial/

webui/AcmePoSummaryCreatePG"

xmlns:oa="http://xmlns.oracle.com/oa">

<modifications>

<move element="OrdersRN.Status" after="OrdersRN.OrderNum"/>

…

<move element="OrdersRN.Description"

after="OrdersRN.Status"/>

<move element="OrdersRN.Buyer" after="OrdersRN.Description"/>

<move element="OrdersRN.Supplier" after="OrdersRN.Buyer"/>

<move element="OrdersRN.Currency" after="OrdersRN.Supplier"/>

<insert before="OrdersRN.Currency">

<oa:messageStyledText id="SiteName" adminCustomizable="true"

cellNoWrapFormat="false"

dataType="VARCHAR2" initSortSeq="none" prompt="Supplier Site"

queryable="false" rendered="true"

required="no" scope="." selectiveSearchCriteria="false"

serverUnvalidated="false" sortState="no" tipType="none"

totalValue="false" userCustomizable="false"



Page 458 of 545

vAlign="middle" viewAttr="SiteName" viewName="PoSummaryVO1"

warnAboutChanges="true"/>

…

</insert>

<move element="OrdersRN.OrderTotal"

after="OrdersRN.Currency"/>

<move element="OrdersRN.DeleteSwitcher"

after="OrdersRN.OrderTotal"/>

<move

element="OrdersRN.UpdateSwitcher"

after="OrdersRN.DeleteSwitcher"/>

</modifications>

</customization>



Page 459 of 545

Slide 19


Deploying Personalizations

Personalizations are first done on a test instance, verified and then deployed into the production instance.

To deploy personalizations from a test instance into a

production instance :

• Extract the personalizations from the test instance.

• Upload the personalizations into the production instance.



Page 460 of 545

Slide 20


Extract the Personalizations – Functional Administrator Page

• Login to E-Business Suite under the Functional Administrator Responsibility.

• Set the Personalization Document Root Pathprofile value to a directory in your file system.



Page 461 of 545

Slide 21


Set Personalization Document Root Path

The full Internal Profile Code is FND_PERZ_DOC_ROOT_PATH.



Page 462 of 545

Slide 22


Import/Export Personalizations




Page 463 of 545

Slide 23


Extract the Personalizations – Select the Page

• Expand the Personalization Repository view

and select the page that needs to be exported to the file system.



Page 464 of 545

Slide 24


Extract the Personalizations – Export to File System

• Click on Export to File System button.



Page 465 of 545

Slide 25


Upload Personalizations into Production Instance – Functional Administrator Page

• Set the FND_PERZ_DOC_ROOT_PATH profile value to a

directory in your file system that has the personalization documents to be uploaded.

• Login to E-Business Suite under the Functional Administrator responsibility.


The profile option should be set at the User level to ensure security.



Page 466 of 545

Slide 26


Upload Personalizations into Production Instance – Exported Personalizations

• Select Exported Personalizations from the side

navigation menu.



Page 467 of 545

Slide 27


Upload Personalizations into Production Instance – Import from File System

• Expand the Exported Personalizations and select the page that needs to be imported from the file system.

• Click on Import from File System button.



Page 468 of 545

Slide 28


Extensions

OA Framework applications are extended by:

• Adding new content or business logic (OA page extensions).

• Extending/overriding existing business logic (BC4J extensions).

Extensions require either changes to Java code or changes to XML files that cannot be done via personalizations. Since personalizations deal with the UI objects, the XML files needed by extensions are BC4J-based XML files.



Page 469 of 545

Slide 29


OA Page Extensions

Custom (new) OA pages that are added to an existing application consist of:

• XML files that define the OA components and declarative properties specified for the pages

• One or more controller Java files

• BC4J XML and java files



Page 470 of 545

Slide 30


Deployment of Page Extensions

To deploy the page extensions:

1. Copy the corresponding controller and BC4J classes to the file system $JAVA_TOP.

2. Import the BC4J substitutions (if any) into the MDS repository.

3. Import the OA component definitions (in XML files) into the MDS repository.



Page 471 of 545

Slide 31


1.Copy .java Classes

• Copy the controller and BC4J classes to $JAVA_TOP:

– Compile the java files in JDeveloper and zip the class files.

– The zip file should contain all the custom BC4J java classes and the controller classes. Pick up the classes from -<JDEV_USER_HOME>\myclasses.

– Preserve the directory structure while zipping these files.

– Extract the zip to $JAVA_TOP.



Page 472 of 545

Slide 32


2. Import Substitutions

Run the jpximport utility to import the substitutions specified in the .jpx definition file into the MDS.

Example:<jdev_install_dir>\jdev\bin\jpximport

<JDEV_USER_HOME>\myprojects\ExtendLabSolutions.jpx



Instructor Note: Demonstrate a JPX file. Open the JPX file of your choice, and show the students how it is simply the substitutions area that you are uploading into the MDS.



Page 473 of 545

Slide 33


3. Import OA Component Definitions

Import the OA component definitions into the MDS using either:

• The Functional Administrator Responsibility page

• The import.bat/XMLImporter tool



Page 474 of 545

Slide 34


View The Deployed Extensions

• Bounce the web server.

• Review your deployed extensions.



Page 475 of 545

Slide 35


BC4J Extensions

Business components you extend consist of:

• XML files that provide the declarative properties for your extended business component.

• Extended Java files with the overridden methods that provide custom business logic programmatically.

Note: Extending BC4J objects is supported. Extending Controllers (CO) is not. Any work done to extend an Oracle-supplied Controller is by definition unsupported.



Page 476 of 545

Slide 36


Deployment of Business Logic Extensions

To deploy business logic extensions:

1. Compile your Java in JDeveloper and zip up your Java classes.

2. Extract the .zip to $JAVA_TOP.

3. Run the jpx import utility to import substitutions specified in the .jpx definition file to the MDS repository.

4. Bounce the web server (if required).

5. Review your deployed extensions.



Page 477 of 545

Slide 37


Summary

In this lessons, you should have learned to:

• Describe the personalization directory structure.

• List the tools used for deploying Personalizations.

• Inspect the MDS repository for personalization documents.

• Deploy Personalizations.

• Deploy a custom page.

• Deploy business logic extensions.

Open the Course Labs book. Complete Lab 10 – Deploying Personalizations Complete Lab 11 – Deploying Extensions



Page 478 of 545







Page 479 of 545

Slide 2


Course Objectives


• Discuss personalizations

• Describe the benefits of personalizations

• Describe the benefits of extensions



Page 480 of 545

Slide 3


Concepts: Pages

A page is a location a user can navigate to from a menu, tab, or another page.

• A page provides a specific piece of functionality.

• A page is also called a form.

• An administrator can create personalizations at the page level.



Page 481 of 545

Slide 4


Concepts: Regions

A region is a specific part of a page.

• Arranged hierarchically (regions within a region, within a region, and so on).

• An administrator can create personalizations at the region level.

• An end user can create personalizations for specific regions (for inquiry pages if enabled).



Page 482 of 545

Slide 5


Concepts: Region Hierarchy

Item

Item

RegionRegion

Region

Region Hierarchy This picture shows how regions and items in a page correspond to the hierarchy you would see in the Personalization Structure page for administrators. The hierarchical grid is an abstraction of the OA Framework-based page. Each indent level in the hierarchy represents a container region. Each leaf node is an item (field or widget). Note that Personalize… region links are shown in the displayed page. Whether these region-level links appear is determined by the FND: Personalization Region Link Enabled (FND_PERSONALIZATION_REGION_LINK_ENABLED) profile option. Some objects listed in the Personalization Structure page may not appear in the same order as they do in the displayed page. For example, the Page Button Bar, which display the “Create Expense Report”, “Import Spreadsheet”, and “Export Spreadsheet” buttons on the top of the page, appear after the “Track Submitted Expense Reports” and “Update Expense Reports” headers in the page hierarchy. Use Expand All on the hierarchy to see the entire hierarchy of regions and items.



Page 483 of 545

Slide 6


Concepts: Items

An item is a field, button, poplist, or other user interface widget.

• Items must be contained in a region.

• An administrator can personalize almost all items.

• An end user can personalize items in specific regions (for inquiry pages if enabled).



Page 484 of 545

Slide 7


Examples of Personalizations

• User-level personalizations (stored queries)

• Administrator-seeded personalizations (site-wide user-level)

• Administrator-level personalization like reordering regions, adding items, adding buttons, changing common items (privacy statements, etc.), and adding columns

• Configurable pages that allow for region-level additions and rearrangements

• Advanced personalizations like adding flexfields to pages

• Customizable Look and Feel (CLAF)



Page 485 of 545

Slide 8



Once you create a user personalization, the page displays a Views button. This allows you to call up any user-created or administrator-seeded user personalizations.



Page 486 of 545

Slide 9



Once you click on the Views button, you now have an additional UI where you can call up your predefined user-level personalizations, including administrator-seeded user-level personalizations.



Page 487 of 545

Slide 10


Administrator-seeded Personalizations

Other than being broadly available, administrator-seeded personalizations are no different from any other user personalization.



Page 488 of 545

Slide 11


Administrator Personalization (After)

1

2 & 3

4

5

The following changes have been made on this page: • The regions have been reordered. Note that the Notifications region is first. • A new tip has been created and put at the bottom of the page. • A new button has been created and put below the new tip. • The privacy statement link has had its TEXT changed. While not visible on this

slide, the privacy statement points to a new URI as well. • A new column (Currency Code) has been added to the Track Submitted

Expenses Reports table, and data has been mapped into that new column.



Page 489 of 545

Slide 12


Configurable Pages (After)



Page 490 of 545

Slide 13


Add a Flexfield (After)

This is the page with the added flexfield. If the flexfield has not been defined, the region would not appear. So, adding a flexfield is a multi-part process involving both E-Business Suite and OA Framework-based capabilities.



Page 491 of 545

Slide 14


Customizing the Look-and-Feel (After)



Page 492 of 545

Slide 15


Personalizations vs. Extensions

Personalization Extension

Done in Page? Yes No

Special Tool? No Yes

Programming? No Yes

Likely to Survive an

Upgrade?

Yes No



Page 493 of 545

Slide 16


Benefits of Personalizations

• Personalizations survive upgrades and patches.

• Administrator-level personalizations are available on any component.

• User-level personalizations are available on queries.

• Administrators can easily disable personalizations for debugging.

• Personalizations can be translated.

• Personalizations can be implemented on a test system, and they allow for immediate feedback.



Page 494 of 545

Slide 17


Benefits of Extensions

• Much more powerful that personalizations.

• Allows changes to business logic.

• Performed in Java.

• Easily deployed to existing servers.

• Capable of changes not possible with mere personalizations.

Limitations of Personalizations • Modifying business logic requires creating an extension to the application

using JDeveloper with OA Extension. Extensions are covered in another section of this class.

• The ability to change page flows depends on how the page flow was implemented. In some cases, URLs in functions may be modified, or destination URIs on navigational elements may be personalized. However, in any case of changing page flows, transaction flows may be affected, and such changes should be thoroughly tested. Page flow changes are generally beyond the scope of the system administrator.

• If you are trying to create a button or link that goes to another page with parameters, the destination page must already be built to accept parameters and do something with them. Usually these would be drilldown pages. If the source page uses nested application modules, it may not be possible to implement passing parameters.

• You cannot replace a List of Values (LOV) with a poplist.



Page 495 of 545

Slide 18


Summary

You should now be able to understand the following:

• The objectives of this course

• The kinds of labs in this course

• The basics of Personalizations vs. Extensions

• The basic architectural components of OA Framework



Page 496 of 545







Page 497 of 545

Slide 2


Objectives


• List the capabilities of personalizations

• Discuss the benefits of personalizations

This lesson covers the personalization features available in the E-Business Suite Release 12.



Page 498 of 545

Slide 3


System Personalization Capabilities

• Menus and responsibilities

• FND messages, lookups, etc.

• Display Preferences

– Colors and fonts

– Branding

– Icons and images

• Page Personalization

– Business preferences

– End user preferences

Menus and responsibilities are system personalizations, as are messages and lookups. These types of personalization apply to both OA Framework-based products and Oracle Forms-based products. Display Preferences are personalizations that apply across OA Framework-based applications and do not affect product functionality. For example, changing the FND: Branding profile option changes the appearance of the product logo in all OA Framework-based pages in the installation of the E-Business Suite, but it does not affect how the pages behave. Page Personalization can affect both the appearance and functionality of an OA Framework-based page.



Page 499 of 545

Slide 4


Menus and Responsibilities

• Menus and responsibilities give a user access to a particular set of functionality, such as pages and sections of pages.

• An administrator usually personalizes shipped menus and responsibilities or creates new ones, often using parts of shipped menus.

System administrators often create new responsibilities for different classes of users. System administrators can also create new menus, modify existing menus, and remove (exclude) portions of existing menus for different responsibilities. This type of personalization applies both to OA Framework-based products and Oracle Forms-based products. Creating menus and responsibilities, as well as setting up other security features, is covered in the System Administrator Fundamentals class offered by Oracle University.



Page 500 of 545

Slide 5


Creating Menus and Responsibilities

• Create menus using:

– Menus page in Functional Administrator responsibility (preferred)

– Oracle Forms-based Menus form in the System Administrator responsibility

• Create responsibilities using:

– Oracle Forms-based Responsibilities forms in the System Administrator responsibility



Page 501 of 545

Slide 6



Create new menus or search for existing menus.

This is an OA Framework-based menus page available to the Functional Administrator. Menus you define in this page can be used for both OA Framework-based pages and Oracle Forms-based forms. Select the link on the menu name to drill down to see its menu entries. Use the Create Navigation Menu button to enter a new menu. Responsibility: Functional Administrator (or UMX: Functional Security Administration) Navigation: Core Services > Menus It is worth noting that the old Oracle E-Business Suite security system has been superceded by a newer security mechanism called, UMX (User Management). Products now leverage this new and more powerful security model. If you want to know more, please visit the Oracle User Management FAQ at: http://www.oracle.com/technology/products/applications/security/oracleusermanagementfaq.htm#Q35



Page 502 of 545

Slide 7



You can copy or update menus.

This is the page you drill down to from the Menus page. You can use this page to examine, update, and duplicate existing menus. Responsibility: Functional Administrator Navigation: Core Services > Menus > link on menu name



Page 503 of 545

Slide 8


Menus Form

Responsibility: System Administrator Navigation: Application > Menu



Page 504 of 545

Slide 9


Responsibilities Form

Responsibility: System Administrator Navigation: Security > Responsibility > Define



Page 505 of 545

Slide 10


Messages

Applications messages are stored in Message Dictionary tables in the E-Business Suite database.

• An administrator often creates new messages or personalizes shipped messages.

• Administrators create or modify messages

– OA Framework-based Messages page in the Functional Administrator responsibility (preferred).

– Oracle Forms-based Messages form in the Application Developer responsibility.

Messages and lookups are system personalizations. System administrators often create new application messages and lookups. This type of personalization applies both to OA Framework-based (web-based) products and Oracle Forms-based (traditional) products. Creating or modifying Oracle Applications messages is covered in the Oracle Applications Developer’s Guide, as well as in some product-specific documentation.



Page 506 of 545

Slide 11


Functional Administrator Messages Page

Create new messages or modify existing messages using the Messages page.

This is an OA Framework-based messages page available to the Functional Administrator. Messages you define in this page can be used for both OA Framework-based (Web-based) pages and Oracle Forms-based (Traditional forms) pages. Select the Create Message button to create a new message. Responsibility: Functional Administrator (or UMX: Functional Security Administration) Navigation: Core Services > Messages



Page 507 of 545

Slide 12


Messages Form

Responsibility: Application Developer Navigation: Application > Messages



Page 508 of 545

Slide 13


Lookups

• Application lookup values are stored in tables in the E-Business Suite database.

• An administrator often personalizes shipped lookup values or creates new ones.

• Lookups are created or modified using:

– Lookup Types page in the Functional Administrator responsibility

– Application Object Library Lookups and Application Utility Lookups forms in the Application Developer responsibility

– Application-specific forms and pages

See the Oracle Applications System Administrator’s Guide, the Oracle Applications Developer’s Guide, and product-specific documentation for further information on lookups.



Page 509 of 545

Slide 14


Functional Administrator Lookup Types Page

Lookup types and codes you define in this page can be used for both OA Framework-based (web-based) pages and Oracle Forms-based (traditional) forms. Select the link on the lookup type name to drill down to see the lookup codes and meanings. Responsibility: Functional Administrator (or UMX: Functional Security Administration) Navigation: Core Services > Lookups



Page 510 of 545

Slide 15


Drill Down to Lookup Codes Page

For those lookup types that are updatable, you can edit existing lookup codes and add new codes with meanings and descriptions by selecting the Update button.



Page 511 of 545

Slide 16


Application Object Library Lookups

This is one of several lookups forms in the E-Business Suite. Responsibility: Application Developer Navigation: Application > Lookups > Application Object Library Note: For clarity, the above screenshot is a traditional Forms 6i based page, not an OA Framework web-based page.



Page 512 of 545

Slide 17


Custom Colors and Fonts

Modify the appearance of the E-Business Suite.

• Custom style sheets

• Custom icons

• Custom Look and Feel (CLAF)

Custom Look-and-Feel (CLAF, or Custom Skin) In Release 12, OA Framework provides pages to declaratively define new a look-and-feel in a convenient HTML user interface.

• A style sheet controls colors and fonts. • Named icons can be replaced with custom icons.

The E-Business Suite includes several skins that you can use or extend. You can apply different skins at the site, responsibility, application, organization, or user level. Creating a new look-and-feel is described in another section of this class.



Page 513 of 545

Slide 18


Branding

Branding includes the display of:

• Corporate ("Oracle") brand name

• Product brand name as text drawn from one of several possible sources

• Global links shown as text at the top of the page



Page 514 of 545

Slide 19


Corporate Branding Image

Change the corporate branding image (“Oracle”) branding in one of two ways:

• Globally across all applications

– Set the profile option “Corporate Branding Image for Oracle Applications”.

• For an individual page, responsibility, and so on

– Use page personalization to replace the corporate branding image with your own.

To set a Global image to be used across all products, set the profile option “Corporate Branding Image for Oracle Applications” (FND_CORPORATE_BRANDING_IMAGE) to the full path name of an image file (GIF) that contains your corporate image. This profile option should be set at the Site level and does not have a default value. To change just a single page’s image, create an administrator personalization for a specific page by setting the Image URI property on the corporateBranding page element to a different image file. This updates the image only for the specific usage on that page. Branding is covered in more detail in the Oracle Applications Framework Personalization Guide Release 12.



Page 515 of 545

Slide 20


Product Branding Image

Product branding is determined in one of three ways:

• Defaults from the current responsibility and page link

• Administrator can declaratively override the default value with a personalization that sets the Text property on the productBranding: formattedText page element to a new value.

• Developer can override the first two values by defining a Form Function and programmatically calling it using the OAPB URL parameter with the page to specify the product branding text.

Personalizing product branding is covered in more detail in the Oracle Applications Framework Personalization Guide Release 12.



Page 516 of 545

Slide 21


Concepts: Page Personalizations

• Personalizations modify the user interface of a page.

• Personalizations are layered on top of the base page at runtime.

– Base product pages are not changed.

• Personalizations survive upgrades. Base Product

Page Definition



Layered Page Personalizations OA Framework-based pages are saved as metadata in the database (page definitions). Each page personalization represents just the change (i.e., the delta change) from the base page definition. Page personalizations are also stored as metadata definitions. At runtime, the personalization definitions are layered over the base page definitions.

Page Personalizations Survive Upgrades Because page personalizations are saved as metadata documents in the database, and that data is not affected by an upgrade, personalizations survive upgrades unchanged. You should test and evaluate each personalization after an upgrade, however. In some cases, your personalizations may no longer be valid. Reasons personalizations might become invalid include:

• Functionality you created or modified for a specific product now may be incorporated into the base product pages, making your personalization no longer necessary after the upgrade.

• A page in a product may have been modified by development to remove fields or regions, in which case personalizations based on those fields would no longer be valid. This scenario is unlikely.

• A page in a product may have been modified by development to add fields or regions, in which case you may want to create additional personalizations after the upgrade.



Page 517 of 545

• A page in a product may have been completely rewritten by development, in which case most or all of the personalizations on that page may be invalid. This scenario is unlikely.



Page 518 of 545

Slide 22


Concepts: User Personalizations

There are two types of personalizations:

• End User personalizations

– No special authority needed

– Available on inquiry pages built to allow saved searches

– Can modify query criteria, display of results

• Administrator personalizations

– Administrator must have profile options set to access the administrator personalization UI.

– Can add fields, make changes for all OA Framework-based pages

Administrator Personalizations and User Personalizations Administrators can personalize most pages, regions, and items in the OA Framework-based parts of the E-Business Suite. Administrators can do personalizations that affect the behavior and functionality of the pages, such as adding new fields and connecting them to data in tables. The changes made by administrators can affect the applications across the entire installation, or at more restricted levels. End users are much more limited in what they can do. Users can only make personalizations to inquiry pages where personalization has been specifically enabled by the application developer. User personalizations affect only the user who creates them. Users can hide some columns, and they can change prompts, order of table columns, query criteria, and sort order of columns, but they cannot add new columns or other items to the page.



Page 519 of 545

Slide 23


Concepts: Personalization Levels

• Administrator Personalization

– Function

– Industry

– Location

– Site

– Organization

– Responsibility

• End User Personalization

– User Views

Base ProductPage Definition



Personalization Levels The various personalization levels are layered. For example, a responsibility-level personalization would take effect above and beyond any personalizations at the site level for a user in the specified responsibility, but any other users at the site not using that responsibility would see only the site-level changes.

Levels • Function Level - the customer administrator can define functions and use

them as context for granular level personalizations. For example, you can create a function-level personalization to "hide the salary field, if the user is updating an employee record, but not when the user is creating a new employee".

• Industry Level – the customer administrator can introduce personalizations that affect all users of a particular industry such as using the term “business unit” rather than “store”, “location”, or “franchise”. Industry level includes a predefined list of vertical market categories, such as Healthcare - Provider and Utilities – Electricity.

• Localization Level - the customer administrator can use locales as context for personalizations such as "showing a different address field label based on country settings".

• Site Level - the customer administrator can introduce global personalizations that affect all users with access to the given application component, such as "setting the number of rows shown in a table".



Page 520 of 545

• Organization Level - the customer administrator can introduce personalizations that affect all users belonging to a particular organization or business unit with access to the application component. Example: "sort notifications by age for one organization and by urgency for another".

• Responsibility Level - the customer administrator can introduce personalizations that affect all users of a particular responsibility with access to the application component. Example: "show a trend graph for the sales manager responsibility".

• Seeded User Level - like the User Level available to End Users, but personalizations made at this level are visible to all users and can only be changed or deleted by the customer administrator. (Also referred to as "Admin-seeded user-level" personalizations.)

Oracle-Seeded Levels Oracle E-Business Suite developers can also seed personalizations as part of the product:

• Seeded Function Level - like the Function Level available to Administrators, but personalizations made at this level can only be changed or deleted by Oracle.

• Seeded User Level - like the User Level available to End Users, but personalizations made at this level can only be changed or deleted by Oracle. (Also referred to as "Oracle-seeded user-level" personalizations.)

• Oracle Applications Developers can create and ship personalizations at any of the Administrator personalization levels discussed above, but these are not protected against change and deletion by Administrators at the customer site.



Page 521 of 545

Slide 24


Personalization Levels and Layers

Add personalization layers to get to a particular personalization level.

• Layer is the definition of a particular personalization that is placed on top of a previous layer.

• Level is the net result of personalization layers to that point in the personalizations stack.



Page 522 of 545

Slide 25


Layers and Levels

Organization Layer

Responsibility Layer

Site Layer

Location Layer

Function Layer

Base Page Layer

Base Page Level (no personalization)

Function Level = Base Page + field

Location Level = Function level + new prompt

Site Level = Location level + hidden field

Org Level = Site level + required field

Resp Level = Org level + reordered fields

Add field

Change prompt

Hide different field

No personalization

Reorder fields

Make field required

Personalizations add themselves like onion-layers to a page. This hierarchy shows the order in which those layers of personalization are applied. Each progress layer up the hierarchy includes all the changes beneath it, plus any changes that it adds to the mix. Understanding this hierarchy is important to debugging unusual behavior. Let’s offer an example. Function Layer: add a field Site Layer: hide the field added at the function layer. In this example, you might think that your new field would appear on the page, but since the field was hidden at a layer above where it was added, the field will not appear on the page. Diagnosing issues like this can be time-consuming to track down all the possible culprits.



Page 523 of 545

Slide 26


Summary


• List the capabilities of personalizations.

• Discuss the benefits of personalizations.



Page 524 of 545







Page 525 of 545

Slide 2


Objectives


• Discuss the basic types of OA Framework extensions

• Describe the basic methodology for OA Framework extensions

• Discuss common extension tasks

• Add a new attribute to an OA Framework page

• Set a default attribute value

• Validate an attribute value



Page 526 of 545

Slide 3


4 Basic Types of Extensions

• Add a new attribute and expose it to the UI.

• Set default attribute values.

– Simple & local method

– Simple & global method

– Method for calculated values

• Validate attribute values.

– Attribute level

– Calculated attribute level

– Cross-attribute level

– Cross-entity level

• Develop a supplemental module (customization).



Page 527 of 545

Slide 4


Adding New Attributes


• Identify and reuse an existing table.


• Identify and reuse existing EOs.

• Identify and extend existing VO.

• Create and deploy a BC4J substitution.

• Use Admin Personalization to expose the new attribute on the UI.

Note: The assumption is that the tables, EOs, VOs, and other BC4J object currently exist. If they don’t, the additional steps of creating those objects will need to be done.



Page 528 of 545

Slide 5



• Simple & local method


– Use Admin Personalization to set the default value.



Page 529 of 545

Slide 6



• Simple & global method




– Set the default value using the BC4J Wizard.

– Create and deploy a BC4J substitution.



Page 530 of 545

Slide 7



• Method for calculated values




– Add code to the EO Create() method to set the default value.




Page 531 of 545

Slide 8



• Attribute Level




– Set the attribute validation using the BC4J Wizard.




Page 532 of 545

Slide 9



• Calculated Attribute Level




– Add code to the EO set<attribute>() method to validate the value.




Page 533 of 545

Slide 10



• Cross Attribute Level




– Add code to the EO validateEntity() method to validate the value(s).




Page 534 of 545

Slide 11



• Cross Entity Level



– Identify and extend existing VO.

– Add code to the VO Validate() method to validate the value(s).




Page 535 of 545

Slide 12


New Development

• Create a new APP ID.


• Create or reuse the database table.

• Create or reuse the EO(s).

• Create or reuse the VO(s).

• Create or reuse the AM(s).

• Create a page or flow of pages.

• Link the new page to an existing application or a new menu.



Page 536 of 545

Slide 13


Common Extension Tasks



• Create and deploy a BC4J Substitution.



Page 537 of 545

Slide 14


Deploying an Extension

BC4J components that are extended consist of the following:

• XML file(s) that provide declarative properties for your extended component(s).

• Java file(s) that provide overridden methods from the base class for the component.

• JPX file(s) that deploy the corresponding BC4J substitutions.

A complete discussion of deployment will occur later. At this point, the common task we are observing is the creation and deployment of a BC4J substitution.



Page 538 of 545

Slide 15



• Open the Project Properties window.

• Navigate to Business Components > Substitutions.

• From the Available list, select the base BC4J object (e.g., PoSummaryVO) that you want to be substituted.

• From the Substitute list, select the extended object (e.g., MyCompanyPoSummaryVO) that you want to substitute.

• Choose Add to create a new substitution rule.

• Select OK to save your changes.



Page 539 of 545

Slide 16





Page 540 of 545

Slide 17



When you save your changes to the project, the BC4J framework updates the project’s .jpx file. The .jpx file is an XML document that includes a “<Substitutes>” section as shown below.

<Substitutes>

<Substitute OldName

=“oracle.apps.fnd.framework.toolbox.tutorial.

server.PoSummaryVO”

NewName

=“mycompany.oracle.apps.fnd.framework.toolbox

.tutorial.server.MyCompanyPoSummaryVO”/>

</Substitutes>



Page 541 of 545

Slide 18


Deploying a BC4J Substitution

There are 2 methods by which you can deploy a BC4J substitution.

• Deploy from within JDeveloper with OA Extension.

• Deploy from the middle-tier server.



Page 542 of 545

Slide 19



Open your Project Properties window. Select Run/Debug. Select the Default Run Configuration, and click the Edit button.



Page 543 of 545

Slide 20



Add –Djbo.project=<NAME> to the Java Options field. Note: The <NAME> value is the .jpx file name without the .jpx extension (e.g., ExtendLabSolution). Be sure to include a space between any existing options and the new option.



Page 544 of 545

Slide 21


Deploy on the Middle-Tier Server

You must load any <ExtensionProject>.jpx files of BC4J substitutions into the MDS Repository

• Use the jpx import utility jpximport.bat

– Located under the jdev\bin directory of your JDeveloper with OA Extension installation.

– Run from the command line

– Running the utility without any parameters displays usage options and format information

• The import utility transforms each substitution into a separate site-level customization document which is then imported into the MDS Repository.

The .jpx files contain information on any BC4J substitutions you made when extending Oracle Applications BC4J objects. To have a .jpx file of BC4J substitutions take effect at runtime in a deployed environment, you must import your substitution information into the MDS Repository. You can load multiple .jpx files into the MDS Repository, but if multiple substitutions apply to the same object, the substitution loaded latest will override previously-loaded substitutions.



Page 545 of 545

Slide 22


Summary


• Discuss the basic types of OA Framework extensions.

• Describe the basic methodology for OA Framework extensions.

• Discuss common extension tasks.

• Add a new attribute to an OA Framework page.

• Set a default attribute value.

• Validate an attribute value.

Open the Course Labs book. Complete Lab X – Adding Attributes Complete Lab X – Setting Default Values Complete Lab X – Adding Validations