Breakpoints

Breakpoints allow users to suspend the execution of a program at a particular location. Breakpoints are typically shown in the UI along with the source code. When a breakpoint is encountered during execution of a program, the program suspends and triggers a SUSPEND debug event with BREAKPOINT as the reason.

If your plug-in needs to show breakpoints in its UI, you can add an IBreakpointListener to the IBreakpointManager. The IBreakpointManager is the central authority over all breakpoints. Breakpoints are added and removed using the breakpoint manager, which in turn informs any listeners about breakpoint activity. The operation of breakpoints can be enabled or disabled using the breakpoint manager. The breakpoint manager can be obtained from the DebugPlugin:

IBreakpointManager mgr = DebugPlugin.getDefault().getBreakpointManager();

Plug-ins that define their own debug models and launch configurations often need to define their own breakpoint types. You can implement breakpoints for your particular debug model by defining a class that implements IBreakpoint.

Breakpoints are implemented using resource markers. Recall that resource markers allow you to associate meta information about a resource in the form of named attributes. By implementing a breakpoint using markers, the debug model can make use of all the existing marker functionality such as persistence, searching, adding, deleting, and displaying in editors.

Why is it important to know about markers when using breakpoints?  When you create a breakpoint type, you must also specify an associated marker type. Every extension of org.eclipse.debug.core.breakpoints should be accompanied by an extension of org.eclipse.core.resources.markers.  This is best demonstrated by looking at the extensions defined by the Java tooling for Java breakpoints.

<extension id="javaBreakpointMarker" point="org.eclipse.core.resources.markers">
	<super type="org.eclipse.debug.core.breakpointMarker"/>
</extension>

<extension id="javaExceptionBreakpointMarker" point="org.eclipse.core.resources.markers">
	<super type="org.eclipse.jdt.debug.javaBreakpointMarker"/>
	<persistent value="true"/>
	<attribute name="org.eclipse.jdt.debug.core.caught"/>
	<attribute name="org.eclipse.jdt.debug.core.uncaught"/>
	<attribute name="org.eclipse.jdt.debug.core.checked"/>
</extension>

<extension point="org.eclipse.debug.core.breakpoints">
	<breakpoint
		id="javaExceptionBreakpoint"
		markerType="org.eclipse.jdt.debug.javaExceptionBreakpointMarker"
		class="org.eclipse.jdt.internal.debug.core.breakpoints.JavaExceptionBreakpoint">
	</breakpoint>
</extension>

The debug plug-in defines a special type of marker, org.eclipse.debug.core.breakpointMarker. When you define a breakpoint marker for your debugger, you should declare it using this marker as a super type. This allows the debug model to find all possible breakpoints within a source file by searching for subtypes of its marker. In the example above, the javaExceptionBreakpointMarker has a super type, javaBreakpointMarker, whose super type is the breakpointMarker. The javaExceptionBreakpoint (defined in the breakpoint extension) designates the javaExceptionBreakpointMarker as its marker.

What does all of this mean? When the debug code obtains a source code file, it can search for all markers whose super type is org.eclipse.debug.core.breakpointMarker. Having found all of the markers, it can then use the extension registry to map the markers to their associated breakpoint classes. In this way, the platform debug code can generically find all breakpoint types that have been set on a particular source file.