24.5 Setting Up Oracle ADF Source Code for Debugging

You can obtain complete source code for Oracle ADF by opening a service request with Oracle Worldwide Support and requesting it. This section explains how to use Oracle ADF source code for debugging purposes inside the Oracle JDeveloper environment.

Note: The instructions below assume you have extracted the adf_1013_3673_source.zip archive into the root C:\ directory to create a C:\adf_1013_3673_source directory, and that your JDeveloper home directory is C:\jdev1013. If you have JDeveloper installed in a different directory, you'll need to substitute that instead.

24.5.1 Setting Up the ADF Source System Library

The first step requires you to define a system library that points to the adfsource.zip file. To accomplish this task, follow these steps:

1. Select Tools | Manage Libraries to display the Manage Libraries dialog.

2. With the Libraries tab selected, click on the System Libraries folder in the tree at the left and click the New button

3. Enter a library name. For example, ADF Source.

4. Enter a source path of C:\adf_1013_3673_source\adfsource.zip

   
   

   Note: Notice the Class Path field is blank. You only need to provide a value for the Source Path field.

   
   

5. Uncheck the Deployed by Default checkbox.

6. Click OK to close the Manage Libraries dialog.

24.5.2 Adding the ADF Source Library to a Project

In order to debug any application using Oracle ADF inside JDeveloper, you just need to add your new ADF Source system library created above to the library list of the project you plan to debug. To accomplish this task, follow these steps:

1. Select the project that you will be debugging in the Application Navigator.

2. Choose Project Properties from the right mouse menu to show the Project Properties dialog.

3. Select the Libraries category in the tree at the left (by default, under the Development profile).

4. Select the ADF Source library in the Available Libraries list on the left

5. Click the (>) button to move this library into your project's Selected Libraries list.

6. Click OK to close the Project Properties dialog.

24.5.3 Seeing Better Information in the Code Editor

Once you have added the ADF Source library to your project, you instantly have access to the helpful Quick JavaDoc feature ([Ctrl]+[D]) that the JDeveloper Code Editor makes available. As shown in Figure 24-3, invoking the Quick JavaDoc on a method like findSessionCookie().

Figure 24-3 Using Quick JavaDoc on ADF API's in Code Editor

24.5.4 Setting Breakpoints and Debugging

After performing the two steps above, you can debug any Oracle ADF code for the current project in the same way as you have been doing for your own Java code. This means that you can press [Ctrl]+[Minus] to type in any class name in Oracle ADF, and JDeveloper will open its source file automatically so you can set breakpoints as desired.

24.5.5 Seeing Better Symbol Information Using Debug Libraries

When debugging Oracle ADF source, as shown in Figure 24-4 by default you will not see symbol information for parameters or member variables of the currently executing method.

Figure 24-4 Local Symbols Are Hard To Understand Without Debug Libraries

This can make debugging a little less useful. You can make the situation better by using the debug versions of the ADF JAR files supplied along with the source, while debugging in your development environment.

Note: The supplied debug libraries are not recommended for use in a test or production environment since they typically have slightly slower runtime performance than the optimized JAR files shipped with JDeveloper.

The debuglib subdirectory of C:\adf_1013_3673_source contains versions of Oracle ADF JAR files from JDeveloper 10.1.3 Build 3673 that have been compiled with additional debug information. When you use these debug JAR files instead of the default optimized JAR files you will see all of the information in the debugger as shown in Figure 24-5.

Figure 24-5 See Local Symbol Information in Debugger Using Debug Libraries

In order to use these debug JAR files, perform the following steps:

1. Make sure JDeveloper 10g is not running. If it's currently running, exit from the product before proceeding with the subsequent steps.

2. Make a backup subdirectory of all existing optimized JAR files in the ./BC4J/lib directory of your JDeveloper installation:

   C:\> cd jdev1013\BC4J\lib
   C:\jdev1013\BC4J\lib> mkdir backup
   C:\jdev1013\BC4J\lib> copy *.jar backup
   
   

3. Notice that the debuglib subdirectory of C:\adf_1013_3673_source contains debug versions of the same ADF JAR files as the ones you just made a backup of. The only difference is that each debug JAR file has the suffix _g.jar instead of just.jar.

4. For each ADF library that you want to have debug symbols for while debugging, copy the _g.jar version of the matching library over the existing, corresponding library in the C:\jdev1013\BC4J\lib directory. This is safe to do since you made a backup of the optimized JAR files in the backup directory in step 2 above.

   For example, for the main ADF Business Components runtime JAR file (bc4jmt.jar), you would copy the C:\adf_1013_3673_source\debuglib\bc4jmt_g.jar to C:\jdev1013\BC4J\lib\bc4jmt.jar.

Since debug libraries typically run a little slower than libraries compiled without debug information, this diagnostic message is to remind you not to use debug libraries for performance timing.

**************************************************************************
*** WARNING: Oracle BC4J debug build executing - do not use for timing ***
**************************************************************************

To change back to the optimized libraries, simply copy the JAR file(s) in question from the ./BC4J/lib/backup directory back to the ./BC4J/lib directory.