Fusion Middleware Documentation
Advanced Search


Developing Applications with Oracle JDeveloper
Close Window

Table of Contents

Show All | Collapse

14 Running and Debugging Java Programs

This chapter describes how to use the tools and features provided by JDeveloper to run and debug Java programs. Debugging is the process of locating and fixing errors in your programs. The JDeveloper integrated debugger enables you to debug Java applications, applets, servlets, JavaServer Pages (JSPs), and Enterprise JavaBeans (EJBs). You can debug a single object or several of them on the same or different machine, because JDeveloper supports distributed debugging.

JDeveloper provides several debugging windows (for example, Breakpoint, Heap, and Stack) that enable you to identify problem areas in your code. In addition, the various JDeveloper debugger and runner icons available from areas in the JDeveloper user interface are described.

This chapter includes the following sections:

14.1 About Running and Debugging Java Programs

JDeveloper offers several techniques to monitor and control the way Java programs run. When running Java programs, JDeveloper keeps track of processes that are run and debugged, or profiled. In addition, JDeveloper offers both local and remote debugging of Java, JSP, and servlet source files.

JDeveloper supports two types of debugging: local and remote. A local debugging session is started by setting breakpoints in source files, and then starting the debugger. Remote debugging requires two JDeveloper processes: a debugger and a debuggee which may reside on a different platform. Once the debuggee process is launched and the debugger process is attached to it, remote debugging is similar to local debugging.

14.2 Understanding the Processes Window

The Processes window keeps track of processes that are run, debugged, or profiled. When two or more such processes are active at the same time, the Processes window is automatically displayed. When a process has completed, it is automatically removed from the Processes window.

  • To open the Processes window, choose Window > Processes from the main menu.

  • To terminate a process within the Processes window, right-click a process in the Processes window and choose Terminate from the context menu.

  • To view the Run Log, right-click a process in the Processes window and choose View Log from the context menu.

14.3 Configuring a Project for Running

Settings that control the way programs are run - such as the target, launch options, and the behavior of the debugger, logger, and profiler - are collected in run configurations.

A project may have several run configurations, each set up for a specific facet of the project or phase of the development process. A run configuration can be bound to the project and be available to all who work on the project, or it can be custom configuration, for your use only.

Note:

Java programs that are run from JDeveloper, for example the Oracle ADF Model Tester, do not inherit the JDeveloper IDE Java options. Therefore in most cases you should set the run/debug Java options you want to use in the run configuration.

14.3.1 How to Choose a Run Configuration

A default run configuration is created for each new project. You can select it or any other configurations you have created to run a selected project.

To choose a run configuration:

  1. From the main menu choose Application > Project Properties.

  2. Select Run/Debug.

    Note:

    If you have not previously accessed the Run/Debug/Profile page, a button labelled Launch displays. Click the button to access the Run/Debug/Profile page.

  3. In the Run Configurations list, choose a run configuration.

14.3.2 How to Create a Run Configuration

You create a new run configuration by copying an existing one, for example, Default. Then you modify the settings for the new configuration

To create a run configuration:

  1. Select a run configuration as described in Section 14.3.1, "How to Choose a Run Configuration."

  2. Click New.

  3. In the Name box, enter a name for the new run configuration.

  4. In the Copy Settings From dropdown box, choose an existing run configuration to copy from.

  5. To create a new run configuration having the same settings as the one it was copied from, click OK.

  6. To create a new run configuration having different settings, choose the new settings and click OK

14.4 How to Run a Project or File

After compiling your project or file, you can run it. For more information about building a project or file, see Chapter 12, "Building Java Projects" The log window displays any warning or error messages that may occur during the run.

To run a project or file:

  1. In the Applications window, select the project or file you want to run.

  2. Run an application in any of these ways:

    • For a project only, from the main menu choose Run > Run > <target>.

    • Right click and from the context menu, select Run.

    • Click the Run icon on the toolbar.

    • Press the F11 key.

    The main method of your Java application starts.

14.4.1 How to Run a Project from the Command Line

In order to run a project from the operating system command line:

  • The project must be a standalone executable.

  • You must select the class file containing the application main() method.

To launch an application:

Enter the following:

java -cp <jdev_install>\jdeveloper\jdev\mywork\Workspace1\Project1\classes package1.Application1

To launch the executable JAR file from the command line:

Enter the following:

java -jar <application>.jar 

where <application> is your JAR file name.

14.4.2 How to Change the Java Virtual Machine

You may need to change the Java Virtual Machine (VM) for which you are developing because of operating system considerations. For example, for client-side applications, you would use the HotSpot Client VM, whereas for executing long-running server applications, you would use the Server VM.

To change the Java Virtual Machine:

  1. Right-click a project in the Applications window and choose Project Properties from the context menu.

  2. Open the Run/Debug/Profile page.

  3. Select a run configuration and click Edit.

    The Edit Run Configuration dialog displays.

  4. On the Launch Settings page, in the Virtual Machine list box, select an available option.

    The selected JVM is used when running and debugging the project.

  5. Click Help for additional information.

14.5 Setting the Classpath for Programs

When you run a Java program from the command line, you must provide the Java Virtual Machine (JVM) with a list of the paths to the class files and libraries that comprise your application. The form of the classpath changes depending on the method you use to run the Java program.

Your Java classes can be stored in Java Archive (*.jar) files, or as separate class (*.class) files in their package directory. There are differences in the ways Java handles JAR files and package directories.

  • When you refer to JAR files in your CLASSPATH, you use the fully qualified path to the JAR file. When you refer to package directories in your CLASSPATH, you use the path to the parent directory of the package.

  • You can refer to both JARs and package directories in a CLASSPATH statement. When you refer to more than one CLASSPATH in the same statement, each CLASSPATH is separated with a semicolon(;).

Once you have defined the classpath, you pass the value to the JVM in different ways, depending on how you run your Java program.

  • Set the CLASSPATH environment variable to run a standalone application using java.exe.

  • Set the CLASSPATH environment variable to.use the -classpath option of java.exe.

  • Embed the CLASSPATH in the <APPLET> tag of an.html file to run an applet in an Internet browser.

You have the option of using either the -classpath option when calling an SDK tool (the preferred method) or by setting the CLASSPATH environment variable.

14.5.1 Setting the CLASSPATH Environment Variable (for java.exe)

The java.exe file is included as part of the Java2 Standard Edition (J2SE). It is intended to be used as a development tool, and is not licensed for distribution with your Java programs. It is used to test your Java applications from the command prompt.

In order to run a Java application from the command prompt, the system environment variable CLASSPATH must be defined to include all of the classes necessary to run your program. This includes any library classes provided with JDeveloper that your program uses.

14.5.2 Using the JDeveloper Library CLASSPATH

JDeveloper ships hundreds of library classes to help you generate your Java programs. The classes come from J2SE, third-party developers, and Oracle Corporation. Each of the libraries is kept separate for easy upgrade. As a result, many archive files may need to be included in your classpath to ensure that any program you create in JDeveloper can be run from the command prompt.

Oracle recommends that you list only the paths to each of the libraries that your project uses. If you list paths that your project does not use, your program will still run, but for performance reasons, you will want to eliminate any unnecessary libraries.

Note:

Never use quotation marks in the classpath even when there is a space character in one of the paths.

14.5.3 Setting the CLASSPATH to Include Your Projects

If you have used the default directory for your output path, you can test your Java application using java.exe by appending the following directory to your classpath:

C:\<jdev_install>\jdeveloper\jdev\mywork\Workspace1\Project1\classes

Having set this variable, you can use java.exe to run your application from the output directory mywork.

If you have deployed your Java program to any other directory, you need to add the path to the parent directory of the application package.

The CLASSPATH variable is a long string that can be difficult to type accurately. To save time and reduce errors, you can set the CLASSPATH as a system environment variable.

14.5.4 Setting the CLASSPATH Parameter (for java.exe)

The Java Runtime Engine (java.exe) doesn't use the CLASSPATH environment variable. The CLASSPATH must be included as a parameter to the java.exe command. The format for the command is:

java -cp <classpath> package.Application

Where classpath is the complete CLASSPATH to your Java program and the dependency classes it uses. Quotation marks are optional if there are no spaces in any of the CLASSPATH directory names.

14.6 Running an Applet

JDeveloper lets you run applets in the AppletViewer or in the Integrated WebLogic Server instance. The AppletViewer provides a test bed to run your applet without launching the web browser. When you want to run your applet in a browser, you can run in the Integrated WebLogic Server instance.

After creating your applet and ensuring that the classpath is set up properly in the HTML file, you can run it by executing the Run command.

To run an applet:

  1. In the Applications window, select the HTML file that contains the <APPLET> tag.

  2. Right-click the HTML file and choose Run.

  3. In the dialog, select the way you want to start the target applet and click OK:

    • In AppletViewer: The applet is launched in the Applet Viewer.

    • In the Server Instance: The integrated server is started and the applet is run in the server.

14.6.1 Using an HTML File to Store Arguments

An applet runs in an HTML page, from which it obtains its display size and other parameters. To run an applet in JDeveloper, you need to provide an HTML file containing the appropriate <APPLET> tag.

Parameter names are case-sensitive, although parameter tags are not:

<APPLET CODE="foo.class" WIDTH=200 HEIGHT=20> </APPLET> 

You can also pass parameters to the applet by including a <PARAM> tag between the <APPLET> and </APPLET> tags:

<PARAM NAME=foo VALUE=true>

Example 14-1 shows an HTML fragment that is used to pass parameters.

Example 14-1 HTML Fragment That is Used to Pass Parameters

<H1>Test File</H1> 
  <HR>
    <APPLET CODE="Test3.class" WIDTH=500 HEIGHT=120>
      <PARAM NAME=level VALUE="8"> 
      <PARAM NAME=angle VALUE="45"> 
      <PARAM NAME=delay VALUE="1000"> 
      <PARAM NAME=axiom VALUE="F"> 
      <PARAM NAME=incremental VALUE="true"> 
      <PARAM NAME=incremental VALUE="true"> 
    </APPLET> 
  <HR>
<A HREF="Test3.java">The source</A>
...

14.6.2 Embedding the CLASSPATH Parameters in the <APPLET> Tag

When running applets, the browser uses a CLASSPATH you supply in the ARCHIVE and CODEBASE parameters to the <APPLET> tag in the host *.html file.

The CODEBASE parameter sets the root directory where the Internet browser will look for your class files. If the classes are stored in the same directory as the HTML page calling the applet, you can omit the CODEBASE parameter entirely. Otherwise, use either an absolute or relative path from the HTML file to the location of the CODEBASE directory. Use forward slashes (/), not backslashes(\) to indicate directories.

The ARCHIVE parameter lists the locations and names of the JAR files that contain your program and its supporting library files, similar to the CLASSPATH used with applications. There are three important differences:

  • The names of the Java Archive files are separated by commas (,), not semicolons(;).

  • If the Java Archive files are in subdirectories of the CODEBASE, use forward slashes (/), not backslashes(\), to indicate directories.

  • Due to the limitations enforced by the Java security model for applets, classes referenced by your ARCHIVE parameter can only be located in subdirectories of the CODEBASE directory. This means that if you attempt to set the location of an archive file using a parent directory (./) you will receive a security violation error.

14.7 Debugging Java Programs

The Debugger provides you with a number of features to investigate your code, and identify and fix problem areas. Two types of debugging are available to analyze your code - local and remote.

A local debugging session is started by setting breakpoints in source files, and then starting the debugger. When debugging an application such as a servlet in JDeveloper, you have complete control over the execution flow and can view and modify values of variables. You can also investigate application performance by monitoring class instance counts and memory usage. JDeveloper will follow calls from your application into other source files, or generate stub classes for source files that are not available.

Remote debugging requires two JDeveloper processes: a debugger and a debuggee which may reside on a different platform. Once the debuggee process is launched and the debugger process is attached to it, remote debugging is similar to local debugging.

Table 14-1 contains the special-purpose debugging windows that enable you to efficiently identify the problematic areas in your code.

Table 14-1 Debugging Windows

Window Description

Breakpoint

Displays the breakpoints for the current workspace and project. For more information, see Section 14.8.1, "How to Use the Breakpoints Window."

Smart Data

Displays the data which is being used in the code that you are stepping through. For more information, see Section 14.8.2, "How to Use the Smart Data Window."

Data

Displays the arguments and local variables for the current context. Note that Full Debug Info must be selected in the Compiler page of the Project Properties dialog. For more information, see Section 14.8.3, "How to Use the Data Window."

Watches

Displays the watches created for fields or variables. A watch evaluates an expression according to the current context. If you move to a new context, the expression is reevaluated for the new context. For more information, Section 14.8.4, "How to Use the Watches Window."

Inspector

Displays a single data item in its own floating window. An inspector evaluates an expression according to the current context. For more information, see Section 14.8.5, "How to Use the Inspector Window."

Heap

Displays information about the heap in the program you are debugging and helps you to detect memory leaks in your program. For more information, see Section 14.8.6, "How to Use the Heap Window."

Stack

Displays the call stack for the current thread. For more information, see Section 14.8.7, "Using the Stack Window."

Classes

Displays information about the classes which have been loaded as your application runs, including the name and package of each class. The debugger can also display the number of live instances of each class and the amount of memory being consumed by those instances. For more information, Section 14.8.8, "How to Use the Classes Window."

Monitors

Displays information for active monitors in your application, as well as information about the status of threads accessing those monitors. This window is useful for examining deadlocks and other thread synchronization problems. For more information, see Section 14.8.9, "How to Use the Monitors Window."

Threads

Displays the threads and the thread groups, highlights the current thread, and shows the name, status, priority, and group of each thread. For more information, see Section 14.8.10, "How to Use the Threads Window."


14.7.1 Understanding the Debugger Icons

Table 14-2 contains the various JDeveloper debugger and runner icons. These icons are available from areas in the JDeveloper user interface, including the Debugger window and the Log window.

Table 14-2 Debugger and Runner icons

Icon Name Description
Array

Array

Represents an array class in any JDeveloper data-related window.

Add Breakpoint

Add Breakpoint

Represents the Breakpoint toolbar button used to create a breakpoint.

Breakpoint menu

Breakpoints menu

Represents the View > Debugger > Breakpoints menu option or the tab icon for the Breakpoints window.

Class

Class

Represents the View > Debugger > Classes menu option, the tab icon for the Classes window and a class in the Classes window (grayed if the class has tracing disabled).

Class without Line Number Tables

Class Without Line Number Tables

Appears in the Classes window. Represents a class which does not have line number tables (obfuscated class)

Current Execution Point

Current Execution Point

Represents the current execution point shown in the source editor margin which you can display by choosing the Run > Show Execution Point menu option.

Current Thread

Current Thread

Represents the current thread in the Threads window.

Data

Data

Represents the View > Debugger > Data menu option; the View > Debugger > Smart Data menu option; and the tab icon for the Data window and Smart Data window.

Debug (Shift + F9)

Debug (Shift + F9)

Represents the Run > Debug <project_name> menu option; the debug toolbar button, a debugging process contained in the processes folder in the Processes window, a log page for a debugging process, the debug layout, and the Remote Debugging and Profiling Project Wizard

Debug Listener node

Debug Listener Node

Represents a debug listener node in the Processes window.

Disabled Breakpoint

Disabled Breakpoint

Represents a disabled breakpoint in the source editor margin and a disabled breakpoint in the Breakpoints window. The icon also represents the Breakpoint toolbar button to disable a breakpoint

Delete breakpoint

Delete Breakpoint

Represents the Breakpoint toolbar button to remove a breakpoint.

Edit Breakpoint

Edit Breakpoint

Represents the Breakpoint Toolbar button, which you can use to edit the selected breakpoint

Garbage Collection

Garbage Collection

Represents the Run > Garbage Collection menu option and the Garbage Collection toolbar button which you can click

Interface

Interface

Represents an interface in the Classes window

Heap

Heap

Represents the View > Debugger > Heap menu option and the tab icon for the Heap window

Heap Folder

Heap Folder

Represents a folder in the Heap window.

Method

Method

Represents a method in the Stack window

Monitors

Monitors

Represents the View > Debugger > Monitors menu option and the tab icon for the Monitors window.

Object

Object

Represents an object in any JDeveloper data-related window

Package

Package

Represents a package in the Classes window (grayed if the package has tracing disabled)

Pause

Pause

Represents the Run > Pause menu option and the Pause toolbar button which you can click.

Primative

Primitive

Represents a primitive item in any JDeveloper data-related window.

Resume

Resume

Represents the Run > Resume menu option and the Resume toolbar button which you can click.

Run

Run

Represents a running process in the Processes window, in a log page for a running process, and in the toolbar to run the selected node.

Run to Cursor (F4)

Run to Cursor (F4)

Represents the Run > Run to Cursor menu option. Lets you run to a specified location and execute the code until it reaches that location

Stack

Stack

Represents the View > Debugger > Stack menu option and the tab icon for the Stack window.

Stack Folder

Stack Folder

Represents the static folder in the Data window

Step to End of Method

Step to End of Method

Represents the Run > Step to End of Method menu option and the Step to End of Method toolbar button which you can click.

Step Into (F7)

Step Into (F7)

Represents the Run > Step Into menu option and the Step Into toolbar button which you can click.

Step Out

Step Out (Shift + F7)

Represents the Run > Step > Out menu option and the Step Out toolbar button which you can click.

Step Over

Step Over

Represents the Run > Step Over menu option and the Step Over toolbar button which you can click.

Terminate

Terminate

Represents the Terminate toolbar button which you can click to stop debugging your application.

Thread

Thread

Represents the View > Debugger > Thread menu option and the tab icon for the Thread window.

Threads

Threads

Represents the View > Debugger > Threads menu option and the tab icon for the Threads window.

Thread Group

Thread Group

Represents a thread group in the Threads window.

Unverified Breakpoint

Unverified Breakpoint

Represents an unverified breakpoint in the source editor margin, and an unverified breakpoint in the Breakpoints window

Unverified Breakpoint

Verified Breakpoint

Represents the verified breakpoint in the source editor margin.


14.7.2 Debugging an Application Deployed to Integrated WebLogic Server

When debugging an application deployed to integrated WebLogic Server, you can make changes to files and they will be reflected in the running application without you having to stop and redeploy the application.

  • Modify Jsf files

    Save and refresh the browser if you are currently viewing the page that you modified. Or navigate to the page if you were not on it. The page will reflect the changes you just made.

  • Save and recompile them. You can see the changes the next time the altered code is executed without having to re-start the application.

If you are stopped at a break point, you can:

  • Modify the class you are currently stopped in including the method that you are currently stopped in.

  • Right click in the editor and rebuild the individual class.

  • Select the Stack tab (by default grouped with the Structure tab under the Applications window). At the top of the stack you will see that the method you are stopped in is obsoleted.

  • Right click on the previous method and select the Pop back to here menu item. JDev will re-position the cursor to the code that invoked the obsolete method.

When you restart execution, the changes you made to the class or method will be reflected.

Note:

you can only modify code that is private to the class. Review the console output after re-compiling. The output will make it clear whether of not the recompiled code is available for run-time.

14.7.3 How to Debug a Project in JDeveloper

Your code must be compiled with debugging information before you can make use of some of the debugger features such as viewing arguments and local variables in the Data window. This saves time when debugging and testing an application.

To set breakpoints and step through your code:

  1. In a source editor, set a breakpoint on an executable statement by clicking in the margin to the left of the statement. For more information, see Section 14.9, "Managing Breakpoints."

    The unverified breakpoints icon appears in the left margin.

  2. Select Run > Debug [filename.java].

    The class runs and stops at the first breakpoint.

  3. From the toolbar, click Step Into to trace into a method call or click Step Over to step over a method call.

  4. Look in the Stack window to examine the sequence of method calls that brought your program to its current state.

  5. Double-click a method to display the associated source code in the source editor.

  6. In the Smart Data and Data windows, examine the arguments and variables.

  7. Display the Threads window to see the status of other threads in your program.

14.7.4 How to Edit and Recompile

The Java Hotswap functionality allows you to edit and recompile sources during a debug session, and the new code in the class files is 'hotswapped' in the debugger. You do not have to end the debug session explicitly. You can continue the debug session and your new code will be used the next time execution reaches that new code.

14.7.5 How to Debug ADF Components

JDeveloper allows you to debug with breakpoints using the ADF Declarative Debugger. If an error cannot be easily identified, you can use the ADF Declarative Debugger in JDeveloper to set breakpoints. When a breakpoint is reached, the execution of the application is paused and you can examine the data that the Oracle ADF binding container has to work with, and compare it to what you expect the data to be. Depending on the types of breakpoints, you may be able to use the step functions to move from one breakpoint to another.

Table 14-3 contains the windows that JDeveloper provides for debugging ADF components.

Table 14-3 ADF Component Debugging Windows

Window Description

ADF Data

Displays relevant data based on the selection in the ADF Structure window when the application is paused at a breakpoint. For more information, see Section 14.8.3, "How to Use the Data Window."

EL Evaluator

Evaluates EL Expressions when a breakpoint is reached during a debugging session. Only JSF applications can use the EL Evaluator.

ADF Structure

Displays a tree structure of the ADF runtime objects and their relationships when the application is stopped at a breakpoint. For more information, see Section 3.11.6, "Structure Window."


You can control what type of information is displayed in each of the debugger windows. To see what options are available in each window such as which columns to display, right-click in a window and choose Preferences from the context menu. Or, you can choose Tools > Preferences from the main menu and expand the Debugger node to display a preferences page for each debugger window. You can also save the debug information as text or HTML output file. For more information. see Section 14.7.9, "How to Export Debug Information to a File."

To use the JDeveloper debugger to control the execution of a program:

  1. Run to a breakpoint. For more information, see Section 14.9, "Managing Breakpoints."

    A breakpoint is a trigger in a program that, when reached, pauses program execution. This allows you to examine the values of some or all of the program variables. When your program execution encounters a breakpoint, the program pauses, and the debugger displays the line containing the breakpoint in the source editor.

  2. Step into a method and execute a single program statement at a time. For more information, see Section 14.7.15, "How to Step Into a Method."

    If the execution point is located on a call to a method, the Step Into command steps into that method and places the execution point on the method's first statement.

  3. Step over a method. For more information, see Section 14.7.16, "How to Step Over a Method."

    If you issue the Step Over command when the execution point is located on a method call, the debugger runs that method without stopping, instead of stepping into it. Program statements are executed one at a time.

  4. Run to the cursor location. For more information, see Section 14.7.20, "How to Run to the Cursor Location."

    This allows you to go to a particular location in the program without having to single step or set a breakpoint.

  5. Pause and resume the debugger. For more information, see Section 14.7.21, "How to Pause and Resume the Debugger."

    You can pause your program when the program is running in the debugger. You can then use the debugger to examine the state of your program with respect to this program location. When you have finished examining that part of the program, you can then continue running the program.

  6. Terminate a debugging session. For more information, see Section 14.7.22, "How to Terminate a Debugging Session.".

When finished, you can modify program values as a way to test hypothetical bug fixes during a program run. If you find that a modification fixes a program error, exit the debugging session, fix your program code, and recompile the program to make the fix permanent.

14.7.6 How to Configure a Project for Debugging

JDeveloper allows you to control how your program is debugged, including enabling and disabling packages and classes and configuring remote debugging options.

To configure debugger and remote debugger options in JDeveloper:

  1. Choose Application > Default Project Properties (to set preferences that apply to all projects)

  2. Choose Application > Project Properties (to set preferences that apply only to the current project).

  3. Select the Run/Debug node.

  4. Select a run configuration. For more information, see Section 14.3, "Configuring a Project for Running."

  5. Click Edit.

  6. Select Tool Settings > Debugger.

  7. Set the options on the Debugger and Remote pages.

  8. Click OK when finished.

14.7.7 How to Set the Debugger Start Options

By setting up the debugger start option, you are specifying how you would like the debugger to behave when you start a new debugging session. Specifically, decide if you want the debugger to execute until a breakpoint is reached, or if you want the debugger to stop when it reaches your project's code (for example, at the beginning of your application's main method).

To set the debugger start options:

  1. From the main menu choose Tools > Preferences > Debugger.

  2. Select a Start Debugging option.

    Table 14-4 Start Debugging Options

    Option Description

    Run Until a Breakpoint Occurs

    When you start debugging, the debugger will let the program you are debugging execute until a breakpoint is reached.

    Step Over

    When you start debugging, the debugger will let the program you are debugging execute until a method in a tracing-enabled class is reached, but it will not stop in a class static initializer method.

    Step Into

    When you start debugging, the debugger will let the program you are debugging execute until any method, including a class static initializer method, is reached.


Note:

You can press F7 to display a choice of methods you want to step into. When there are multiple methods, they are highlighted when you press F7. You can click the one you want to step into.

This feature is useful there can be multiple method calls on a line, and you may be interested in a specific one that might not be the first one encountered.

14.7.8 How to Launch the Debugger

You must build the project before debugging it. The project is built using options you specify on the Compiler page of the Project Properties.

To build a project and start the debugger:

  1. In the Applications window, select the project.

  2. Right-click and choose Project Properties > Compiler.

  3. If not already enabled, select Full Debug Info.

  4. Click OK to close the dialog.

  5. Use one of the following methods to start the debugger:

    • To start the debugger using the current run configuration, from the main menu choose Run > Debug <target>.

    • To start the debugger using your choice of run configuration, select the dropdown menu beside the Debug icon on the toolbar and click the required run configuration name.

If the project builds successfully, the debugger starts.

14.7.9 How to Export Debug Information to a File

You can export debug information generated by the JDeveloper debugger to either a text or HTML output file from within any of the debugger windows.

To export debug information to file:

  1. Start debugging by clicking Debug from the toolbar.

  2. Once the debugger has stopped at a breakpoint, locate the debugger window containing the information you would like to export.

  3. Right-click in a debugger window and choose Preferences from the context menu.

  4. In the appropriate Preferences - Debugger page below Columns, select which columns you want to show or hide in the debugger window and output file.

  5. Click OK to close the Preferences dialog.

  6. In the debugger window, right-click and choose Export.

  7. In the Export dialog, enter the name of the file. The output file is saved as a text file with tabs between columns and new lines between rows. To export to an HTML file, add the extension as.html or .htm (case-insensitive).

If the project builds successfully, the debugger starts.

14.7.10 Using the Source Editor When Debugging

When the debugger stops (for example, at a breakpoint after completing a step command, or when paused), the source file for the current class will open in the source editor and will be marked with the execution point, as shown in Figure 14-1.

Figure 14-1 Execution Point Icon

Execution Point

If JDeveloper cannot locate the source file for the class while debugging, the Source Not Found dialog is displayed prompting you for the source file location.

You can use the source editor to debug to:

  • Hover over a variable name to see its value.

  • Set a breakpoint, click in the source editor's margin.

  • Remove a breakpoint, click the breakpoint in the source editor's margin.

    Figure 14-2 Breakpoint Icon

    Breakpoint Icon

14.7.11 Using Context Menu Items

The debugger adds several menu items to the source editor's context menu, including those shown in Table 14-5.

Table 14-5 Debugger Context Menu Items

Item Function

Run to Cursor

Run to the current location of the cursor and execute the code until it reaches that location.

Watch (Ctrl+F5)

Add an expression to the Watches Window.

Inspect

Open up a floating Inspector window.

Step Into Method at Cursor

Executes Run to Cursor, and then steps into the method that the cursor is currently on.


14.7.12 Using Tooltips

The debugger displays tooltips in the source editor if you hover the mouse over the name of a data item. By default, the tooltip will show the name, value, and type of the data item; providing an easy way to quickly inspect a data item without adding it in Data window or Watches window. If the data item is an array or object, you can inspect children of the selected item deep in the object hierarchy. The tooltip displays 20 children data items, use the navigation buttons to view remaining data items.

The columns that display in the tooltip depend on the column settings that were enabled in the Tools > Preferences – Debugger – Tooltip page.

If the project builds successfully, the debugger starts.

14.7.13 Using Java Expressions in the Debugger

Java expressions are used in the Watches window, Inspector window, Breakpoint Conditions, and Breakpoint Log Expressions. You can specify a Java expression that you want the debugger to watch or inspect. The expression must be a legal Java expression that the debugger can evaluate. The debugger accepts Java expressions in the forms shown in Table 14-6.

Table 14-6 Java Expressions Accepted by Debugger

Java Expression Form

Simple variable name

rect

Field access

rect.width

Method call

myString.length()

Array element

myArray[3]

Array length

myArray.length

Comparison operation

rect.height == 100
myArray.length > 7

Arithmetic operation

rect.width * rect.height
x + y + z

Logical operation

frame1.enabled && frame1.visible

textField1.hasFocus || textField2.hasFocus

Instance of operator

<my_value> instanceof java.lang.String

Shift operator

x << 2

y >> 1

Binary Operator

keyEvent.modifiers & java.awt.event.InputEvent.CTRL_MASK

Question-colon operation

y>5 ? y*7 : y*4

Static field name

java.awt.Color.pink

Fully qualified class name

java.awt.Color


14.7.14 Moving Through Code While Debugging

The JDeveloper debugger lets you control the execution of your program; you can control whether your program executes a single line of code, an entire method, or an entire program block. By manually controlling when the program should run and when it should pause, you can quickly move over the sections that you know work correctly and concentrate on the sections that are causing problems. For more information, see Section 14.7.7, "How to Set the Debugger Start Options."

The debugger lets you control the execution of your program by:

  • Stepping Into a Method

  • Stepping Over a Method

  • Controlling Which Classes are Traced Into

  • Locating the Execution Point for a Thread

  • Running to the Cursor Location

  • Pausing and Resuming the Debugger

  • Terminating a Debugging Session

The Step Into and Step Over commands offer the simplest way of moving through your program code. While the two commands are very similar, they each offer a different way to control code execution.

The smallest increment by which you step through a program is a single line of code. Multiple program statements on one line of text are treated as a single line of code – you cannot individually debug multiple statements contained on a single line of text. The easiest approach is to put each statement on its own line. This also makes your code more readable and easier to maintain.

14.7.15 How to Step Into a Method

The Step Into command executes a single program statement at a time. If the execution point is located on a call to a method, the Step Into command steps into that method and places the execution point on the method's first statement.

The Step Into action will highlight methods on a line any time it is invoked on a line with multiple methods. The current execution point determines what line of code will the debugger step into. Moving the cursor does not alter the execution point or cause a different set of methods to become available to step into.

This feature is particularly useful when a selected outer method belongs to an interface and you do not know beforehand where the method that will actually get called is implemented.

If the execution point is located on the last statement of a method, choosing Step Into causes the debugger to return from the method, placing the execution point on the line of code that follows the call to the method you are returning from.

The term single stepping refers to using Step Into to run successively though the statements in your program code.

You can step into a method in any of the following ways:

  • Select Run > Step Into.

  • Press the F7 key.

  • Click the Step Into button from the toolbar.

    Figure 14-3 Step Into Button

    Step Into Icon

Note:

Step Into will only cause stepping on an already-started debugging process.

When you set the debugger to start by stepping into, the debugger will let the program you are debugging execute until a method in a tracing-enabled class is reached.

As you debug, you can step into some methods and step over others. If you are confident that a method is working properly, you can step over calls to that method, knowing that the method call will not cause an error. If you aren't sure that a method is well behaved, step into the method and check whether it is working properly.

14.7.16 How to Step Over a Method

The Step Over command, like Step Into, enables you to execute program statements one at a time. However, if you issue the Step Over command when the execution point is located on a method call, the debugger runs that method without stopping (instead of stepping into it), then positions the execution point on the statement that follows the method call.

If the execution point is located on the last statement of a method, choosing Step Over causes the debugger to return from the method, placing the execution point on the line of code that follows the call to the method you are returning from.

You can step into a method in any of the following ways:

  • Select Run > Step Over.

  • Press the F8 key.

  • Click the Step Over button on the toolbar.

    Figure 14-4 Step Over Button

    Step Over Button

Unlike previous releases of JDeveloper, you cannot start debugging by clicking the Step Over button. Step Over will cause stepping only on an already-started debugging process.

When you set it to start by stepping over, the debugger will let the program you are debugging execute until a method in a tracing-enabled class is reached, but it will not stop in class static initializer method.

As you debug, you can step into some methods and step over others. If you are confident that a method is working properly, you can step over calls to that method, knowing that the method call will not cause an error. If you aren't sure that a method is well behaved, step into the method and check whether it is working properly.

14.7.17 Controlling Which Classes Are Traced Into

Normally, you should set the tracing include and exclude lists in the project properties before you start debugging. However, if you need to change the tracing include and exclude lists, you can do so from the Classes window. Right-click in the Classes window and choose Tracing from the context menu. The Tracing dialog appears in which you can adjust the tracing include and exclude lists.

When you specify a package to be included or excluded from tracing, all descending classes within that package are included or excluded as well unless you've specified them individually.

To closely examine part of your program, you can enable tracing on only the files you want to step through in the debugger. For example, you usually don't want to step through classes that are in the J2SE library because you're not going to troubleshoot on them; you usually only want to trace into your own classes.

14.7.18 How to Step Through Behavior as Guided by Tracing Lists

If you exclude a class or package, and you instruct the debugger to step into that class, the debugger runs straight through that code without pausing. The debugger pauses at the next line of code in a class which has not been excluded. The tracing include and exclude lists are used for all step commands including Step Into, Step Over, Step Out, and so on. Using these lists does not prevent you from setting a breakpoint in a class which has been excluded. If the debugger stops at such a breakpoint, the step commands will be disabled. To enable tracing for a class, you can adjust the tracing include or exclude list by adding or removing a class or package:

To adjust the tracing include or exclude list:

  1. Right-click a project in the Applications window and choose Project Properties from the context menu.

  2. Select the Run/Debug node.

  3. Choose a run configuration and click Edit.

  4. In the Edit Run Configuration dialog select Tools Settings > Debugger.

  5. In the Tracing Classes and Packages to Include and Tracing Classes and Packages to Exclude fields, enter the name of the packages or classes you want to include or exclude in the appropriate field, separated by a semicolon (;). For example:

    oracle.xml;org.apache;org.omg;org.w3c;org.xml
    

    You can also click Edit to open the Tracing Classes and Packages to Include/Exclude dialog, then click Add or Remove. If you click Add, the Class and Package Browser dialog appears. If you click Remove, the selected class or package is removed from the appropriate tracing List. Navigate to the class or package you want to add and click OK. The class or package is added to the appropriate tracing list.

By leaving the include lists blank, you are actually specifying that you would like to enable tracing in all packages except for those specifically listed in the exclude list. For example:

include:
exclude:java;javax

14.7.19 How to Locate the Execution Point for a Thread

When you're debugging, the line of code that is the current execution point for the current thread is highlighted and the execution point icon appears in the left margin of the source editor.

The execution point marks the next line of source code to be executed by the debugger.

To find the current execution point:

  1. Choose Run > Find Execution Point from the main menu.

  2. Right-click a thread in the Threads window and choose Go To Source of Thread.

    The debugger displays the block of code containing the execution point in the source editor.

14.7.20 How to Run to the Cursor Location

When stepping through your application code in the debugger, you may want to run to a particular location without having to single step or set a breakpoint.

To run to a specific program location:

  1. In a source editor, position your text cursor on the line of code where you want the debugger to stop.

  2. Run to the cursor location in any of the following ways:

    • In the source editor, right-click and choose Run to Cursor.

    • Choose the Run > Run to Cursor option from the main menu.

    • Press the F4 key. The F4 key works unless you Operating System (OS) intercepts that key.

      Note:

      On ADC or SLC machines, F4 key is intercepted and never reaches the debugger.

Any of the following conditions may result:

  • When you run to the cursor, your program executes without stopping, until the execution reaches the location marked by the text cursor in the source editor.

  • If your program never actually executes the line of code where the text cursor is, the Run to Cursor command will cause your program to run until it encounters a breakpoint or when your program finishes.

14.7.21 How to Pause and Resume the Debugger

You can pause your program when the program is running in the debugger. You can then use the debugger to examine the state of your program with respect to this program location. When you have finished examining that part of the program, you can then continue running the program.

When you are using the debugger, your program can be in one of two possible states: running, or paused by the debugger. When your program is waiting for user input, it is still considered to be running. When your program is in the running mode, Pause is available. When your program is paused by the debugger, the available debugger buttons include Resume, Step Over, and Step Into.

You can pause the debugger in the following ways:

  • Choose Run > Pause from the main menu.

  • Click the Pause icon from the debugger toolbar.

    Figure 14-5 Pause Icon

    Pause Icon

Your program may be paused at a location for which there is no source available. In this case, the Source Not Found dialog displays, prompting you for the source file location or whether to generate stub files.

Also, your program may be paused at a location where tracing is disabled because the class is on the tracing exclude list. For example, your program may be paused in the java.lang.Object.wait method.

While the debugger is paused, you can force garbage collection to occur. The results of the garbage collection are immediately reflected in the Classes and the Heap window. This enables you to find memory leaks in your application.

To resume the debugger when it is paused, choose Run > Resume.

14.7.22 How to Terminate a Debugging Session

Sometimes while debugging, you will find it necessary to restart the program from the beginning. For example, you might need to restart the program if you step past the location of a bug.

To terminate the current debugging session:

  • Choose the Run > Terminate - <target> menu option, or

  • Click Terminate in the debugger toolbar.

Terminating a debugging session closes all debugger windows. However, this action does not delete any breakpoints or watches that you have set, which makes it easy to restart a debugging session.

14.7.23 How to View the Debugger Log

The Debugger log displays information about the debugging process. You can view the Debugger log at any time while the debuggee process is still active.

To view the Debugger log while the process is still active:

  • In the View menu, select Debugger and then select Log, or

  • In the Processes window, right-click the process and select View Log in the context menu.

14.7.24 How to Debug an Applet

JDeveloper allows you to control how your Applet program is debugged. For more information about running applets, see Section 14.6, "Running an Applet."

To debug an applet:

  1. In the Applications window, select the HTML file that contains the <APPLET> tag.

  2. Click Debug in the toolbar.

    The applet starts. The debugger will stop at breakpoints you have set in your applet source code.

14.8 Using the Debugger Windows

JDeveloper provides a number of special-purpose debugging windows to help you analyze your code and identify problem areas. You can open the debugger windows by choosing View > Debugger, then choosing a window from the menu, for example, Breakpoints.

14.8.1 How to Use the Breakpoints Window

Information about set breakpoints can be viewed in the Breakpoints window. For more information about this window including its context menu options, press F1 in the Breakpoints window.

To open the Breakpoints window to display a list of set breakpoints:

  • Choose View > Breakpoints from the main menu. The Breakpoints window appears.

14.8.2 How to Use the Smart Data Window

Unlike the Data window which displays all arguments, local variables, and static fields for the current method, the Smart Data window displays only the data that appears to be relevant to the source code that you are stepping through. Specifically, the debugger analyzes the source code near the execution point and finds the variables, fields, and expressions, that are used in the lines of code that you are stepping through.

For more information, see Section 14.7.19, "How to Locate the Execution Point for a Thread."

The Smart Data window also displays the current return value of a non-void method when you set a breakpoint in the method and issue a Step to End of Method command or Step Out command. The return value is not displayed for Step Over or Step Into commands.

By default, the debugger analyzes only one line of code for each location and analyzes up to two locations. You can adjust these settings in the Tools > Preferences - Debugger - Smart Data page which you can also access by right-clicking in the Smart Data window and choosing Preferences from the context menu.

To open the Smart Data window:

  1. Set a breakpoint in the Source Editor and start a debugging session.

  2. Click Debug from the toolbar.

  3. When the debugger hits a breakpoint, select View > Debugger > Smart Data.

14.8.3 How to Use the Data Window

You use the Data window to display information about variables in your program. In the current context, which is controlled by the selection in the Stack window. If you move to a new context, the Data window is updated to show the data for the new context. If the current class was compiled without debug information, you will not be able to see the local variables. The debugger analyzes the local variable memory locations in the stack frame to show you as much information as possible.

The Data window also displays the current return value of a non-void method when you set a breakpoint in the method and issue a Step to End of Method command or Step Out command. The return value is not displayed for Step Over or Step Into commands.

To open the Data window:

  1. Open source files in the Source Editor and set breakpoints.

  2. In the toolbar, click Debug.

  3. When the debugger pauses at a breakpoint, select Window > Debugger > Data from the main menu.

14.8.3.1 How to View Array Elements in the Data Window

You can set the number of elements in an array that you want to display in the Data Window.

To view array elements in Data window: 

  1. Start debugging the project and open Data window.

  2. Select the array in the Data window and expand to view its elements.

    If the array contains more than 20 elements, the Data window displays first 20 elements.

    • To view the next 20 entries, click Next.

    • To view the previous 20 entries, click Previous.

    • To view the first 20 entries, click First.

    • To view the last 20 entries, click Last.

    • To change the default display size of 20, select the array, right-click and select Adjust Range from the context menu, and enter the new value in the New Count field. Click OK when you are done.

14.8.4 How to Use the Watches Window

A watch enables you to monitor the changing values of variables or expressions as your program runs. After you enter a watch expression, the Watches window displays the current value of the expression. As your program runs, the value of the watch changes as your program updates the values of the variables in the watch expression.

A watch evaluates an expression according to the current context which is controlled by the selection in the Stack window. If you move to a new context, the expression is re-evaluated for the new context. If the execution point moves to a location where any of the variables in the watch expression are undefined, the entire watch expression becomes undefined. If the execution point returns to a location where the watch expression can be evaluated, the Watches window again displays the value of the watch expression.

14.8.4.1 How to Open the Watches Window

The Watches window displays the values for a watched program, based on breakpoints you have set in a source file.

To open the Watches window: 

  1. Open source files in the Source Editor and set breakpoints.

  2. Click Debug from the toolbar.

  3. When the debugger pauses at a breakpoint, select Window > Debugger > Watches from the main menu.

14.8.4.2 How to Add a Watch

There are multiple ways to add a watch.

To add a watch: 

  • Right-click an item in the Data window and choose Watch from the context menu.

  • Drag and drop variables, fields, and objects from the Data window to the Watches window.

  • Select text in the source editor, right-click, and choose Watch from the context menu.

14.8.4.3 How to Watch a Static Field

To watch a static field:

Enter the full name of the class followed by a period (.) and the name of the field. For example:

java.io.File.separator

To watch the current exception while stopped at an exception breakpoint, enter:

_throw

14.8.5 How to Use the Inspector Window

The Inspector window allows you to single out a selected variable, field or object, and display the same information that is available in the Watch or Data windows. For more information about this window, including its context menu options, press F1 in the Inspector window.

The Inspector window is slightly different from the other windows in that it floats by default, and you can have multiple instances of Inspector windows. Each Inspector window contains one data item. You can drag one Inspector window into another and dock them together.

To open the Inspector Window:

  1. Set at least one breakpoint in the Source Editor.

  2. Click Debug from the toolbar.

  3. When the debugger reaches a breakpoint, select a variable in the Source Editor, right-click, and choose Inspect.

    The floating Inspect window appears and contains the variable you selected. If you want to inspect something else, enter a new expression or variable in the text field, or select a previous one from the dropdown list.

    If no variable or expression is selected, the Inspect dialog appears pre-populated with the text under the cursor in the editor as the expression to inspect. Click OK to open the Inspector window.

The Inspector window will appear floating in the center of your screen, but you can dock the Inspector window with other windows. To prevent docking, press the Ctrl key while moving the window. An inspector evaluates an expression according to the current context of the Stack window. For more information, see Section 14.8.7, "Using the Stack Window."

If you move to a new context, the expression is reevaluated for the new context. If the execution point moves to a new location where any of the variables in the expression are undefined, the entire expression becomes undefined. If the execution point returns to a location where the expression can be evaluated, the inspector again displays the value of that expression.

14.8.6 How to Use the Heap Window

The Heap window displays information about the heap in the program you are debugging and helps you to detect memory leaks in your program. You can view all instances of a class as well as why an object has not been garbage collected.

Two types of folders display in the Heap window:

  • Class Folder

    Displays the name of the class and how many instances of the class exist in memory, and when expanded lists the specific instances and their addresses in the heap.

  • Reference Path Folder

    Contains all the "root" references which point, either directly or indirectly, to a specific object. Root references are static fields, stack variables, pinned objects. The garbage collector will not discard an object if there are any root references. Expanding a root reference will show you the reference path from the root reference to the specified object.

To open and use the Heap window:

  1. Open source files in the Source Editor and set breakpoints.

  2. In the toolbar, click Debug.

  3. When the debugger hits the breakpoint, select Window > Debugger > Heap from the main menu.

  4. Right-click in the Heap window and choose Add New Type from the context menu. Alternatively, drag a class node from the Classes window into the Heap window. Or, right click on a class node in the Classes window and choose Display in Heap from the context menu. Information about the classes appears in the Heap window.

14.8.7 Using the Stack Window

The Stack window displays the call stack for the current thread. When you highlight a line in the Stack window, the Data window, Watches window, and all Inspector windows are updated to show data for the highlighted method.

14.8.7.1 How to Open the Stack Window

In the Stack window, you can highlight a line in the stack thread to update values in the Data, Watches, and Inspector windows.

To open the Stack window: 

  1. Open source files in the Source Editor and set breakpoints.

  2. Click Debug from the toolbar.

  3. When the debugger pauses at a breakpoint, from the main menu, select Window > Debugger > Stack.

14.8.7.2 How to View the Stack of a Tread

You can view the stack of a selected thread in the Stack window.

To view the stack of a thread: 

  1. Start debugging the project and open the Stack window.

  2. Select the thread from the dropdown list, above the columns.

    The Stack window immediately reflects the stack of the selected thread.

14.8.8 How to Use the Classes Window

The Classes window displays which classes have been loaded and may also include useful information, such as the number of instances of a class. In conjunction with the Classes window, the debugger also includes a garbage collection tool when you want to force a run of the Java garbage collector. When you run the garbage collector, the impact is shown immediately in the Classes window. You can only force a run of the garbage collector when you are using a virtual machine that allows the debugger to do so.

To open the Classes window:

  1. Set a breakpoint in the Source Editor and start a debugging session.

  2. When the debugger hits a breakpoint, select Window > Debugger > Classes.

    The Classes window displays all the classes that are currently loaded, how many instances of that class are being used, and how much memory that number of instances requires.

14.8.8.1 How to Change the View Order

You can change the order in which items in each column of the Classes Window displays.

To change the ascending or descending view order: 

  • Click at the top of a column to change the sort order. You can sort by:

    • Name

    • Count

    • Memory

    • File

If the Show Packages check box is selected, by default the classes display in a tree structure, where each branch represents a package. Also, the icon and entry next to each class or package indicates whether the class is included or excluded from tracing. The special icon shown in Figure 14-6 for a class without line number tables is used for classes to indicate that tracing is not possible because the class has been stripped or obfuscated.

Figure 14-6 Icon Indicating Tracing Is Not Possible

Icon Indicating Tracing Is Not Possible

In the Classes window, choose Preferences from the context menu to select which columns to view from the following available options:

  • Count

  • Memory

  • File

14.8.9 How to Use the Monitors Window

Java supports multithreading at the language level through the use of synchronization. Synchronization is the coordinating of activities and data access among multiple threads. The mechanism that Java uses to support synchronization is the monitor. The Monitors window displays status and control information for active monitors.

The Monitors window will also open automatically if the debugger is in a deadlock state.

To open the Monitors window:

  1. Open source files in the Source Editor and set breakpoints.

  2. In the toolbar, click the Debug icon.

  3. When the debugger stops at the breakpoint, select Window > Debugger > Monitors.

14.8.10 How to Use the Threads Window

The Threads window displays the names and status of all the threads and thread groups in your program. The columns that display in this window depend on those column settings that are enabled in the Tools > Preferences > Debugger > Threads page or by choosing Preferences from the Threads window context menu options which you can access by right-clicking in the Threads window

To open the Threads window:

  1. Open source files in the Source Editor and set breakpoints.

  2. Click Debug from the toolbar.

  3. When the debugger stops at a breakpoint, choose Window > Debugger > Threads from the main menu.

    The step commands including Step Over, Step Into, and Set Next Statement apply to the current thread. To select a different thread, right-click a thread and choose Select Thread from the context menu.

    When you highlight a thread in the Threads window, the Stack window is automatically updated to show the stack for the highlighted thread.

14.8.11 How to Set Preferences for the Debugger Windows

You can choose to customize various debugger window settings including the column resize mode and other options you want to display.

Tip:

If the debugger has trouble connecting to the debuggee (the program you are debugging), try increasing the connection retry setting.

To set any of the Debugger window preferences:

  1. Choose Tools > Preferences > Debugger.

    The debugging panel appears with customizable fields.

  2. Make your selections from the fields and options provided.

  3. To set any options for a specific debugger window, expand the Debugger node and click the appropriate window node. For example, if you want to change the columns displayed in the Smart Data window, click Smart Data.

  4. Edit any of the available options as desired.

  5. Click OK when you are done.

14.8.12 How to Specify Which Columns Display in the Window

You can choose which columns display in each of the debugger windows. *

To specify which columns display in the window:

  • Right-click in the window and choose Preferences from the context menu. Under Columns, select the columns you want to be displayed in the Breakpoints window.

  • Or, in the window, right-click on the columns heading and select column names.

14.9 Managing Breakpoints

A breakpoint is a trigger in a program that, when reached, pauses program execution allowing you to examine the values of some or all of the program variables. By setting breakpoints in potential problem areas of your source code, you can run your program until its execution reaches a location you want to debug. When your program execution encounters a breakpoint, the program pauses, and the debugger displays the line containing the breakpoint in the source editor. You can then use the debugger to view the state of your program. Breakpoints are flexible in that they can be set before you begin a program run or at any time while you are debugging. Figure 14-7 displays an example breakpoint in a Java Application source file.

Figure 14-7 Breakpoint in Source Editor

Breakpoint in Source Editor

Breakpoints set on comment lines, blank lines, declarations, and other non-executable lines of code are invalid and will not be verified by the debugger.

The JDeveloper debugger supports a number of different types of breakpoints:

  • Source breakpoints

  • Exception breakpoints

  • Method breakpoints

  • Class breakpoints

  • File breakpoints

  • Deadlock breakpoints

Deadlock breakpoints are useful in situations when you find it difficult to locate the source of the deadlock. When a deadlock breakpoint is encountered, the debugger halts. The deadlock breakpoint is automatically enabled when you start debugging.

Information about set breakpoints can be viewed in the Breakpoints window.

14.9.1 Understanding Verified and Unverified Breakpoints

While debugging, you can place a breakpoint to the left of any line of code in the source editor. However, for a breakpoint to be valid, it must be set on an executable line of code. Before a method is first executed, the debugger verifies all valid breakpoints in the method. Breakpoints set on comment lines, blank lines, declarations, and other non-executable lines of code are invalid and will not be verified by the debugger.

When a breakpoint has been verified as valid, the icon displayed in the source editor margin and in the Breakpoints window changes to the icon shown in Figure 14-8.

Figure 14-8 Verified Breakpoint Icon

Verified Breakpoint

14.9.2 Understanding Deadlocks

A deadlock occurs when one or more threads in your program are blocked from gaining access to a resource or waiting on a condition that cannot be satisfied. A common deadlock in Java is a monitor block cycle deadlock.

A monitor block cycle deadlock occurs when two or more threads are unable to proceed because each is waiting to enter synchronized code that one of the others has already entered.

Example 14-2 shows a typical Java synchronization deadlock.

Example 14-2 Java Synchronization Deadlock

synchronized (a) 
 {
 ...
 synchronized (b)  {
 ...
  }
  ...
 }

At the same time, thread 2 is executing the following code:

synchronized (b) 
{
...
  synchronized (a) 
  {
  ...
   }
   ...
 }  

A deadlock will occur if thread 1 enters the synchronized (a) as thread 2 enters the synchronized (b). Thread 1 will be blocked from entering synchronized (b) until thread 2 finishes the synchronized (b) and thread 2 will be blocked from entering synchronized (a) until thread 1 finishes the synchronized (a). A deadlock is also called a "deadly embrace." This example is for two threads but the same situation could occur for 3, 4, 5, and so on threads. The deadlock breakpoint can detect this type of deadlock.

Another kind of deadlock is where one thread calls the wait method on a particular object and no other threads call the notify method on that object. The most common cause of this kind of deadlock is timing. The notifying thread may have called notify before the waiting thread called wait. The important thing to know about calling wait is that even if notify was already called many times before, the wait method waits until notify is called again. Also, notify doesn't return any kind of error if there was no thread waiting. The deadlock breakpoint cannot detect this type of deadlock.

If you think your program is hanging, click Pause to pause your program in the debugger, and open the Monitors window. Perhaps you can see that one thread is waiting, investigate the code. If you can see that another thread probably called notify before the first thread called wait, there is a deadlock. This kind of deadlock is very hard to detect. You must know your code well in order to figure out which other thread should have called notify.

14.9.3 Understanding the Deadlock Breakpoint

The JDeveloper debugger sets a persistent deadlock breakpoint when it starts running. A deadlock breakpoint is useful in situations when you find it difficult to locate the source of the deadlock. When the debugger encounters a deadlock breakpoint, the debugger halts. It can detect a monitor block cycle deadlock as described above. The Monitors window can be useful when working with deadlocks.

The deadlock breakpoint has the following characteristics:

  • It is a persistent breakpoint that is created automatically when you use JDeveloper.

  • It cannot be deleted, but it can be disabled.

  • It pauses the debugger if a monitor block cycle deadlock is detected. A monitor block cycle deadlock occurs when two or more threads are unable to proceed because each is waiting to enter synchronized code that one of the others has already entered.

The JDeveloper debugger automatically creates a persistent deadlock breakpoint; this breakpoint will occur whenever a monitor block cycle is detected. You cannot delete a persistent breakpoint. You cannot create a new deadlock breakpoint, but you can edit the existing persistent deadlock breakpoint.

Not all Java Virtual Machines support deadlock detection; for example, the HotSpot VM does not support deadlock detection.

14.9.4 Understanding Grouped Breakpoints

Grouped breakpoints let you enable a set of breakpoints. When the debugger reaches a certain point in your code, you can instruct the debugger to enable a breakpoint or a group of breakpoints that was previously disabled.

For example, even though your code might be catching a NullPointerException, it may not be behaving correctly. In some cases, NullPointerExceptions occur more frequently than expected which causes the debugger to stop repeatedly for NullPointerExceptions, including those that are of no consequence to your code. This situation can be resolved by creating a breakpoint group, adding this breakpoint to the group, and disabling the breakpoint group so that the debugger does not stop at this breakpoint when debugging.

Next, you can create a source breakpoint in some code that you know is executed just before the problematic NullPointerException is thrown. You can set the actions for this source breakpoint so that when the source breakpoint occurs, it will automatically enable the breakpoint group which contains the exception breakpoint.

14.9.5 How to Edit Breakpoint Options

JDeveloper allows you to edit the options of a breakpoint after you have added it in the source code. From the Edit Breakpoint dialog, you can:

  • Set a breakpoint option.

  • Set the threads to which the breakpoint will apply.

  • Set a pass count for the breakpoint.

  • Put the breakpoint in a breakpoint group.

  • Choose what actions the debugger will take when the breakpoint occurs.

To view and modify the options of a breakpoint:

  1. If the Breakpoints window is not open, select View > Breakpoints from the main menu.

  2. In the Breakpoints window, select a breakpoint.

  3. Right-click and choose Edit, or click the Edit icon on the Breakpoint toolbar.

    The Edit Breakpoint dialog appears with a Definition tab, a Conditions tab, and an Actions tab.

  4. Make any necessary changes to the breakpoint options.

  5. To accept the changes, click OK.

14.9.6 Editing a Breakpoint

You can right-click to edit a breakpoint located in the source editor. The Edit Breakpoint dialog shown in Figure 14-9 displays, where you can specify the definition of the breakpoint. In the dialog, you can edit some of the most important breakpoint attributes, such as enabled/disabled, condition and more.

  • Figure 14-9 Edit Breakpoints Dialog

    Edit Breakpoints dialog

You can also hover over a breakpoint in the source editor to display the dialog in Figure 14-9.

14.9.7 How to Set Source Breakpoints

A source breakpoint is a breakpoint set in the source code and is the default type of breakpoint.

To set a source breakpoint, do one of the following:

  • In the source editor, click in the left margin next to a line of executable code.

  • In the source editor, right-click in the left margin next to a line of code, then choose Toggle Breakpoint (F5).

  • Choose View > Breakpoints to display the Breakpoints window. Then, right-click anywhere in this window and choose Add Breakpoint from the context menu. From the submenu, select Source Breakpoint as the breakpoint type, then complete the package, source file name, and line number information in the dialog. The source filename should not include any directory information, but must include the extension of the file. For example:

    Application1.java or MyWebApp.jsp
    

    You'll probably want to set a least one breakpoint before you start debugging, but it is not necessary. While your program is running in the debugger, you can set a breakpoint. The program pauses when it reaches the breakpoint.

14.9.8 How to Control Breakpoint Behavior

You can control how the debugger behaves when a breakpoint occurs.

To control how the debugger behaves when a breakpoint occurs:

  1. In the Breakpoints window toolbar, click Add Breakpoint. Or, select a breakpoint and click Edit.

  2. Click the Actions tab in the New/Edit Breakpoint dialog. The Actions tab allows you to change these behaviors:

    • Halt execution (default)

    • Beep

    • Log breakpoint occurrence (enter a tag or an expression)

    • Enable a group of breakpoints

    • Disable a group of breakpoints

14.9.9 How to Delete a Breakpoint

When you no longer need to examine the code at a breakpoint location, you can delete the breakpoint. You can delete breakpoints either using the source editor or in the Breakpoints window.

To delete a breakpoint, do one of the following:

  • In the left margin of the source editor, click the breakpoint you want to delete.

  • In the left margin of the source editor, right-click the breakpoint you want to delete, and choose Toggle Breakpoint.

  • In the source editor, place the cursor in the line of code containing the breakpoint, and press F5.

  • To delete all currently set breakpoints, right-click in the Breakpoints window and select Delete All.

  • Select the breakpoint in the Breakpoints window and click Delete Breakpoint on the toolbar.

Caution:

You cannot undelete a breakpoint.

14.9.9.1 How to Disable a Breakpoint

When you disable a breakpoint, all the breakpoint settings remain defined, but the breakpoint is not triggered when your program is run; your program will not stop on a disabled breakpoint. Disabling a breakpoint is useful if you have defined a breakpoint that you don't need to use now, but might need to use at a later time.

To disable a breakpoint, do one of the following:

  • In the source editor, right-click the breakpoint symbol in the left margin and choose Disable Breakpoint.

  • In the Breakpoints window (Window > Debugger > Breakpoints) right-click the breakpoint you want to disable and choose Disable.

  • To disable a group of breakpoints in the Breakpoints window, select the group that you want to disable, right-click and choose Disable Group.

    You can also disable breakpoints from the Breakpoint toolbar. Select the breakpoint or breakpoint group, and click Disable on the toolbar.

  • To disable all current breakpoints, right-click in the Breakpoints window, and choose Disable All from the context menu.

14.9.9.2 How to Enable a Breakpoint

You can reenable a disabled breakpoint.

To reenable a disabled breakpoint:

  • To enable a breakpoint that is disabled, right-click the disabled breakpoint symbol (or entry in the Breakpoints window), and choose Enable.

  • To enable all breakpoints that have been set, right-click in the Breakpoints window, and choose Enable All.

  • To enable a group of breakpoints, right-click a breakpoint group in the Breakpoints window, and choose Enable Group.

    You can also enable breakpoints from the Breakpoint toolbar. Select the breakpoint or breakpoint group, and click Enable on the toolbar.

14.9.10 How to Set Instance Breakpoints

Breakpoints typically have effect whenever they are reached. An instance breakpoint is associated with a specific instance of the class that defines the method where the breakpoint appears.

An instance breakpoint is a source breakpoint that has been associated with an instance filter that identifies the selected instances. Instance breakpoints do not persist between runs of the debugger. Instance filters are shown in the Instance Filters column of the Breakpoints window.

To set an instance breakpoint:

  1. Set the source breakpoint that you will convert to an instance breakpoint. It must be in a method of the instance's class. For more information, see Section 14.9.7, "How to Set Source Breakpoints.".

  2. Set a second breakpoint at some point where the desired instance will be accessible.

  3. Define the instance filter:

    • Start or resume the debugger.

    • When the debugger stops at the second breakpoint, find the desired instance in the Data window, Smart Data window, or Watches window.

    • Right-click the instance, choose Instance Filters, and choose the source breakpoint that is to become an instance breakpoint.

      Repeat for other instances you want to track.

  4. Resume the debugger.

    The debugger will stop at the instance breakpoint only for the selected instances.

14.9.11 How to Set Exception Breakpoints

Breakpoints are typically attached to a particular line of code; they pause the debugger when a particular line of code is about to be executed. In addition, you can set a breakpoint to be activated when a certain type of exception is thrown. Exception breakpoints are not associated with a particular line of code.

To set an exception breakpoint:

  1. In the Breakpoints window, click Add Breakpoint on the Breakpoint toolbar. From the submenu, choose Exception Breakpoint.

    The Create Exception Breakpoint dialog appears.

  2. In the Definition tab, enter or choose the name of an exception class.

  3. If desired, select or clear the Break for Caught Exceptions or Break for Uncaught Exceptions checkboxes. Both checkboxes are selected by default.

  4. Click OK.

The debugger will now pause if an exception of the specified type is thrown.

By default, the debugger automatically creates a persistent exception breakpoint for uncaught throws for java.lang.Throwable. This breakpoint will occur whenever an uncaught exception is thrown. You cannot delete a persistent breakpoint, although you can disable it.

14.9.12 How to Make a Breakpoint Conditional

When you make a breakpoint conditional, the debugger pauses when a certain condition is met. When a breakpoint is first set, the debugger pauses the program execution each time the breakpoint is encountered. However, using the Edit Breakpoints dialog, you can customize breakpoints so that they are activated only in certain conditions.

The Conditions tab in the Edit Breakpoint dialog is where you enter an expression that is evaluated each time the debugger encounters the breakpoint while executing the program. If the expression evaluates to true, then the breakpoint pauses the program. If a breakpoint condition cannot be evaluated, the debugger will stop at the location as if it was an unconditional breakpoint.

When the debugger stops at a line with a conditional breakpoint, a ghost window appears next to the breakpoint icon showing the breakpoint condition. If the debugger stopped because the condition was true, the condition is shown with a green checkmark icon; if it stopped because the condition could not be evaluated, the condition will be shown with a question mark icon.

For example, suppose you want a breakpoint to pause on a line of code only when the variable mediumCount is greater than 10.

To set a breakpoint condition:

  1. Set a breakpoint on a line of code by clicking to the left of the line in the source editor.

  2. Open the Breakpoints window by choosing View > Debugger > Breakpoints.

  3. In the Breakpoints window, right-click the breakpoint you just set and choose Edit.

  4. In the Edit Breakpoint dialog, click Conditions.

  5. Enter an expression in the Condition field, for example, mediumCount > 1

  6. Click OK.

You can enter any valid Java language expression in the Edit Breakpoint dialog, but all symbols in the expression must be accessible from the breakpoint's location, and the expression cannot contain any method calls. For an exception breakpoint, you may want to use the exception object in your condition by using _throw.

You can also right-click a breakpoint located in the source editor to set conditions. Or, with your mouse cursor, hover over a breakpoint icon in the gutter of an editor window. For more information, see Section 14.9.6, "Editing a Breakpoint.".

14.9.13 Using Pass Count Breakpoints

The Pass Count field specifies the number of times that a breakpoint must be passed for the breakpoint to be activated. Pass counts are useful when you think that a loop is failing on the nth iteration. The debugger pauses the program the nth time that the breakpoint is encountered during the program run. The default value is 1.

If the Pass Count column is shown in the Breakpoints window, you can see the pass count value decrement each time the breakpoint line of code is encountered during the program execution. If the pass count equals 1 when the breakpoint line is encountered, the breakpoint is activated, and the program pauses at that line.

When pass counts are used together with breakpoint conditions, the breakpoint pauses the program execution the nth time that the condition is true; the condition must be true for the pass count to be decremented.

14.9.14 How to Examine Breakpoints with the Breakpoints Window

To see the list of breakpoints, choose Window > Debugger > Breakpoints from the main menu. Breakpoints that have been verified as valid by the debugger are indicated by the icon shown in Figure 14-8. You can use the Breakpoints window to quickly find the breakpoint location in your source code.

To use the Breakpoints window to locate a breakpoint in the source editor:

  1. In the Breakpoints window, select a breakpoint.

  2. Right-click and choose Go to Source from the context menu.

14.9.15 How to Manage Breakpoint Groups

You can enable or disable several breakpoints with a single action, by creating a breakpoint group and putting breakpoints into it. Once you've created a breakpoint group, you can enable, disable, or remove it like a single breakpoint.

14.9.15.1 How to Create a Breakpoint Group

You create a breakpoint group by first creating a breakpoint, then editing it to create a breakpoint group. This enables all the breakpoints contained in the selected group. When a breakpoint is enabled, it means that the conditions and actions are executed when the breakpoint is encountered.

To create a breakpoint group: 

  1. In the Breakpoints window, right-click a breakpoint and choose Edit from the context menu.

    The Edit Breakpoint dialog appears.

  2. In the Breakpoint Group Name field, enter a group name for this breakpoint.

  3. Click OK.

    A new group is created in the Breakpoints window, and is indicated by a folder icon. The breakpoint you just edited is automatically put in the new group.

14.9.15.2 How to Move a Breakpoint into a Breakpoint Group

To move a breakpoint, you can either drag-and-drop it into the breakpoint group, or follow these steps.

To move a breakpoint into a breakpoint group: 

  1. In the Breakpoints window, right-click a breakpoint and choose Edit from the context menu.

    The Edit Breakpoint dialog appears.

  2. From the Breakpoint Group Name field, select a breakpoint group from the dropdown list, or enter a new group name.

  3. Click OK.

    The breakpoint is added into the specified group.

14.9.15.3 Enabling Disabling or Removing a Breakpoint Group

To enable, disable, or remove a breakpoint group, in the Breakpoints window, right-click a breakpoints group, and choose Enable Group, Disable Group, or Delete Group from the context menu.

You can also enable or disable a group from the Breakpoint toolbar. With the group name selected in Breakpoints window, click the Enable or Disable icon on the toolbar. All the breakpoints of the selected group will be enabled or disabled.

14.10 Examining Program State in Debugger Windows

Even though you can view your program by running and stepping through it, you usually need to examine the values of program variables to uncover bugs. For example, it is helpful to know the value of the index variable as you step though a loop, or the values of the parameters passed in a method call. When your program is paused in the debugger, you can examine the values of variables, arguments, fields, and array items.

14.10.1 How to Inspect and Modify Data Elements

You can inspect and change the values of data items using the Data, Smart Data, Inspector, or Watches windows during the course of your debugging sessions.

JDeveloper also allows you to inspect a data item without adding it in Data window. When the debugger has stopped at a breakpoint in the Source Editor, hover the mouse over a data item to view the its name, value, and type. If the data item is an object or an array, you can inspect children of the selected item deep in the object hierarchy.

14.10.1.1 How to Inspect a Data Item

When you inspect a data item, you evaluate it with different expressions while your debugging session is running. You can then modify program data values as a way to test hypothetical bug fixes during a program run. If you find that a modification fixes a program error, you can exit the debugging session, fix your program code accordingly, and recompile the program to make the fix permanent.

To inspect a data item: 

  1. Open the Data window while the debugger is stopped at a breakpoint.

  2. Right-click an item in the Data window and choose Inspect from the context menu.

    The floating Inspector window opens displaying the item's name, value, and other related information. The columns which display in this window depend on those column settings that were enabled in the Tools > Preferences - Debugger - Inspector page. For more information, see Section 14.8.5, "How to Use the Inspector Window."

  3. To evaluate the item for an expression, choose Edit Expression from the context menu.

    You can also add a watch expression or further inspect the data item.

  4. When you are done, close the Inspector window.

14.10.1.2 How to Modify the Value of a Variable

You can modify program data values during a debugging session as a way to test hypothetical bug fixes during a program run. If you find that a modification fixes a program error, you can exit the debugging session, fix your program code accordingly, and recompile the program to make the fix permanent.

When you modify the value of a variable, the modification is effective for that specific program run only; the changes you make through the Data or Watches windows do not affect your program source code or the compiled program. To make your change permanent, you must modify your program source code in the source editor, then recompile your program.

The new value needs to be type-compatible with the variable you want to assign it to. A good rule of thumb is that if the assignment would cause a compile-time or run-time error, it is not a legal modification value.

To modify the value of a variable in the Data window: 

  1. Open the Data window while the debugger is stopped at a breakpoint.

  2. Right-click an item in the Data window and choose Modify Value from the context menu.

    The Modify Value dialog appears with the selected item's name and its current value.

  3. Enter a new value for the item.

    • If you are modifying a primitive value, you can enter a new value.

    • If you are modifying a reference pointer (other than a string), you can enter the memory address of an existing object or array.

    • If you are modifying a string, you can enter either a new string value or the memory address of an existing string.

  4. Click OK to change the value for the item and to close the dialog.

    The new value appears in the Data, Smart Data, Inspector, or Watches windows.

14.10.2 How to Set Expression Watches

A watch enables you to monitor the changing values of variables or expressions as your program runs. After you enter a watch expression, the Watch window displays the current value of the expression. As your program runs, the value of the watch changes as your program updates the values of the variables in the watch expression.

A watch evaluates an expression according to the current context which is controlled by the selection in the Stack window. If you move to a new context, the expression is reevaluated for the new context. If the execution point moves to a location where any of the variables in the watch expression are undefined, the entire watch expression becomes undefined. If the execution point returns to a location where the watch expression can be evaluated, the Watches window again displays the value of the watch expression.

To open the Watches window, choose Window > Debugger > Watches from the main menu.

You can also add a watch in one of the following ways:

  • Select a data item in the Data window. Then right-click, and choose Watch.

  • Right-click in the Watches window and choose Add Watch.

  • Use the mouse to drag a data item from the Data window and drop it on the Watches window.

14.10.2.1 How to Add a Watch from the Source Editor

You can add a watch to an expression in the source editor.

To add a watch from the Source Editor:  

  1. In the source editor, select the expression you want to watch with your cursor.

  2. Right-click and choose Watch from the context menu to add the expression to the Watches window.

    A dialog appears with the expression.

  3. Edit the expression, if necessary.

  4. Click OK.

14.10.2.2 How to Edit a Watch

You can edit a watch by selecting its expression in the Watches window.

To edit a watch: 

  1. Select the expression in the Watches window, then right-click and choose Edit Watch.

    The Edit Watch dialog appears.

  2. Enter a new expression or modify the existing one and click OK.

14.10.2.3 How to Delete a Watch

You can edit a watch by selecting its expression in the Watches window.

To delete a watch: 

  1. Select the expression in the Watches window.

  2. Press the Delete key or right-click and choose Remove Watch from the context menu.

    You can also delete all the watches by choosing Remove All Watches from the context menu.

    Caution:

    You cannot restore a deleted watch.

14.10.3 How to Modify Expressions in the Inspector Window

You can modify an existing expression in the inspector window.

To modify an expression in the Inspector window:

  1. You can type the new expression in the corresponding text box, or in the Inspector window, right-click and choose Edit Expression from the context menu.

    The Edit Expression dialog appears.

  2. Enter a new expression.

  3. Click OK.

14.10.4 How to Show and Hide Fields in the Filtered Classes List

While debugging, you can use filters to reduce the number of fields that are displayed when you expand an object in a data-related debugger window. You can perform this task in the Smart Data window, the Data window, the Inspector window, the Watches window, and the left-hand side of the Monitors window through the Object Preferences dialog. Displaying fewer fields narrows your focus when debugging and may make it easier to locate and isolate potential problems in your program.

For example, you can create filters for classes in the data windows so that the debugger displays only the fields of interest to you. This drastically reduces clutter and allows you to find the relevant data more quickly.

To show or hide fields in the filtered classes list:

  1. Select an object in a data-related debugger window. Right-click and choose Object Preferences from the context menu.

    Choosing Object Preferences lets you go directly to the Object Preferences dialog for this specific object from which you can specify filters to control which fields are displayed and which fields are not displayed when you expand an object.

  2. In the Object Preferences dialog, you can easily traverse the superclass hierarchy of the selected object, defining or updating the filters for each superclass. Select a class in the Types window and choose the fields to hide or display in the Value column of the debugger window.

  3. Click the arrows to shuttle filters from the Fields to Show list to the Fields to Hide list.

  4. Click OK when you are done.

14.11 Debugging Remote Java Programs

In addition to debugging code locally in the JDeveloper IDE, you can also debug code which is located on a remote machine or running in a different VM instance. This means that you can use the debugger to debug code that has already been deployed. The debugger can simultaneously attach to multiple remote VMs, so you can seamlessly debug distributed applications, such as JSPs deployed to a web server accessing EJBs deployed to an application server.

The main difference between remote debugging and local debugging is how you start the debugging session. For local debugging, JDeveloper automatically launches the program you want to debug (called a debuggee process) and then attaches the debugger to that program. For remote debugging, you must manually launch the program you want to debug. Also, if you are debugging a JSP or a servlet, you must manually start a browser to invoke your JSP or servlet.

Once the debuggee is launched and the JDeveloper debugger is attached to it, remote debugging is very similar to local debugging. Remember that you can use remote debugging when the debuggee process is running on the same machine as JDeveloper or when the debuggee process is running on a different machine.

Unlike local debugging, you must choose which protocol to use before you start your remote debugging session. The remote debugging protocols are configured in Debugger - Remote page of the Edit Run Configuration dialog.

You can also debug Web pages such as JSPs or servlets using the HTTP Analyzer. For more information, see Chapter 8, "Auditing and Profiling Applications.

  • Select Attach to JPDA to attach to the debugger application at a specified address. For more information about the Sun Java Platform Debugger Architecture (JPDA) Connection and Invocation, see http://java.sun.com/javase/6/docs/technotes/guides/jpda/conninv.html

  • Select Listen for JPDA to specify that the debugger listen for a debuggee to attach to the debugger. Also, choose this option if you are debugging remote PL/SQL programs.

14.11.1 How to Start a Java Process in Debug Mode

After you've configured a project for remote debugging, you can start your remote debugging session by issuing the appropriate command based on the debugging protocol and the environment.

To start the Java process, enter the following at the command line:

java [-client|server] -cp <project_directory>\classes -agentlib:jdwp,<option1>[=<value1>],<option2>[=<value2>]... <java_main_class> 

The available options are:

  • server(=n/y)

    If set to y, then the Java process waits for a Debugger to attach. If set to n (default), the process attaches itself to the debugger application at the specified address.

  • address

    Specifies the port for the connection. Defaults to 4000.

  • timeout

    Time interval after which the connection attempt times out. Defaults to 2 seconds.

  • suspend =(y/n)

    If set to y (default), the Java process runs after the debugger connects to it. If set to n, the debuggee process starts right away without waiting for the debugger to connect to it.

Command line examples:

  • java -cp <project_directory>\classes -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=4000

    Listen for a debugger connection on port 4000, but begin execution without waiting for the debugger. Timeout after 2s (default). Implement the Client VM (default).

  • java -server -cp <project_directory>\classes -agentlib:jdwp=transport=dt_socket,server=n,suspend=y,timeout=3,address=8000

    Attach to a debugger connection on port 8000. Begin execution only after connecting to the debugger. Timeout after 3s. Implement the Server VM.

For more information about the Sun JPDA Connection and Invocation, see
http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html
.

14.11.2 How to Use a Project Configured for Remote Debugging

Any project can be configured to perform remote debugging.

To configure a project for remote debugging:

  1. Click Debug from the toolbar.

    The appropriate Attach to dialog appears.

  2. In the Host list box, enter or select the name or IP address of the machine where the remote debuggee has been started.

  3. In the Port list box, enter or select the port number for the remote debuggee.

  4. Click OK.

    In the Log window, once the debugger has connected, a successful connection message appears.

  5. If you are remote debugging a JSP or servlet, you will want to access your JSP or servlet by launching your browser.

    If you are remote debugging an EJB, you will want to run an EJB client that will access your EJB.

  6. Continue with your debugging session as usual.

  7. To detach the debugger from the remote debugging process without terminating the debuggee process, choose the Run > Detach menu option. T

    This option is appropriate for remote debugging an application server.

  8. To terminate the remote debugging process, choose the Run > Terminate menu option, or select the Terminate icon.

14.11.3 How to Configure JPDA Remote Debugging

This section describes how to configure JDeveloper for Java Platform Debugger Architecture (JPDA) remote debugging.

To configure your project for remote debugging:

  1. Make changes in the JSP section of global-web-application.xml as follows:

    <init-param> 
       <param-name>debug</param-name> 
       <param-value>class</param-value> 
    </init-param>
    
  2. Start commands for Integrated WebLogic Server (make sure -server is the first parameter).

    value="-server -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=4000 -Xms512m -Xmx750m -XX:PermSize=128m -XX:MaxPermSize=256m -Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy -Djava.awt.headless=true -Dhttp.webdir.enable=false"/> 
    

To configure JDeveloper for remote debugging:

  1. Choose Application > Project Properties, select the Run/Debug/Profile node, select a run configuration and click Edit.

  2. Select the Remote Debugging and Profiling check box.

  3. On the Debugger - Remote page, verify that Protocol is set to Attach to JPDA.

  4. Close the Preferences dialog.

  5. Set breakpoints in your code and from the Debug button dropdown list select the desired run configuration. Complete the connection dialog and verify connection to the debuggee.

  6. Access JSP previously deployed to server via a browser. The breakpoint should be hit and all work as expected.