Eclipse Debugging. This article describes how to debug a Java application in Eclipse.

1. Overview

1.1. What is debugging?

Debugging means running a program interactively while you watch its source code and variables.

A breakpoint marks a line where the program stops. While it is stopped, you can inspect and change variables.

A watchpoint stops the program when a field is read or modified.

1.2. Debugging support in Eclipse

Eclipse starts Java programs in debug mode and lets you control their execution with debug commands. The Debug perspective arranges the views you need for this.

1.3. Setting breakpoints

To set a breakpoint, right-click the left border of the Java editor and select Toggle Breakpoint, or double-click the border.

The following screenshot shows a breakpoint on the line Counter counter = new Counter();.

1.4. Starting the debugger

Right-click a Java file with a main method and select Debug As Java Application.

Afterwards, the Debug button in the tool bar starts the same launch configuration again.

Without breakpoints, the program runs as usual. When the program reaches a breakpoint, Eclipse asks whether to switch to the Debug perspective. Answer Switch.

1.5. Controlling the program execution

The tool bar buttons and the following shortcuts control the execution.

Table 1. Debugging shortcuts
Key	Description
`F5`	Step into: runs the current line; if it calls a method, the debugger stops in that method.
`F6`	Step over: runs the current line, including any method call, and stops at the next line.
`F7`	Step return: finishes the current method and stops in its caller.
`F8`	Resume: runs until the next breakpoint or watchpoint.

The following picture shows these buttons in the tool bar: Resume, Step Into, Step Over and Step Return.

The Debug view shows the call stack, which is the chain of method calls that led to the current line.

1.6. Breakpoints view

The Breakpoints view lists all breakpoints and watchpoints. Clear the checkbox of a breakpoint to deactivate it, or delete it via the view’s tool bar.

The Skip All Breakpoints button deactivates all breakpoints at once; press it again to reactivate them.

1.7. Inspecting variables

While the program is stopped, the Variables view shows the fields and local variables of the selected stack frame.

After a step over a method call, the view also shows the method’s return value.

The view menu can show static variables.

It also configures the columns. For example, select Layout Select Columns… Actual Type to see the runtime type of each variable.

Showing the actual type of the variables

1.8. Changing variable values

You can change the value of a variable in the Variables view while the program is stopped.

The Variables view uses toString() to show a value. If this shows something like com.vogella.combug.first.Counter@587c94, define a detail formatter: right-click the variable and select New Detail Formatter….

Enter a Java expression for the output, for example a call to getResult().

2. Advanced debugging

2.1. Breakpoint properties

Right-click a breakpoint and select Breakpoint Properties…. A hit count stops the program only when the breakpoint is reached that many times. A condition stops it only when a Java expression evaluates to true. As the condition runs every time the line is reached, you can also use it for logging.

2.2. Watchpoints

A watchpoint is a breakpoint on a field. Double-click the left border next to the field declaration to set one. In its properties, choose whether it stops on read access, on modification, or both.

2.3. Exception breakpoints

An exception breakpoint stops when an exception is thrown. Click Add Java Exception Breakpoint in the tool bar of the Breakpoints view to create one.

You choose whether it stops for caught exceptions, uncaught exceptions, or both.

2.4. Method breakpoints

Double-click the left border next to a method declaration to set a method breakpoint. It stops when the method is entered, when it exits, or both.

2.5. Class load breakpoints

A class load breakpoint stops when a class is loaded. Double-click the left border next to the class declaration, or right-click the class in the Outline view and select Toggle Class Load Breakpoint.

2.6. Step filters

Step filters skip packages when you step through code, for example the classes of a test framework. Configure them in Window Preferences Java Debug Step Filtering.

2.7. Remote debugging

Eclipse can debug a Java program running in another JVM, also on another machine. Start that program with the debug agent:

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005 -jar app.jar

suspend=y makes the program wait until the debugger connects.

In Eclipse, open Run Debug Configurations… and create a Remote Java Application configuration with the host and port.

You need the source code of the program in your workspace.

2.8. Drop to frame

Drop to Frame restarts the execution at a stack frame you select in the Debug view, so you can run part of the program again. Right-click the frame and select Drop To Frame.

Only the stack is reset. Fields and external state, such as database entries, keep their values.

For example, if you drop to the frame of count(), the for loop restarts, but the field result keeps its value.

3. Exercise: Debugging

3.1. Create the project

Create a Java project called com.vogella.combug.first with the package com.vogella.combug.first and the following classes.

package com.vogella.combug.first;

public class Counter {
  private int result = 0;

  public int getResult() {
    return result;
  }

  public void count() {
    for (int i = 0; i < 100; i++) {
      result += i + 1;
    }
  }
}

package com.vogella.combug.first;

public class Main {

  public static void main(String[] args) {
    Counter counter = new Counter();
    counter.count();
    System.out.println("We have counted " + counter.getResult());
  }
}