16.4 Understanding a Typical Oracle ADF Model Debugging Session

If you are not able to easily find the error in your web page or its corresponding page definition file, you can use the JDeveloper debugging tools to investigate where your application failure occurs. Specifically, the goal for debugging the interaction between the web page and the Oracle ADF Model layer is to pause the application by setting breakpoints on the execution of the Oracle ADF page lifecycle and to examine the data loaded at runtime. When the objects of the Oracle ADF Model layer do not contain the data that you expect to see, this observation will help you to identify the probable contributing factor.

Generally, the process for debugging proceeds like this:

1. Run the application and look for missing or incomplete data, actions and methods that are ignored or incorrectly executed, or other unexpected results.

2. Create a debugging configuration that will enable the ADF Log and send Oracle ADF Model messages to the JDeveloper Log window. For more information, see Section 16.4.2, "Creating an Oracle ADF Debugging Configuration".

3. Choose Go to Java Class from the Navigate menu (or press Ctrl + -) and use the dialog to locate the Oracle ADF class that represents the entry point for the processing failure.

   
   

   Tip: JDeveloper will locate the class from the user interface project that has the current focus in the Application Navigator. If your workspace contains more than one user interface project, be sure the one with the current focus is the one that you want to debug.

   
   

4. Open the class file in the Java editor and find the Oracle ADF method call that will enable you to step into the statements of the method.

5. Set a breakpoint on the desired method and run the debugger.

6. When the application stops on the breakpoint, use the Data window to examine the local variables and arguments of the current context.

Once you have set breakpoints to pause the application at key points, you can proceed to view data in the JDeveloper Data window. To effectively debug your web page's interaction with the Oracle ADF Model layer, you need to understand:

• The Oracle ADF page lifecycle and the method calls that get invoked

• The local variables and arguments that the Oracle ADF Model layer should contain during the course of application processing

Awareness of Oracle ADF processing, as described in Section 16.5, "Debugging the Oracle ADF Model Layer", will give you the means to selectively set breakpoints, examine the data loaded by the application, and isolate the contributing factors.

Note: JSF web pages may also use backing beans to manage the interaction between the page's components and the data. Debug backing beans by setting breakpoints as you would any other Java class file.

16.4.1 Turning on Diagnostic Logging

Even before you use the actual debugger, running with framework diagnostics logging turned on can be helpful to see what happened when the problem occurs. To turn on diagnostic logging set the Java System property named jbo.debugoutput to the value console. Additionally, the value ADFLogger lets you route diagnostics through the standard J2SE Logger implementation, which can be controlled in a standard way through the OC4J j2ee-logging.xml file.

The easiest way to set this system property while running your application inside JDeveloper is to edit your project properties and in the Run/Debug panel, select a run configuration and click Edit to edit it. Then add the string -Djbo.debugoutput=console to the Java Options field.

16.4.2 Creating an Oracle ADF Debugging Configuration

ADF Faces leverages the Java Logging API (java.util.logging.Logger) to provide logging functionality when you run a debugging session. Java Logging is a standard API that is available in the Java Platform, starting with JDK 1.4. For the key elements, see the section "Java Logging Overview" at http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html.

Because standard Java Logging is used, you can edit the j2ee-logging.xml file to control the level of diagnostics you receive in the Log window:

• When you conduct a debugging session within JDeveloper, you will use JDeveloper embedded-OC4J and will want to modify the file in your JDeveloper install here:

  <JDev_Install>/jdev/system/oracle.j2ee.10.1.3.xx.xx/embedded-oc4j/config

• Similarly, when you want to conduct a remote debugging session on Oracle Application Server, you can modify the file here:

  <OAS_Home>/j2ee/<OC4J_INSTANCE>/config

• Or, when you want to conduct a remote debugging session on standalone OC4J, you can modify the file here:

  <OC4J_Home>/j2ee/home/config

To edit ADF package-level logging in the j2ee-logging.xml file:

If you want to change the logging level for Oracle ADF, you can edit the <logger> elements of the configuration file.

Note: By default the level is set to INFO for all packages of Oracle ADF. However, Oracle recommends level="FINE" for detailed logging diagnostics.

For the packages oracle.adf.view.faces and oracle.adfinternal.view.faces, edit:

<logger name="oracle.adf" level="INFO"/><logger name="oracle.adfinternal" level="INFO"/>

For the Oracle ADF Model layer packages, edit these elements:

<logger name="oracle.adf" level="INFO"/><logger name="oracle.jbo" level="INFO"/>

Alternatively, you can create a debug configuration in JDeveloper that you can choose when you start a debugging session.

To create an Oracle ADF Model debugging configuration:

1. In the Application Navigator, double-click the user interface project.

2. In the Project Properties dialog, click Run/Debug and create a new run configuration, for example, named ADF debugging.

3. Double-click the new run configuration to edit the properties.

4. In the Edit Run Configuration dialog, for Launch Settings, enter the following Java Options for the default ojvm virtual machine:

   -Djbo.debugoutput=adflogger -Djbo.adflogger.level=FINE

   Oracle recommends the level=FINE for detailed diagnostic messages.

16.4.3 Understanding the Different Kinds of Breakpoints

You first need to understand the different kinds of breakpoints and where to create them.

To see the Debugger Breakpoints window, use the View | Debugger > Breakpoints menu choice from the main JDeveloper menu, or optionally the key accelerator for this: [Ctrl]+[Shift]+[R].

You can create a new breakpoint by selecting the New Breakpoint menu choice from the right-mouse menu anywhere in the breakpoints window. The Breakpoint Type dropdown list controls what kind of breakpoint you will create. The valid choices are:

• Exception — break whenever an exception of this class (or a subclass) is thrown.

  This is great when you don't know where the exception occurs, but you know what kind of exception it is (e.g. java.lang.NullPointerException, java.lang.ArrayIndexOutOfBoundsException, oracle.jbo.JboException, etc.) The checkbox options allow you to control whether to break on caught or uncaught exceptions of this class. The (Browse...) button helps you find the fully-qualified class name of the exception. The Exception Class combobox remembers most recently used exception breakpoint classes. Note that this is the default breakpoint type when you create a breakpoint in the breakpoints window.

• Source — break whenever a particular source line in a particular class in a particular package is run.

  You rarely create a source breakpoint in the New Breakpoint window. This is because it's much easier to create it by first using the Navigate | Go to Class menu (accelerator [Ctrl]+[Shift]+[Minus]), then scrolling to the line number you want -- or using Navigate | Go to Line (accelerator [Ctrl]+[G]) -- and finally clicking in the breakpoint margin at the left of the line you want to break on. This is equivalent to creating a new source breakpoint, but it means you don't have to type in the package, class, and line number by hand.

• Method — break whenever a method in a given class is invoked.

  This is handy to set breakpoints on a particular method you might have seen in the call stack while debugging a problem. Of course, if you have the source you can set a source breakpoint wherever you want in that class, but this kind of breakpoint lets you stop in the debugger even when you don't have source for a class.

• Class — break whenever any method in a given class is invoked.

  This can be handy when you might only know the class involved in the problem, but not the exact method you want to stop on. Again, this kind of breakpoint does not require source. The Browse button helps you quickly find the fully-qualified class name you want to break on.

• Watchpoint — break whenever a given field is accessed or modified.

  This can be super helpful to find a problem if the code inside a class modifies a member field directly from several different places (instead of going through setter or getter methods each time). You can stop the debugger in its tracks when any field is modified. You can create a breakpoint of this type by using the Toggle Watchpoint menu item on the right-mouse menu when pointing at a member field in your class' source.

16.4.4 Editing Breakpoints to Improve Control

After creating a breakpoint you can edit the breakpoint in the breakpoints window by selecting Edit in the context menu on the desired breakpoint.

Some really interesting features you can use by editing your breakpoint are:

• Associate a logical "breakpoint group" name to group this breakpoint with others having the same breakpoint group name. Breakpoint groups make it easy to enable/disable an entire set of breakpoints in one operation.

• Associate a debugger action to occur when the breakpoint is hit. The default action is to just stop the debugger so you can inspect things, but you can add a beep, write something to a log file, and enable or disable group of breakpoints.

• Associate a conditional expression with the breakpoint so that it the debugger only stops when that condition is met. In 10.1.3, the expressions can be virtually any boolean expression, including:

  • expr ==value

  • expr.equals("value")

  • expr instanceoffully.qualified.ClassName

  
  

  Note: Use the debugger watch window to evaluate the expression first to make sure its valid.

  
  

16.4.5 Filtering Your View of Class Members

An excellent but often overlooked feature of the JDeveloper debugger is the ability to filter the members you want to see in the debugger window for any class. In the debugger's Data window, pointing at any item and selecting Object Preferences from the right-mouse context menu brings up a dialog that lets you customize which members appear in the debugger and (more importantly sometimes) which members don't appear.

These preferences are set by class type and can really simplify the amount of scrolling you need to do in the debugger data window. This is especially useful while debugging when you might only be interested in a handful of a class' members.

16.4.6 Communicating Stack Trace Information to Someone Else

If you are unable to determine what the problem is and resolve it yourself, typically your next step is to ask someone else for assistance. Whether you post a question in the OTN JDeveloper Discussion Forum or open a Service Request on Metalink, including the stack trace information in your posting is extremely useful to anyone who will need to assist you further to understand exactly where the problem is occurring.

JDeveloper's Stack window makes communicating this information easy. Whenever the debugger is paused, you can view the Stack window to see the program flow as a stack of method calls that got you to the current line. Using the right-mouse Preferences menu on the Stack window background, you can set the Stack window preference to include the Line number information as well as the class and method name that will be there by default. Finally, the other useful context menu option Export lets you save the current stack information to an external text file whose contents you can then post or send to whomever might need to help you diagnose the problem.