OAF - Standards

Oracle Application Framework Developer's Guide, Release 12.1.3

1489

Chapter 8: Standards and Guidelines

Oracle E-Business Suite Java Coding Standards

Overview

This document describes general Java coding standards that apply to any Java code you write. It is organized into the following categories:

x Generalx Performancex Internationalizationx Patching Binary Compatible JavaIf you need information about file naming conventions, standard file contents/organization, or directory (package) structures for any OA Framework application file types (including Java files), see OA Framework File Standards (Naming, Package Structure and Standard Content).

For information about coding standards (including performance guidelines) related to specific areas of OA Framework application coding, see the Model, View and Controller coding standards. For example, for all the standards related to the definition and implementation of view objects, see the OA Framework Model Coding Standards.

Standards Column Description Key

Column Header

Description

No The standard's number. Note that, for convenience, some standards appear in multiple documents. In these cases, the duplicate references the original standard.

Rule The standard or guideline content.

Reason Provides additional explanation for why the standard or guideline is recommended.

General

No Rule Reason

Oracle Application Framework Developer's Guide

1490

A1 You should have only one top level "outer" class per Java file. Inner classes are permitted, but remember that the concatenated name (combination of the outer and inner class names) can't exceed 50 characters.

The Java Release Infrastructure (JRI) requires each Java file to have a valid package declaration and to contain exactly one top-level class declaration.

A2 Public constants should be used sparingly, and should never be changed after code is shipped.

The Java compiler does not force recompilation of files that referenceconstants when those constants change (the Java compiler optimizes reference to public static final variables to their actual value in the code that refers to them). Rather than reuse a constantname, create a new constant to maintain backward compatibility with existing constants.

For all classes that have an Interface defined, all public constants should be declared in the interface as opposed to any implementation of that interface.

A3 Member variables may have the public, protected, private or default visibility, however, member variables that are "public" should usually be made private with public

accessors defined for them: setXX(), getXX()

It is a poor design practice to publish public member variables allowing direct access by other classes. This is fragile, and it breaks the object's encapsulation.

If the accessors are overridable, the class code must use the accessor instead of using the private member variables directly. This will allowsubclasses to easily add behavior to the accessors.

A4 Avoid client-side Java (Swing, EWT, applets and so on) All client-side Java in Oracle E-Business Suite is planned for replacement. No new client-side Java code should be written without senior management approval.


1491

A5 Never use Java in the database. No robust patching infrastructure, undesirable overhead of supporting another JVM and performance.

A6 Never catch and "swallow" exceptions unless you can fix the cause of the exception, and no user action/notification is required.

While writing initial code, it is often tempting to "swallow" exceptions (catch an exception and do nothing with it, or simply write a message to the console). It is very likely that if you do this frequently, you will overlook some catch block, and fatal exceptions could be thrown that are not handled properly.

A23 Do not use the browser cookie to store state information. Browser cookies are reserved for OA Framework internal use only. They add request bloat, and there is a corporate initiative to reduce cookie usage.

Performance

No Rule Reason

A7 Use a StringBuffer for concatenation. Strings are immutable objects, so when used for concatenation, unnecessary temporary objects will be created.

A8 Size your StringBuffer properly. If initial StringBuffer size is not enough, the original char[] will be discarded and moved to a newly allocated one, thus creating unnecessary temporary objects.

A9 Use String.equals() for String equality testing. This defaults to object reference equality and then to char by char comparison.

A10 Do not use exceptions for regular code path execution.

For example, some OA Framework developers have

used ViewObjectImpl.findAttributeDef()

which throws an exception when the attribute is missing. Instead, you should use the JDeveloper method ViewObjectImpl.lookupAttributeDef()

To fill the stack trace for an exception, the JVM has to deoptimize the code to report a correct trace.


1492

which returns null when the attribute is missing.

A11 Size your collections properly. This avoids resizing at runtime and rehashing for hashtables and hashmaps.

A12 Do not use synchronized collections for thread local or read only objects.

For example:

1. Avoid using Vectors for objects that do not need thread safety (that is, only used by one thread at any point of time). Use ArrayLists in this case.

2. Avoid using Hashtable for objects that do not need thread safety (that is, only used by one thread at any point of time). Use HashMaps in this case.

Synchronization adds unnecessary overhead in this case since it needs to acquire the monitor, execute the method and release the monitor.

A13 Minimize the size of synchronized code blocks. This reduces the wait time for other threads contending for the same code block.

A14 Avoid writing finalizers. Finalizers are unpredictable, often dangerous and generally unnecessary. They make it hard to debug memory leaks, prolong the lifetime of an object and place extra burden on the garbage collector.

This prolongs lifetime of an object and places extra burden on the garbage collector since it runs the finalizer.

A15 Do not call System.gc. It should be left to the discretion of the JVM to run garbage collection.

GSCC Error File.Java.8

A16 Do not use your own debug classes. Use the

standard writeDiagnostics() method.


1493

A17 Do not call debug routines (or write diagnostics) without first checking if debug/diagnostics is enabled for the level at which you want to record a log entry.

Avoid adding too many calls to the debug class. In this case, "too many" is is proportional to the amount of work the method is doing. For example, logging in a given method should not be doing more work than the method itself (this usually happens when extensive logging is added during development to debug some error, and never removed).

Logging overhead is significant (even if the debug mode is silent).

You should check that logging is enabled at a given level, because we recommend to customers that the highest (most restrictive) level of logging (unexpected exceptions) always be turned on so that OAM can collect information on these errors.

A18 Avoid calling System.err.println or

System.out.println in the normal code path

execution. Use standard debugging or logging instead.

Developers often forget to remove these calls which can slow the system significantly.

There is only one output stream and one error stream in the JVM. Multiple threads calling those methods have to be synchronized, and will potentially block. Also in production (iAS 1,0.2.2.2), the std out is not redirect to a file, and is lost.

GSCC warning File.Java.17.

A19 Avoid doing a lot of string manipulation in PL/SQL when you can do it in Java instead.

Multibyte string manipulation in PL/SQL is very slow.

A20 Use Buffered I/O classes such as

BufferedReader and BufferedWriter.

I/O devices are optimized to work with bulk data. For example, without buffering, each invocation of a print method on a writer would cause characters to be converted into bytes and written immediately to the file, which is inefficient.

Internationalization

No Rule Reason


1494

A21 Do not use resource bundles.

Use Message Dictionary to programmatically obtain translated values for any strings that will display in the UI.

Note that declarative data intended for UI display (OA Framework UI component XML metadata, menu definitions, profile options and so on) are all directly translatable.

Resource bundles cannot be used across technology stacks and are not as reliable / available as data in the database.

A22 Do not use Java APIs that rely on the platform encoding or locale.

Bad Code Examples:

byte[] bytes = ....

new String(bytes)

byte[] b = str.getBytes();

OutputStream out = ...

new PrintWriter(out)

Patching Binary Compatible Java

Standard (New Code)

Any of the following changes to shipping code impact link compatibility of referencing classes. Ifyou do not have a complete account of the products or code that may be referencing your classes, you should NEVER make any of the following changes in an ARU.

Select a rule link below for additional information. See Sun Microsystems' Patching Binary Compatible Java document for a detailed list of their rules for ensuring binary compatibility.

Rule Reason


1495

Changes to a method signature x Changing the return type or parameter type requires redelivery of the associated class.x Changing the return type from String to void, even if no classes use the return type, requires redelivery of the associated class.x Changing a type to a super class (or to a subclass, interface, implementation class) also requires redelivery.

Changes to final variable values Constant field values (String constant, primitive type constants) are in-lined into the classes. You must recompile and redeliver all the classes that use this constant.

Changes to a field signature (type, modifier)

You must recompile and redeliver all classes that reference this field.

Change a static method to an instance method or vice versa

You must recompile and redeliver all classes that call this method.

Change of a method location within a class hierarchy (specifically, if you move it down the hierarchy)

You must recompile and redeliver all classes which reference the method you move.

Change to an interface definition If you change an interface, any class implementing or referencing the interface change will need to be recompiled and redelivered.

OA Framework File Standards (Naming, Package Structure and Standard Content)

Overview

This document describes file naming conventions, standard file contents, and directory (package) structures for all OA Framework application files. The document is organized as follows:

x Package Namingx File Namingx Standard File Contents/Organizationo Java Fileso OA Component XML Fileso BC4J XML Filesx Package / Source Control Directory Structure


1496

Standard Compliance

The naming and package structure standards described in this document are required only ifthey can be applied consistently to all the files in your product. If you have older files that comply with earlier versions of the OA Framework naming and package/directory standards, it is not necessary to rework them to satisfy the current guidelines (in this case, we recommend that you follow the original conventions when creating new files to ensure consistency within your product). That said, however, it is preferable for all products to follow the same conventions to facilitate discovery, reuse and customer extensions. If you can schedule a refactoring exercise, you should.

Related Information

x Files in a Typical OA Framework ApplicationPackage Naming

Note: For customers, see Extending OA Framework Applications for recommended package structure and naming conventions for custom logic.

Package names are used to group Java classes/interfaces and individual XML UI files. The Oracle corporate standard on package names requires that they begin with a lower case letter and use initial capitals rather than underscores for each subsequent word in the name (for

example: oracle.apps.fnd.wf.statusMonitor).

At the highest level, all Oracle E-Business Suite code goes into the oracle.apps package.

You should NOT create your code under the following restricted packages:

x oracle.apps.fnd.frameworkx oracle.jradx oracle.mdsx oracle.jbox oracle.cabox oracle.jdbcSee the Package / Source Control Directory Structure section below for additional package definition instructions.

Warning: Do not confuse the Java package (directory structure) with the OA Components Package, a special XML file that can contain multiple, related OA components. Naming standards for the OA Components Package are provided below.

File Naming

All files in an OA Framework application should comply with the following naming conventions.

Java Class/Interface Names


1497

File names for general Java classes and interfaces should comply with Oracle corporate naming guidelines: class names should be succinct, descriptive nouns.

x A factory class for a class should be named by appending the word Factory to the original class's name (for example, OAWebBeanFactory)x Exception classes should have the word Exception as the last part of their names (for example, OAAttrValException)

Name Length Limit

Java Files

Java files names may not exceed 50 characters. If inner classes are used, the concatenated inner class name with the outer class name may not exceed 50 characters.

OA Extension Component XML Files

OA Extension (page, region, attribute set and package) XML file names may not exceed 30 characters. Furthermore, for performance reasons, these file names must always be as short as possible regardless of the 30 character limit. Given this, you must try to use commonabbreviations like "Emp" for "Employee," "Num" for "Number ," "Desc" for "Description" and so on whenever possible. Do not sacrifice clarity for brevity. If the abbreviation cannot be understood by the average consultant or customer, do not abbreviate.

BC4J XML Files

BC4J XML files names may not exceed 30 characters.

Capitalization

For all file type names (except for the generated BC4J server.XML, the LAF

-.xml (all lower

case),-.xss (all lower case), and custom renderer

.uit files), the first letter in every word should be capitalized except where

standard, upper case suffixes are required as described below. Note that approved abbreviations and acronyms should also use the initial capitalization scheme. For example:

Correct Incorrect

PoSearchPG POSearchPG

SuppliersLovRN SuppliersLOVRN

Naming Summary by File Type

This provides an at-a-glance look at the naming standards by OA Framework file type.

File Extension

File Type

Standard Examples


1498

.xml Page Definition

PG orPG

The page name should convey the object it presents (an employee, a supplier, an item, a purchase order, an applicant, and so on), and the function being performed (search, promote, hire, approve, view). For some pages, the object is sufficient.

For update/create pages, just the object should be used (unless the create and update pages are different as shown in the examples).

Warning: Never give pages step number names (for example: PoCreateStep1PG.xml, PoCreateStep2PG.xml). Always describe the page function (PoDescPG.xml, PoLinesPG.xml)

x EmployeePG.xml (employee update)x EmpCreatePG.xml (differentiated only if update and create are separate tasks)x EmpViewPG.xml (view employee info)x EmpHirePG.xml (hire new employees)x EmpPromotePG.xml (promote employees)x EmpSearchPG.xml (search for employees)x HomePG.xml (home page)x MgrHomePG.xml (home for tailored for managers)x PoAttachPG.xml (attachments specific to POs)x AttachPG.xml (attachments not specific to one object)

.xml Shared Region Definition

RN orRN

The region name should convey the object it presents (an employee, a supplier, an item, a purchase order, an applicant, and so on), and the function being performed or the structure (search, promote, hire, approve, view, table, HGrid, Tree and so on). For some pages, the object is sufficient.

Note: Some older regions are named with suffix "RG". All new regions should use "RN as shown".

Warning: There are additional naming standards for regions which are created within the context of a parent page, and not in their own XML file as is the case for a shared region. See the OA Component XML Files section below for additional information.

x EmpSummaryRN.xmlx PoApproveRN.xmlx CustomerContactsRN.xmlx ItemTypeHGridRN.xml


1499

.xml Shared List of Values (LOV) Definition

LovRN

The Lov should be named for the objects the LOV queries.

x RetiredEmpsLovRN.xmlx AllEmpsLovRN.xmlx MgrEmpsLovRN.xml

.xml Attribute Set Package

An attribute set file name should match the name of the associated table (every table should have its own attribute set).

Note: If you need to create an attribute set package for commonly used transient attributes with no associated base table, name the packageTransient.

See the OA Component XML Filessection below for additional information about attribute set naming.

x FwkTbxEmployees.xml(table name is FWK_TBX_EMPLOYEES)x FwkTbxPoHeaders.xml(table name is FWK_TBX_PO_HEADERS)x Transient.xml

.xml UI Components Package

The package file should be named for the module files it contains.

See the OA Component XML Filessection below for additional information about the package file, including when and how to use it.

x NewHire.xmlx ItemCatalog.xmlx PoCreate.xmlx ApprovedSupplierList.xml

.xml, .java Entity Object

EO

The EO should be named for the objects stored in its underlying entity. For example, the entity FWK_TBX_PO_HEADERS stores purchase order headers, so the associated EO name is PurchaseOrderHeaderEO.

EO names are always singular as they model a single object.

Exception: Java entity objects created for _TL tables should be named TLEO. The entity object created for the corresponding _B table should follow the standard naming

x EmployeeEO.xmlEmployeeEOImpl.javax SupplierEO.xmlSupplierEOImpl.javax SupplierSiteEO.xmlx SupplierSiteEOImpl.javax PurchaseOrderHeaderEO.xmlPurchaseOrderHeaderEOImpl.javax PurchaseOrderLineEO.xmlPurchaseOrderLineEOImpl.javax LookupCodeTLEOL.xmlLookupCodeTLEOOImpl.javax LookupCodeEO.xml


1500

convention. See Entity Objects for Translatable Tables for additional information.

LookupCodeEOImpl.mxl

.xml [Entity] AssociationObject

ToAO

The AO name should convey the relationship between a parent and its child entities (or entity if it's a 1:1).

x PoHeaderToLinesAO.xmlx SupplierToSitesAO.xmlx EmployeeToContactsAO.xml

.xml, .java View Object / View Row

VO

The VO name should convey the nature of the query.

VO names are always plural as they model a collection of rows.

x AllEmployeesVO.xmlAllEmployeesVOImpl.javaAllEmployeesVORowImpl.javax NewHiresVO.xmlNewHiresVOImpl.javaNewHiresVORowImpl.java

.xml View Link

ToVL

The VL name should convey the relationship between the master and detail VOs.

x ManagerToDirectsVL.xmlx PoHeaderToLinesVL.xmlx ItemToApprovedSuppliersVL.xml

.xml, .java ApplicationModule

AM

The AM name should convey the purpose of the UI module it services (which is either a shared region, or a discrete "task" ranging in scope from one to several related pages).

Note: If you opt to generate an interface for your application module, BC4J will automatically assign this name as the interface name.

x EmployeesAM.xmlEmployeesAM.java (optional interface)EmployeesAMImpl.javax ItemCatalogAM.xmlItemCatalogAMImpl.javax PoSummaryAM.xmlPoSummaryAMImpl.javax ApprovedSupplierListAM.xmlApprovedSupplierListAMImpl.java


1501

.xml, .java [Validation]ApplicationModule

VAM

Since VAMs are associated with the top-level object in a composition (or an individual entity) they should be named for the EO noun(s), or the composition. For example, a "purchase order" is comprised of a PurchaseOrderHeaderEO with a PurchaseOrderLineEO and a PurchaseOrderShipmentEO. In this case, the expert is named "PurchaseOrderVAM."

x EmployeeVAM.xmlEmployeeVAMImpl.javax SupplierVAM.xmlSupplierVAMImpl.javax PurchaseOrderVAM.xmlPurchaseOrderVAMImpl.java

Defined as part of the SAM; may have a .java implementation

Service Service

For business object services, the interface's name should be the singular name of the associated business object.

x PurchaseOrderServicePurchaseOrderService.javax SupplierServiceSupplierService.javax EmployeeServiceEmployeeService.javax PriceListServicePriceListService.java

.xml, .java [ Service ]ApplicationModule

SAM

The service implementation's name should match the service bean interface name plus the "SAM" suffix instead of the "Service" suffix.

Note: Since preexisting application modules may be used for service bean implementations, it is not necessary to change the AM's original name to comply with this naming convention.

Important: When you define the data model for your service application module, be sure to specify a singular view instance name, without a VO or SVO suffix. For example, if you select the SuppliersSVO to add to the SupplierSAM data model, you must rename the view instance to Supplier, rather than Suppliers or SuppliersSVO.

x EmployeeSAM.xmlEmployeeSAMImpl.javax SupplierSAM.xmlSupplierSAMImpl.javax PriceListSAM.xmlPriceListSAMImpl.java


1502

.xml, .java [ Service ]View Object

SVO

View objects created to correspond directly to individual entities in a business object should be named for the corresponding entity.

View objects created to support specific tasks or data views should be named with a description of the associated data.

For example, if a view object includes candidate new hires for reference during an interview/approval process, the view object might be named CandidatesSVO.

Top-level SVOs in a composite object should be given a business object name. For example, the top-level table in the ToolBox purchase order is FWK_TBX_PO_HEADERS, but the associated SVO is PurchaseOrdersSVO since the business object name is "Purchase Order."

Note: Since preexisting view objects may be used in service bean implementations, it is not necessary to change the VO's original name to comply with this naming convention.

x PurchaseOrdersSVO.xmlPurchaseOrdersSVOImpl.javax PurchaseOrderLinesSVO.xmlPurchaseOrderLinesSVOImpl.javax RejectedRequisitionsSVO.xmlRejectedRequisitionsSVOImpl.javax CurrentEmployeesSVO.xmlCurrentEmployeesSVOImpl.java

.xml, .java [ Service ] Domain Set

DVO

Domain set view objects created to correspond directly to individual entities in a business object should be named for the corresponding entity with additional descriptive information if required to identify a specific data set.

For example, a DVO that simply queries all employees would be called EmployeesDVO, while one that queries only temps would be called TemporaryEmployeesDVO.

x EmployeesDVO.xmlEmployeesDVOImpl.javax ManagersDVO.xmlManagersDVOImpl.javax ActiveEmployeesDVO.xmlActiveEmployeesDVOImpl.javax CandidateNewHiresDVO.xmlCandidateNewHiresDVOImpl.javax TemporaryEmployeesDVO.xmlTemporaryEmployeesDV


1503

OImpl.java

.xml [ Service ] View Link

ToSVL

The view link name should convey the relationship between the master and detail view object.

Important: When you define the properties of your service view link, be sure to specify singular accessor names for the view link source and destination. For example, when defining a SuppliertoSitesSVL, specify the Source accessor name as Supplier and the Destination accessor name as SupplierSite.

x ManagerToDirectsSVL.xmlx PoLineToShipmentsSVL.xmlx ItemToApprovedSuppliersSVL.xml

Defined as part of theSVO; may have a .java implementation

[Service] Data Object

The typed data row should be named for the associated view object. For example, if the SVO is named PurchaseOrderLinesSVO (plural), the corresponding typed data row should be named PurchaseOrderLine(singular).

x PurchaseOrderPurchaseOrder.javax SupplierSiteSupplierSite.javax EmployeeEmployee.javax PatientPatient.java


1504

Defined as part of the SVO; may have a .java implementation

[Service] Filter

Filter

A filter should be named for the associated data object. For example, if the data object is named PurchaseOrderLine, the corresponding filter should be named PurchaseOrderLineFilter.

Since an SVO can have multiple associated filters, feel free to choose a descriptive name that captures the primary purpose of the filter.

x PurchaseOrderFilterPurchaseOrderFilter.javax ApprovedPurchaseOrderFilterApprovedPurchaseOrderFilter.javax EmployeeFilterEmployeeFilter.javax ManagerFilterManagerFilter.java

.xml [Service] Test Suite

Test

The test suite should be named for the associated service.

If your test suite spans multiple services, choose a descriptive name without the "Service" name component. For example: ProcureToPayTest.mxl.

x EmployeeServiceTest.xmlx SupplierServiceTest.xmlx ProcureToPayTest.xml

.xml, .java [Validation ] View Object

VVO

The VVO name should convey, to the extent that is practical/possible, the specific validation that it performs.

x EmpIdForNameVVO.xmlEmpIdForNameVVOImpl.javax EmpNameForIdVVO.xmlEmpNameForIdVVOImpl.java

.xml, .java [ApplicationProperties ] View object

PVO

The PVO name should clearly identify its affiliation with a single application module. For example, if an application module named EmployeeAM has an associated application properties view object, it should be named EmployeePVO.

Application properties view object associated with a PurchaseOrderAM:

x PurchaseOrderPVO.xmlx PurchaseOrderPVOImpl.java

Application properties view object associated with a SupplierAM:

x SupplierPVO.xmlx SupplierPVOImpl.java.java Entity

ExpertExpert

Since experts are associated with the top-level object in a composition (or an

x EmployeeExpert.javax SupplierExpert.javax PurchaseOrderExpert.jav


1505

individual entity) they should be named for the EO noun(s), or the composition. For example, a "purchase order" is comprised of a PurchaseOrderHeaderEO with a PurchaseOrderLineEO and a PurchaseOrderShipmentEO. In this case, the expert is named "PurchaseOrderExpert."

a

.xml, .java UI Controller

CO orCO

The CO name should convey its usage. Ideally, this should be similar to its associated region name.

x EmpSearchCO.javax EmpResultsCO.javax EmployeeCO.javax EmpFooterCO.java.xml, .xss Look-

and-Feel (LAF)

-

The LAF name should convey the LAF family and the device for which the LAF is intended. The Custom Look-and-Feel (CLAF) UI automatically generates .xml and .xss files for the LAF name specified.

x custom-desktop.xmlx custom-desktop.xssx custom-pda.xmlx custom-pda.xss

.uit Custom Renderer

The custom renderer name should convey the web bean component for which you are customizing the rendering.

Custom renderer files must reside under $HTML_TOP/cabo/templates// where

would be a LAF

name, such as 'custom-desktop'.

Custom icon files must reside under $HTML_TOP/cabo/images// where

would be a LAF name, such as 'custom-desktop'.

x sideBar.uitx tabBar.uitx pageLayout.uit

Standard File Contents / Organization

Java Files


1506

This section focuses on the structure of your Java files. All Java classes and interfaces that you code must also comply with the Oracle Corporate Java Coding Standards, and the various Java coding standards published in this Developer Guide.

Comments

All files should have a standard Oracle E-Business Suite copyright/history comment at the top of the page. Javadoc-style methods should be used for public and protected interface/class

declarations, methods and fields. All internal comments should use the double slash // which

allows for the use of /* ... */ to comment out chunks of code.

Example of a standard copyright/history comment:

/*===========================================================================+

| Copyright (c) 2000 Oracle Corporation, Redwood Shores, CA, USA|

| All rights reserved.|

+===========================================================================+

| HISTORY|

| 22-Jan-00 lxharris Created.|

| 25-Apr-00 mmnakamu Modified to user cabo controls|

| 31-Aug-00 lewe Added initializeChild()|

| 27-Oct-00 shira Overhauled for MarlinMerge|

| 03-Apr-02 pambale Enhancement 2293247: Added getTotalValues()|

| 04-Apr-02 nbajpai Bugfix 2252743: Added setWrapEnabled()|


1507

| 06-May-02 pambale Doc bug 2311433: Modified method javadocs|

| 28-Jun-02 nbajpai deprecated setWrapEnabled()|

| 09-Jul-02 pambale ER 1930333: Added getter and setter for|

| DETAIL_VIEW_ATTRIBUTE_NAME|

| 18-Sep-02 pambale ER 1930333: Added getter and setter for|

| ROW_HEADER_VIEW_ATTRIBUTE_NAME|

| 08-Oct-02 pambale ER 2502892: Bypass processForm* for inner|

| tables|

| 08-Oct-02 nbajpai Bug 2637673. Added getFWKColumnHeaderData()|

| & isCallfromFWK().|

+===========================================================================*/

Imports

Per the Oracle corporate Java coding standards, you may not use wide imports (in other words,

a package import like oracle.apps.fnd.framework.* unless you are referring to a

standard Java package). Each class/interface that you require must be explicitly imported.Remove any imports that you do not actually use in the code.

Source Control Header

All files in an OA Framework application must include an ARCS source control header.


1508

You must add the constants RCS_ID and RCS_ID_RECORDED to all Java files as shown below (these should be added at the top of your class in accordance with the Content Order guidelines below). Remember to import the oracle.apps.fnd.common.VersionInfo class.

Note the standard Javadoc comments used by the OA Framework for these public constants.

package oracle.apps.fnd.framework.toolbox.webui;

import oracle.apps.fnd.common.VersionInfo;

public class ExampleClass

{

/**

* Oracle E-Business Suite internal source control identifier.

*/

public static final String RCS_ID="$Header$";

/**

* Oracle E-Business Suite internal source control identifier.

*/

Public static final boolean RCS_ID_RECORDED =

VersionInfo.recordClassVersion(RCS_ID,"oracle.apps.fnd.framework.toolbox.webui");

}

Variable Names


1509

Member variables should have names that are nouns, noun phrases, or abbreviations for nouns.

x Local variable and parameter names should be short, yet meaningful.x In order to distinguish member variables from variables local to a method, all member variables must be prefixed with the letter "m". All remaining words in the name should have their first letter capitalized. For example:private int mMaxLinesx Constant variable names should be in upper case. Different words should be separated by an underscore. Constant names should be descriptive and not unnecessarily abbreviated. For example: MIN_VALUE, MAX_VALUE and BUTTON_SUBMIT_BEAN.

Method Names

The first letter of a method name should be in lower case. All other words in the same name should have their first letter capitalized. For example:

public void prepareForRendering(OAPageContext pageContext);

x Method names should be verbs or verb phrases.x Methods to get and set an attribute for the variable X should be named getX and setX.x A method that tests a Boolean condition X about an object should be named isX.x A method that converts its object to a particular format F should be named toF.x Whenever possible and appropriate, the names of methods in a new class should be based on names of an existing class that is similar, especially a class from the standard Java Application Programming Interface classes.

Content Order

Contents should be added to Java files in the following order from the top of the page to the bottom.

1. (Required) Oracle E-Business Suite copyright comment2. (Required) Package declaration3. (As Needed) Import statements in ascending alphabetical order within each package

Packages should be listed in the following order: 1. Java2. Oracle classes/interfaces from outside Applications (BC4J, cabo, JDBC, and so

on)3. Oracle E-Business Suite AOL4. Oracle E-Business Suite OA Framework5. Other Oracle E-Business Suite products6. Your product

4. (Required) Class/interface Javadoc5. (Required) Class declaration6. (Required) ARCS source control headers w/ standard Javadoc comments7. (As Needed) Public fields w/ Javadoc8. (As Needed) Protected fields w/ Javadoc9. (As Needed) Private fields10. (As Needed) Public constructor w/ Javadoc


1510

11. (As Needed) Protected constructor w/ Javadoc12. (As Needed) Private constructor13. (As Needed) Public methods w/ Javadoc *14. (As Needed) Protected methods w/ Javadoc *15. (As Needed) Private methods *

* Note: For the BC4J classes with generated methods, it is appropriate (and recommended for ease of use) to organize your file so that the methods with code are located at the top, and the template methods are located at the bottom after a delineating comment like the one shown below. Within these two regions, you should organize your methods as described above.

/*===========================================================================+

| Begin BC4J Generated Code Here

+===========================================================================*/

OA Component XML Files


JDeveloper will add the ARCS source control header automatically when you create page, region, attribute set and package files. The value is stored in a special XML attribute named file-version that can be viewed using the JDeveloper UI Component Property Inspector (the property name is File Version).

AutoPatch Driver Commands

Since the XML page definition files are essentially loader files that must be loaded into a database, they require AutoPatch driver dbdrv commands. For these files, JDeveloper automatically adds the dbdrv commands as comments when the files are created. An example dbdrv command for this file type is shown below:

Region Names


1511

This section describes the naming standards for region IDs inside the OA component definition XML file.

Note: As a reminder, region names should not exceed 30 characters, and they should be as short as possible. Abbreviations (which would be understood by consultants and customers) are encouraged.

Generally, region names used as IDs within a file should follow the naming conventions described above for shared region XML file names with the following exceptions:

x The top level page region (which has a style of pageLayout) must be named PageLayoutRN.x If the top-level page region has one main content region which holds other content regions and items, this region must be named MainRN.x For pages which include UI abbreviation or icon keys at the top of the page (for example, the "indicates a required field" key), this first key region must be named KeyRN. Any subsequent key regions added further down the page should be qualified with its parent region name (for example, ResultsKeyRN in a ResultsRN region).x Any contextual information regions at the top of a page should be named InfoRN.x Certain standard navigation regions are given special names: PageActionButtonsRN,TrainRNx Regions added only for the purpose of affecting layout should be named with a noun that concatenates a short reference to the parent content region name if needed, location indicator if needed and a short name of the layout style used with the region. Layout region names shouldnt be suffixed with RN. Location indicators, if needed to avoid confusion, could use relative position indicators such as Top, Bottom, Middle, Left, Right, Center and TopLeft or sequence numbers like in the case of a series of rows. When using a sequence number, the location indicator follows the short name of the layout style like in Row1, Row2 and Row3. See the page hierarchy below the following sample uses cases.

Example Use Cases Region Names

Employee search criteria EmpSearchRN

Employee search results EmpResultsRN

Primary employee information (for update or view)

EmployeeRN

Contextual information region InfoRN

Employee contact information (for update or view)

EmpContactsRN

Employee direct reports (for update or view) EmpDirectsRN

Key region added below the EmpResultsRN region.

ResultsKeyRN

Table listing employees EmpTableRN


1512

Tree listing employees EmpTreeRN

HGrid listing employees EmpHGridRN

The following partial page hierarchy illustrates the application of the layout region standard:

CustDetailsPGPageLayoutRN

MainRN (default single column header)

InfoRN (default double column header)

... (region items)ContactsRN (default single column header)

ContactsTableLayout (table layout)

ButtonsRow (row layout)

ButtonsCell (cell format)

ContactCreate (submit button)

SpacerRow (referenced spacer for vertical spacing)

ResultsRow

ResultsCell (cell format)

ContactsTableRN (table)

... (region items)ContractsRN (default single column header)

ContractsTableLayout (table layout)

ContractsButtonsRow (row layout)

ContractsButtonsCell (cell format)

ContractCreate (submit button)

ContractsSpacerRow (referenced spacer for veritical spacing)

ContractsResultsRow (table layout)

ContractsResultsCell (cell format)


1513

ContractsTableRN (table)

... (region items)

Item Names

This section describes the naming standards for item IDs inside the OA component definition file.

Note: Region item names should also not exceed 30 characters, and they should be as short as possible. Abbreviations (which would be understood by consultants and customers) are encouraged.

The item label (also known as its prompt) is typically a user-friendly name for the underlying data object name, so you should use this label as the item's name. For objects with no label, use the name of the associated object; use a made-up unique name as a last resort to substitute for the label. See the example use cases below.

Warning: Never use the reserved word name on its own.

Warning: Item names must be unique within a single page regardless of the region hierarchy. This is an HTML limitation that the OA Framework will attempt to solve in a future release. For now, when you encounter a duplicate, prefix the item name with a short version of the parent region name. For example in an employee search/results page, use EmpNum in the search region and ResultsEmpNum in the results region. Please dont use notations like EmployeeNum and Employee_Num to work around duplicates, because this does not comply with the standard and it's hard to debug if you mistakenly refer to the wrong item.

Example Use Cases Item Names

A text field with the prompt Supplier Name SupplierName

A text field with the prompt Salary, followed by a second text field with the prompt Salaryunder a Manager header.

x Salaryx MgrSalaryA poplist with the prompt Employee Type EmpType

A display-only column for item description Description (if no duplicates, otherwise ItemDesc).

An Apply button Apply

A Go button, followed by a second Go buttonin the Results region.

x Gox ResultsGoOA Component Packages


1514

For OA components, you have the option of grouping discrete tasks comprised of more than one page in a physical XML file called a package (not to be confused with packages corresponding to the directory structure for storing individual files).

Note: Oracle E-Business Suite developers may use OA component packages ONLY for attribute sets (this is a Required Standard for the Fusion release). Objects included in OA component packages cannot be personalized. Packages will be deprecated in the Fusion release in favor of libraries. The OA Framework will provide an upgrade path only for attribute sets.

Attribute Sets

Attribute sets are created in OA component package files named for the associated table as illustrated in the summary table above. Additionally, the following naming standards apply:

x The individual attribute sets should be named for the columns they represent. When derriving the Document Name value (attribute set name) from a column name, remove

underscore characters and capitalize initial letters. Example: the PARTY_NAME column

name maps to the PartyName Document Name.

Warning: Never abbreviate the table column name when creating the Document Name;

reproduce it exactly without the underscores.

Note: In the OA Component XML files, "Name" is a reserved word. If you have a column named "name," prefix it with the object type to avoid compilation errors. For example, in the ToolBox Tutorial we have a table (FWK_TBX_ADDRESSES) with a column named

NAME. The corresponding attribute set Document Name for this column is therefore

AddressName.

x When more than one attribute set maps to the same column, follow the conventions above and add a suffix to the Document Name. The suffix is composed of an

underscore and the prompt name (or a meaningful abbreviation of the prompt name).

Example: for the column PARTY_NAME the first attribute set will have a Document

Name of PartyName (note that this should be created for the most popular use/case and

prompt). Subsequent attribute sets (if required) will have the Document Names

PartyName_Supplier, PartyName_Emp and so on.x When creating a button attribute set, base the Document Name property on the button's label using the same conventions described for column-based attribute sets. For example, a button with the label Add More Rows would have the attribute set name AddMoreRows.x When creating attribute sets for transient UI components (like a search field), the Document Name property should convey the meaning/use of the component in

accordance with the naming standards described here.

For additional information, see Creating Attribute Sets.

BC4J XML Files



1515

All source controlled BC4J XML files (which currently includes the object metadata files and the package-level server.xml files) require an ARCS source control header. You must add this information at the third line after the DOCTYPE declaration statement using the following format:

Package / Source Control Directory Structure

When you create and source control your files, you will define packages and directories that comply with structure illustrated in Figure 1 below.

Figure 1: Illustration of OA Framework application file directory structure.


1516

Directory Definitions

..java/*

This directory and its subdirectories contain all the Java and BC4J XML files for your product. These untranslated files will be deployed in the Apps.zip that is created for OA Framework application ARUs.

..java/[]

This directory is optional and exists for historical reasons to support product teams that already have a subproduct grouping.

Note: This subdirectory is neither required nor recommended for most product teams.


1517

..java/schema/[]

This directory is optional and allows for the grouping of all related "schema objects" under a subschema directory (anything related to entity objects). Thus, all your related entity objects (EOs), validation view objects (VVOs) and validation application modules (VAMs) would come under the same subschema folder. Many product teams do not create the optional subschema directories and

instead use just the java/schema/server directory.

..java/schema/server

This directory contains BC4J XML and Java files for entity objects (EOs), including the EOs themselves, validation application modules (VAMs), validation view objects (VVOs), [entity] association objects (AOs), entity experts and other associated Java files.

This directory does NOT hold BC4J XML and Java files for application modules and view objects intended to support the user interface (see .../java//server).

..java//[]

This level in the directory structure is inteded to define a functional unit. The subcomponent directory is optional; teams are free to define the level of granularity that makes the most sense (if you create subcomponents, however, we recommend that you create subcomponents around small functional units to simplify the logistics around parallel coding and patching).

Example components include:

.../java/vacancy for creating and editing vacancies

.../java/applicant for displaying/processing applicants

Any classes, interfaces and exceptions which can be used by both server and webui components should be included at this level of the directory structure. For

example, in the OA Framework, the OAException class is included in the

oracle.apps.fnd.framework package.

Service (application module) interfaces and associated data object and filter implementations would also be included here.

..java//[]/test

Includes XML test scripts associated with services. Each

oracle.apps...[] with a

service interface should have an associated test directory.

..java//server


1518

This directory contains BC4J XML and Java files associated with functional (user interface) components and services including root (UI) application modules, nested application modules, view objects and view links.

This also includes service application module implementations, domain sets, view objects and view links.

This directory does NOT hold BC4J XML and Java files for entity objects and their associated validation application modules, validation view objects, entity experts, and so on (see .../java/schema/server).

..java//webui

This directory contains Java UI controllers associated with functional components.

This directory does NOT contain the XML page or region definitions (see .../mds//webui)

..java/lov/server

This directory contains BC4J XML and Java files (if any) associated with Lists of

Values (LOVs).

..java/lov/webui

This directory contains any Java UI controllers associated with LOVs.

..java/poplist/server

This directory contains BC4J XML and Java files (if any) associated with

poplists.

..java/util/server

This directory contains miscellaneous utility files referenced by other objects in

the server name-space. Typically, these are Java files, however, it may contain

BC4J view objects used by the utility to query the database.

..mds/*

This directory and its subdirectories contain all XML page, region, attribute set

and package definition files. These files will be translated and deployed separately

from Apps.zip. At the customer site, these files will be loaded into a set of mds

repository tables. Because the files are loaded into the repository at the customer's

site, you are able to create granular patches containing just the affected files.

..mds/[]


1519

This directory is optional and exists for historical reasons to support product teams that already have a subproduct grouping.

Note: This subdirectory is neither required nor recommended for most product teams.

..mds/attributeset

This directory contains AttributeSets organized by database table name. See

Creating Attribute Sets for additional information.

..mds//webui

This directory contains XML files associated with functional components, tasks

or page flows. The /[] name in the mds

directory should match the corresponding /[]

name in the java directory.

..mds//webui/customizations

This directory contains seeded XML customization files associated with files in

the webui directory. See the OA Frameweork Personalization Guide for additional

information.

..mds//webui/customizations/

This directory contains seeded XML page customizations by layer type, which

can be either a user or a function name. See the OA Frameweork Personalization

Guide for additional information.

..mds//webui/customizations//

This directory contains seeded XML page customizations by layer value, which

can be either a function name or the name seededdeveloper. At a customer site the

directory name seededcustomer may be created automatically as well. The names

of the customized files in is directory should match the corresponding names in

the webui directory. See the OA Frameweork Personalization Guide for additional

information.

..mds/lov/webui

This directory contains region definition XML files for LOVs.

Example: Differences Between Packages and Source Control Directories

When you define packages for your Java UI controllers, BC4J model objects/metadata, and view metadata files they all begin with oracle.apps.. For example, a Java


1520

UI controller named MessageSearchCO.java (for searching in Message Dictionary) might belong to the following package. Note in this example that "messages" is the component.

oracle.apps.fnd.messages.webui

When it's time to check this file in, it should be added to the directory:

$FND_TOP/java/messages/webui/MessageSearchCO.java

Similarly, the page definition for the Message Dictionary search (named MsgSearchPG.xml)would be added to the same package as the UI controller:

oracle.apps.fnd.messages.webui

But at checkin time, it would be added to the following directory:

$FND_TOP/mds/messages/webui/MessageSearchPG.xml

The root application module for the Message Dictionary application (files comprising the application module are named MessageDictionaryAM.xml andMessageDictionaryAMImpl.java) would be added to following pacakge:

oracle.apps.fnd.messages.server

And checked in to:

$FND_TOP/java/messages/server/MessageDictionaryAM.xml$FND_TOP/java/messages/server/MessageDictionaryAMImpl.java

The entity object for this same application (MessageEO.xml and MessageEOImpl.java) would be added to the following package:

oracle.apps.fnd.messages.schema.server

And checked in to:

$FND_TOP/java/messages/schema/server/MessageEO.xml$FND_TOP/java/messages/schema/server/MessageEOImpl.java

Finally, the validation application module and a validation view object used by the entity objects would be added to the following package:

oracle.apps.fnd.messages.schema.server

And checked in to:

$FND_TOP/java/messages/schema/server/MessageVAM.xml$FND_TOP/java/messages/schema/server/MessageForCodeVVO.xml$FND_TOP/java/messages/schema/server/MessageForCodeVVORowImpl.java


1521

In summary, when reviewing the diagram above, remember that the /java

and /mds source control directories correspond to the

oracle.apps. package name. All subdirectories beneath this level

are the same in both use cases.

OA Framework Model Coding Standards

Information about the forthcoming passivation feature is provided for preview/planning purposes only; passivation is not supported in Release 12.

Overview

This document lists the coding/declarative definition standards for the model in an OA Framework Model-View-Controller application. It is organized into the following categories:

x Universal (Applies to All "Model" Code) o Generalo Performanceo State Managementx Application Moduleso Performanceo State Managemento Service Interfacex View Objects, View Rows and View Linkso Generalo Service Interfaceo Performanceo State Managemento Internationalizationx Entity Objects, Association Objects and Entity Expertso Generalo Performancex Standard Code/Validation Tasks

Note: Before building your application, please review the corresponding view and controllerstandards also. These three documents combine with the administrative OA Framework File Standards (Naming, Package Structure and Standard Content) and the Oracle E-Business Suite Java Coding Standards to provide a complete picture of OA Framework coding/declarative definition standards.

Standards Column Description Key


1522

Column Header

Description

No The standard's number. Note that, for convenience, some standards appear in multiple documents. In these cases, the duplicate references the original standard.

Rule The standard or guideline content.

Reason Provides additional explanation for why the standard or guideline is recommended.

Universal (Applies to All "Model" Code)

No Rule Reason

General

M1 Never import any classes or interfaces from the

framework.webui.* packages in your server code. For

example, importing and using the following is prohibited:

oracle.apps.fnd.framework.webui.xxxxxoracle.apps.fnd.framework.webui.xxxxx

The OA Framework is designed to support separate client and server tiers. As such, the code for each of these tiers must remain distinct.

See the oracle.apps.fnd.framework package for interfaces which can be safely referenced by code on both tiers.

M121

Use "UTF-8" for encoding attribute in xml tag of BC4J xml files.

Java supports various encodings in two groups.

One is Basic encoding set and another is Extended encoding set.

Basic encoding set supports some European and American local encoding and Unicode encodings, implemented by lib/rt.jar file.

Extended encoding set supports Asian local encodings, vendor-specific encodings, minor European encodings and so on, implemented by


1523

lib/charsets.jar.

In some customer environments, that do not require extended encodingsupport, lib/charsets.jar may not exist in the Java class path causing a java.lang.NoSuchMethodError.

This standard avoids the error.

Performance

M15 Never use JDBC directly. Always use a view object instead, and the view object should be defined declaratively and not programmatically if possible.

If you must call a PL/SQL routine, use the

oracle.apps.fnd.framework.OADBTransaction to

create a CallableStatement.

Encapsulation allows us to put in diagnostics, add features, and improve performance in one place, rather than thousands.

M2 If you must issue prepared statements, then call the proper

defineColumnType() on all the columns in the SELECT

with proper sizes.

There are two advantages in doing this. First, this eliminates an extra round trip that the JDBC will need to do to describe the columns. Second, this reduces the prepared statement memory footprint. Without a set precision, for example, all VARCHAR2 columns default to 4KB.

GSCC warning File.java.21

M3 Always call registerOutParameters() with proper

precision for callable statements

This reduces the callable statement memory footprint. Without a set precision, for example, all VARCHAR2 columns default to 32KB.

GSCC warning File.java.22

State Management


1524

For additional information, see OA Framework State Persistence Model (Passivation).

M4 Use BC4J custom properties (those that you create by calling

setProperty(String, Object)) only for caching objects

as a convenience/performance optimization. These properties are not passivated, so you must be able to rebuild the object if the value is lost.

M5 Never add member variables to BC4J objects, controllers or any supporting utility classes that you create unless unless they are transient or final.

Note: For final member variables, it is common practice to also declare them static because you only need one instance per JVM for the constant; however, it does not violate the state management coding standard to declare a member variable final without declaring it static.

If you use transient member variables in your BC4J objects, then you need to clean these values up when the application module is released for use by another thread. To do this,

override OAApplicationModuleImpl.beforeRelease()

or OAViewObjectImpl.resetSession() to perform your

custom cleanup. For more information, see the corresponding Javadoc for these methods. (Values that you save by calling

pageContext.putTransactionValue() andpageContext.putTransactionTransientValue()

from your controller are automatically cleaned up by the OA Framework before the application module release.)

Valid Standard Exception Cases:

x For classes that implement the oracle.apps.fnd.framework.webui.OAReleas

eListener interface, you can include stateful

member variables as long as the class correctly

implements the java.io.Serializable interface.x For member variables generated by the BC4J wizards, the OA Framework skips this check because these variables are used for caching purposes.

Developer-created member variables are not passivated (even if not marked as transient), and should be avoided unless they can be safely reinitialized after an AM is passivated. In this case, they should either be identified as transient or final.

M67 If you need to manipulate an entity object's state as described in Implementing Java Entity Objects, do not call

setNewRowState(byte state) on an OAEntityImpl

instance. Call setNewRowState(byte state) on an

OAViewRowImpl instance instead.

Also see related standard M69.

BC4J does not correctly passivate entities whose row state is set by calling

setNewRowState on the

EntityImpl. In this case, the entities will always be activated with the default BC4J new row state (STATUS_NEW).


1525

Application Modules

No Rule Reason

Performance

M6 Do not indiscriminately retain more than one application module while navigating between pages.

See State Management in the OA Framework for additional information.

A root application module is tightly coupled with a database connection. Retaining multiple application modules will increase the number of connections required to support multiple users, which adversely effects product scalability.

M7 If you implement the oracle.apps.fnd.framework.

webui.OAReleaseListener interface to

programmatically determine whether an application module should be released, be sure to implement a condition in the release listener under which the AM is actually released.

Otherwise, this is a potential application module memory and connection leak.

M70 For all application modules, enable the Lazy Loading option as described in Implementing the Model (for new application modules, this is enabled for you by default).

See Application Modules in Detail for additional information about this feature, including usage considerations.

Tip: For existing application modules that were created before this feature was introduced, you may use a mass conversion script.

The Lazy Loading option defers instantion of view instances and nested application modules until they are needed. This is moreperformant than choosing to instantiate all referenced objects at AM instantiation time regardless of whether or not they are needed.

State Management



1526

M8 Set each root application module's Retention Level

to MANAGE_STATE.

Important: Do NOT set your root application module's Retention Level to MANAGE_STATE unless you are

ready to fully implement and certify your page for passivation support.

When an application module's Retention Level is set

to MANAGE_STATE, the application module and its contents (including nested application modules) are passivated; if passivation is enabled in the system. See the OA Framework State Persistence Model (Passivation)document for more detailed information. Setting an application module's Retention Level to

MANAGE_STATE may cause your application to break if your page is not certified for passivation support. See Application Module Retention Level for more details on how to set this property correctly.

Note: If you have any pages that are not fully prepared to implement passivation and you are certain that the root application module is connection-agnostic, as defined in the Passivation document, set their root application module's Retention Level to

CONNECTION_AGNOSTIC. This improves system scalability until you are ready to fully support passivation for these pages.

This allows OA Framework to recover connections and memory under resource load, support session failover, and other pending features such as Save For Later and JVM failover.

M9 Removed as this is no longer applicable.

See Supporting the Browser Back Button.

n/a


1527

M10 Never count on an application module using the same database connection in subsequent requests when passivation is enabled (in the JSP Forward case, do not count on an application module using the same database connection across page boundaries).

For example:

x Never design pages to post and commit in separate requests.x Do not use PL/SQL "Select for update" methodfor locking rows across requests.x Do not use PL/SQL global variables to hold mutable state across requests.x Avoid using global temporary tables across requests. If necessary, you must write methods for saving/recreating the data if the application module is passivated.

If you think you have a permanent exception case, you must obtain an exemption from the OA Framework or Performance teams. See Database State Outside BC4Jin the OA Framework State Persistence Model (Passivation) document for an interim workaround.

For scalability reasons, the OA Framework pools connections. Although you might get the same connection in subsequent requests, you should assume that you will not.

M62 If you implement an OAReleaseListener, make sure

it is Serializable (see the Javadoc for additional information).

The release listener is passivated; therefore it must be Serializable.

Service Interface

M74 For Service Interface only: When you define the data model for your service application module, you must specify a singular view instance name, without a VO or SVO suffix. For example, if you select the SuppliersSVO to add to the SupplierSAM data model, you must rename the view instance to Supplier, rather than Suppliers or SuppliersSVO.

This is required to support the generation XML Schema per changes for the new Service Data Object (SDO) standard.

View Objects, View Rows and View Links

No Rule Reason

General

M11

If a WHERE clause should always be enforced, such as the multi-org security WHERE clause, create that clause as part of the view object at design time.

No user of your view object can override/replace that WHERE clause, although they can add their own supplemental conditions.


1528

M12

You should NOT generate anoracle.apps.fnd.framework.

server.OAViewObjectImpl unless you intend

to specialize its behavior or write code to initialize/execute the view object's query.

M13

Encapsulate the WHERE clause and bind parameter settings or SQL modification logic in a

custom method named initQuery() (or a

variant if you have several of these:

initManagersQuery(),

initNewEmployeesQuery(),

initAllEmployeesQuery() and so on).

M14

Trivial view objects (like those used for poplists, Lists of Values and validation view objects) should be based on a plain SQL statement, and not on entity objects.

All other view objects (including read-only view objects) should be based on entity objects unlessyou specifically want to avoid the inherent coordination benefits whereby changes to an entity object are reflected in all the view objects that reference it.

Note: For entity object-based view objects, the OA Framework recommends -- but does not require --the use of associations for references objects. They facilitate view object and view link creation.

There are several reasons for this:

x It is necessary if you are performing DMLx Multiple view objects based on the same entity object can automatically see updates made by any one of themx At some point, if the view object is large enough with enough foreign keys, you might see more efficient memory usage


1529

M66

Always use unique bind targets in your SQL statements, even if they bind to the same value. Always use ascending bind targets, and do not skip numbers in the sequence.

Note that this assumes you are using Oracle-style binding as required in OA Framework Model Coding Standard M23.

Incorrect

select emp_name from employees

where emp_id = :1

and manager_id = :1

select emp_name from employees

where emp_id = :1

and manager_id = :1

and deptno = :4

Correct

select emp_name from employeeswhere emp_id = :1and manager_id = :2and deptno = :3

This is actually a JDBC coding standard violation that may work when you initially code it, but may fail at the customer site (particularly when personalizations are applied).

M31

You must expliclity initialize all view objects that are not used to query data from the database to suppress any efforts by BC4J to query the database.

For detailed instructions on how to address this in different scenarios, see View Objects in Detail: Initialization Guidelines.

This unwanted query may result in a SQL exception due to unbound WHERE clause parameters, or the loss of newly inserted rows that are not properly passivated/activated.

M71

When accessing an application module, use

getApplicationModule() instead of

getRootApplicationModule() whenever

This ultimately improves modularity and reuse.


1530

possible.

Also see guideline C11 in the Controller Coding Standards.

Service Interface

M72

For Service Interface only: If a service view object supports partial failure, then the service view object can only be based on one updateable entity object.

Changes posted in a service view object, are actually posted in the underlying entity object. However, if a post to an entity object fails, then the corresponding view object row needs to be reverted. If the view object is based on more than one updateable entity object, it becomes more complicated to revert all entity objects if only some entity objects fail.

M73

For Service Interface only: If a row modifies other rows that are neither its parent nor its children,then the corresponding SVO is is recommended not to support partial failure. If the SVO has to enable partial failure, then:

1. The API needs to make sure that all the changes made to the other rows are reverted back before throwing an exception.

2. If the modification of other rows occur in the validation cycle, then the modifications should be addressed after validation. This avoids the situation where a row fails and is rolled back to its original state, but the other rows are left in an inconsistent state.

3. If an entity needs to modify other entities that are neither its parent nor its children in the commit cycle, the modifications should be done after the entity itself has been posted successfully. This requirement avoids the situation where an entity modifies other entities, but the entity itself fails later and is reverted leaving the other entities in an inconsistent state.

4. If the modification of other rows occur in the validation cycle, and the underlying

entity object fails during postChanges or

commit, then the underlying entity object should revert all changes made to the other rows before throwing the exception.

If a row makes changes to other rows, and the row fails and needs to be reverted, then changes made to all the other rows also need to be reverted. Since OA Framework does not know how to revert the other rows, your API needs to take care of this before throwing an exception.


1531

M75

For Service Interface only: When you define the properties of your service view link, you must specify singular accessor names for the view link source and destination. For example, when defining a SuppliertoSitesSVL, specify the Source accessor name as Supplier and the Destination accessor name as SupplierSite.

This is required to support the generation XML Schema per changes for the new Service Data Object (SDO) standard.

Performance

M16

Always create view objects declaratively if you can. Create view objects programmatically ONLY if you CANNOT create them declaratively.

Note: If you must create a dynamic view object,we recommend that you use an oracle.apps.fnd.framework.server.OAVi

ewDef instead of a SQL statement to define the

view object. The OAViewDef is a more performant

option, and it allows you to create an "OA" view object which is essential for UI component binding.

If you create a dynamic view object from an oracle.apps.fnd.framework.server.OAVi

ewDef, you must follow the usage rules

documented in the OAViewDef Javadoc.

Dynamic view objects have to be described by BC4J through an additional execute call for the VO prepared statement, and they potentially result in non shareable SQL.

M17

If you must programmatically create a view object or view object attribute:

x Do not create dynamic view objects without a name (and do not use a null name like "").x Make sure you avoid a naming collision by checking to see whether a VO or attribute of that name already exists or before trying to create it.x Be sure to remove any view objects which are no truly longer required (however, you

should use AM.findViewObject() to

reuse one that has already been created; don't recreate it unnecessarily as the VO is cached on the AM and automatically cleared when the AM is released).

Naming the dynamic view object gives you the ability to look it up next time you need it instead of recreating it.

M18

Avoid creating generic view objects just so you can reuse them in different places. Create dedicated, task-specific view objects instead that are as small as possible.

The "one VO fits all" approach adds complexity to your SQL, increases number of attributes and VO memory footprint. You should consider view objects to be UI/task-specific.


1532

M19

If you create your view object declaratively, try to avoid changing the WHERE clause definition or order by clause at runtime. If you can, create multiple definitions of the same view object, each with a different WHERE clause (note that it is appropriate to change the WHERE clause if you have complex search criteria).

These actions invalidate the cached statement and require reparsing.

M20

Always generate anoracle.apps.fnd.framework.server.OAVi

ewRowImpl subclass for the view objects (VOs)

that you create. Furthermore any code you write to call accessors on the view row should use the named accessors (for example,

getSupplierName()) on the VO row instead of

the generic accessors.

Accessing the VO attributes through the index is significantly faster; especially for VOs with a large number of attributes (10+).

x Avoid using getAttribute("")

which performs a expensive scan to lookup the index.

M21

If possible, define your view object as "Read Only" and "Forward Only."

Note that this standard makes the most sense for view objects that are not tied to the UI.

No validation and smaller memory footprint. Prevents BC4J from buffering all of the result set in themiddle tier.

M22

If your view object is based on multiple entity objects, restrict the number of Key Attributes to a minimal set that uniquely identifies the row.

This improves performance by reducing the primary key comparison logic for lookups, and it also reduces the cost of encryption when each primary key value has to be encrypted in your application for security purposes. The also reduces HTML footprint, since the primary key is sent to the browser.

M23

ALWAYS use Oracle-style binding (:1, :2) in your SQL. Do NOT use ANSI JDBC-binding (?).

This avoids parsing SQL at runtime to do String replacement.

It's also necessary for any view objects with a DATE value in the WHERE clause due to a mismatch between the Java and Oracle Date formats when the month format mask is MON.Due to that, to_date() function might return a error.

Warning: ANSI JDBC-style binding will be desupported in the Fusion release.

Proposed GSCC Warning


1533

File.Java.24

M24

Always use bind variables for any values that are passed from the client. Do not use literal values (for example, do not simply concatenate a value to the WHERE clause).

M25

Always make sure that precision is specified for all String columns in the view object (including both declarative and programmatically defined view objects). Furthermore, the precision needs to match the database column - if you change the column size or generate the VO against an invalid database, the VO definition can be out of synch.

Note: This is specified automatically for any VO defined since Oracle JDeveloper.

This reduces the view object memory footprint. Without a set precision, for example, all String columns default to 4KB in size each.

M26

Do not execute searches by default nor allow blind queries. Remember that the FND: View Object Max Fetch Size profile option is set to "200" by default for Oracle E-Business Suite development. Even with search criteria, you cannot query > 200 rows without first presenting your case to the Applications Performance Tuning team for approval.

M27

Do not use select* in the view object definition. Data model changes will break the code.

M28

For view objects which are not bound to a UI component, fetch only the number of rows you want to display; no more. Set the VO prefetch size to an appropriate value.

Note: This is handled for you automatically for view objects used with UI components (for example, if the VO is serving up rows to a table displaying 10 rows, the prefetch value is set to 10).

M29

Avoid calling vo.getRowCount() to perform a

simple row existence check.

For VOs that you query, use vo.first() or

getRowCount() causes the entire

view object row set to be fetched to middle tier.

GSCC Warning File.Java.19


1534

vo.hasNext() and check for a null result.

For VOs that you populate programmatically without performing a query, you could also use:

if (vo.getFetchedRowCount == 0)

M30

Never call VO.getEstimatedRowCount(). getEstimatedRowCount()

executes select count(*) on the

VO. This count is not guaranteed to stay the same, thus the method name.

GSCC Warning File.Java.20

M32

This standard has been revised for clarity and moved to the controller coding standards for a better fit with the revised content. See OA Controller Coding Standard C32.

M33

Use view links carefully (note that they are required when performing DML on master/detail entity objects related by a composite association, and by certain UI components like the Tree and HGrid).

In cases where they are not required, do not use them if you don't want to buffer data for the life of the transaction.

View links buffer data as you navigate from master to master. If practical from a design perspective, code the master on one page and the detail on a second page (pass the search criteria on the request).

M34

When creating a RowSet or RowSetIterator make sure you name and close them when you're done

using closeRowSet() and

closeRowSetIterator() respectively.

You can (and should) reuse them using the ViewObjectImpl.findRowSetIte

rator() method.

M36

Tune your SQL!!!! Fix all SQL statements with:

x Full table scans/full index scansx Hash joinsx Non-mergable viewsx Parse time > 0.3 secondsx Sharable memory >= 100KDo not add decode or nvl conditions in WHERE clauses to control join conditions or filters.

See Enabling a Database Trace in the Testing OA Framework Applications chapter for instructions on checking your OA Framework SQL statements.

If the SQL is poorly written, response time and scalability will be adversely affected.

Additional information for Oracle E-Business Suite internal audiencenes only:

x SQL Repository (explains concepts mentioned in standard like hash joins, non-mergable views and so on)x Performance presentations onwriting scalable SQL

Additional information on SQL tuning for all audiences is also available in your Oracle 10g Database documentation (also published on the


1535

Oracle Technology Network site).

M61

If you have a dynamic view object created from an

OAViewDef, and if no database query is needed

for the view object (you typically call

ViewObjectImpl.setMaxFetchSize(0) for

these view objects), then make sure to set the expert mode (full SQL) property to true with

OAViewDefImpl.setExpertMode(true) or

OAViewDefImpl.setFullSql(true).

If the FullSql property is false (the

default), then BC4J framework tries to build (derive) the SQL from the EO attributes. Setting FullSql to trueoptimizes the performance and allows BC4J to save the VO state properly for passivation purposes.

State Management


M37

Whenever you dynamically set a WHERE clause or bind WHERE clause parameters, always clear any possible preexisting values before executing the query as shown:

vo.setWhereClause(null);vo.setWhereClauseParams(null);...vo.executeQuery();

Note: Upon setting up query criteria and executing the view object query, make sure your view object query criteria remains consistent with the executed query. In other words, do not change or reset query criteria unless the new criteria will be consumed within a request (for JSP forward case, before the page boundary is reached).

The preexisting WHERE clause parameters must be cleared to avoid exceptions like "java.sql.SQLException: ORA-01008: not all variables bound", in case the previous where clause had more parameters.

The view object query criteria must remain consistent with the executed query because an inconsistent view object state could cause undesired side effects. Note that OA Framework has the right to call ViewObject.executeQuery() for a view object that is already prepared for query execution, and this may not be what you intended if you redundantly set up query criteria and, for instance, cleared the view object cache or


1536

passivated and activated the view object.

M38

Don't just assume your view object exists, or that it contains the expected data; you could get a

NullPointerException. Always check for null

and handle this case.

M39

All view objects must have a primary key (this is essential for correct passivation support).

If you want to perform DML operations (insert, update, delete) on a view object row, always use the primary key instead of the row index. In a Real Application Cluster with database partitions, the same database row can have a different ROWID in different partitions. Similarly, if a table is partitioned, the ROWID can change inside a transaction if the row is migrated. This leads to problems if you rely on the ROWID as your primary key.

See the View Object topic in Implementing the Model for information about defining primary keys.

Exception: This isn't necessary for view objects that truly do not have a logical primary key (for example, a view object that simply selects the sum or average of something).

Tip #1: When the -

Djbo.debugoutput=console runtime

JDeveloper Java Option is used, BC4J logs a diagnostic warning upon passivation, and throws an exception upon activation, for VOs without primary keys. See OA Framework State Persisistence Model (Passivation) - Controlling View Object Passivation for additional information.


1537

M40

Updateable view objects should always be passivated.

Master/detail view objects related by view links must also be passivated.

The following is a guideline.

For read-only view objects with a primary key, passivation should be enabled if the view object is referenced by a UI component.

For read-only view objects with a primary key that aren't used by UI components, enable passivation if you need to preserve view object state like range, WHERE clause, current row and so on. Otherwise, disable passivation.

For read-only view objects without a primary key, disable passivation.

Note: If you disable passivation, make sure that

your controller's processRequest() method

handles data initialization as stated in Browser Back Button Support Guidelines: View Object Data Initialization. Also note that BC4J does not automatically recreate programmatically created view objects if they are passivation-disabled. In

this case, your controller's processRequest()

method must call server-side code capable of finding/recreating the view object (the OA

Framework enters processRequest() while

rebuilding the web bean hierarchy after passivation). See the Passivation documentation for additional information.

Passivation has an associated cost, and should be avoided when unnecessary.

M60

Do not try to store UI state in an entity object transient attribute (for example, do not try to store a table bean's selector value).

Instead, use a view object transient attribute and designate it as a passivation-enabled attribute.

This ensures that the value persists after passivation / activation.


1538

M65

When you iterate view object rows to perform some operation on selected rows, be sure to evaluate all the view object ranges, and not just the current view object range.

When BC4J rebuilds a view object during activation, row positions may change as the refreshed result set may include newly inserted rows in the database and/or reflect the removal of deleted rows in the database. As a result, the rows that were in the displayed range may no longer be in the current range after activation.

M69

Whenever you create and insert a new row into a transactional view object, always immediately set its row state to STATUS_INITIALIZED after you perform the row insert. View objects rows should not appear to have pending changes immediately after they are created and defaults are applied. For example:

Row row = vo.createRow();

vo.insertRow(row);

row.setNewRowState(Row.STATUS_INITIALIZED);

Exception: If you explicitly require that the row remain "dirty" so it is posted and committed regardless of further user changes, you may avoid making this state change.

Note: You cannot use this method for

OAPlsqlViewObjectImpl view objects (they

are not based on entity objects, and ultimately, BC4J manages this state at the entity object level). Please see the OAPlsqlViewRowImpl.setNewRowState()

Javadoc for additional information about controlling the state for this special case.

Also see standard M67.

Doing this ensures that rows that have not been edited by the user are not validated or posted to the database (even if you set defaults for the row). For example, if you have a table ofexpenses that is prepopulated with 5 "temporary" rows, but the user only needs to record 2 expenses, you want the 3 untouched rows to be ignored when you validate / commit the changes. Setting the row state as described here achieves this.

Note this also ensures that "temporary" rows do not trigger the save model warning message if the user tries to abandon th

OAF - Standards

Documents

Transcript of OAF - Standards