Provides support for launching programs and defines interfaces for a debug model to support an extensible set debug architectures.
Note: this package is part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to soloicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.
Eclipse Debug Tools provides classes and interfaces to support the launching, registration, and manipulation of debuggable and non-debuggable programs. An extensible set of debug architectures and languages are supported by the definition of a "debug model" - a set of interfaces representing common artifacts in debuggable programs. The debug plug-in itself does not provide any implementations of a debug model. It is intended that third parties providing an integrated set of development tools for a specific language will also implement a debug model for that language, using an underlying debug architecture of their choice. For example, Java Tooling provides an implementation of a debug model based on the standard Java Debug Interface (JDI).
The "debug model" is represented by the set of interfaces defined in org.eclipse.debug.core.model. A client implements a debug model by providing an implementation of these interfaces in a plug-in. (There is no explicit extension point that represents a debug model). Each debug architecture will have its own way of initiating a debug session. Generally, each debug model will provide one or more launchers capable of initiating a debug session. A "launcher" is an extension point defined by the debug plug-in. A launcher is responsible for starting a debug session, and registering the result with the debug plug-in. Launching is a client responsibility.
The common elements defined by the debug plug-in are:
Debug model elements and breakpoints are displayed in the workbench. To support configurable and extensible presentation, the debugModelPresentations extension point is used. Extensions may be registered for a specific debug model. It is intended that an implementation of a debug model will also provide an implementation of a debug model presentation. The presentation provides:
Breakpoints are used to suspend the execution of a program being debugged. There are many kinds of breakpoints - line breakpoints, conditional line breakpoints, hit count breakpoints, exception breakpoints, etc. The kinds of breakpoints supported by each debug architecture (for example, JDI), and the information required to create those breakpoints is dictated by each debug architecture. Thus, Eclipse Debug Tools supports an extensible set of breakpoint types.
Eclipse Debug Tools provides a breakpoint manager that maintains the collection of all known breakpoints. Clients add and remove breakpoints via this manager. Breakpoints are represented by markers in the workspace, providing persistence and an extensible set of breakpoint attributes. Eclipse Debug Tools defines the root breakpoint marker and the common line breakpoint marker, as well as the attributes for these markers. Breakpoint creation is a client responsibility - that is, choosing which resource to associate a breakpoint with.
The breakpoint definitions in plug-in org.eclipse.debug.core are as follows:
<extension id="breakpoint"
point="org.eclipse.core.resources.markers">
<super type="org.eclipse.core.resources.marker"/>
<persisted value="true"/>
<extension id="lineBreakpoint"
point="org.eclipse.core.resources.markers">
<super type="org.eclipse.debug.core.breakpoint"/>
<super type="org.eclipse.core.resources.textmarker"/>
<persisted value="true"/>
</extension>
The breakpoint lifecycle begins with breakpoint creation. The location in which a breakpoint may be placed, and the attributes that its debug target requires to install the breakpoint is specific to each debug model. For this reason, breakpoint creation is a client responsibility. Generically, the breakpoint creation scenario involves the following steps:
Note that verifying the location of the breakpoint is valid is also a client responsibility.
Breakpoints are persisted via the standard marker mechanism. Breakpoints defined with the persisted attribute as false will not be persisted. Breakpoints are restored at workspace startup time by the breakpoint manager - that is, all persisted markers which are a subtype of the root breakpoint marker are added to the breakpoint manager. To allow for selective persistence of breakpoints, the root breakpoint marker defines a "persisted" attribute. If this value is set to false, the breakpoint will not be persisted.
As breakpoint markers are modified (created, removed, and attribute values are changed), resource deltas are created by the platform. The breakpoint manager translates pertinent resource deltas into breakpoint change notifications (breakpoint added/removed/changed messages). Interested listeners may register with the breakpoint manager. The breakpoint manager only fires change notifications for registered breakpoints. This simplifies breakpoint processing for clients, as resource delta traversal and analysis is not required. Thus clients have two options - listening to resource deltas from the platform, or listening to change notification from the breakpoint manager. However, clients should be careful to note that breakpoints marker deltas should only be considered as breakpoint changes if a breakpoint is currently active (registered with the breakpoint manager).
Removing a breakpoint from the breakpoint manager signals the end of the breakpoint lifecycle. A breakpoint may be removed with the method org.eclipse.debug.core.IBreakpointManager.removeBreakpoint(IMarker), or by deleting the underlying marker (in the later case, the breakpoint manager notices a breakpoint has been deleted, and automatically removes it).
Clients can define new kinds of breakpoints with the appropriate plug-in XML and subtyping any of the defined breakpoint markers. For example, a client may define an exception breakpoint as a subtype of the root breakpoint, or a client might define a conditional breakpoint as a subtype of the line breakpoint. The breakpoint manager does not define generic breakpoints of these types since the attributes required are debug model dependent.
Debug targets are notified of breakpoints via the IBreakpointListener mechanism. The breakpoint manager only notifies debug targets of breakpoints added/changed/removed, after a target has been created. Since breakpoints are often in existence before a debug target is launched, a debug target is responsible for querying the breakpoint manager for breakpoints in existence when it is created - see org.eclipse.debug.core.IBreakpointManager.getBreakpoints(String), which provides a list of active breakpoints for a specific debug model.