Effective Java Debugging with Eclipse

Effective Java Debugging with Eclipse

Learning to write code efficiently is only one step towards becoming a coding master. Another step is learning to debug. When it comes to legacy or 3rd party code you will need to debug in order to understand how the code behaves. In this post I will give you some basic tips on how to master your debugger and become more efficient.

This is a follow up to My Top 10 Tips on how to be more productive with the Eclipse IDE (which you should read before this one). I’ll assume you already know how to launch a Debug configuration for your project in your Workspace.

Note: Click on the images to reveal a larger screenshot.

1. Breakpoints

Basic Breakpoints
This is essential and you probably already know how to use it – the Breakpoint.

In case you’re not familiar with them, you create a breakpoint by double-clicking on the left side of a line of code. The execution of your application will then halt at that point so you can analyze the state and hopefully find the cause of your misbehaving code.

Exception Breakpoints
Sometimes an exception occurs, but you are not sure where (e.g. no stack trace available) or the exception is not logged and not visible. This is the right time to create a global breakpoint that pulls the hand brake if a certain exception occurs.

You’ll find this in the Breakpoints view of the Debug perspective.

Conditional Breakpoints
To speed up debugging by not stopping at a breakpoint everytime, you can add a condition. The breakpoint will only stop your application if the condition is fulfilled – and will not unnecessarily disturb your hunt for the bug.

You can get there with a right-click on your break point > Breakpoint Properties...

2. Detail Formatter

While debugging and inspecting variables/objects in your debug perspective, you might encounter textual representations of objects that are not really meaningful. Usually the .toString() method on an object is used for the debug UI. It’s not the greatest idea to implement the .toString() method just for debugging purposes. Instead you can set up a detail formatter that takes care of the textual representation of your object.

You can get there by right-clicking on the variable in the Variables view, then selecting New Detail Formatter....

3. Logic Structure

Here you can see what a difference a small click can make. Both Views show the same Map object. By activating Logic Structure in your Variables view, you get the “contents” and structure of objects presented as you would expect it for a human reader.

4. Drop To Frame

In case your application stopped at your break point and the interesting things had already happened, you can “Drop To Frame”. This means you can jump back in your stack and then start debugging from there…

5. Inspect and Watch

Inspect provides you basically with the same functionality as the Variables View – you can unfold and inspect the various values of the object. Watch on the other hand enables you to observe a specific Object and see how it changes over time.

6. Change Variable Values

The Variables View can do more than just display values. You can also edit values. I don’t think there is much more to say about it 😉

7. Step Into, Over and Return – Shortcuts

Try to memorize the following function keys. They will greatly speed up your debugging by avoiding constantly having to use your mouse.

  • F5 – Step Into
  • F6 – Step Over
  • F7 – Step Return
  • F8 – Run until next breakpoint is reached

8. Step Filtering

Step Filtering
With “Step Filters” you can filter out types that you do not wish to see or step through while debugging. This helps you to stay focused on the actual code and does not expose you to the inner workings where you might not even have the source. Have a look at Holger’s Effective Mockito post about Step Filtering in conjunction with Mockito.

You’ll find this in: Preferences > Java > Debug > Step Filtering

9. Remote Debugging

With Remote Debugging you can debug an application running on a different machine. The debugging itself is like any other app that you usually launch from within Eclipse. This is what you need to do:

  1. Make sure the source code on your machine and the application on the other machine are in sync.
  2. Start the application on the other machine with the following command line parameters:
    java -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005

    suspend=y/n declares whether the JVM of the application you want to debug will wait for Eclipse to connect or if it will start right away.
    address=5005 configures the TCP port to use for remote debugging.

  3. Create a Remote Java Application Debug Launch Configuration.
  4. Specify the Host and Port for your remote application.
  5. Add all the source projects of the application you want to debug to the Source tab.

10. Heap dump + Memory Analyzer

Sometimes you need a bigger picture of the inner workings of your application than you can get with line-by-line debugging – especially for finding memory leaks. In this case you are better off with the Eclipse Memory Analyzer (MAT). My colleague Ian wrote a blog post about how to create a heap dump and analyze it.
Update 21.01.2013: Ian just published an other more detailed article about the Eclipse Memory Analyzer: "10 Tips for using the Eclipse Memory Analyzer"

These are just a few tips regarding debugging. If you have feedback or something to add, please feel free to leave a comment below.

  • Aurélien Pupier
    Posted at 13:20, 2013-01-08


    Cool, just discovered Logic Structure and it is really nice. Thank you.

    FYI, about Heap Dump, MAT has a built-in and simpler way to create a dump directly from the UI. See my blogpost https://www.bonitasoft.org/blog/eclipse/acquire-heap-dump-from-mat/


  • Riccardo Cossu
    Posted at 13:30, 2013-01-08

    Thanks for the tips, I never used n.4 before, but it seems really helpful.

    There’s more about conditional breakpoints, I think I will write something about it 🙂

  • Javin
    Posted at 13:44, 2013-01-08

    Fantastic tips, must known for any Java developer working in Eclipse. Conditional breakpoint, along with Exception breakpoint is my favorite tip which helps to stop any particular thread, very helpful during multi-threaded debugging. I have also shared few tips here https://goo.gl/H5Li0, you may like.

  • Aaron Digulla
    Posted at 18:31, 2013-01-08

    If you need to debug a complex bug, have a look at Chronon (https://chrononsystems.com/). It records all state changes of your code and allows to move freely along the timeline. So it can answer questions like:

    – Show me who called this method
    – How often was this exception thrown and where?
    – Show me a list of all the arguments that a method was called with
    – Jump to the place in the code where a certain byte was written in a file

  • Pierre-Charles David
    Posted at 19:30, 2013-01-08

    A technique I find very useful is to use conditional breakpoints to add tracing witthout changing an application’s source. Simply define an expression of this form:

    System.out.println(“Something useful here.”);
    return false;

    In this simple case the breakpoint will never stop the program. You can enable/disable the trace simply by enabling/disabling the breakpoint. And because you don’t need to change to source for this, this can be used to add traces even in compiled plug-ins, for example from the platform itself.

    Also important to note: you can define your own logical structures, either directly in the Eclipse Preferences (Java > Debug > Logical Structures), and both detail formatters and custom logical structures can be contributed by extension point. In our team we have defined custom ones, for GMF for example, in a plug-in that everybody can install in their dev environment.

  • Jordi Planadecursach
    Posted at 01:17, 2013-01-09

    3. Logic Structure!!! this one should be published. How much I hate going thru de maps. This single click will prevent my white hairs to appear.

  • Sebastien Ganfon
    Posted at 10:27, 2013-01-14

    I really like the use of Conditional Break points to add logs without modifying the code. They are also useful to add so Thread.sleep during multi-threaded debug.
    One thing I m missing though is the ability to set a break point at a certain line in a class without having the source code. Sometimes you are having issues in third parties libraries and would like to inspect variables there but I have not found a way to set line break points in classes I do not have the source code for.

  • Huong
    Posted at 20:52, 2013-03-18

    What versions of Eclipse and Java are you using?
    I have Java 7, Eclipse Juno as well as Indigo but the debugger doesn’t stop at break points. Look forward to your response. Thanks.