10 Running and Debugging Java Application Projects

10.4.1.1 Running the Selected File

Let's demonstrate how this works when you run a class. A typical target for running a project looks something like the following:

<target name="run2" depends="...">
        <java fork="true" classname="MyMainClass" classpath="MyRunClasspath" />
</target>

The target runs the file specified by classname. To run the currently selected file in the IDE, you need to modify the above target to something like the following:

<target name="run-selected-file" depends="compile" description="Run Single File">
      <fail unless="runclass">Must set property 'classname'</fail>
      <java classname="${runclass}">
         <classpath refid="run.classpath"/>
      </java>
</target>

10.4.1.2 Getting a Reference to the Currently Selected File in the IDE

Once you have an Ant target for running the selected file, you have to get a reference to that file in the IDE and store it in a property. For example, the run-selected-file target above looks for the currently selected file in the runclass property.

You store this reference in the same place where you map the build target (run-selected-file) to the IDE action. First we will look at how to do this and then we will explain it in detail:

 <action name="run.single">
        <target>run-single</target>
        <context>
            <property>runclass</property>
            <folder>${src.dir}</folder>
            <pattern>\.java$</pattern>
            <format>java-name</format>
            <arity>
                <one-file-only/>
            </arity>
        </context>
    </action>

The runclass property is a newly defined property that holds the file that you want to run and is referenced by the java task.

Now let's take a look at the following lines to see how it works.

<action name="run.single">
      <target>run-selected-file</target>
      <context>
        <property>runclass</property>

• <action name="run.single"> maps the Run File command and the F9 shortcut to the run-selected-file target.

• <context> sets the context on which the Ant target is executed. In this case, it is the name of file that you want to run.

• runclass is the name of the property that holds the context. You can choose any unique name for this property. This property must be set by the IDE before the target can be run.

• <arity> specifies that runclass can hold only one file. If you want the property to be able to hold more than one file (such as for the Compile File target), you can use the following, where the comma (,) is the separator between file names:

  <arity>
            <separated-files>,</separated-files>
  </arity>
  

• <format>java-name</format> specifies that the IDE should pass the relative file name to the target but delimited by periods (.) and without an extension. Other formatting options include the following:

  • relative-path - specifies that the IDE should pass the relative file name to the target

  • relative-path-noext - Same as relative-path, but the file's extension is removed

  • absolute-path - Absolute file name

  • absolute-path-noext - Same as absolute-path, but the file's extension is removed

• <folder>${src.dir}</folder> specifies that the file name should be relative to the src.dir directory and that this action is only enabled for the src.dir directory.

  Note:

  The IDE does not define the ${src.dir} property for you. You have to define the property or import the .properties file that the Ant is using in project.xml. See Using Properties in the project.xml File for more information.

• <pattern>\.java$</pattern> is the regular expression which the file names must pass. You use <pattern> to limit which files can be passed to the Ant target. In this case, you want the target be executed only with files that end in .java.

10.4.1.3 Debugging the Selected File

The process is basically the same for writing targets to debug and run a single file. The debug-selected-files target looks something like this:

 <target name="debug-selected-files" depends="compile" if="netbeans.home" description="Debug a Single File">
       <fail unless="classname">Must set property 'classname'</fail>
       <nbjpdastart name="${classname}" addressproperty="jpda.address" transport="dt_socket">
          <classpath refid="run.classpath"/>
          <!-- Optional - If source roots are properly declared in project, should
          work without setting source path.
          <sourcepath refid="debug.sourcepath"/> -->
       </nbjpdastart>
       <java classname="${classname}" fork="true">
          <jvmarg value="-Xdebug"/>
          <jvmarg value="-Xnoagent"/>
          <jvmarg value="-Djava.compiler=none"/>
          <jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
          <classpath refid="run.classpath"/>
       </java>
 </target>

• This is basically the same as the debug target. Instead of passing the program main class to java, you pass the classname property, which is set by the IDE to the currently selected file.

Then you map the debug-selected-files target to the debug.single action:

<action name="debug.single">
      <target>debug-selected-files</target>
      <context>
         <property>classname</property>
         <folder>${src.dir}</folder>
         <pattern>\.java$</pattern>
         <format>java-name</format>
         <arity>
            <one-file-only/>
         </arity>
      </context>
</action>

• <property> now stores the context in the classname property.

• Since java can only take single file, you set <arity> to <one-file-only>.

• Setting <format> to java-name and making it relative to src.dir creates a fully-qualified class name for the currently selected file.

  Note:

  The IDE does not define the ${src.dir} property for you. You have to define the property or import the .properties file that the Ant is using in project.xml. See Section 6.2.4.9.1, "Using Properties in the project.xml File" for more information.

10.8.1.1 How to Create a Debug Target for a Free-form Java Project

To run a free-form project in the IDE's debugger, you have to have a special target in your project's build script. That target needs to be mapped to the IDE's Debug Project command.

If you do not have a debug target written for your project, the IDE offers to generate a basic target for you when you first try to debug the project. You can then inspect the target and customize it for the project's specific requirements.

To create a debug target for a free-form project:

1. Set the free-form project as the main project by choosing Run > Set Main Project in the main menu and selecting the project.

2. Choose Debug > Debug Main Project from the main menu.

3. Click Generate in the Debug Project dialog box.

   When you click Generate, a target named debug-nb is created in a file named ide-targets.xml. The generated ide-targets.xml file is a build script that imports your main build.xml file, so your debug target can take advantage of targets and properties set by or referenced by your main build script.

   In addition, a mapping for this target is created in the project.xml file so that the target is called whenever you choose the Debug Project command in the IDE. If you write the target from scratch, you must also create this mapping yourself. For more information, see Section 10.8.1.1.2, "Manually Mapping a Target to a Menu Item."

4. Verify that the generated debug-nb target properly takes into account all of the elements of your project.

   In particular, you might have to modify the <classpath> argument in the target if it does not include all of the items in your run classpath.

After the target is created, you can begin debugging the project.

To debug the project:

1. Set a breakpoint in your main class by clicking in the left margin of the line where you want to set the breakpoint.

   The line with the breakpoint is highlighted in pink.

2. Right-click the project's node again and choose Debug Project.

   The target should run and start execution of the program. Progress of the running target is shown in the Output window and the status of the debugger is shown in the status bar at the bottom of the Output window.

<?xml version="1.0" encoding="UTF-8"?>
    <project basedir=".." name="YourProjectName">
        <import file="../build.xml"/>
        <!-- TODO: edit the following target according to your needs -->
        <!-- (more info: http://www.netbeans.org/kb/articles/freeform-config.html#debugj2se) -->
        <target name="debug-nb" depends="init,compile">
            <nbjpdastart addressproperty="jpda.address" name="NameOfProject" transport="dt_socket">
            <classpath path="ClasspathSpecifiedInYourRunTarget"/>
            </nbjpdastart>
            <java classname="MainClassSpecifiedInRunTarget" classpath="ClasspathSpecifiedInYourRunTarget" fork="true">
               <jvmarg value="-Xdebug"/>
                <jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
            </java>
        </target>
    </project>

<?xml version="1.0" encoding="UTF-8"?>
    <project basedir=".." name="YourProjectName">
        <!-- TODO: edit the following target according to your needs -->
        <!-- (more info: https://netbeans.org/kb/articles/freeform-config.html) -->
        <target name="debug-nb">
            <path id="cp">
                <!-- TODO configure the runtime classpath for your project here: -->
            </path>
            <nbjpdastart addressproperty="jpda.address" name="NameOfProject" transport="dt_socket">
                <classpath refid="cp"/>
            </nbjpdastart>
            <!-- TODO configure the main class for your project here: -->
            <java classname="some.main.Class" fork="true">
                <classpath refid="cp"/>
                <jvmarg value="-Xdebug"/>
                <jvmarg value="-Xnoagent"/>
                <jvmarg value="-Djava.compiler=none"/>
                <jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
            </java>
        </target>
    </project>

<path id="cp">
    <pathelement location="libs">
    <pathelement location="build">
</path>

10.8.1.2 How to Create a Debug Target for a Free-form Web Project

In a free-form project, you must set up your own Ant target to run a project in the debugger. However, you can use the IDE to generate a debug target for you. When you do so, the IDE maps the debug target to the Debug Project command. Alternatively, if you have your own debug target, you must map it to the Debug Project command yourself.

To generate a debug target:

1. Set the project as the main project and choose Debug > Debug Main Project (Ctrl+F5) from the main menu or right-click the project in the Projects window and choose Debug.

   If no target is mapped to the Debug Project command, you are prompted to let the IDE generate an IDE-specific debug target in nbproject/ide-targets.xml.

2. Click Generate.

   The IDE does the following:

   • Generates a target named debug-nb. The target is generated in the new nbproject/ide-targets.xml file, together with other targets that support it, such as the -load-props, -check-props, -init, and debug-display-browser targets. These targets do the following:

     • Checks whether Ant is running inside the IDE (if="netbeans.home").

     • Starts the debugger with the nbjpdaconnect task.

     • Connects the debugger to the application to be debugged at the specified host (jpda.host) and port number (jpda.address).

     • Opens the IDE's web browser at the URL specified by the client.url property.

     Note:

     These targets are not generated in the IDE. Therefore, you need to change the generated code so that it looks as follows:

     <target name="-load-props">
            <property file="nbproject/project.properties"/>
     </target>
     
     <target name="-check-props">
            <fail unless="session.name"/>
            <fail unless="jpda.host"/>
            <fail unless="jpda.address"/>
            <fail unless="jpda.transport"/>
            <fail unless="web.docbase.dir"/>
            <fail unless="debug.sourcepath"/>
            <fail unless="client.url"/>
     </target>
      
     <target depends="-load-props, -check-props" name="-init"/>
     
     <target depends="-init" name="debug-nb" description="Debug Project">
            <nbjpdaconnect address="${jpda.address}" host="${jpda.host}"
             name="${session.name}" transport="${jpda.transport}">
                 <sourcepath>
                     <path path="${debug.sourcepath}"/>
                 </sourcepath>
            </nbjpdaconnect>
            <antcall target="debug-display-browser"/>
     </target>
     
     <target name="debug-display-browser">
            <nbbrowse url="${client.url}"/>
     </target>
     

     There's no need for you to customize the generated targets. All you have to do is set the properties that the IDE requires to use the targets it generated. For example, you need to tell the IDE where your application's sources are. To do this, you will set properties in the nbproject/debug.properties file that the IDE created for you when it generated the debug-nb target above. Using the -load-props target above, the IDE will load the properties when you run the debug-nb target.

   • Generates and defines debug properties. The properties are defined in the new nbproject/debug.properties file. The properties define the following:

     • The sources that are to be debugged.

     • The server to which the application to be debugged is to be deployed.

     • The port number and address to be used.

     • The client URL.

   • Maps the debug-nb target to the Debug Project command.

3. In the Files window, go to the nbproject/debug.properties file and edit the debug properties as shown in Example 10-3, if necessary.

   Example 10-4 Adding properties to a new debug.properties file

     jpda.session.name=MyProject
     jpda.host=localhost
    
     # Sun Java System Application Server using shared memory (on Windows)
     # jpda.address=localhost4848
     # jpda.transport=dt_shmem
    
     # Sun Java System Application Server using a socket
     # jpda.address=9009
     # jpda.transport=dt_socket
    
     # Tomcat using shared memory (on Windows)
      jpda.address=tomcat_shared_memory_id
      jpda.transport=dt_shmem
    
     # Tomcat using a socket
     #jpda.address=11555
     #jpda.transport=dt_socket
    
     src.folders=src
     web.docbase.dir=web
    
     # you can change this property to a list of your source folders
     debug.sourcepath=${src.folders}:${web.docbase.dir}
    
     # Client URL for Tomcat
     client.url=http://localhost:8084/MyProject
    
     # Client URL for Sun Java System Application Server
     # client.url=http://localhost:8080
   

   Property	Value	Notes
   jpda.session.name		The display name given in the Sessions window when you debug the project.
   jpda.host		The host that the application to be debugged uses to connect to the debugger, such as localhost.
   jpda.address	The bundled Tomcat Web Server defaults are 11555 for socket connections and tomcat_shared_memory_id for shared memory connections.	To set a different address, right-click the Tomcat node in the Services window and choose Properties. In the Properties sheet, change the Debugging Port property (for socket connections) or Name property (for shared memory connections). Then close the Properties sheet. Now stop and restart the Tomcat Web Server, if you had already started it.
   jpda.transport	dt_socket (for socket connections) or shmem (for shared memory connections).	To set a different transport, right-click the Tomcat node in the Services window and choose Properties. In the Properties sheet, change the Debugging Type. Then close the Properties sheet. Now stop and restart the Tomcat Web Server, if you had already started it.
   web.docbase.dir src.folders	The location of your web root (web.docbase.dir) and Java source files (src.folders).	Multiple source roots can be included in the sourcepath by means of the ":" delimiter. Note that the Java source folders must be specified as Source Package Folders in the Java Sources panel of the Project Properties dialog box. (Right click the project, choose Properties, then click Java Sources in the Project Properties dialog box.)
   client.url		The URL that should be opened in the IDE's default browser, such as http://localhost:8084/MyProject.

   
   

If you use the IDE to generate the debug target, as described in the previous section, the target is automatically mapped to the Debug Project command. However, if your debug target was not generated by the IDE, you must map it to the Debug Project command manually.

To map a debug target to the Debug Project command:

1. In the Projects window, right-click the project node and choose Properties.

2. Click Build and Run in the left panel of the Project Properties dialog box.

3. Click Add, select your debug target, and type a label, such as "Debug Project."

If you want to map the debug action to a target in a separate Ant script, open the project's project.xml file and add the following to <ide-actions>:

  <action name="debug">
    <script>path_to_Ant_script</script>
    <target>name_of_target</target>
  </action> 

To add the command to the project node's contextual menu, add the following to <context-menu>:

  <ide-action name="debug"/>

10.8.2.1 GUI Snapshots

After you create a project you can start a debugging session, take a GUI snapshot of the application, and then work with the snapshot to locate source code, add listeners to events and view the event log of GUI components.

To take a GUI snapshot:

1. Click the Debug button in the toolbar to start a debugging session.

   Alternatively, right-click the project node in the Projects window and choose Debug.

   When you start the session, the IDE will launch your application and open the Debugging window.

2. Choose Debug > Take GUI Snapshot from the main menu.

   When you choose Take GUI Snapshot, the IDE takes a snapshot of the GUI and opens the snapshot in the main window.

10.8.2.2 Working with the Visual Debugger

The GUI snapshot is a visual debugging tool that can help you locate the source code for GUI components. The source code for GUI components can sometimes be difficult to locate and the snapshot provides a way for you to locate the code based on the GUI instead of searching through the code. You can select components in the snapshot and invoke tasks from the context menu to view the source code for the component, show the listeners and set breakpoints on components.

10.8.2.3 How to Configure Java Debugger Options

You can configure the options for debugging Java applications in the Options window.

To configure Java debugging options:

1. Open the Options window by choosing Tools > Options from the main menu. (If you are running on Mac OS X, choose NetBeans > Preferences.)

2. Select the Java Debugger tab in the Java category of the Options window.

3. Select a category in the Java Debugger tab to configure the global settings for the behavior of the Java debugger.

4. Click apply in the Options window to apply the changes.

10.9.2.1 Debugger Windows and Context

Most debugger windows depend on the current context. When you change the current context, the contents of these windows are updated to reflect the new context.

For example, the Debugging window shows the threads in the current session, while the Call Stack window shows the call stack for the current thread. The Variables window shows the variables that are local to the current call, and the Loaded Classes window shows the classes that have been loaded by the current session. For more information on viewing classes and class instances, see Section 10.9.6, "Viewing Program Information When Debugging."

The exceptions are the Breakpoints and Watches windows. These windows list all breakpoints and watches set in the IDE. While the set of watches is shared by all sessions, an individual watch expression is evaluated and displayed based on the current context. For information on setting breakpoints, Section 10.9.4, "Managing Breakpoints."

For information on debugging threads, see Section 10.9.6.8, "Debugging Threads in the IDE."

For information on examining the call stack for the current thread, see Section 10.9.6.9, "Using the Call Stack."

10.9.2.2 The Source Editor and Context

When a variable is active in the current context, the Source Editor displays the value of the variable when you move the pointer over it. In cases where a program includes different variables with the same name, the Source Editor displays the value based on the current context, and not on the instance of the variable in the source code.

10.9.4.1 How to Set a Java Breakpoint

All Java breakpoints are defined globally and therefore affect all IDE projects that include the source on which a breakpoint is set. For example, if you set a class breakpoint on com.me.MyClass in one project, the IDE stops execution every time it encounters that class during a debugging session for other projects that include the class.

To set a line, field or method breakpoint in the Source Editor:

• Click in the left margin next to the line in the source code or put the insertion point in the line and choose Debug > New Breakpoint from the main menu.

A field, method or line breakpoint is created depending on if the line contains a field declaration, method declaration or other code. The corresponding breakpoint annotation is visible in the left margin next to the line of source code.

The IDE tests the validity of set breakpoints when the debugger session is starting or when a debugger session is already running. If a breakpoint is invalid the IDE uses a broken annotation to indicate the invalid breakpoint and displays an error message in the Debugger Console.

To set all other types of breakpoints:

1. In the Source Editor, select the code element on which you want to set a breakpoint.

   For example, if you want to set a class breakpoint on the class BeanCounter, select the class name in the class declaration.

2. Choose Debug > New Breakpoint (Ctrl+Shift+F8).

   The New Breakpoint dialog box opens with a suggested breakpoint type and target filled in.

3. If necessary, adjust the suggested breakpoint type in the Breakpoint Type drop-down list.

4. Enter the package and class name for which you want to set the breakpoint.

5. Set any additional options you require in the New Breakpoint dialog and click OK.

   The IDE creates the new breakpoint for the selected source element.

To modify an existing breakpoint:

1. Choose Window > Debugging > Breakpoints (Alt+Shift+5) to open the Breakpoints window.

2. Right-click any breakpoint and choose Properties to open the Breakpoint Properties dialog box.

3. Adjust any settings or actions you require and click OK.

   The IDE updates the breakpoint for the selected source element.

To enable and disable a breakpoint:

• Right-click the breakpoint in the Breakpoints window and choose Enable or Disable.

You can modify and enable line, field and method breakpoints by right-clicking the breakpoint icon in the left margin of the Source Editor and choosing from the Breakpoint submenu.

When a debugging session is running, use code completion in the New Breakpoint dialog box.

10.9.4.2 How to Set a Conditional Breakpoint

You can set conditions on a breakpoint so that execution only breaks if the condition is true. Set conditions on any breakpoint except thread breakpoints by selecting the Conditions checkbox and entering the condition. For all breakpoints you can specify how often the breakpoint is triggered by selecting the Break When Hit Count checkbox and choosing a criteria from the drop-down list and specifying a numerical value.

Class breakpoints and exception breakpoints enable you to set the following conditions:

• For class breakpoints, you can exclude classes triggering the breakpoint by selecting the Exclude classes checkbox and specifying the classes to exclude.

• For exception breakpoints, you can filter the classes triggering the breakpoint by selecting the Filter on Classes Throwing the Exception checkbox and specifying the names of classes to match or exclude.

To set a conditions on a breakpoint:

1. Create a new breakpoint or open an existing breakpoint's customizer by right-clicking its name in the Breakpoints window and choosing Customize.

2. Select the Condition checkbox and type the condition in the Condition field. The condition must follow the Java syntax rules. The condition can include anything that can be on the right side of the equal sign (=). The condition can also include variables and methods that are within the current context. The following are exceptions:

   • Imports are ignored. You must use fully qualified names, such as obj instanceof java.lang.String.

   • You cannot access outerclass methods and variables directly. Use this.variableName or this$1.

   • (Optional) Select the Break When Hit Count checkbox and choose a criteria from the drop-down list and specify a numerical value.

   Conditional line breakpoints have a icon in the left margin of the Source Editor.

10.9.4.3 How to Organize Breakpoints Into a Group

The Breakpoints window lists all of the breakpoints defined for all of your IDE projects. If you have numerous breakpoints set in the IDE, it is useful to organize these breakpoints into groups. Once your breakpoints are placed into groups, you can enable, disable, and delete them as a single unit.

To add a breakpoint to a custom group:

1. Choose Windows > Debugging > Breakpoints (Alt+Shift+5) to open the Breakpoints window.

2. Right-click the breakpoint and choose Move Into Group and select a custom group from the list.

   Note:

   To create a custom group, right-click the breakpoint and choose Move Into Group > New and type the name of the new group in the dialog box.

To remove a breakpoint from a custom group:

• In the Breakpoints window, right-click the breakpoint and choose Move Into Group > Default.

Alternatively, you can modify how breakpoints are organized from the Breakpoints window by clicking Breakpoint Groups ( ) and selecting a grouping strategy from the context window. If you choose Nested you can specify the specific groups and the order of the groups that are displayed.

10.9.4.4 About Source Maps Support

Web client JavaScript debugger and node.js debugger use generated source maps to allow debugging in the original source files.

To debug the code you wrote but not the code that is executed as compressed or translated, the IDE scans your project files to find any present source map and assure that any breakpoint set in the files which were translated for execution (for example, compressed or transpiled), are submitted to the target files. During stepping through the application, the code positions and variable names are translated according to the existing source maps.

10.9.5.1 How to Manage a Local Debugging Session

Local debugging is the process of debugging a program that is running on the same computer as the IDE. The IDE starts the debugger, then runs the application inside the debugger. When you start a debugging session, the IDE automatically opens the debugger windows and prints debugger output to the Output window.

10.9.5.2 How to Manage a Remote Debugging Session

Remote debugging is the process of debugging an application that is running on a different computer. This technique is useful when you are developing an application that runs on a web server or in a different environment than the computer on which you are developing the application.

To start a remote debugging session:

1. On the computer where the application is located, start the application in debugging mode.

2. On the computer where the IDE is running, open the projects that contain the source for the application.

3. Choose Debug > Attach Debugger to open the Attach dialog box.

4. Select the appropriate Connector from the drop-down list, enter any required process information, and click OK.

For details on the transport and connector options, see the JPDA documentation, Connection and Invocation Details, for your version of the JDK from the Java Platform Debugger Architecture home page at http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/conninv.html.

The instructions for starting an application in debugging mode and the method for connecting to the VM depends on your VM. See your VM documentation for further details.

10.9.5.3 How to Step Through Your Program

After execution of your program is halted, step through your lines of code using the commands listed in Table 10-3 in the Debug menu or the corresponding icons in the toolbar:

To view source code files potentially available to the Debugger:

• Choose Window > Debugging > Sources (Alt+Shift+8) to open the Sources window.

  The Sources window lists the source directories on your project classpath. The current source file is checked by default, meaning that the Debugger uses it during the debugging session. If you want the Debugger to be able to step into source files other than the current one, you can select those files in this window.

10.9.5.4 How to Fix and Continue in a Debugging Session

If you find a problem while debugging, you can use the Apply Code Changes command to fix your source and then continue debugging with the changed code without restarting your program.

It is not possible to use the Apply Code Changes command to do the following:

• Change a modifier of a field, a method, or a class

• Add or remove methods or fields

• Change the hierarchy of classes

• Change classes that have not been loaded into the virtual machine

To fix your code:

1. From the main menu, choose Debug > Apply Code Changes to recompile and begin repairing your source code.

   • If there are errors during compilation, nothing is changed in your program. Edit your source code as needed, then execute the Apply Code Changes command again.

   • If there are no errors, the resulting object code is swapped into the currently executing program. However, all calls on the call stack continue running the unfixed code. To use the modified code, you must pop from the call stack any calls that contain modified code. When the calls are reentered, they use the modified code.

     Note:

     If you modify the currently running method, the IDE displays an alert box. If you click Pop Call, the most recent call is removed from the current call stack. If you click Leave Call, the program executes with the original version of the code. If there is only one call in the stack, you cannot pop the call and continue. For more information on popping the call stack, see Section 10.9.6.9, "Using the Call Stack."

2. Continue the program to verify that the fixed version of your code works correctly.

The Apply Code Changes command does not automatically rebuild JAR files, executable files, or similar files. You must rebuild these files if you want to debug them in a new session.

10.9.5.5 How to Finish a Debugging Session

If necessary, stop the current debugging session using the Shift-F5 shortcut. You can also close a specific debugging session using the Sessions window.

To finish the current debugging session:

• Choose Debug > Finish Debugger Session (Shift+F5).

To finish one of several debugging sessions:

1. Open the Sessions window by choosing Window > Debugging > Sessions (Alt+Shift+6).

   The information given for each session includes the session name and state. In most cases, the state corresponds to the state of the process associated with the session. One session is always considered the current session, unless no sessions are running. By default, the current session is the session that you most recently started.

2. Right-click the debugging session you want to stop and choose Finish.

For information on local debugging sessions, see Section 10.9.5.1, "How to Manage a Local Debugging Session."

For information on remote debugging sessions, see Section 10.9.5.2, "How to Manage a Remote Debugging Session."

10.9.6.1 Using the Variables Window

For each variable within the current call, the Variables window displays information including the variable name, type, and value. Choose Window >Debugging > Variables to open this window.

The Variables window also displays all of the static fields from the present class and all superclasses for each variable, as well as all of the inherited fields from all superclasses. For information on how to a call the current call, see Section 10.9.2, "Choosing Current Context in the Debugger."

You can change the value of a local variable directly in the Variables window and then continue running your program with the new value in place.

In some cases, the debugger assigns a pound sign (#) and a number as the variable's value. This number is an unique identifier of the given instance. You can use this identifier to determine if a variable points to the same instance or to a different instance. You cannot edit this value.

10.9.6.2 Using the Loaded Classes Window

The Loaded Classes window displays the classes loaded on the heap and the percentage and number of object instances. You can sort the classes by class name or the number or percentage of instances. You can also use the filter box at the bottom of the window to filter the list by class name. If you open the Loaded Classes window when a debugging session is running, it closes automatically when you end the debugging session. If you open the window when no debugging session is running, it stays open until you close it.

The contents of the Loaded Classes window is dependent on the current context. When you change the current session, the Loaded Classes window is updated to show the classes for that session. Choose Window > Debugging > Loaded Classes to open this window.

To view information for a particular class, right-click a class in the Loaded Classes window and select Show in Instances. The Instances window displays the number of class instances, fields, and references to the class that occur in the current context.

10.9.6.3 Using the Events Window

The Events window displays the events associated with GUI form elements according to the triggering order and also displays the listeners that are associated with the event. Open the Events window by right-clicking a component in the Visual Debugger and choosing Show Listeners in the context menu.

Expand the Custom Listeners node or the Internal SWT/Swing Listeners node to view a list of listeners in the project. Right-click a listener and choose Go to Component Source to open the source file at the line where the listener is defined.

10.9.6.4 Evaluating Variables in the Source Editor

You can also evaluate a variable directly in the Source Editor by moving the insertion point over the variable. If the variable is active in the current context, the value of the variable is displayed in a tool tip. In cases where a program includes different variables with the same name, the Source Editor displays the value based on the current context, and not on the instance of the variable in the source code. Structured values can be expanded into a detailed view. Expandable tooltips feature an Expand icon ( ) on the left. Alternatively, you can expand a tooltip by pressing the Space bar.

You can track the changes in the value of a variable during program execution by setting a watch on the variable. When you create a watch, the value of the variable is immediately evaluated and displayed in the Watches window.

10.9.6.5 How to Create a Watch

A watch enables you to track the changes in the value of a variable or expression during program execution. The Watches window lists all of the watches you have defined for all of your IDE projects.

To open the Watches window:

• Choose Window > Debugging > Watches (Alt+Shift+2).

To create a watch from the Source Editor:

1. Select the variable or expression in the Source Editor, right-click, and choose New Watch (Ctrl+Shift+F7).

   The New Watch dialog box opens with the variable or expression entered in the text field.

2. Click OK.

   The Watches window opens with the new watch selected.

To create a watch from the Variables window:

1. Choose Window > Debugging > Variables.

2. Click the Create New Watch icon ( ) in the toolbar.

You can click in the Value cell to edit the value directly in the Watches window.

If you specify an expression, follow the syntax rules of the debugger that you are using.

When you create a watch, the value of the variable or expression is immediately evaluated and displayed in the Watches window. The value of the watch is based on the current context. When you change the current context, the Watches window is updated to show the value of the watch for that context.

When a debugging session is running, you can use code completion in the New Watch dialog box.

For information on how to view variable values during a debugging session, see Section 10.9.6, "Viewing Program Information When Debugging."

10.9.6.6 How to Create a Fixed Watch

A fixed watch describes the object that is currently assigned to a variable while a normal watch describes the content of the variable. Fixed watches are specific to the Java 2 debugger.

For example, consider the following code:

java.awt.Dimension dim=new java.awt.Dimension(10,20);
java.awt.Dimension newDim=dim;
dim=new java.awt.Dimension(20,30);
newDim.height=15

With the debugger stopped on the second line, you can create a normal watch on the variable dim. If you create a fixed watch on the variable dim, the watch describes the object that is currently assigned to the variable, which is java.awt.Dimension(10,20). If you press F8 to step over the code three times, the value of the normal watch becomes java.awt.Dimension(20,30). This change occurred on the third line of source code. The value of the fixed watch is java.awt.Dimension(15,20). The fixed watch was created on the object with a height of 10, but the fourth line changed the height of this object to 15.

To create a fixed watch:

• In the Variables or Watches window, right-click a variable and choose Create Fixed Watch.

  The fixed watch is added to the Watches window.

10.9.6.7 How to Pin a Watch

You can set a watch or multiple watches in your code to review a variable value in the Source Editor. The pinned watch updates its value like a watch in the Watches window and keeps the last known value even after the debugging session finishes.

To pin a watch:

1. Hover a mouse over a variable or a selected expression in the Source Editor area until the IDE displays the tooltip with the value of the variable or your selection.

2. Press the Enter key or click the Pin icon ( ) in the tooltip.

   The IDE adds a watch pinned into the Source Editor and displays a pinned watch window with two icons on the right side - the Comment ( ) and Close ( ) icons. You can drag the pinned watch window with the mouse.

To display the pinned watches in the Variables and Watches windows, right-click in either window and choose Show Pinned Watches from the context menu.

10.9.6.8 Debugging Threads in the IDE

All the threads created in the current session are displayed in the Debugging window. Choose Window > Debugging > Debugging (Alt+Shift+9) to open the Debugging window. You can also see the list of threads in the current session in the Threads window. Choose Window > Debugging > Threads (Alt+Shift+7) to open the Threads window.

The information given for each thread is the thread name, state and if the thread is suspended. One thread is the current thread. By default, the current thread is the thread in the current session from which the debugger gained control. When you select a different current session, the Threads window is updated to show the threads for that session.

10.9.6.9 Using the Call Stack

In a debugging session, you can see the call stack for the current thread in the Debugging window (opened automatically whenever you start a debugging session). If you expand the node for the current thread you can see a list of the sequence of calls made during the execution of the thread.

The information given for each call (marked by a icon) includes the name of the call, followed by the file name and line number of the call's currently executing statement. If the sources are available, you can right-click the call and choose Go To Source to go to the source code of the call.

Alternatively, you can open the Call Stack window by choosing Window > Debugging > Call Stack (Alt +Shift+3).

10.9.6.10 How to Evaluate Code

When you are in a debugging session, you can evaluate any code snippet to view the values of local variables for the current method, class variables, and method calls.

You can view the values returned by each method call in the expression by stepping through an expression.

To evaluate an expression:

1. Start a debugging session.

2. Choose Debug > Evaluate Expression (Ctrl+F9) from the main menu.

3. Type a code snippet in the Evaluate Code window and click in the bottom right corner of the window). The result is shown in the Variables view. The result with historical values is shown in the Evaluation Results view.

   Click the Create New Watch button ( ) in the Variables view to set a watch for the expression. The watch is added to the Watches view.

If you evaluate a method that changes a global variable, the global variable's value is changed in the debugging session as well.

If you try to evaluate a variable that is outside the scope of the current method, a message displays "variable" is not a known variable in current context. Use the Call Stack window to change the current method context.

If you try to access a global variable before the file that contains the variable is instantiated, a message displays Cannot access instance variable "variable" from static context.

10.9.6.11 How to Step Through an Expression

When you are in a debugging session, use the Step Over Expression command to step through an expression and view the values returned by each method call in the expression.

Use the Step Over Expression command to achieve a more fine-grained stepping than other debugging steps. Step Over Expression enables you to proceed through each method call in an expression and view the input parameters and resulting output values of each method call. Invoke the Step Over Expression command just as you would any other step commands. If there are no further method calls, Step Over Expression behaves like the Step Over command.

Each method call in an expression has some input (parameters) and output values. Each time you use the Step Over Expression command in an expression, the debugger resumes VM execution and then stops before executing the next method call. You can inspect the output values for the previous method and the input parameters for the next method in the Variables window. Invoking Step Over Expression again resumes the VM execution until the next method call in the expression.

To step through an expression:

1. Place a breakpoint in the line containing the expression you want to debug and start the debugging session.

   When you start the debugger, the VM stops before executing any of the method calls in the expression.

2. Choose Debug > Step Over Expression (Shift+F8) from the main menu.

   The debugger steps to the first method call in the expression but does not execute the method. The Variables window displays the input parameters of the method.

3. Invoke Step Over Expression again to execute the first method and step to the next method call in the expression.

   The Variables window displays the output values of the executed method and any input parameters for the next method in the expression.

   In the Source Editor, the executed method call is underlined and the next method call in the expression is highlighted. Mouse over the executed method to display a tooltip and view the output values.

4. Invoke Step Over Expression again to step to the next method call in the expression.

   The Variables window displays the output values under the Return Values node.