The Debug Model

Overview

The debug platform defines the standard debug model - a collection of Java interfaces modeling objects and operations common to many debuggers. Additionally, it provides a set of views and actions that operate on the standard model. Each debugger provides an implementation of the model interfaces. This allows many debuggers to shared the same user interface (the Debug perspective) and promotes a similar look and feel between debuggers. Clients provide an implementation of a model and get a major portion of their user interface for free. Of course, clients may contribute views and actions to customize and enhance features specific to their debugger.

Model Elements

Elements in the standard model have a hierarchical relationship and extend the base IDebugElement interface.

API's for retrieving model content are synchronous. This means the methods block while content is retrieved, abstracting remote connections/communication (for example, retrieving the stack frames in a thread). Since debuggers are often communicating with remote and potentially unreliable devices, debug views retrieve content in non-UI threads to avoid blocking the user interface.

Operations

Following is a table of the operations defined by the standard model and a summary of the elements that implement the operations by default (for example, threads support the suspend/resume operation).

IDebugTarget IThread IStackFrame
IStep
-
ITerminate
ISuspendResume
IDisconnect
-
-
IDropToFrame
-
-
-

Generally, models implement operations in a non-blocking fashion. For example, when a thread is asked to step, a model will set up or initiate a step operation and then return. The step operation will then proceed asynchronously, notifying the platform of its progress by firing events.

The toolbar actions provided by the debug platform work against the operation interfaces rather than the model element interfaces. This allows a debugger to implement the operations on arbitrary elements.

Debug Events

A debug model fires DebugEvent's to describe its execution to the platform - for example, when a thread suspends, resumes, or terminates. Each event is associated with a debug model element and also describes a reason for the event. For example, a thread suspended due to a breakpoint. The platform updates its views and actions based on these events. Debug element implementations should extend the abstract DebugElement provided by the platform which provides convenience methods for firing events.

Stepping and event firing

Event firing is performed by the DebugPlugin. Events are fired in sets - all events that occurred at the same location/time in a program are fired in a single set. Most event sets contain one event. However, it might be possible for two events to occur at the same location - for example, a step completes at the same location as a breakpoint. Events are queued and fired in a separate dispatch thread. Clients interested in event notifications may register IDebugEventSetListener's with the DebugPlugin.

Rendering Elements

Model elements are displayed in the debug perspective with text and images. The platform provides default images for the standard elements and simple names (by calling getName()). However, models usually contribute an org.eclipse.debug.ui.debugModelPresentation extension to generate custom labels. The extension contributes an implementation of IDebugModelPresentation.

Default debug model images

Exercise

This exercise demonstrates debug model elements and operations. You must write code to retrieve stack frames and simulate stepping with event firing. From the Welcome Samples Page (Help -> Welcome -> Samples) Import the Counter sample into your workspace. Hint: to quickly find the locations in the code that need to be completed, search for the text "Exercise 2 ", or look for it in the Tasks view. Note: Tasks in the plugin.xml file do now show up automatically in the task view, only the tasks in the java files will be there.

Answers