# 3.1 Debug Platform Change Notes

This document describes new features and important changes in the 3.1 debug platform, relative to the 3.0 release.

## New Features

### Breakpoint Organizers

The breakpoints view allows breakpoints to be displayed in groups. The platform supports breakpoint groupings by breakpoint type, file, project, and breakpoint working sets and resource based working sets (as well, it supports nested groupings). The `breakpointOrganizers` extension point allows for other grouping strategies to be contributed to the debug platform.

A new, optional, `name` attribute has been added to the breakpoints extension point to provide a type name for breakpoints. This name appears as the group label, when the user chooses to group breakpoints by type. If this attribute is not specified on a breakpoint extension, the breakpoints are considered to not have a type, and will be displayed in the "Others" group.

### Logical Structure Providers

Logical structures have been enhanced to allow clients to more easily contribute more than one logical structure for a given value. The new extension point `logicalStructureProviders` allows clients to contribute an implementation of an `ILogicalStrugureProvider`. A logical structure provider provides a simple way to contribute a single factory of logical structures for a debug model.

In addition the optional interface `ILogicalStructureTypeDelegate2` has been added to allow a logical structure delegate to provide a dynamic label for a value's logical structure type.

### Process Console Enhancements

The debug console has been enhanced to allow output to be multiplexed between the console and/or a file. As well, the encoding used to translate output to characters can now be specified. All of these options are available to the user on the "Common" launch configuration tab. As well, the options are available programmatically as launch configuration attributes. The following attributes have been added to `org.eclipse.debug.ui.IDebugUIConstants`.

- `ATTR_CONSOLE_ENCODING`
- `ATTR_CAPTURE_IN_CONSOLE`
- `ATTR_CAPTURE_IN_FILE`
- `ATTR_APPEND_TO_FILE`

### Memory View

The Memory view, which was first released in 3.0 as internal API, has become public API in 3.1. See the new extension point `memoryRenderings`, and the new API package `org.eclipse.debug.ui.memory` for more information.

### Parse Arguments

A convenience API method has been added to `DebugPlugin` to separate arguments in a single string into an array of arguments that can be passed to the command line for execution. See `DebugPlugin.parseArguments(String)`.

### Run To Line Handler

Many debuggers implement "run to line" functionality by creating a breakpoint at the line a user has chosen to "run to", and then resuming execution until that breakpoint is hit. A new API class, `RunToLineHandler`, has been created to simplify the task. The handler manages the "skip breakpoints while performing run to line" user preference as well canceling the operation if another breakpoint is hit before the "run to line" operation completes.

### Run To Line Action Delegate

The `RunToLineActionDelegate` introduced in 3.0 can now also be contributed to a view (in 3.0 it could only be contributed to an editor). The action additionally implements `IViewActionDelegate`.

### Variable Value Editors

A new extension point, `variableValueEditors`, allows debuggers to contribute custom editors for modifying a variable's value selected in the Variables view.

### Launch Shortcut Keybindings

To register a key-binding for a launch shortcut, define a command with an id the same as the launch shortcut id, suffixed with the launch mode. For example, the id of the "Java Application" launch short cut is org.eclipse.jdt.debug.ui.localJavaShortcut, so the command id for launching in debug mode is org.eclipse.jdt.debug.ui.localJavaShortcut.debug. Then define a key-binding for your command.

When the command is invoked via the key-binding, the selection or active editor will be used as the target for the launch shortcut's launch method. The shortcut is only invoked if the shortcut is enabled for the selection or editor.

### Source Lookup/Display Facility

API methods have been added to `DebugUITools` to facilitate source lookup and display. See the methods `lookupSource(Object, ISourceLocator)` and `displaySource(ISourceLookupResult, IWorkbenchPage)`. When a source lookup result for a stack frame is displayed, the open editor is also annotated with an appropriate instruction pointer.

### Watchpoints (IWatchpoint) and Images

As watchpoints are common to many debug architectures, the notion of an IWatchpoint has been added to the debug model. A watch point is a breakpoint that suspends execution when an associated variable is read and/or written. As well, default images for rendering watchpoints have been added to the debug platform.

### Colors and Fonts for Debug Elements

In 3.1, debug model presentations (`IDebugModelPresentation`) may optionally implement `IColorProvider` and `IFontProvider` to override default fonts and colors for debug elements.

### Inserting Elements into Debug View

The Debug view allows for debug models to insert arbitrary elements into the debug model element hierarchy. For example, the Java debugger now displays lock information directly in the view. To override the default presentation in the view, a debugger must provide an `IWorkbenchAdapter` or `IDeferredWorkbenchAdapter` for the relevant element(s). The debug platform provides default adapters for the standard debug elements.

Debug elements were always required to implement `IAdaptable`, and now must be subclasses of `PlatformObject` in order for workbench adapters to be properly registered and retrieved for debug elements.

### Abstract Debug Element

An abstract implementation of a debug element is provided in 3.1 - `DebugElement`. Clients implementing debug models may choose to subclass this class when implementing debug models. The class provides convenience methods for firing debug events, reporting exceptions, and retrieving adapters.

### Drop to Frame Platform Action/Interface

The debug platform provides a "drop to frame" action and corresponding capability interface (`IDropToFrame`). Debug elements supporting the capability should implement this new interface to share the global action.

### Context Menu Launching in Editors

Launching from the context menu (for example, "Run As > Java Application"), is now available in editors (In 3.1, this was only available in the package explorer and resource navigator). To leverage this feature, the editor input associated with a executable file must have an `ILaunchable` adapter registered for it.

### Support for Unregistered Launch

The launch framework allows for a launch to be performed without registering a launch object with the launch manager. An unregistered launch does not appear in the Debug view. A new launch method has been added to `ILaunchConfiguration`, accepting a boolean argument determining whether the launch should be registered (`launch(String mode, IProgressMonitor monitor, boolean build, boolean register)`), and a new method has been added to `ILaunchManager` to determine if a launch is registered (`isRegistered(ILaunch launch)`).

### Reusable Breakpoint Ruler Toggle Actions

Providing double-click breakpoint creation in an editor's vertical ruler is a common feature for debuggers. The debug platform provides two actions to facilitate this: `RulerToggleBreakpointActionDelegate` and `ToggleBreakpointAction`. A debugger must contribute the `RulerToggleBreakpointActionDelegate` to the appropriate editor (see javadoc for more details), and also register an `IToggleBreakpointsTarget` adapter with the editor.

### Environment Variables Case Preservation

Support has been added to `ILaunchManager` to retrieve the environment variables defined in the OS preserving case. This is important on the WIN32 operating system. Although WIN32 is case insensitive, depending on what you intend to do with the environment, the lack of normalization may or may not cause problems. This method `getNativeEnvironmentCasePreserved()` returns mixed-case keys using the variable names recorded by the OS. Use `getNativeEnvironment()` instead to get a WIN32 system environment where all keys have been normalized to uppercase.

### Closing an Input Stream

An optional extension, `IStreamsProxy2`, can be implemented by implementations of `IStreamsProxy`. When implemented, it allows the input stream associated with a process to be closed. This is used to allow the user to signal EOF when typing in the console.

### Launch in Debug Mode when Workspace Contains Breakpoints

Since 3.0, The user preference "Launch in debug mode when workspace contains breakpoints" is used to control whether a launch should use debug mode even when "run" is pressed by the user, based on the presence of breakpoints in the workspace. A new method, `getBreakpoints(ILaunchConfiguration configuration)`, has been added to the abstract implementation of `LaunchConfigurationDelegate`, to determine which breakpoints should be considered as relevant for a particular launch. By default, all breakpoints in the workspace are considered, but subclasses may override. For example, the Java Application launcher only considers Java breakpoints.

### Case Insensitive Source Lookup and Relative Paths

The debug platform's source lookup facilities now lookup source in folders and directories in a case insensitive manner on platforms that are case insensitive. As well, relative path names are supported in folders and directories.

## Changes

### Debug Event Dispatch

In releases 3.0 and prior, calling `DebugPlugin.fireDebugEventSet(DebugEvent[])` resulted in debug events being fired synchronously in the calling thread. In 3.1, debug event set listeners are notified of debug events asynchronously in a different thread than the event is reported in.

### Debug Actions and Content in Background Jobs

In 3.1, many actions that call debug element APIs (like "stepOver"), now create jobs to communicate with debug elements in background threads. This avoids blocking the UI in the case that a debug element method requires communication with a debug target that can block, hang, or timeout. Similarly, many of the debug views populate their content using background jobs to avoid blocking the UI thread. The net difference is that in 3.1, more than one thread might be accessing a debug model's APIs where previously only the UI thread was.

### Contextual Launch from Top Level Run/Debug Menus

The top level menus no longer support the perspective element, and launch shortcuts must specify a "`contextualLaunch`" element to appear in the Run/Debug cascade menus.