11i Extend Oracle Applications: Building OA Framework Applications Student Guide

11i Extend Oracle Applications: Building OA Framework Applications Student Guide Course Code D18994GC11 Edition 1.1 English Month Year October 2005 Part Number D19286

Copyright Oracle Corporation, 2005. All rights reserved. This documentation contains proprietary information of Oracle Corporation. It is provided under a license agreement containing restrictions on use and disclosure and is also protected by copyright law. Reverse engineering of the software is prohibited. If this documentation is delivered to a U.S. Government Agency of the Department of Defense, then it is delivered with Restricted Rights and the following legend is applicable: Restricted Rights Legend Use, duplication or disclosure by the Government is subject to restrictions for commercial computer software and shall be deemed to be Restricted Rights software under Federal law, as set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013, Rights in Technical Data and Computer Software (October 1988). This material or any portion of it may not be copied in any form or by any means without the express prior written permission of the Education Products group of Oracle Corporation. Any other copying is a violation of copyright law and may result in civil and/or criminal penalties. If this documentation is delivered to a U.S. Government Agency not within the Department of Defense, then it is delivered with Restricted Rights, as defined in FAR 52.227-14, Rights in Data-General, including Alternate III (June 1987). The information in this document is subject to change without notice. If you find any problems in the documentation, please report them in writing to Worldwide Education Services, Oracle Corporation, 500 Oracle Parkway, Box SB-6, Redwood Shores, CA 94065. Oracle Corporation does not warrant that this document is error-free. Oracle and all references to Oracle Products are trademarks or registered trademarks of Oracle Corporation. All other products or company names are used for identification purposes only, and may be trademarks of their respective owners. Authors: Bill Sawyer, Sara Woodhull, Liza Lyons, Suvarna Gaddipati Technical Contributors and Reviewers: Eric Bing, Anne Carlson, Siu Chang, John Zerbel, Mark Sullivan, Bill Curtis This book was published using: oracletutor

Table of Contents Introduction and the OA Framework Architecture...1-1 11i Extend Oracle Applications: Building OA Framework Applications...1-2 Course Objectives...1-3 Lesson Objectives...1-5 Day 1...1-6 Day 2...1-7 Day 3...1-8 Day 4...1-9 Day 5...1-10 Advantages of Java...1-11 3 Pillars of Java Programming...1-13 Core Java Specification...1-15 Design Patterns...1-16 Frameworks...1-18 What is a Framework?...1-20 Parts of OA Framework...1-21 Model-View-Controller (MVC) Design Pattern...1-23 Flexible Architecture...1-24 OA Framework Architecture...1-25 Resources...1-26 Summary...1-27 Introduction to the Model-View-Controller (MVC) Design Pattern...2-1 11i Extend Oracle Applications: Building OA Framework Applications...2-2 Objectives...2-3 Model-View-Controller (MVC) Design Pattern...2-4 Model: Business Components for Java...2-5 Model: Application Modules...2-6 Model: Entity Objects...2-7 Model: View Objects...2-8 Model: Controlling Transactions...2-9 View: OA Framework-Based Page...2-10 View: Java Objects in a Page...2-11 View: A Framework Example...2-12 View: Page Hierarchy...2-13 View: A Framework Region...2-14 View: Reusing Page Components with the Extends Property...2-15 View: Attribute Sets Improve Consistency...2-16 View: Data Source Binding...2-17 The View - Design Time...2-18 The View - Personalization...2-19 Controller: Controlling UI Behavior...2-20 Controller: Handling a GET Request...2-21 Controller: Handling a POST Request...2-22 Controller: The OAPageContext Object...2-23 Controller: Applications Context...2-25 Client and Server...2-26 Resources...2-27 Summary...2-28 Setting Up Your Development Environment...3-1 11i Extend Oracle Applications: Building OA Framework Applications...3-2 Objectives...3-3 i

Basic JDeveloper Deployment...3-4 Configure the JDEV_USER_HOME Environment Variable on Your PC...3-6 Get Tutorial.zip File and Extract...3-8 Start JDeveloper and Verify Installation...3-10 Checking DB Connections...3-12 Setting Up Connections...3-14 Connection Wizard...3-15 OA Workspaces and OA Projects...3-19 OA Project Settings...3-20 Summary...3-22 Implementing Your First OA Framework Page: Hello World...4-1 11i Extend Oracle Applications: Building OA Framework Applications...4-2 Objectives...4-3 Finished Page...4-4 Overview...4-5 Prerequisite: Set Up Your Development Environment...4-6 Step 1. Create a New OA Workspace and Empty OA Project...4-8 Step 2. Set Run Options in OA Project Settings...4-12 Step 3. Create the OA Components Page File...4-13 Step 4. Modify the Page Layout (Top-level) Region...4-16 Step 5. Create the Second Region (Main Content Region)...4-18 Step 6. Create the First Item (Empty Field)...4-20 Step 7. Create a Container Region for the Go Button...4-22 Step 8. Create the Second Item (Go Button)...4-23 Step 9. Save Your Work...4-24 Step 10. Run Your Page Using the Run Option...4-25 Step 11. Add a Controller...4-28 Step 12. Edit Your Controller...4-29 Step 13. Build Your Controller...4-32 Step 14. Test Your Work Using the Run Option...4-33 Step 15. Test Your Work Using the Debugger...4-34 Summary...4-38 Basics of the Model...5-1 11i Extend Oracle Applications: Building OA Framework Applications...5-2 Objectives...5-3 BC4J Objects...5-4 Encapsulation The "Reuse Onion"....5-5 Entity Objects...5-6 Entity Object...5-7 Entity Objects: Creation Standards...5-8 Entity Object Automatic Features...5-9 Entity Object Information...5-10 Association...5-11 Entity Association...5-12 View Objects...5-16 View Object...5-17 View Object Rows...5-23 Creating View Objects in the VO Wizard...5-24 View Object Java Files...5-25 View Object Files...5-26 View Object Non-BC4J Solution...5-27 View Object BC4J Solution...5-28 View Object BC4J Solution - Read-Only...5-29 View Object Initial Query...5-30 View Object EO Population...5-31 View Object EO Uniqueing...5-32 ii

View Object Entity-Derived Attributes...5-33 View Object EO Fault-in...5-34 View Object Reference EOs...5-35 View Object VO/EO Merge - Part 1...5-36 View Object VO/EO Merge - Part 2...5-37 View Object VO/EO Merge - Part 3...5-38 Master-Detail Relationships...5-39 View Link...5-40 Application Module...5-42 Transaction...5-45 BC4J Packages in JDeveloper...5-46 Summary...5-47 Guided Demonstration - Setting Up Your Development Environment...5-48 Basics of the View...6-1 11i Extend Oracle Applications: Building OA Framework Applications...6-2 Objectives...6-3 Terminology...6-4 OA Workspaces and OA Projects...6-5 Region Styles...6-6 Named Children and Indexed Children...6-8 Page Layout Region...6-9 Item Styles...6-10 More Item Styles...6-11 Attribute Sets...6-12 Extending Other Objects...6-13 CSS Styles...6-14 Common CSS Styles...6-15 Binding Items to Data...6-17 Creating a Region with the Region Wizard...6-18 Destinations and Links...6-19 Mailto Links...6-20 Standards Help Meet Many Requirements...6-21 General Naming Rules...6-22 Page and Object Naming Rules...6-25 Styles and Bean Names...6-26 Attribute Set Standards...6-27 Attribute Sets...6-29 Attribute Set Naming Conventions...6-30 More Attribute Set Standards...6-31 More Standards Information...6-32 Overview of Building Search Regions...6-33 Simple Search...6-34 Advanced Search...6-35 Personalized Views...6-36 Construction Mode...6-37 Results-based Search...6-38 Auto Customization Criteria Search...6-39 Construction Mode of "None"....6-40 Manually-Built Search Regions...6-41 Disabling Blind Queries...6-42 Lists of Values (LOVs)...6-43 Defining an External LOV...6-45 Summary...6-47 Basics of the Controller...7-1 11i Extend Oracle Applications: Building OA Framework Applications...7-2 Objectives...7-3 iii

Common Logic to Code...7-4 Typical Locations for Code...7-5 Handling Queries...7-6 View Object initquery Code...7-7 Dynamic WHERE Clauses...7-9 Using findbykey Instead of initquery...7-10 Processing a Button Press...7-11 Checking for Button Presses and Getting Parameters from Requests...7-12 Example: Manually-built Search...7-13 The Process...7-14 Example Search: Controller...7-15 Forwarding to Another Page...7-16 Setting Titles with Message Dictionary...7-17 Event Flow Overview...7-18 Initial Setup Flow...7-19 Controller Event Flows in OA Framework...7-20 GET Event Flow Overview...7-21 GET Event Flow (1) Get info and validate user...7-22 GET Event Flow (2) Fetch Metadata...7-23 GET Event Flow (3) Get Root AM, Validate Session...7-24 GET Event Flow (4) Instantiate BC4J and UIX Classes...7-25 Example Bean Hierarchy Structure...7-26 GET Event Flow (5) processrequest...7-27 GET Event Flow (6) Post-Processing...7-28 GET Event Flow (7) UIX Renders the Page...7-29 Structure of a Web Bean...7-30 Data Binding...7-31 POST Event Flow Overview...7-32 POST Event Flow (1-3) Submit, Client-Side Validation...7-33 POST Event Flow (4 & 5) Validate User and Retrieve State...7-34 POST Event Flow (6) Apply Form Data...7-35 POST Event Flow (6) More of processformdata...7-36 POST Event Flow (7) processformrequest...7-39 Summary...7-40 Implementing a Search...8-1 11i Extend Oracle Applications: Building OA Framework Applications...8-2 Objectives...8-3 Finished Page Before Search...8-4 Finished Page After Search...8-5 Finished List of Values Page...8-6 Finished Drilldown-to-Details Page...8-7 Overview...8-8 Task 1: Create Your Project...8-9 Task 2: Create Your Page's Model Components...8-11 Task 3: Create Your Initial Page...8-21 Task 4: Configure a Results-Based Search...8-24 Task 5: Convert Search Region to Auto Customization Criteria...8-29 Task 6: Add a List of Values (LOV) to Your Employee Name Field...8-32 Overview...8-37 Task 1: Create the Details Page View Object...8-39 Task 2: Create the Details Page UI...8-42 Task 3: Implement the View Object Query...8-47 Task 4: Implement the Drilldown to the EmpDetailsPG...8-49 Summary...8-52 Debugging OA Framework Applications...9-1 11i Extend Oracle Applications: Building OA Framework Applications...9-2 iv

Objectives...9-3 Oracle9i JDeveloper Debugger...9-4 Invoking the Oracle9i JDeveloper Debugger for OA Framework Pages...9-6 Fundamentals of Debugging...9-7 Breakpoints...9-8 Setting Breakpoints...9-9 Editing Breakpoints...9-10 Breaking on Exceptions...9-12 Setting Breakpoints During Runs...9-13 Exception-style Breakpoint...9-14 Debugger Windows: Data...9-15 Debugger Windows: Smart Data...9-16 Debugger Windows: Stack...9-17 Other Debugger Windows...9-18 Stepping Through a Program...9-19 Customizing Debugger Windows...9-21 Debugging Declarative Applications...9-22 More Debugging Tips...9-23 Understand BC4J Interactions...9-24 Debugging Validation and Commits...9-26 Demonstration...9-27 Overview...9-28 Task 1: Investigate Unexpected Code Execution (Part 1)...9-30 Task 2: Resolve a NullPointerException (NPE)...9-31 Task 3: Resolve a ClassCastException...9-33 Task 4: Resolve a SQLStmtException...9-34 Task 5: Use a Class Breakpoint...9-38 Task 6: Investigate Unexpected Code Execution (Part 2)...9-39 Task 7: Explore Application Module Retention Behavior...9-41 Task 8: Resolve a Common Missing Import...9-44 Task 9: Investigate Unexpected UI Results...9-45 Summary...9-46 Implementing a Create (Part 1)...10-1 11i Extend Oracle Applications: Building OA Framework Applications...10-2 Objectives...10-3 Implementing a Create Overview...10-4 Implementing a Poplist...10-5 Extending a Shared Region...10-6 Creating a New Row...10-7 Initializing a View Object...10-8 Creating and Initializing a VO Row...10-9 Getting the Data...10-10 Saving a Row to the Database...10-11 Overview...10-12 Task 1: Build the Create Page...10-14 Task 2: Implement the Positions Poplist...10-22 Task 3: Implement Row Initialization (Create a View Object Row)...10-25 Task 4: Implement the Apply Button Handling...10-26 Task 5: Revise Search Page to Include Create Employee Button...10-30 Summary...10-32 Implementing a Create (Part 2)...11-1 11i Extend Oracle Applications: Building OA Framework Applications...11-2 Objectives...11-3 Implementing a Create Overview...11-4 Validation...11-5 What Triggers Validation...11-6 v

Client-side Validation...11-7 Server-side Validation Attribute Level...11-8 Server-side Validation Entity Object Level...11-9 Server-side Validation View Object Level...11-10 Validation Helpers...11-11 Using SQL to Validate EOs...11-12 EOs Need VOs to Hold SQL...11-13 Solution: "Validation VOs" and "Validation AMs"...11-14 Where Do These Fit in the "Reuse Onion"?...11-15 Situation: Purchase Order Business Object...11-16 Solution: Entity Expert...11-17 Customer Extends Code...11-18 Entity Expert Primary Access Point to VAMs and VVOs...11-19 Benefits of Using Entity Experts...11-20 Building Entity Experts...11-21 Associate Entity Expert with EO...11-22 Building VVOs and VAMs...11-23 Referencing VVOs and VAMs...11-24 Defaulting Data - Model Interactions...11-25 Back Button Primer...11-27 Transaction Unit Helper...11-28 Allow the Back Button?...11-30 Overview...11-31 Task 1: Handle the Back Button in Your Application...11-32 Task 2: Implement Employee Business Logic Using Declarative Validation...11-36 Task 3: Implement Employee Business Logic Using Java Code...11-38 Task 4: Validate and Set the Start Date...11-42 Task 5: Add Logic to Make Employee Name...11-45 Task 6: Creating VVOs for Validations...11-47 Task 7: Create an Entity Expert Class...11-50 Task 8: Validate and Set the ManagerId...11-52 Task 9: Validate and Set the Position...11-54 Task 10 (Optional): Validate and Set the End Date and Salary...11-56 Task 11: Implement Cross-Attribute (Entity Level) Business Logic...11-59 Summary...11-62 Implementing Partial Page Rendering (PPR)...12-1 11i Extend Oracle Applications: Building OA Framework Applications...12-2 Objectives...12-3 Implementing PPR Overview...12-4 What Is Partial Page Rendering (PPR)?...12-5 Uses of PPR...12-6 OA Framework Features Using PPR...12-7 Item Styles That Support PPR Events...12-8 PPR Requirements...12-9 Create Page Flow...12-10 Create Page Flow with PPR...12-11 Dynamic Page Structure...12-12 Dynamic Page Structure Actions...12-13 Overview...12-14 Task 1: Create an "Application Properties" View Object...12-16 Task 2: Configure Position Item to Fire PPR Action on Change...12-17 Task 3: Configure the MgrName Item to React to PPR Events...12-18 Task 4: Implement PPR Event Handling...12-19 Summary...12-22 Implementing a Delete...13-1 11i Extend Oracle Applications: Building OA Framework Applications...13-2 vi

Objectives...13-3 Implementing a Delete Overview...13-4 Error Handling Overview...13-5 Exception Types...13-6 Message Types...13-8 Message Dictionary...13-9 Attribute-level Exceptions Example...13-10 OAAttrValException Entity Attribute Example...13-11 Other Features...13-12 Dialog Pages...13-13 Example: Redirect to a Basic Warning Page...13-14 Message Boxes...13-15 Message Boxes Example...13-16 Resources...13-17 Overview...13-18 Task 1: Implement a Delete in Your EmployeeEOImpl Class...13-20 Task 2: Implement a Delete Switcher...13-21 Task 3: Implement the Delete Action...13-26 (Optional) Challenge Task: Create and Implement the Status Column...13-32 Summary...13-36 Implementing an Update...14-1 11i Extend Oracle Applications: Building OA Framework Applications...14-2 Objectives...14-3 Finished Page...14-4 Overview...14-9 Task 1: Make a Copy of Your EmployeePG...14-10 Task 2: Add an Update Column to the Search Page...14-12 (Optional) Challenge Exercise: Create a Multistep Update...14-15 Task CE-1: Modify EmpUpdatePG to Create the "Step 1" Page...14-16 Task CE-2: Build the "Step 2" Page...14-18 Task CE-3: Build the "Step 3" Page...14-21 Task CE-4: Build and Implement the Shared Train...14-24 Task CE-5: Build and Implement the Shared Navigation Buttons...14-26 Summary...14-32 Creating Applications' Menus and Function Security...15-1 11i Extend Oracle Applications: Building OA Framework Applications...15-2 Objectives...15-3 Example Menu...15-4 Menu: Global Menu...15-5 Menu: Tabs...15-6 Menu: Horizontal Navigation...15-7 Menu: Side Navigation...15-8 Menu: Subtab...15-9 Menu: Task/Property Menu...15-10 Menu Structures...15-11 Oracle Applications Forms...15-12 Creating Menus...15-13 Register Functions...15-14 Functions...15-15 Menu Context...15-16 Creating Responsibilities...15-18 Creating Users...15-19 Using JSP Pages for Testing...15-20 Creating JSP Pages to Call Menus...15-21 Future Direction: Navigation and Security Separate...15-22 Grants and Permissions Structures...15-23 vii

Summary...15-24 Personalizing and Extending OA Framework Pages...16-1 11i Extend Oracle Applications: Building OA Framework Applications...16-2 Objectives...16-3 Personalization vs Extension...16-4 Personalization Capabilities...16-5 Types of Extensions...16-6 Oracle Applications Technology Stack Overview...16-7 User Interface Personalization...16-8 Administrator Personalization...16-9 Administrator Personalization Features...16-10 User Personalizations...16-11 User Personalization Features...16-12 Benefits of Personalizations...16-13 Extension Types...16-14 Adding a New Page...16-15 Extensions: Adding a New Page...16-16 Adding Attributes...16-17 Add Attribute Scenario...16-18 Override Default Values Scenario...16-19 Override Attribute Validation Scenario...16-20 Summary...16-21 Naming Standards and Deploying an OA Framework Page...17-1 11i Extend Oracle Applications: Building OA Framework Applications...17-2 Objectives...17-3 OA Framework File Standards...17-4 Package Names...17-5 File Names...17-9 Standard File Suffix Abbreviations...17-10 Region and Item Names...17-12 JDeveloper to Apache Mapping...17-13 Deploying Model and Controller Files...17-15 Deploying the BC4J Substitutions File...17-17 Deploying the View...17-18 XMLImporter...17-19 Compatibility...17-21 Summary...17-22 Understanding OA Framework State Management...18-1 11i Extend Oracle Applications: Building OA Framework Applications...18-2 Objectives...18-3 Agenda...18-4 State Management...18-5 State Architecture...18-6 Root Application Module...18-7 Application Module Default Behavior...18-8 Servlet Session...18-9 Applications User Session (ICX Session)...18-10 Page Context...18-11 Request...18-12 Parameter Values...18-13 Token Types...18-14 Ways to Pass Parameters...18-15 Related Topic: Passivation...18-16 Passivation...18-17 Demonstration: Application Module Management...18-18 viii

Expense Report Flow...18-20 Setup Flow...18-21 Related Pages on Same Menu Tab...18-22 Different Page Flows: Create Missing Supplier...18-23 Recommendations: Multipage Flow...18-24 Recommendations: Multipage Flow with Side Trip Flow...18-25 More Recommendations for Side Trip Flow: Use "Extended Pages"....18-26 Recommendations: Unrelated Pages...18-27 Summary...18-28 ix

Preface Profile Before You Begin This Course Before you begin this course, you should have the following qualifications: Thorough knowledge of Oracle Applications System Administration Working experience with Java programming Prerequisites There are no prerequisites for this course. How This Course Is Organized 11i Extending Oracle Applications: Building OA Framework Applications is an instructor-led course featuring lecture and hands-on exercises. Online demonstrations and written practice sessions reinforce the concepts and skills introduced. xi

Related Publications Oracle Publications Title Part Number Additional Publications System release bulletins Installation and user s guides Read-me files International Oracle User s Group (IOUG) articles Oracle Magazine xii

Typographic Conventions Typographic Conventions in Text Convention Element Example Bold italic Caps and lowercase Courier new, case sensitive (default is lowercase) Initial cap Italic Quotation marks Uppercase Glossary term (if there is a glossary) Buttons, check boxes, triggers, windows Code output, directory names, filenames, passwords, pathnames, URLs, user input, usernames Graphics labels (unless the term is a proper noun) Emphasized words and phrases, titles of books and courses, variables Interface elements with long names that have only initial caps; lesson and chapter titles in crossreferences SQL column names, commands, functions, schemas, table names The algorithm inserts the new key. Click the Executable button. Select the Can t Delete Card check box. Assign a When-Validate-Item trigger to the ORD block. Open the Master Schedule window. Code output: debug.set ( I, 300); Directory: bin (DOS), $FMHOME (UNIX) Filename: Locate the init.ora file. Password: User tiger as your password. Pathname: Open c:\my_docs\projects URL: Go to http://www.oracle.com User input: Enter 300 Username: Log on as scott Customer address (but Oracle Payables) Do not save changes to the database. For further information, see Oracle7 Server SQL Language Reference Manual. Enter user_id@us.oracle.com, where user_id is the name of the user. Select Include a reusable module component and click Finish. This subject is covered in Unit II, Lesson 3, Working with Objects. Use the SELECT command to view information stored in the LAST_NAME column of the EMP table. Arrow Menu paths Select File > Save. Brackets Key names Press [Enter]. Commas Key sequences Press and release keys one at a time: [Alternate], [F], [D] Plus signs Key combinations Press and hold these keys simultaneously: [Ctrl]+[Alt]+[Del] xiii

Typographic Conventions in Code Convention Element Example Caps and Oracle Forms When-Validate-Item lowercase triggers Lowercase Column names, table names SELECT last_name FROM s_emp; Passwords PL/SQL objects DROP USER scott IDENTIFIED BY tiger; OG_ACTIVATE_LAYER (OG_GET_LAYER ( prod_pie_layer )) Lowercase italic Uppercase Syntax variables SQL commands and functions CREATE ROLE role SELECT userid FROM emp; Typographic Conventions in Oracle Application Navigation Paths This course uses simplified navigation paths, such as the following example, to direct you through Oracle Applications. (N) Invoice > Entry > Invoice Batches Summary (M) Query > Find (B) Approve This simplified path translates to the following: 1. (N) From the Navigator window, select Invoice then Entry then Invoice Batches Summary. 2. (M) From the menu, select Query then Find. 3. (B) Click the Approve button. Notations: (N) = Navigator (M) = Menu (T) = Tab (B) = Button (I) = Icon (H) = Hyperlink (ST) = Sub Tab xiv

Typographical Conventions in Oracle Application Help System Paths This course uses a navigation path convention to represent actions you perform to find pertinent information in the Oracle Applications Help System. The following help navigation path, for example (Help) General Ledger > Journals > Enter Journals represents the following sequence of actions: 1. In the navigation frame of the help system window, expand the General Ledger entry. 2. Under the General Ledger entry, expand Journals. 3. Under Journals, select Enter Journals. 4. Review the Enter Journals topic that appears in the document frame of the help system window. xv

xvi