JDeveloper: Development Methodology
JDeveloper is used for developing OA Framework–based pages in E-Business Suite. For this reason, the very first step is to download the JDeveloper. Once the right version of JDeveloper has been downloaded, the next step is to perform some minor configurations to your desktop and JDeveloper. After your configurations are complete, you can begin development. JDeveloper provides various wizards to quickly create pages in OA Framework. In the following sections, you will not only learn the configurations steps, but also take a look at the files that JDeveloper creates behind the scenes.
JDeveloper and Desktop Configuration
In this section, we will go through the steps required to get your desktop ready for development of OA Framework applications. It is assumed that you have access to an E-Business Suite VISION environment.
Download JDeveloper for OA Framework
You must download the right version of JDeveloper depending upon the version of your E-Business Suite. This information is available from Metalink Note 416708.1 and is listed in the table shown next:
|E-Business Version and Patching Level||Download JDeveloper from Patch|
|Base 11.5.10 (patch 3438354)||Patch 4045639|
|11.5.10 CU1 (patch 4017300)||Patch 4141787|
|11.5.10 CU2 (patch 4125550)||Patch 4573517|
|11.5.10 RUP3 (patch 4334965)||Patch 4725670|
|11.5.10 RUP4 (patch 4676589)||Patch 5455514|
|11.5.10 RUP5 (patch 5473858)||Patch 6012619|
|11.5.10.RUP6 (patch 5903765)||Patch 6739235|
|Base R12||Patch 5856648|
|R12.0.1 (patch 5907545)||Patch 5856648|
|R12.0.2 (patch 5484000 or 5917344)||Patch 6491398|
|R12.0.3 (patch 6141000 or 6077669)||Patch 6509325|
|R12.0.4 (patch 6435000 or 6272680)||Patch 6908968|
|R12.0.5 (No new ATG code released)||Patch 6908968 (same as R12.0.4)|
|R12.0.6 (patch 6728000 or 7237006)||Patch 7523554|
The JDeveloper that you will download from Metalink comes bundled with BC4J, MDS, and FND libraries that match the version of libraries that are deployed on the server. The easiest way to double-check the version of your E-Business Suite instance is to run a query on the ad_bugs table. For example, to confirm if you are on R12.0.4, run the following SQL query. If the query returns a record, then you are on R12.0.4 or higher.
SELECT creation_date FROM ad_bugs WHERE bug_number IN ( '6435000','6272680');
After downloading the zip file from Metalink, extract it to any directory on your desktop. Let us assume you have downloaded the zip file from Metalink to c:\oaf\ r124. For R12 RUP3, the file name is p6908968_R12_GENERIC.zip. The next step is to unzip this file in c:\oaf\r124. This will create three directories: jdevbin, jdevdoc, and jdevhome.
Please note that for Oracle Applications 11i, the JDeveloper version is 9i, whereas in R12 the JDeveloper version is 10g.
How to Configure the Environment for OA Framework Development
To configure JDeveloper for OAF development, you must create an environment variable JDEV_USER_HOME on your desktop. On a Windows desktop, this can be performed by navigating to System Properties | Advanced tab, and then clicking Environment Variables. Create a new user variable named JDEV_USER_ HOME, and a variable value that points to
\jdevhome\jdev—e.g., c:\oaf\r124\jdevhome\jdev. Please note that it is not mandatory to use \jdevhome\jdev\. You can use any directory on your desktop as your JDEV_USER_HOME. In fact, having a JDEV_USER_HOME independent of your JDeveloper installation directory will isolate your development area from future upgrade of JDeveloper, such as when your E-Business Suite instance gets upgraded to R12.1.
If you are a consultant who works with multiple customers, you may set JDEV_ USER_HOME to c:\oaf\dev\
. Of course, when you do development for a specific customer, you will then switch the value of JDEV_USER_HOME to an appropriate value and then start JDeveloper. In this book, we will assume that the JDEV_USER_HOME is set to c:\oaf\r124\jdevhome\jdev.
Copy the file c:\oaf\r124\jdevbin\Tutorial.zip to c:\oaf\r124\jdevhome and unzip Tutorial.zip. If you get the message, “This folder already contains this file,” click Yes to All. To start JDeveloper, double-click c:\oaf\r124\jdevbin\jdev\bin\ jdevW.exe. If you get the message, “Would you like to migrate from a previous version of JDeveloper?” simply click No, assuming this is the first time you are running JDeveloper.
In JDeveloper, you create a workspace that encapsulates your development efforts. Within the workspace, you create a project. For example, when doing development on HRMS, you may decide to create an Oracle Applications Workspace called xxhrms, and within that, you can create projects like xxiRecruitment, xxLearningMgmt, xxSelfServiceHR, and so on. It is important to note that a workspace created for OA Framework must be a workspace configured for OA Framework. The steps are very well documented in the tutorials that come with JDeveloper.
In this book, we will not try to show you how to create a very simple Hello World page; the OA Framework tutorial that comes bundled with JDeveloper goes into a great deal of detail on how basic pages get created from scratch. To access this help, open the index.htm in C:\oaf\r124\jdevdoc or your equivalent jdevdoc directory. On this page, click link Oracle Application Framework Toolbox Tutorials and expand the Content section in the left hand side pane. In that navigation tree, you will find Chapter 2, “Hello, World!”
By now, you should be able to open the sample tutorials delivered by Oracle in JDeveloper. Simply select File | Open and open C:\oaf\r124\jdevhome\jdev\ myprojects\ toolbox.jws. Once you open the workspace, all the projects within that workspace are opened as well. In R12, you will receive a message, “Do you want to migrate these files?” Click Yes. The reason you receive this message is because these tutorial files were developed with Oracle in JDeveloper 9i, which you are now trying to open using JDeveloper 10g.
Configuring the OA Framework Project
One of the first mandatory steps before you can run any page in JDeveloper is to get hold of a so-called DBC (Database Connectivity) file. DBC is specific to each instance of Oracle E-Business Suite. When running pages from JDeveloper, you have to be authenticated against Oracle E-Business Suite instance. It is this E-Business Suite instance for which you will require the DBC file. The DBC file, among other things, lists the machine on which the E-Business Suite database is running, the name of the database, and the port number at which database listener is listening to the requests.
Log in to your midtier using a tool such as putty, ssh, or other similar tool. You will have to log in as a Unix user who owns a midtier installation of Oracle Apps. Once logged in, you can go to the $FND_SECURE directory as shown:
Locate the relevant DBC file, which most likely will be listed at the end. Double-check that this DBC file is indeed the correct file by opening this file in text editor. Copy this file in ASCII mode to c:\oaf\r124\jdevhome\jdev\dbc_files\secure onto your desktop. A sample DBC file will look as shown in the following listing:
cd $FND_SECURE ls ltr *.dbc
#DB Settings #Tue May 13 23:36:30 BST 2008 GUEST_USER_PWD=GUEST/ORACLE APPL_SERVER_ID= 5EB4D8C6752C9CBAE0408F516C030FC126162113943872805134358175301238 APPS_JDBC_DRIVER_TYPE=THIN JDBC\:processEscapes=true GWYUID=APPLSYSPUB/PUB TWO_TASK=R124 FNDNAM=APPS DB_PORT=1533 DB_HOST=r12.com
It is obvious from the sample DBC file that it contains all the information required to establish a database connection to Oracle Apps Database except the password details.
DBAs sometimes run a process named Autoconfig that can change the APPL_SERVER_ID. For example, Autoconfig can be run after patches delivered by the Application Technology Group have been applied. Autoconfig is also run after a new application is registered with E-Business Suite. Therefore, it is important to ensure that you are using the latest DBC file from the server, so that APPL_SERVER_ID is always correct.
Connecting JDeveloper to Oracle Apps Database for Design and Runtime Use
The first step in connecting JDeveloper to Oracle Apps Database is to ensure that you have a valid username and password for the Oracle E-Business Suite instance that corresponds to your DBC file. The following table lists the information that you must note down before creating a relationship between JDeveloper and an E-Business Suite instance.
Creating a Database Connection
A database connection is required to connect JDeveloper with the Oracle E-Business Suite database. In JDeveloper, select File | New | Connections (under the General category) | Database Connection. Click the Next button, give your connection a user-friendly name, and click Next. In the UserName field, enter apps, set the password to an appropriate value, and then click Next. Enter the host name, JDBC port, and SID as shown in the previous table. Click Next to test the connection. Ensure that the Status of Test Connection is Success.
Configuring the Project Property
To access an OA Framework page in E-Business Suite, a user must be authenticated using his or her FND username and password. Once the login is authenticated, the user navigates to a responsibility from where he or she can access a menu. The menu in turn is attached to an AOL function that points to an OA Framework page.
When running the same page from JDeveloper, the user is not presented with a list of responsibilities nor prompted to enter FND username and password in JDeveloper. Running a page in OA Framework can be as simple as right-clicking a page and selecting Run. The selection of FND username, password, and responsibility occurs behind the scenes, as these details are held against project properties.
Specify the Runtime Connection project properties under Oracle Applications in the left-hand pane, as shown in Figure 9-6. The DBC file in this case will be picked from c:\oaf\r124\jdevhome\jdev\dbc_files\secure. You can use your own username that you use to log in to Oracle E-Business Suite. This user must have access to the responsibility specified in the project runtime property. These are free text fields, so care must be taken to enter the correct and valid values.
Running Hello World from Tutorial
Once you open c:\oaf\r124\jdevhome\jdev\myprojects\toolbox.jws and configure the project property for Tutorial.jpr, you can right-click the project to rebuild the files. Next, right-click the page you wish to run and select Run as shown in Figure 9-7.
Location of Files on the File System
Java uses the CLASSPATH argument, which tells JVM (Java Virtual Machine) the location of classes and packages as defined by the user. When a Java application is running, it searches the required Java files in all the locations within the CLASSPATH argument. It is quite common that in both Unix-like and Windows operations systems, the CLASSPATH is defined as an environment variable.
In Oracle E-Business Suite, the CLASSPATH variable contains numerous directories and JAR files. One of the directory locations within the CLASSPATH variable is JAVA_TOP, and this is where Java code for Oracle Apps is deployed. When users run an OA Framework page, the required class files are searched and loaded into JVM from JAVA_TOP at runtime.
Similar to other Java applications, the classes in Oracle Applications are grouped within packages. In this context, a package identifies the location of a file on the file system. For example, a file Utility.class exists within different packages as shown next, with each Utility.class having a different functionality.
oracle.apps.fnd.security.Utility.class oracle.apps.pay.utils.Utility.class oracle.apps.igs.recruitment.server.Utility.class
These class files physically exist in the location on the file system as shown next:
$JAVA_TOP/oracle/apps/fnd/security/Utility.class $JAVA_TOP/oracle/apps/pay/utils/Utility.class $JAVA_TOP/oracle/apps/igs/recruitment/server/Utility.class
The calling program will make reference to the correct Utility.class by executing the Java class from the correct directory location.
Equivalent of JAVA_TOP in JDeveloper
In Java, a developer writes logic into JAVA files and after compilation a corresponding CLASS file is created. Oracle Apps product development teams do not deliver JAVA (source code) files of their OA Framework applications to their customers. $JAVA_TOP is a purely runtime environment where the CLASS, XML, and JAR files are deployed. At runtime, JVM searches classes in specific packages within the $CLASSPATH environment variable, which leads to search being performed in $JAVA_TOP at runtime.
However, in JDeveloper, there is no $JAVA_TOP. The equivalent directory for $JAVA_TOP is
When you do development, all your JAVA and XML files get created in
/myprojects. When you compile/build your OA Framework project, CLASS and XML files get created in /myclasses.
Directory Tree Structure within $JAVA_TOP
As you know, the directory tree created on the file system maps to the packages that are created for Java objects. JDeveloper wizards create the directory tree behind the scenes to match the packages used for creating MDS or BC4J objects.
As seen in Figure 9-8, there are different package naming conventions that must be followed. All the components within brackets (< >) are optional. Immediately under $JAVA_TOP/oracle/apps is the short name of an application that is registered in Oracle E-Business Suite. This can also be a custom application short name; however, custom application development should go under the $JAVA_TOP/xxcust/oracle/apps directory tree provided that XXCUST is the short name for your custom application in our example.
Figure 9-8. Directory tree for some common objects like entity objects, view objects, and so on
For custom OA Framework objects, some DBAs prefer creating a new directory location that is totally independent of $JAVA_TOP. Such a directory location can then be added to the CLASSPATH so that the Oracle Framework engine can find your custom objects at runtime. Regardless of whether you use a custom directory or $JAVA_TOP/xxcust, your custom code will have packages with the naming convention of xxcust.oracle.app, and when deployed, it will be stored under the
Entity objects are always created in packages whose name ends with .schema.server. The view objects should be created in a package that ends with .server but not within .schema.server. All the page definitions and controllers should be created within packages that end with .webui. For custom LOVs (lists of values), the package name for a view object should be xxcust.oracle.apps.
.lov.server and the package for a LOV region should be xxcust.oracle.apps. .lov. webui.
In this book, we use XXCUST as a short name of our custom application; however, for your implementation this could be replaced by a short name of your company. For example, if you are developing an extension for a company called FocusThread, then the package naming convention could be xxft.oracle.apps.
in the package name must be a valid application short name when creating OA Framework pages. When creating BC4J objects, you can use any text for ; however, it is a good practice to ensure the use of a valid application short name.
Files Created by JDeveloper in OA Framework
When creating OA Framework pages or BC4J objects, JDeveloper creates a mixture of files behind the scenes. The following table looks at these files. Please note that a file will reside in a myclasses subdirectory after the file has been compiled or after the project or workspace has been rebuilt.
It is not mandatory to deploy JAVA files of your custom development to $JAVA_ TOP/xxcust/ as they are source code for your customization; however, it is a good to store them in $JAVA_TOP/xxcust/ or an appropriate custom code directory location for documentation purposes unless your organization uses specialized tools for release management of the custom code.