Using the Debugger

Before you are able to debug your project, the code needs to compile and run cleanly. You first need to create a run configuration for your application and to make sure that it starts properly. Next, you need to set up the debug configuration in a similar way using the Run > Debug... menu. You also need to select the class to be used as the main Java class by the debugger (see also Figure 14-2). You can have as many debug configurations for a single project as you wish. When the debugger is started (from Run > Debug... ), it is opened in a new window, and you are ready to start debugging.

Figure 14-2. Setting the project's main Java class in the debug configuration

Setting Breakpoints

When you launch your application for debugging, Eclipse automatically switches to the Debug perspective. The most common debugging procedure is undoubtedly to set breakpoints that will allow the inspection of variables and the values inside conditional statements or loops. To set breakpoints in the Package Explorer view of the Java perspective, double-click the selected source code file to open it in an editor. Walk through the code and place your cursor on the marker bar (along the left edge of the editor area) on the line including the suspected code. Double-click to set the breakpoint (see also Figure 14-3). Now start the debugging session from the Run > Debug... menu. It is important not to put multiple statements on a single line because you cannot step over or set line breakpoints on more than one statement on the same line.

Figure 14-3. Breakpoint markers visible in the left margin of the editor

Inspecting Variables

The Variables view (in the Display window) displays the values of the variables in the selected stack frame (see Figure 14-4).

Figure 14-4. Viewing variables in the Display window

To view a requested variable, simply expand the tree in the Variables view until you can see the requested element. You can also watch variables in the Variables view as you step through the code in the Debug view. When the debugger stops at a breakpoint, you can continue the debugger session by selecting the Step Over option from the Run > Debug... menu (see Figure 14-5).

Figure 14-5. Debugger commands in the Run... menu

This steps over the highlighted line of code and continues execution at the next line in the same method (or it will continue in the method from which the current method was called). To suspend the execution of threads in the Debug view, select a running thread and Click the Suspend button in the Debug view toolbar. The current call stack for the thread is displayed, and the current line of execution is highlighted in the editor in the Debug perspective. When a thread is suspended, the cursor is placed over a variable in the Java editor and the value of that variable is displayed in a small hovering window. Also, the top stack frame of the thread is automatically selected and the visible variables in that stack frame are displayed in the Variables view. You can examine the appropriate variable in the Variables view by clicking its name.

Remote debugging

The Eclipse debugger offers an interesting option for debugging remote applications. It can connect to a remote VM running a Java application and attach it to the internal debugger. Working with a remote debugging session is for the most part similar to local debugging. However, a remote debugging configuration requires different settings in the Run > Debug... window. You need to first select the Remote Java Application entry in the left-hand view and then click the New button. A new remote launch configuration is created and three tabs are shown: Connect, Source, and Common.

In the Project field of the Connect tab, select which project to use as a reference for the launch (for source code lookup). In the Host field of the Connect tab, type the IP address or domain name of the remote host where the Java program is running. In the Port field of the Connect tab, type the port where the remote VM is accepting connections. Generally, this port is specified when the remote VM is launched. Select the Allow termination of remote VM option when you want the debugger to determine whether the Terminate command is available in a remote session. Select this option if you want to be able to terminate the VM to which you are connecting. Now when you select the Debug option, the debugger attempts to connect to a remote VM at the specified address and port, and the result is displayed in the Debug view.

If the launcher is unable to connect to a VM at the specified address, an error message appears. In general, the availability of remote debugging functionality depends purely on the Java VM (Virtual Machine) that runs on the remote host. Figure 14-6 shows the setting of connection properties for a remote debugging session.

Figure 14-6. Setting connection properties for a remote debugging session