Sometimes while debugging, you may have wanted to stop at a breakpoint only when a certain condition applies. To do this you may have used following coding pattern:

public void doSomething(Message message) {
    if (message == null) {
    	System.out.println("message is null");
    }

    // Do something with message that doesn't handle nulls well, eg...
    if (message.isFormatted() {
        //...
    }
}

It turns out lines 2-4 are temporary lines that will be removed later. They are only required for debugging so you can set a breakpoint on line 3. Although effective, this approach has its drawbacks. Firstly, you’re adding temporary code to production code and have to remember to remove it before checking in the eventual fix. Another problem arises if you want to stop only after a method has been called n times. You can introduce counting code but you’re stuck with the same problem as before.

There’s an Eclipse feature called conditional breakpoints that makes this a lot easier. The condition is attached to the breakpoint so doesn’t interfere with existing code and you can stop conditionally after a number of calls.

How to create a conditional breakpoint

To create a conditional breakpoint, first set a breakpoint on a line (Ctrl+Shift+B), right-click on the breakpoint and select Breakpoint Properties. Then configure a condition that returns a boolean. Eclipse only stops if the conditions returns true.

The the easiest way to see it work is via the following video. It shows how to add a breakpoint that stops in the method process, a method that’s called 3 times from a main method (for Car, House and Boat). The breakpoint only stops when the method is called with the string House. The sysouts in the console confirm that the breakpoint only activates when House was passed.

Notes:

• The condition must evaluate to/return a boolean and you don’t need to put it in an if statement. The condition can be as complex as you want to make it, combining && and ||.
• If the normal flow allows for the field to be null, use null-checking to avoid an unnecessary error popping up, eg. model != null && model.equals(“House)
• You can use autocomplete (Ctrl+Space) in the condition text box.

Other conditions: Stop after a number of calls or a field/expression value changes

You should find that the conditional code works for 90% of your requirements. But Eclipse does provide other conditions to cater for the other situations.

If you want to stop a breakpoint only after the line has been executed a certain number of times, select Hit Count and enter a number. This is handy for running through loops where you’re only interested in, say, the 2nd iteration. Also use it when you know a method shouldn’t be called more than n times in a scenario but suspect a bug is causing it to be called more than n times.

Hit Count and your Condition are AND’ed together, so it normally only makes sense to use the one or the other. Eclipse will only stop at the breakpoint if the breakpoint’s been hit n times and the condition is true.

If you want to stop only when the value of a field or expression changes, select value of condition changes under Suspend when. In this case, the condition doesn’t have to evaluate to a boolean. You can use this to evaluate a single variable or a full expression, combining && and || (to break on single field changes, rather use Eclipse’s Watchpoints feature).

Breakpoint conditions are normal Java code

The breakpoint condition consists of normal Java code, ie. with scope restrictions and the possibility of compilation/runtime errors. The condition’s scope is the same as the location at which the breakpoint is placed, so you can access variables and methods as you would be able to from code where the breakpoint is placed.

The condition can be as complex as you want to make it (eg. combining && and ||) and can even consist of multiple lines (yes, you can even put sysouts in them). Just ensure that the code eventually evaluates to/returns a boolean.

If there is an error in the condition, Eclipse will pop up a message similar to the following (only when hitting the breakpoint):

You should investigate your conditional code to make sure you don’t have a compile/runtime error. NPE is a common cause for error but you could also get compilation errors (eg. you misspelled a variable name). Click Edit Condition to correct the breakpoint.

Related Tips

• Skip over certain classes when using Step Into in Eclipse’s debugger
• Always run/debug the last launched class instead of the selected one in Eclipse
• Run/debug a class in Eclipse as a JUnit test or Java app with a single keystroke
• Disable Eclipse formatting for certain sections of code only
• Jump to the start and end of methods, loops, blocks and XML tags