Learn To Use the Eclipse Debugger



Mark Dexter

Eclipse & Java: Using the Debugger

The link to the Camtasia movie tutorial where each note is found follows that note. If you are confused by the note or don't understand what it is referring to, you may puruse that tutorial to refresh your memory.

Debugger is a set of tools that allows us to:
      * pause a running program at any point.
      * examine the contents of the variables.
[ Lesson 01 ]

To display line numbers:   Window → Preferences... → General → Editors → Test Editors → Check the box "Show line numbers" → OK [ Lesson 01 ]

To set a breakpoint:   Double click on gutter to immediate left of line of source code. Breakpoint tells debugger to pause at this point. To eliminate a breakpoint:   Double click the breakpoint. [ Lesson 01 ]

To START a debug session:   Run → Debug As → Java Application → Editors → There appears the dialog box "Confirm Perspective Switch" → Check "Remember my decision" → Yes Eclipse switches to the Debug perspective. [ Lesson 01 ]

To STOP a debug session:   Press the stop button (red square). [ Lesson 02 ]

To start a NEW debug session:   Press the Debug Button (looks like an insect "bug"). [ Lesson 02 ]

Debugger's Debug View:   shows
      * Class being run.
      * Thread being run.
      * Stack Frame(s) - where we are in the program.

To work the Debug View:  
      Resume button continues execution until another breakpoint or end of program.
      Terminate button stops the debug session.
      Step Into <F5> button moves into the method or constructor being called and pauses.
      Step Over <F6> button executes current line of code and stops at next line.
      Step Return <F7> button finishes the current method and returns to the calling method.
[ Lesson 01 ]

To go to another line without using a breakpoint → Use the "Run to Line" command:   Select (click on) the target line → Run (or Right Click) → Run to Line <Ctrl><R> [ Lesson 02 ]

Debugger's Job Editor: highlights line of code that we are about to execute. [ Lesson 01 ]

Debugger's Outline View: [ Lesson 01 ]

To set up Debug Filters to skip Java language classes and third party libraries:   Right click in Debug Window → Edit Step Filters... → Check box "Use Step Filters → Check box "Java.*" → OK   This filters out any packages starting with the word "Java" and thereby lets us skip all of the "Java" related stack frames. Note, back in the Debug Window, that the "Use Step Filters" button is now toggled on. Ensure that it is on when you want the filters to be operational. [ Lesson 02 ]

Debugger's Stack Frames (in the Debug View): The top stack frame in a stack always point to where we are presently. A new stack frame is added to the top of the stack when entering a constructor or method. The top stack frame is removed when returning from a constructor or method. Selection of Stack Frame correspondingly changes the members in the Variables View and the selected line in the Editor View. [ Lesson 02 ]

Debugger's Variables View (Upper right portion of screen) let's us see the value of variable in real time: [ Lesson 01 ] Variables are defined (ie: "in scope") corresponding generally to the currently selected stack frame (Debug View) and specifically to the currently selected source code line (Editor View). Variables and their values change as you step through the code. Detailed Pane of Variables View: Select a variable or object → Notice the display in the lower portion ofthe view, aka "the detailed pane" → This is the output of the toString() method of the selected variable.   Menu of Variables View: Select options from the two submenus, "Java" (which members to display) and "Layout". [ Lesson 02 ]

To inspect the value of an object that is in scope:   [ <Ctrl><Shift><I> ] or Select (click on) the object → Right Click → Inspect   View values of variables (Variables View) [ Lesson 02 ]

Add a Dynamic Watch Expression:   To see the value of an expression that is not a simple variable Window → Show View → Expressions Right Click → Add Watch Expression... Type any expression → OK   Values will change dynamically as you step through the code. [ Lesson 03 ]

Add a Static (Snap Shot) Watch Expression:   Window → Show View → DisplayNotice Display View has opened at the bottom of the screen Type any expression (can use Code Assist) → Highlight the expression → Right Click → InspectWe see values in the pop-up window → <Ctrl><Shift><I> → moves everything to the Expressions View → Will NOT change dynamically as you step through the code unless you do this: → Right mouse click → Convert to Watch Expression. [ Lesson 03 ]

Add Dnynamic code to the Display Window:   Window → Show View → DisplayNotice Display View has opened at the bottom of the screen.Type any Java code (can use Code Assist). → Highlight the expression. → Right click. → Execute →   Output is printed in the Console View just as if running from a Java application. [ Lesson 03 ]

Selecting Valid Parts of an Expression → Highlight top-most part of an expression → then drill down one level at a time:   Place cursor anywhere on the expression → <Alt><Shift><UP> To restore previous selection:   Place cursor anywhere on the expression → <Alt><Shift><DOWN> [ Lesson 03 ]

Debugger's Breakpoints View (Upper right portion of screen):   Can toggle breakpoints on and off, create new breakpoints or delete breakpoints. Add Java Exception breakpoint:     Click Java Exception Breakpoint Button (just above Breakpoints View) OR → Run → Add Java Exception Breakpoint... → Opens a Java Exception Breakpoint dialog box   Type the kind of exception to look for { Note: With JUnit Tests, always use caught exceptions since all JUnit Tests are caught exception. ] → Click on the "Matching Item" selection → A NullPointerException is added to the Breakpoints View. Change Java Exception breakpoint Properties:     Go to Brealpoints View → Right click on a particular exception → Breakpoint Properties... → You see the Java Exception Breakpoint Properties dialog box. → Check/uncheck as desired → OK [ Lesson 04 ]

To Terminate & Relaunch a Debug Session:   Right click in the Debug dialog window. → Terminate and Relaunch [ Lesson 04 ]

Hot Code Replace:   Change code in debugger. → Resume [ Lesson 04 ]

To go back to beginning of method:   Click "Drop To Frame" button. [ Lesson 04 ]

Set number of times to bypass breakpoint before suspending execution:     Breakpoints tab → Right click the breakpoint → Breakpoint Properties... → Enter number of times to bypass breakpoint. → OK [ Lesson 05 ]

Conditional Breakpoints (suspend only if condition is true):   Set number of times to bypass breakpoint before suspending execution:     Breakpoints tab → Right click the breakpoint → Breakpoint Properties... → Type condition ( Example: this.getBooksForPerson( p1 ).size() > 0 ) → OK [ Lesson 05 ]

Watchpoints (field breakpoints):   This is useful for identifying where a certain value is used or changed. Set one watchpoint instead of setting multiple breakpoints!   Click in trough beside name of a field Click on Debug Perspective → Breakpoints tab → Right click breakpoint → Breakpoint Propertis dialog appears → May suspend on Field Access or on Field Modification → OK Execution suspends whenever that field is accessed. [ Lesson 05 ]

Set breakpoint only the first time that a new class is loaded:     Click in trough beside name of a class. [ Lesson 05 ]

Stop in Main Breakpoint:   Set breakpoint at first line of code, which is upon entering the main method.   Run → Open Debug Dialog... → Java Application → Class (eg: MyLibrary) → OPens the run configuration dialog → Check Stop in main → Debug   Execution will now always stop at the first line of code in the main( ) method. [ Lesson 05 ]

Suspend a program during a debug session at any moment     Press the Suspend Button. [ Lesson 05 ]

Step into Selection     Hold <Ctrl><Alt> → Hover over name of method → Name of method turns into a hyperlink → Click hyperlink with mouse → You will step into the method. → OR → Select name of method → <Ctrl><F5> [ Lesson 05 ]

See source code without Debugger stepping into the selection. Works in Editor and does not require that there be a Debugger session working.     Select name of method → Press <Ctrl> and hover over name of method → Name of method turns into a hyperlink → Click on method hyperlink &rarrr; Source code of method then opens.   Note that position of Debugger has not moved at all. [ Lesson 05 ]

Configure Eclipse to use a special version of a JRE (Java Runtime Engine) that will allow us to Debug into Java classes.   This allows us to study the source code of the standard Java libraries.   This allows us to step into and study the code of the top Java programmers themselves!     Window → Preferences → Java → Installed JREs → Observe that you have your standard JRE installed. → Add... → JRE Type: Standard VM → JRE Name: Debug JRE → Browse... → Go to the JDK home directory. Example: C:\Program Files\Java\jdk1.6.0_01Expand (click "+") and observe that you have both source code and Javadocs. → OK → Keep the standard JRE as the default for new projects by leaving it checked. Do not place a check beside the new Debug JRE. → OK → Now add the Debug JRE to the project. → Select the project → Project → Properties → Java Build Path → Libraries tab → Add Library → JRE System Library → Next> → Click radio button to select Alternate JRE → Select Debug JRE → Finish → We will now remove the standard JRE. → Click on the standard JRE → Remove → Standard JRE is only removed from the project, not the system! → OK   Now when you look at your project, it says JRE System Library [Debug JRE]Eclipse rebuilt the project using the new Debug JRE.   We can now debug right into the Java System classes. [ Lesson 06 ]

Use the Debugger to Study Object references and the String .equals( ) method. [ Lesson 06 ]

Run a recursive method in debug mode to learn more about how recursion works.   A recursive method is a method that calls itself (that calls itself, that calls itself ....) Some value(s) change during the calls to eventually end the program, otherwise the program would never end.     Open the factorial method in the MyUtilities class. → Note that this method works only if n<=12 since the maximum value that a Java integer can be is 2,147,483,647.     Press resume → Observe the creation of a new stack frame on top as you call the new method again, going one level deeper into the program. → Notice that the variable "result" does not take on a value while the method continues being called because it has not yet been evaluated. → Continue pressing resume observing the value of n decreasing until it becomes less than 1 → Step over → The base case (n<=1) kicks in, ending the recursive process → This is where we BEGIN doing our calculation → Step over until n=2, then we find our first stack value for result (result=2) → Press "Step Return" to get out of that stack frame, noting that n=3 → Step over, noting that result=6 → Step Return and Step Over again to see n=4, result=24 → Step Return and Step Over again to finally get n=5 and result=120 [ Lesson 07 ]

Run a recursive method in debug mode a second time for more explanation. (Begin at time 6:20 of lesson #7.)     Click the Debug button. (It looks like an insect type bug.) → Click the resume button until you get to n=1. → Think of it this way → Each time that we call the recursive method, we add another frame on top of the stack until we eventually get to the point where n=1. Up until this point, no real calculations have been done. The frames are just holding the places for the yet-to-be-determined return values from the factorial (recursive) methods. When we finally get the the value n=1, we will not return any more stack frames because we are just going to return the value of 1. Since the top frame can now return the value of 1, the result is returned from the top frame to the frame just below it. That is when the actual calculation(s) take place.

Thus there are two parts to processing a factorial method:

  1. Add stack frames for each method call until the method stops calling itself.
  2. Return the result from the top frame to the one below, remove the top stack, and continue returning results until we are back to the original calling method.

There are thus two conditions for recursive methods.

  1. The method must eventually stop calling itself.
  2. You need enough memory to hold the stack frames. [ Lesson 07 ]

Rewind the Program Back to An Earlier Frame. Take another look at the Drop To Frame command.   Rerun the debug session.   Press resume until n=1. → In lesson 4, we learned that pressing the "Drop to Frame" button would "rewind the debug session" by pressing a previous line in the Editor View and then pressing the "Drop-to-Frame" button. → OR → Select a lower stack frame and go back to that frame. → Remember that the top stack frame is where we are right now in the program. Thus each lower stack frame is from an earlier point in the program. Therefore selecting a lower stack frame takes us back in time. → Clcik on a lower stack frame → Click on the Drop to Frame button. → The program returns to that point in the program. → There are some things that are done in a program that prevents rewinding the program. The the Drop to Frame button becomes disabled. [ Lesson 07 ]

Uses of Drop to Frame Button if the Program Can Be Rewound

  1. Select an earlier line in the Editor View.
  2. Select a lower stack frame. [ Lesson 07 ]

Testing and Debugging

Test-Driven Development
  1. Think about what the method should do.
  2. Write a test case that will test this method.
  3. Write the new method.
  4. Test the new method.
  5. When it passes ... we're done!

... the unit tests document the program without the need to maintain separate written documentation that can easily become out of date.

Mark Dexter, Using Test-First Development

  1. Start a debug session.
  2. Set and use breakpoints.
  3. Navigate through a program with step commands.
  4. Examine variables and expressions.
Mark Dexter, Eclipse & Java: Using the Debugger

Follow and implement the lessons and activities of Mark Dexter's seven 15-minute tutorials of Using the Debugger [csg] [web]

Refer to this Tutorial Companion Guide [pdf].
Import this DebuggerTutorial project into your Eclipse workspace. Click here for directions.
  1. Startup, Step Over, Step Into, Step Return [End Prj 01]

  2. Examine Contents of Variables [End Prj 02]

  3. Add Watch Sessions, JUnit Tests [End Prj 03]

  4. Exception Breakpoints, Change Values [End Prj 04]

  5. Breakpoint Options, Watchpoints [End Prj 05]

  6. Debug into Java System Classes → Object references and the equals( ) method. [End Prj 06]

  7. Study Recursion, Stack Frames → Anatomy of a recursive method. [End Prj 07]

Create A "New" Project From An Existing Project

These are really "backups of prior stages" of a single, cumulative project. It would be tragic if, upon experiencing a "bug" during tutorial #12 that could not be corrected, you had to redo all eleven prior tutorials in order to continue the project. Taking a few moments at the beginning of each new stage of the project (each new tutorial) ensures that you always have a "last good stage" that is only one tutorial away. This also facilitates later review of code of a specific tutorial at that particular stage of development.

  1. Create a new project:   File → New → Project.. → Java → Java Project → Next → Project Name: TB12 → Create new project in workspace → Select a JRE (Java Runtime Environment) → Select Project layout → Finish

  2. Copy path of location of source project:   Right mouse click name of project → Properties → Select ("highlight") the location (eg: "H:\TotalBeginnerProjects\TB11") → Copy with <Ctrl-C> → Cancel

  3. Open the Import Wizard:   Select ("highlight") name of new project → From the main menu bar, select File → Import....

  4. Select Type of Resources To Import:   General → File System → Next.

  5. Specify Path and Files To Import:   Identify source directory as the "From directory:" → Paste <Ctrl-V> location of the source project (eg: "H:\TotalBeginnerProjects\TB11") → Click the "Browse..." button → The "Import from directory" dialog box appears with name of source folder → Click "OK" → Click the "Select All" button → Type name of "Into folder" (existing destination folder) if it is not already there. → Check ✓ "Overwrite existing resources without warning" → Select "Create selected folders only" → Finish



MIT Tutorial [pdf]
[csg] [web]

This excellent tutorial introduces the Eclipse Java Debugger.



UBC Tutorial
[csg] [web]

This excellent tutorial introduces the Eclipse Java Debugger.



Leszek Tutorial
[csg] [web]

This excellent tutorial introduces the Eclipse Java Debugger.



Wisconsin Tutorial
[csg] [web]

This excellent tutorial introduces the Eclipse Java Debugger.



Dave Quigley Tutorial
[csg] [web]

This excellent tutorial by Stony Brook University's Dave Quigley introduces the Eclipse Java Debugger.



Omniscient Debugging

This is not an Eclipse Debugger plug-in, but this does look like a really interesting debugger though. On 18 February 2007 the author, Bil Lewis <Bil@LambdaCS.com> made the following statement regarding its use with Eclipse.

Eclipse will launch the ODB from the RUN menu. [Import the ODB, set the main class to be com.lambda.Debugger.Debugger, and set the argument to be the program you want to run. (It's a bit lame, but simple. I am begging some folks for help with Eclipse.) I expect the same can be done for other IDEs.]

URL:   http://www.comscigate.com/    Last Revised:  February 4, 2006