6 Debugging an Oracle ADF Application

Like any debugging task, debugging the web application's interaction with Oracle Application Development Framework (Oracle ADF) is a process of isolating specific contributing factors.

To identify and fix application problems, the ADF Debugger provides declarative breakpoints that you can set at the ADF object level (such as task flows and ADF lifecycle phases), as well as standard Java breakpoints. ADF declarative breakpoints provide a high-level object view for debugging ADF applications. For example, you can break before a task flow activity to see what parameters would be passed to the task flow. To perform the same function using only Java breakpoints would require you to know which class or method to place the breakpoint in. ADF declarative breakpoints should be the first choice for ADF applications.

For more information about debugging an ADF application, see the Using the ADF Declarative Debugger section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

6.1 Using ADF Source Code with the Debugger

If you have valid Oracle ADF support, you can obtain complete source code for Oracle ADF by opening a service request with Oracle Worldwide Support. You can request a specific version of the Oracle ADF source code. You may be given download and password information to decrypt the source code ZIP file. Contact Oracle Worldwide Support for more information.

Adding Oracle ADF source code access to your application debugging session will:

• Enhance the use of Java code breakpoints by displaying the Oracle source code that's being executed when the breakpoint is encountered. You can also set breakpoints easier by clicking on the margin in the source code line you want to break on. Without the source code, you will have to know the class, method, or line number in order to set a breakpoint within Oracle code.
• For Java code breakpoints set within the source code, you will be able to see the values of all local variables and member fields in the debugger.

After you have received or downloaded the "outer" ZIP, unzip it with the provided password to access the actual source code ZIP file. The ADF source code ZIP name should be a variant of the ADF version number and build number. For example, the ADF source ZIP may have a format similar to adf_vvvv_nnnn_source.zip, where vvvv is the version number and nnnn is the build number. Extract the zip into a folder that has the same name as the zip. For example, if the ADF zip is named adf_111150_6013_source, extract it into a folder called adf_111150_6013_source.

To add an ADF source library to a project:

1. From the main menu, select Window > Preferences.
2. In the Preferences dialog, select ADF > ADF Source Code Location.
3. In the ADF Source Code Locations page, click Add.
4. In the Add ADF Source Bundle Location dialog, navigate to the ADF source location by clicking Browse in the Location field. The Bundle information field is populated. Then click OK.
5. Click OK in the Preferences dialog.

Note: When multiple versions of WLS (for example, 10.3.5 and 10.3.6) and ADF runtime are configured in OEPE, and the shared libraries from these distributions have the same sub-version, only the latest WAR/JAR from the latest WLS runtime will be registered in the OEPE shared library registry. If the version of ADF source code (for example, 11.1.1.6.0) provided to OEPE is targeted to an older WLS/ADF runtime, it will not be mapped to the later version of the runtime JAR.

6.2 Setting ADF Declarative Breakpoints

You use the ADF Declarative Debugger features in OEPE to declaratively set breakpoints on ADF task flow activities, ADF bindings, and ADF lifecycle phases. ADF declarative breakpoints provide a high-level object view for debugging ADF applications. For example, you can break before a task flow activity to see what parameters would be passed to the task flow. To perform the same function using only Java breakpoints would require you to know which class or method to place the breakpoint in. ADF declarative breakpoints should be the first choice for ADF applications.

The ADF Declarative Debugger also supports standard Java code breakpoints. You can set Java code breakpoints in any ADF application. You may be able to use Java code breakpoints when an ADF declarative breakpoint does not break in the place you want.

The ADF Declarative Debugger is built on top of the Java debugger, so it has the features and behaviors of the Java debugger. But instead of needing to know the Java class or method, you can set ADF declarative breakpoints in visual editors.

6.2.1 Setting and Using ADF Task Flow Breakpoints

You can add breakpoints to task flow activities in the task flow editor by selecting a task flow activity and using the context menu to toggle or disable breakpoints on that activity. After the application pauses at the breakpoint, you can view the runtime structure of the objects as well as a list of data for a selected object in the ADF Structure and Data window.

When an ADF declarative breakpoint is set, it appears as a red dot icon in the task flow activity.

To set and use a breakpoint on a task flow activity:

1. Double-click the task flow in the Project Explorer to open in the task flow editor.
2. Right-click a task flow activity and choose Toggle Breakpoint from the context menu.

   A blue dot appears on the task flow activity, signifying that the breakpoint has been set.

3. Start the debugging process. You can:
   • From the main menu, choose Run > Debug As, and then select the server.
   • From the Project Explorer, right-click the project, adfc-config.xml, faces-config.xml, task flow, or page and choose Debug As, and then select the server.
4. When the application is paused at a breakpoint, a red triangle appears next to the breakpoint icon on the task flow activity. You can now examine the application using the ADF Structure and Data window or the Debug window.
5. The ADF Structure and Data window appears by default. You can use this window to examine runtime structure and corresponding data values.
6. Select a node in the ADF structure in the left pane and view pertinent data in the right pane. Task flow activity declarative breakpoints pause the application just before the task flow activity is executed. You can use the Step Into (F5) function to pause the application just prior to executing the called task flow default activity.
7. Continue debugging the application as required.

6.2.2 Setting and Using ADF Page Definition Breakpoints

You can add breakpoints to page definition executables and bindings in the page definition editor by selecting a binding or executable item and using the context menu to toggle or disable 'before' or 'after' breakpoints on that item. After the application pauses at the breakpoint, you can view the runtime structure of the objects as well as a list of data for a selected object in the ADF Structure and Data window.

To set and use ADF page definition breakpoints:

1. In the page definition editor, in the Outline section, right-click the binding or executable you want to set the breakpoint on. From the context menu, select Toggle Breakpoint Before or Toggle Breakpoint After or both depending on where you want to place the breakpoint. A blue triangle appears on the item indicating that the breakpoint has been set, as shown in the following figure.
   
   
2. From the main menu, select Window > Open Perspective > Debug. The Breakpoints window lists the breakpoints you have set selected by default. You can deselect breakpoints in the Breakpoints window if you do not want them to be considered by the debugger. Double-clicking a breakpoint in the Breakpoints window opens the page definition editor with the particular binding or executable in focus.
3. Start the debugging process. You can:
   • From the main menu, choose Run > Debug As, and then select the server.
   • From the Project Explorer, right-click the project or page and choose Debug As, and then select the server.
4. When the application is paused at an ADF page definition breakpoint, a red triangle appears on the impacted binding element in the page definition editor, as shown in the following figure. You can now examine the application using the debugging resources available.
   
   
5. The ADF Structure and Data window appears by default when you work in the Debug perspective. You can use this window to examine runtime structure and corresponding data values.
6. Select a node in the ADF structure and view pertinent data in the right pane.
7. Continue debugging the application as required.

6.2.3 Setting and Using ADF Lifecycle Phase Breakpoints

You can set Before and After breakpoints on all the ADF lifecycle phases in the ADF Lifecycle diagram. For each phase, you can set Before only, After only, or both. You can set breakpoints on as many phases as you want. The ADF Lifecycle diagram is available from the Breakpoints window. You can set ADF lifecycle breakpoints on any of the ADF lifecycle phases:

• JSF Restore View
• Initialize Content
• Prepare Model
• JSF Apply Request Values
• Apply Input Values
• JSF Process Validations
• Validate Input Values
• Process Update Model
• JSF Update Model Values
• Validate Model Updates
• JSF Invoke Application
• Process Component Events
• Metadata Commit
• Prepare Render
• JSF Render Response

To set and use ADF lifecycle phase breakpoints:

1. Select Window > Show View > Breakpoints to open the Breakpoints window.
2. In the Breakpoints window, click the Add ADF Lifecycle Breakpoints button in the toolbar.

   The ADF Lifecycle Diagram is displayed.

3. In the ADF Lifecycle Diagram, select the left checkbox to set a breakpoint before the phase, or select the right checkbox to set a breakpoint after the phase, or select both.
4. Start the debugging process. You can:
   • From the main menu, choose Run > Debug As, and then select the server.
   • From the Project Explorer, right-click the project, adfc-config.xml, faces-config.xml, task flow, or page and choose Debug As, and then select the server.
5. When the application is paused at an ADF lifecycle phase breakpoint, you can examine the application using the debugging resources available.
6. The ADF Structure and Data window appears by default when you work in the Debug perspective. You can use this window to examine runtime structure and corresponding data values.
7. Select a node in the ADF structure and view pertinent data in the right pane.
8. Continue debugging the application as required.

6.3 Using the EL Expression Evaluator

When the application is paused at a breakpoint, you can use the EL expression evaluator to enter an EL expression for evaluation. You can enter arbitrary EL expressions for evaluation within the current context. If the EL expression no longer applies within the current context, the value will be evaluated to null. The EL Evaluator is available for debugging any JSF application.

To use the EL Evaluator:

1. Set a break point in the JSF application.
2. Start the debugging process.
3. When the breakpoint is reached, click the ADF EL Evaluator tab to bring it forward.
4. Enter an EL expression in the Expression field.

   When you click in the field after entering #{ or after a period, a discovery function provides a selectable list of expression items. Auto-completion will be provided for easy entry. You can evaluate several EL expressions at the same time by separating them with semicolons.

5. When you finish entering the EL expression, click Evaluate and the expression is evaluated.

6.4 Using the ADF Structure and Data Window

The ADF Structure and Data window displays the ADF structure on the left pane, and relevant data for a given object in the right pane.

When you use the Debug perspective of OEPE, the ADF Structure and Data window opens by default. To manually launch the ADF Structure and Data window, choose Window from the main menu, and then select Show View > ADF Structure and Data.

6.4.1 Using the ADF Structure pane

When the application is paused at a breakpoint, the ADF Structure pane displays a tree structure of the ADF runtime objects and their relationships within the application. In particular, it shows the hierarchy of view ports, which represent either the main browser window or contained regions. When you select different items in the ADF Structure pane, the data display in the accompanying ADF Data pane changes.

The roots of the hierarchy are the sibling nodes Scopes and ADF Context.

• Scopes: Displayed at the top of the ADF Structure hierarchy above its sibling ADF Context node. There is only one Scopes node in the ADF Structure hierarchy. You can expand the Scopes node to show a list of child scope nodes (such as viewScope and pageFlowScope). If you select a child scope node, the ADF Data pane displays the variables and values for that scope.
• ADF Context: Displayed as the root node of the ADF Structure hierarchy below its sibling Scopes node. There will only be one ADF Context within the ADF Structure hierarchy.

6.4.2 Using the ADF Data pane

When an application is paused at an ADF declarative breakpoint, the ADF Data pane (in the ADF Structure and Data window)s displays relevant data based on the selection in the ADF Structure pane.

The ADF Data pane displays the following types of data:

• You can inspect the values of requestScope, viewScope, pageFlowScope, applicationScope, and sessionScope by expanding each corresponding node in the ADF Structure pane.
• When the ADF context is selected in the ADF Structure pane, the current value of the ADF context variables will be displayed in the ADF Data pane.
• Selecting a view port within the ADF Structure hierarchy will display the view port's current view port details in the ADF Data pane.
• In the ADF Structure pane, each individual ADF task flow within a page flow stack hierarchy is selectable. An ADF task flow selected in the ADF Structure pane will display the current task flow information in the ADF Data pane.
• When you select a page or page fragment node in the ADF Structure hierarchy, the corresponding UI component tree is displayed within the ADF Data pane.

---

Copyright © 2013, Oracle. All rights reserved.