12 Running and Debugging Java Projects

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:

• About Running and Debugging Java Programs

• Understanding the Processes Window

• Configuring a Project for Running

• How to Run a Project or File

• Macros

• Setting the Classpath for Programs

• Debugging Java Programs

• Using the Debugger Windows

• Managing Breakpoints

• Examining Program State in Debugger Windows

• Debugging Remote Java Programs

About Running and Debugging Java Programs

JDeveloper tracks run, debugged, or profiled Java processes, and supports local and remote debugging. For local debugging, set breakpoints in source files to start a session before starting the debugger, and for remote debugging, launch the debuggee process to which the debugger process is attached.

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. 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.

Understanding the Processes Window

The Processes window opens to track processes that are run, debugged, or profiled. Use Processes in Window to open a Processes window, which when a process has completed, automatically removes it from the 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.

Configuring a Project for Running

Run configurations group the settings that control the running of programs. A project may use several run configurations, either custom or those that are bound to a project.

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.

How to Choose a Run Configuration

A new project has a default run configuration created for it, but you can create a custom run configuration. Use the procedure to select 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.

   Note:

   The last edited run configuration is the active run configuration.

How to Create a Run Configuration

Use the procedure to create a run configuration. Copy an existing configuration to create a new run configuration, and modify its settings.

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 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

How to Run a Project or File

Compile a project or file, run it, and view warning or error messages in the log window. Use the procedure to run a project or file.

After compiling your project or file, you can run it. For information about building a project or file, see 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.

How to Run a Project from the Command Line

A project can be run from the operating system command line if it is a standalone executable, and the class file containing the application main() method is selected.

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.

How to Change the Java Virtual Machine

The Java Virtual Machine may need changes according to operating systems: client-side applications need the HotSpot Client VM, whereas executing long-running server applications need the Server VM. Use the procedure 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.

Macros

Macros are a series of commands and actions that can be stored and run whenever you need to automate tasks that are performed repeatedly and regularly.

A macro  helps you to automate a task that you perform repeatedly or on a regular basis. It is a series of commands and actions that can be stored and run whenever you need to perform the task.  However in our case, the macro facility allows you to use a placeholder to represent an expression whose value is not known at the time the macro is being written.

Path locations that vary by installation or platform are a very common use for macros. Some examples might help clarify:

• Built-in IDE macros (qualifier = ide) include oracle.home, workspace.dir, and project.dir

• Environment variables (qualifier = env) provide access to platform-specific environment variables; they include JAVA_HOME, WAS_HOME, and HOSTNAME

• System properties (qualifier = prop) provide access to the Java system properties such as java.version, java.io.tmpdir, and file.separator

• User-Defined properties can be anything the user wants to define where none of the predefined macro handlers provide the needed value.

MacroHandlers are the classes that map the macro names to macro values. The JDEV-runner module provides you the options to define new macros, select macros for use in expressions, edit macros, etc.

Setting the Classpath for Programs

A Java program run from the command line needs the JVM with a list of the class paths to the files and libraries that comprise the application. The method that is used to run the Java program determines the form of the classpath.

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.

Setting the CLASSPATH Environment Variable (for java.exe)

The Java2 Standard Edition includes the java.exe file is a development tool that can be used to test a Java application from the CLI.

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.

Using the JDeveloper Library CLASSPATH

JDeveloper ships hundreds of library classes from J2SE, third-party developers, and Oracle Corporation to help you generate your Java programs.

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.

Setting the CLASSPATH to Include Your Projects

If the output path is set to the default directory, test the Java application using java.exe by appending the classes directory to your classpath.

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.

Setting the CLASSPATH Parameter (for java.exe)

The Java Runtime Engine (java.exe) does not use the CLASSPATH environment variable, so the complete CLASSPATH to your Java program, or classpath, must be included as a parameter to the java.exe command.

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.

Debugging Java Programs

The local and remote Debugger provides a number of features to investigate code, identify, and fix problem areas.

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 12-1 contains the special-purpose debugging windows that enable you to efficiently identify the problematic areas in your code.

Table 12-1 Debugging Windows

Window	Description
Breakpoint	Displays the breakpoints for the current workspace and project. See How to Use the Breakpoints Window.
Smart Data	Displays the data which is being used in the code that you are stepping through. See 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. See 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. See 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. SeeHow 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. See How to Use the Heap Window.
Stack	Displays the call stack for the current thread. See 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. SeeHow 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. SeeHow 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. See How to Use the Threads Window .

Understanding the Debugger Icons

The JDeveloper user interface, including the Debugger window and the Log window, provides several debugger and runner features.

Table 12-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 12-2 Debugger and Runner icons

Icon	Name	Description
	Array	Represents an array class in any Jdeveloper data-related window.
	Add Breakpoint	Represents the Breakpoint toolbar button used to create a breakpoint.
	Breakpoints menu	Represents the View > Debugger > Breakpoints menu option or the tab icon for the Breakpoints window.
	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	Appears in the Classes window. Represents a class which does not have line number tables (obfuscated class).
	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	Represents the current thread in the Threads window.
	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)	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	Represents a debug listener node in the Processes window.
	Delete Breakpoint	Represents Delete Breakpoint in the toolbar. Click to remove a breakpoint.
	Disable	Represents a disabled breakpoint in the source editor margin and a disabled breakpoint in the Breakpoints window. The icon also represents the Disable Breakpoint command in the toolbar. Click to disable a breakpoint.
	Disable All Breakpoints	Represents Suspend All Breakpoints command in the toolbar. Click to run the application without stopping at the breakpoints, then return to debugging mode.
	Edit Breakpoint	Represents the Edit Breakpoint command in the toolbar, which you can use to edit the selected breakpoint.
	Enabled	Represents an active breakpoint in the source editor margin and the Enable Breakpoint command in the toolbar. Click to enable the selected breakpoint. When the debugger is not running, the enabled breakpoint icon looks same as the unverified breakpoint icon.
	Garbage Collection	Represents the Run > Garbage Collection menu option and the Garbage Collection command in the toolbar, which you can click.
	Interface	Represents an interface in the Classes window.
	Heap	Represents the View > Debugger > Heap menu option and the tab icon for the Heap window.
	Heap Folder	Represents a folder in the Heap window.
	Method	Represents a method in the Stack window.
	Monitors	Represents the View > Debugger > Monitors menu option and the tab icon for the Monitors window.
	Object	Represents an object in any Jdeveloper data-related window.
	Package	Represents a package in the Classes window (grayed if the package has tracing disabled).
	Pause	Represents the Run > Pause menu option and the Pause toolbar button which you can click.
	Primitive	Represents a primitive item in any Jdeveloper data-related window.
	Resume	Represents the Run > Resume menu option and the Resume toolbar button which you can click.
	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)	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	Represents the Window > Debugger > Stack menu option and the tab icon for the Stack window.
	Stack Folder	Represents the static folder in the Data window
	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)	Represents the Run > Step Into menu option and the Step Into toolbar button which you can click.
	Step Out (Shift + F7)	Represents the Run > Step > Out menu option and the Step Out toolbar button which you can click.
	Step Over	Represents the Run > Step Over menu option and the Step Over toolbar button which you can click.
	Terminate	Represents the Terminate toolbar button which you can click to stop debugging your application.
	Threads	Represents the Window > Debugger > Threads menu option and the tab icon for the Threads window.
	Thread Group	Represents a thread group in the Threads window.
	Unverified Breakpoint	Represents an unverified breakpoint in the source editor margin, and an unverified breakpoint in the Breakpoints window
	Verified Breakpoint	Represents the verified breakpoint in the source editor margin.

Debugging an Application Deployed to Integrated WebLogic Server

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

When debugging an application deployed to an 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. To debug the application, start the server in debug mode. Go to ORACLE_HOME/jdeveloper/jdev/bin and run java -? to see the run configuration options available for the version of the JDK you are running.

• 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.

How to Debug a Project in JDeveloper

Compile code with debugging information, and use debugger features such as viewing arguments and local variables in the Data window. Use the procedure to set breakpoints and step through the code.

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.

   The unverified breakpoints icon appears in the left margin.

2. Select Run > Debug filename.jpr.

   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.

How to Edit and Recompile

While debugging, use the HotSwap feature to fix errors and replace class definitions, without stopping and restarting the application. HotSwap is an enhancement to the Java Platform Debugger Architecture that is implemented in the JVM in JDeveloper.

While debugging, use the HotSwap feature to fix errors and substitute corrected class definitions, without stopping and restarting your application. HotSwap is an enhancement to the Java Platform Debugger Architecture (JPDA) in Java 2 SDK v1.4, and has been implemented in JDeveloper's Java virtual machine, OJVM.

When the debugger is paused you can recompile classes. When the debugger resumes after code has been HotSwapped, threads that are currently executing old method definitions will continue to do so until those methods return. For subsequent method calls, the class definition will be used. However, existing instances of the class will not be modified, and class variables will not be reset. Use HotSwap to modify the logic of class methods. In most cases you cannot use HotSwap to make more substantial changes, such as adding or removing fields or methods.

Using FastSwap Deployment to Minimize Redeployment

Changes made to a deployed Web application are expected to be displayed when a browser is refreshed. IDEs provide incremental compilation support for editing and build steps. On the server side, the WebLogic Server FastSwap deployment feature in JDeveloper makes for smooth deployment and test cycles.

Today's Web application developers expect to make changes to a deployed application and see those changes immediately by refreshing the browser. On the Java EE side, developers typically have to go through the following cycle to see their changes in action.

Edit -> Build -> Deploy -> Test

These steps, along with the many required descriptor elements, makes developing applications with Java EE seem complex and top-heavy. Among these steps, the build and deploy cycles are necessitated by Java and by the application server being employed. IDEs are trying to make the edit and build steps seamless by providing incremental compilation support. On the server side, the WebLogic Server FastSwap deployment feature, available in JDeveloper, makes the deploy and test cycles just as seamless.

How FastSwap Deployment Works

The Java EE dynamic class redefinition is limited in that the declared fields and methods of a class cannot change. The purpose of FastSwap alleviates this restriction in WebLogic Server by allowing the dynamic redefinition of classes with new shapes to facilitate iterative development.

Java EE 5 introduced the ability to redefine a class at run time without dropping its classloader or abandoning existing instances. This allowed containers to reload altered classes without disturbing running applications, vastly speeding up iterative development cycles and improving the overall development and testing experiences. The usefulness of the Java EE dynamic class redefinition is severely curtailed, however, by the restriction that the shape of the class – its declared fields and methods – cannot change. The purpose of FastSwap is to remove this restriction in WebLogic Server, allowing the dynamic redefinition of classes with new shapes to facilitate iterative development.

With FastSwap, Java classes are redefined in-place without reloading the classloader, thereby having the decided advantage of fast turnaround times. This means that you do not have to wait for an application to redeploy and then navigate back to wherever you were in the Web page flow. Instead, you can make your changes, auto compile, and then see the effects immediately.

Supported FastSwap Application Configurations

A FastSwap deployment requires that the WebLogic Server runs in the development mode, and that support is available for changes to class files in exploded directories.

The following application configurations are supported when using FastSwap deployment:

• FastSwap is only supported when WebLogic Server is running in development mode. It is automatically disabled in production mode.

• Only changes to class files in exploded directories are supported. Modifications to class files in archived applications, as well as archived JAR files appearing in the application's classpath are not supported. Examples are as follows:

  • When a Web application is deployed as an archived WAR within an EAR, modifications to any of the classes are not picked up by the FastSwap agent.

  • Within an exploded Web application, modifications to Java classes are only supported in the WEB-INF/classes directory; the FastSwap agent does not pick up changes to archived JARs residing in WEB-INF/lib.

Enable FastSwap in Your Application

Enable FastSwap in an application by creating a deployment descriptor for the Oracle WebLogic server in the weblogic-application.xml file.

To enable FastSwap in your application, create an Oracle WebLogic deployment descriptor weblogic-application.xml and enable Fast Swap.

FastSwap can also be enabled for a standalone Web application by creating the WebLogic deployment descriptorweblogic.xml and enabling Fast Swap.

Overview of the FastSwap Process

The steps describe how the FastSwap deployment process works.

See Limitations When Using FastSwap.

The following steps describe how the FastSwap deployment process works:

1. Once FastSwap is enabled at the descriptor level, an appropriate classloader is instantiated when the application is deployed to WebLogic Server.

2. Open a browser to see the application at work. Modify (add/edit/delete) the methods and/or classes and then compile them.

   Note that the FastSwap agent does not compile Java files.

3. Refresh the browser or send a new request to the application.

   The FastSwap agent tries to find all classes that have been modified since the last iteration by looking at all directories in the classpath. Considering an exploded application with a single Web application, the following directories are examined for any class file modifications based on their timestamps:

   ExampleApp/APP-INF/classes
   ExampleApp/webapp/WEB-INF/classes
   

   The FastSwap agent redefines the modified classes in the application and then serves the request.

Application Types and Changes Supported with FastSwap

JDeveloper supports FastSwap with POJOs, web applications, and enterprise applications deployed in the exploded format although no support is available for resource adapters.

FastSwap is supported with POJOs (JARs), Web applications (WARs) and enterprise applications (EARs) deployed in an exploded format. FastSwap is not supported with resource adapters (RARs).

The following types of changes are supported with FastSwap:

• Addition of static methods

• Removal of static methods

• Addition of instance methods

• Removal of instance methods

• Changes to static method bodies

• Changes to instance method bodies

• Addition of static fields

• Removal of static fields

• Addition of instance fields

• Removal of instance fields

The following table lists detailed change types supported with FastSwap:

Table 12-3 Supported Application Types and Changes

Scope	Java Change Type	Supported	Notes
Java Class	Add method	Yes	Addition of the finalize method is not supported.
Instance (non-abstract)	Remove method	Yes	Addition of the finalize method is not supported.
	a) Add field	Yes
	b) Remove field	Yes
	c) Change method body	Yes
	d) Add constructor	Yes
	e) Remove constructor	Yes
	f) Change field modifiers	Yes
	g) Change method modifiers	Yes
Class-level (static)	Add method	Yes
	Remove method	Yes
	Change body method	Yes
Class Hierarchy Changes	Change list of implemented interfaces	No
	Change extends "SuperClass"	No
Abstract Java Class	Add abstract method	Yes
	Delete abstract method	Yes
	All other supported changes (a–g) listed in Instance	Yes
"final" Java Class	Same supported changes (a–g) listed in Instance	Yes
"final" Java Method	Same supported changes (a–g) listed in Instance	Yes
"final" Java Field	Same supported changes (a–g) listed in Instance	Yes
Enum	Add constants	No
	Remove constants	No
	Add/remove methods	No
Anonymous Inner Class	Add/remove fields	NA	Not supported by the Java language
	Add/remove methods	No
Static Inner Class	Same supported changes (a–g) listed in Instance	Yes
Member Inner Classes (non-static inner classes)	Same supported changes (a–g) listed in Instance	Yes
Local Inner Classes	Same supported changes (a–g) listed in Instance	Yes
Java Interface	Add method	Yes
Java Reflection	Access existing fields/methods	Yes
	Access new methods	No	New methods are not seen using Reflection and some synthetic methods are exposed.
	Access new fields	No	New fields are not seen using Reflection.
Annotations on Classes	Add or remove method/field annotations	No
Annotation Type	Add or remove methods/attributes	No
Exception Classes	Same supported changes (a–g) listed in Instance	Yes
EJB Interface	Add/remove methods	No	Changes to EJB interfaces involve Reflection, which is not fully supported.
EJB 3.0 Session/MDB EJB Implementation Class	Add/remove methods	No	Any support classes referenced by the EJB classes can be modified.
	Add/remove fields	No
EJB 3.0 EntityBean	Add/remove methods	No	Any support classes referenced by the EJB classes can be modified.
	Add/remove fields	No
EJB Interceptors	Add/remove methods	No	Any support classes referenced by the EJB classes can be modified.
	Add/remove fields	No

Limitations When Using FastSwap

Several limitations, such as the unavailability of support for the addition or removal of Java annotations or methods on EJB Interfaces, are associated with FastSwap deployment.

The following limitations apply when using FastSwap deployment:

• Java reflection results do not include newly added fields and methods and include removed fields and methods. As a result, use of the reflection API on the modified classes can result in undesired behavior.

• Changing the hierarchy of an already existing class is not supported by FastSwap. For example, either a) changing the list of implemented interfaces of a class; or b) changing the superclass of a class, is not supported.

• Addition or removal of Java annotations is not supported by FastSwap, since this is tied to the reflection changes mentioned above.

• Addition or removal of methods on EJB Interfaces is not supported by FastSwap since an EJB Compilation step is required to reflect the changes at run time.

• Addition or removal of constants from Enums is not supported.

• Addition or removal of the finalize method is not supported.

• When you change a field name, the object state is not retained. This type of change occurs as follows: the field with the old name is deleted and a field with the new name is added. As such, any state in the old field is not carried over to the renamed field. You should expect an instance value to be reset when you change a field name.

Handling Unsupported FastSwap Changes

When FastSwap is enabled, it redefines classes in the existing classloaders. If the redefinition fails, the JVM throws an UnsupportedOperationException both in the Log window and in the server log file while the application continues to run.

When FastSwap is enabled, after you recompile a class, FastSwap attempts to redefine classes in existing classloaders. If redefinition fails because your changes fall outside the scope of supported FastSwap changes, the JVM throws an UnsupportedOperationException in the Log window and in the server log file. Your application will not reflect the changes, but will continue to run.

To implement your changes, you can redeploy the application or affected modules (partial redeploy), depending on the application type and the extent of your changes.

How to Debug ADF Components

JDeveloper supports ADF Declarative Debugger so that applications can be debugged with breakpoints, and breakpoint types decide how the application moves from one breakpoint to another. An application execution pauses to facilitate the comparison of the data that is available, and the expected data for the functioning of the binding container.

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 12-4 contains the windows that Jdeveloper provides for debugging ADF components.

Table 12-4 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 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 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. See How to Export Debug Information to a File.

How to Use JDeveloper Debugger to Execute a Program

Use the procedure to use the JDeveloper debugger to control the execution of a program. If the fix proves effective, exit the debugging session, fix the code, and recompile to save the changes.

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

1. Run to a breakpoint.

   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.

   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..

   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.

   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.

   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.

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.

How to Configure a Project for Debugging

Manage the way a program is debugged, how it enables and disables packages and classes, and configures remote debugging options. Use the procedure to configure debugger and remote debugger options in JDeveloper.

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.
5. Click Edit.
6. Select Tool Settings > Debugger.
7. Set the options on the Debugger and Remote pages.
8. Click OK when finished.

How to Set the Debugger Start Options

Set the debugger start option to specify how the debugger functions at the start of a new debugging session. Use the procedure 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 12-5 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.

How to Launch the Debugger

Specify build options on the Compiler page of the Project Properties, and build the project because the debugger starts if the project builds successfully. Use the procedure to build a project and start 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.

How to Export Debug Information to a File

From a debugger window, export the debug information that the JDeveloper debugger generates to a text or HTML output file. Use the procedure 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 a 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).

Using the Source Editor When Debugging

When the debugger stops, the source editor displays the source file for the current open class marked by an icon for execution.

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 the figure.

Figure 12-1 Execution Point Icon

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 12-2 Breakpoint Icon

  

Using Context Menu Items

The debugger adds the Run to Cursor, Watch, Inspect, and Step Into Method at Cursor menu items to the context menu of the source editor.

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

Table 12-6 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.

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.

Using Java Expressions in the Debugger

Specify the legal Java expressions that are used in the Watches window, Inspector window, Breakpoint Conditions, and Breakpoint Log Expressions for the debugger to monitor and evaluate.

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 12-7.

Table 12-7 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

Moving Through Code While Debugging

Use the debugger to manage how JDeveloper executes a single line of code, a method, or a code block in a program. Use the Step Into and Step Over commands to traverse program code.

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. See 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.

How to Step Into a Method

Set the debugger to start by stepping into code using the Step Into command, so that the program that is being debugged executes until a method in a tracing-enabled class is reached. Use any of the listed methods 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 the debugger will step into. Moving the cursor using the arrow or tab key alters the execution point for the method 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 12-3 Step Into Button

  

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 are not sure that a method is well behaved, step into the method and check whether it is working properly.

How to Step Over a Method

Set the debugger to start by using the Step Over command so that the program being debugged executes until a method in a tracing-enabled class is reached, but does not stop in the class static initializer method. Use any of the listed methods 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 12-4 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.

Controlling Which Classes Are Traced Into

Set the tracing include and exclude lists in Project Properties or Classes before debugging. The descending classes within the specified package are included or excluded.

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.

How to Step Through Behavior as Guided by Tracing Lists

If a class or package is excluded, the debugger that is set to step into a class runs through that code without pauses. Use the procedure to adjust the tracing include or exclude list.

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

How to Locate the Execution Point for a Thread

During the debugging process, the line of code that is the current execution point for the thread is highlighted and the left margin of the source editor displays the icon for the execution point. Use the procedure to find the current execution point.

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.

How to Run to the Cursor Location

Step through application code in the debugger to a particular location without single stepping or setting a breakpoint. Use the procedure to run to a specific program 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.

How to Pause and Resume the Debugger

Pause debugger running at a point in the program so that the debugger can evaluate the code at the location, and then resume debugging. Use the Pause option for Run, or use Pause on the debugger toolbar to pause 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 12-5 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.

How to Terminate a Debugging Session

Terminate a debugging session using Terminate in the Run menu if the debugger has run past a bug location, and needs a restart. Termination of a session closes all debugger windows without deleting breakpoints or watches that had been set.

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.

How to View the Debugger Log

Select Log for Debugger in the Window menu to view the Debugger log for an active debugger session.

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:

• Select Window > Debugger > Log

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

Using the Debugger Windows

Use special-purpose debugging windows to analyze code and identify problem areas. Use the options that are available by either right-clicking in a window and selecting Preferences from the context menu, or by selecting Preferences for Tools, and saving the debug information as text or HTML output file.

Jdeveloper provides a number of special-purpose debugging windows to help you analyze your code and identify problem areas. 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.

How to Open Debugger Windows

Set a breakpoint to start a debugging session and at a breakpoint, select a specific window from the Debugger menu for Window. You can open and use Debugger windows for classes, Heap, Data, Log, Monitors, Stack, Smart Data, Threads, and Watches depending on requirements.

You open a Debugger window by setting a breakpoint and starting a debugging session. When the Debugger stops at the breakpoint, select Window > Debugger > deubugger_window. For example, Window > Debugger > Threads. You can access the Breakpoints windows by simply starting a debugging session (it is also accessible from Window > Breakpoints)

Select one of the following Debugger windows depending on the information you want to see: Classes, Heap, Data, Log, Monitors, Stack, Smart Data, Threads, and Watches. See the following sections for information on using these windows.

How to Use the Breakpoints Window

Select Breakpoints from the Window menu to open a window to display a list of set breakpoints. The Breakpoints window displays information about set breakpoints.

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 Window > Breakpoints from the main menu. The Breakpoints window appears.

How to Use the Data Window

The Data window displays information about variables in a program. It also displays the current return value of a non-void method when a breakpoint in the method is set, and the Step to End of Method command or Step Out command is run.

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.

How to View Array Elements in the Data Window

Set the number of elements in an array to be displayed in the Data Window. Use the procedure 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.

How to Use the Smart Data Window

The Smart Data window displays data that is relevant to the source code that is being stepped through. Set the options for smart data on the Smart Data page, selecting Debugger for Preferences for Tools.

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. See 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.

How to Use the Watches Window

A watch monitors the changing values of variables or expressions as a program runs. The values of the variables in the watch expression change to reflect program updates and changing contexts.

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 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.

How to Add a Watch from the Source Editor

Use the procedure to add a watch from the Source Editor. A watch can also be added by selecting Watch from the context menu of an item selected in the Data window or by dropping items from the Data window to the Watches window.

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.

You can also add a watch in the following ways:

• 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.

How to Watch a Static Field

To view a static field, enter the full name of the class followed by a period and the name of the 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

How to Edit a Watch

Edit a watch by selecting its expression in the Watches window. Use the procedure 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.

How to Delete a Watch

Delete a watch by selecting its expression in the Watches window. Use the procedure 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.

How to Use the Inspector Window

In the Inspector window, select a variable, field, or object, and get the information from the Watch or Data windows displayed. Use the procedure to open the Inspector Window.

The Inspector window enables 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. See 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.

How to Use the Heap Window

The Heap window displays information about the heap in the program that is being debugged, and helps identify memory leaks in a program. The heap window holds the Class Folder and the Reference Path Folder.

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 use the Heap window:

• 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.

Using the Stack Window

The Stack window displays the call stack for the current thread.

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.

How to Use 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.

How to View the Stack of a Tread

The Stack window displays the stack of a selected thread. Use the procedure to view the stack of a thread.

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.

How to Use the Classes Window

The Classes window displays the classes that have been loaded and information such as the number of instances of a class and the memory needed. The window also shows garbage collector runs.

The Classes window displays which classes have been loaded and may also include useful information, such as the number of instances of a class and how much memory that number of instances requires. 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.

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 12-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 12-6 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

How to Use the Monitors Window

Java uses the synchronization mechanism to coordinate activities and data access among multiple threads. The Monitors window displays status and control information for active monitors.

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.

How to Use the Threads Window

The Threads window displays the names, status, and thread groups of all the threads in a program. Use Threads for Debugger in the Preferences for Tools to set the columns that get displayed in the 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

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.

How to Set Preferences for the Debugger Windows

You can customize the settings for the Debugger window. Use the procedure to set preferences for the Debugger window.

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 debugger (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.

How to Specify Which Columns Display in the Window

The debugger windows only displays the columns that you select. Right-click in the window and select Preferences from the context menu, or right-click a column heading to specify which columns get displayed 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.

Managing Breakpoints

Set breakpoints in source code so that the running of the program pauses at points that needs debugging. JDeveloper supports Source breakpoints, Exception breakpoints, Method breakpoints, Class breakpoints, File breakpoints, and Deadlock 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. The figure displays an example breakpoint in a Java Application source file.

Figure 12-7 Breakpoint in Source Editor

Description of "Figure 12-7 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.

Understanding Verified and Unverified Breakpoints

During debugging, the debugger verifies all breakpoints by checking if they have been set in executable lines of code, and displays an icon to indicate that they have been validated.

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 the figure.

Figure 12-8 Verified Breakpoint Icon

Understanding Deadlocks

A deadlock, such as the common monitor block cycle deadlock, blocks one or more threads in a program from gaining access to a resource, or waits on a condition that cannot be satisfied. To debug, pause your program by clicking Pause in the debugger, and open the Monitors window.

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.

The following example shows a typical 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.

Understanding the Deadlock Breakpoint

You can disable the persistent deadlock breakpoint that the debugger automatically sets when JDeveloper starts. The debugger pauses program running when it encounters a monitor block cycle deadlock.

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.

Understanding Grouped Breakpoints

JDeveloper supports Grouped breakpoints that allow you to use multiple breakpoints as a set. Enable breakpoints that are disabled when the debugger encounters the set points for program pauses, or set source breakpoints so that the debugger automatically enables the breakpoint group which contains the exception breakpoint.

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.

How to Edit Breakpoint Options

Using the Edit Breakpoint dialog, edit the options for a breakpoint after it has been added in the source code. Use the procedure to view and modify the options of a breakpoint.

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.

Editing a Breakpoint

Right-click a breakpoint located in the source editor to edit its attributes, such as enabled, disabled, or condition, in the Edit Breakpoint dialog.

You can right-click to edit a breakpoint located in the source editor. The Edit Breakpoint dialog shown in the figure 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 12-9 Edit Breakpoints Dialog

  
  Description of "Figure 12-9 Edit Breakpoints Dialog"

You can also hover over a breakpoint in the source editor to display the dialog in the figure above.

How to Set Source Breakpoints

A source breakpoint that is set on a line of executable code in the source pauses program execution. Set a source breakpoint by using Breakpoints in Window, or Toggle Breakpoint after right-clicking in the left margin next to a line of code.

A source breakpoint is the most common type of breakpoint. It is set on a line of the source code and program execution is paused when it hits that line.

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 Window > 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 might 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.

How to Control Breakpoint Behavior

Manage debugger functioning at a breakpoint by setting halt execution, beep, the enabling or disabling of a group of breakpoints. Use the procedure to control how the debugger behaves when a breakpoint occurs.

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

How to Delete a Breakpoint

Delete a breakpoint when it is not required using either the source editor or the Breakpoints window. Use the detailed options 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.

How to Disable a Breakpoint

Disabling a breakpoint retains all the defined breakpoint settings, but does not trigger the breakpoint during the program run. Disable a breakpoint using the options that are detailed.

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.

How to Enable a Breakpoint

You can re-enable a disabled breakpoint by using the Enable, Enable All, and the Enable Group options from the right-click context menu in the Breakpoints window. You can also use Enable on the Breakpoints toolbar.

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.

How to Set Instance Breakpoints

Instance filters that are displayed in the Instance Filters column of the Breakpoints window are source breakpoints with instance filters that identify selected instances. Use the procedure to set an instance breakpoint.

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.
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.

How to Set Exception Breakpoints

Set exception breakpoints that are activated when a certain type of exception is thrown during the running of a program. Use the procedure to set an exception breakpoint.

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.

How to Make a Breakpoint Conditional

The debugger pauses program execution every time a breakpoint is encountered, and by setting a condition using the Edit Breakpoints dialog, you can customize breakpoints so that they are activated only in certain conditions. Use the procedure to set a breakpoint condition.

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.

Using Pass Count Breakpoints

Use the Pass Count field to specify the number of times that a breakpoint must be passed before a breakpoint is activated. If the default number, one, is set, when the program reaches the breakpoint line, the breakpoint is activated, and the program pauses.

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.

How to Examine Breakpoints with the Breakpoints Window

Select Breakpoints in the Debugger menu for Window to view a list of breakpoints, and the breakpoints that have been validated by the debugger. Use the procedure to use the Breakpoints window to locate a breakpoint in the source editor.

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 12-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.

How to Manage Breakpoint Groups

Create a breakpoint group, enable or disable it, or remove it like a single breakpoint.

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.

How to Create a Breakpoint Group

Create a breakpoint, and edit it to create a breakpoint group so that all breakpoints in the selected group can be enabled collectively. Use the procedure 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.

How to Move a Breakpoint into a Breakpoint Group

Use the procedure to move a breakpoint into a breakpoint group, or drag-and-drop the breakpoint into the 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.

Enabling Disabling or Removing a Breakpoint Group

In the Breakpoints window, right-click a breakpoints group, and select the Enable Group, Disable Group, or Delete Group options from the context menu to enable, disable, or remove 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.

Examining Program State in Debugger Windows

Program variables reveal bugs. Pause a program in the debugger to examine the values of variables, arguments, fields, and array items.

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.

How to Inspect and Modify Data Elements

When debugging, use the Data, Smart Data, Inspector, or Watches windows to view and edit data items. In the Source Editor, when the program pauses at a breakpoint, hover the mouse pointer over an item to get its details.

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.

How to Inspect a Data Item

When debugging, test a data item with different expressions to spot bugs, and if an edit fixes an error, exit the program, fix the bug, and then recompile the program. Use the procedure 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.

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.

How to Modify the Value of a Variable

When debugging, test hypothetical bug fixes, and if a fix fits, exit the program, fix, and then recompile, but change program source code as the fix does not change the code. Use the procedure to modify the value of a variable in the Data window.

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.

Note:

Some object types cannot be modified while the program is running. A warning appears if you attempt to modify such an object type.

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.

How to Modify Expressions in the Inspector Window

Use the inspector window to modify an existing expression. Use the procedure to modify an expression 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.

How to Show and Hide Fields in the Filtered Classes List

When debugging, in a data-related debugger window, filter the number of displayed fields for an expanded object so as to narrow focus, locate, and isolate potential errors in the program. Use the procedure to show or 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.

Debugging Remote Java Programs

Debug code on a remote computers or on VM instances. Manually launch the program to be debugged, and use the remote debugging protocols on the Debugger - Remote page of the Edit Run Configuration dialog to debug code that has been deployed remotely.

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. See Auditing and Monitoring Java Projects.

• Select Attach to JPDA to attach to the debugger application at a specified address. For information about the Java Platform Debugger Architecture (JPDA) Connection and Invocation, see http://docs.oracle.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.

How to Start a Java Process in Debug Mode

To Start a Java process in the Debug mode, configure the project for remote debugging, start the remote debugging session, and run the command appropriate to the debugging protocol and the environment.

After you have 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.

Note:

The options shown are applicable if you are running JDK 1.6 or later. See the documentation for the version of JDK you are running if earlier than JDK 1.6.

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 information about the JPDA Connection and Invocation, see http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/conninv.html.

How to Use a Project Configured for Remote Debugging

A project must be configured for remote debugging. Use the procedure to configure a project 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.

How to Configure JPDA Remote Debugging

Configure JDeveloper for remote debugging by using the Java Platform Debugger Architecture. Use the procedures to configure a project for remote debugging, and to configure JDeveloper for 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.