<html>
<head>
<title>3.1 Debug Platform Change Notes</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>

<body bgcolor="#FFFFFF" text="#000000">
<h1>3.1 Debug Platform Change Notes</h1>
<p>This document describes new features and important changes in the 3.1 debug 
  platform, relative to the 3.0 release.</p>
  
<h2>New Features</h2>

<h3> Breakpoint Organizers</h3>
<p>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 <code>breakpointOrganizers</code> extension point allows for other grouping 
  strategies to be contributed to the debug platform.</p>
<p>A new, optional, <code>name</code> 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 &quot;Others&quot; group.</p>
<h3>Logical Structure Providers</h3>
<p>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 <code>logicalStructureProviders</code> 
  allows clients to contribute an implementation of an <code>ILogicalStrugureProvider</code>. 
  A logical structure provider provides a simple way to contribute a single factory 
  of logical structures for a debug model.</p>
<p>In addition the optional interface <code>ILogicalStructureTypeDelegate2</code> 
  has been added to allow a logical structure delegate to provide a dynamic label 
  for a value's logical structure type.</p>
<h3>Process Console Enhancements</h3>
<p>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 &quot;Common&quot; launch configuration tab. As well, the options are 
  available programmatically as launch configuration attributes. The following 
  attributes have been added to <code>org.eclipse.debug.ui.IDebugUIConstants</code>.</p>
<ul>
  <li><code>ATTR_CONSOLE_ENCODING</code></li>
  <li><code>ATTR_CAPTURE_IN_CONSOLE</code></li>
  <li><code>ATTR_CAPTURE_IN_FILE</code></li>
  <li><code>ATTR_APPEND_TO_FILE</code></li>
</ul>
<h3>Memory View</h3>
<p>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 <code>memoryRenderings</code>, 
  and the new API package <code>org.eclipse.debug.ui.memory</code> for more information.</p>
<h3>Parse Arguments</h3>
<p>A convenience API method has been added to <code>DebugPlugin</code> to separate 
  arguments in a single string into an array of arguments that can be passed to 
  the command line for execution. See <code>DebugPlugin.parseArguments(String)</code>.</p>
<h3>Run To Line Handler</h3>
<p>Many debuggers implement &quot;run to line&quot; functionality by creating 
  a breakpoint at the line a user has chosen to &quot;run to&quot;, and then resuming 
  execution until that breakpoint is hit. A new API class, <code>RunToLineHandler</code>, 
  has been created to simplify the task. The handler manages the &quot;skip breakpoints 
  while performing run to line&quot; user preference as well canceling the operation 
  if another breakpoint is hit before the &quot;run to line&quot; operation completes.</p>
<h3>Run To Line Action Delegate</h3>
<p>The <code>RunToLineActionDelegate</code> 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 <code>IViewActionDelegate</code>.</p>
<h3>Variable Value Editors</h3>
<p>A new extension point, <code>variableValueEditors</code>, allows debuggers 
  to contribute custom editors for modifying a variable's value selected in the 
  Variables view.</p>
<h3>Launch Shortcut Keybindings</h3>
<p>To register a key-binding for a launch shortcut, define a command with an <font face="Courier New, Courier, mono">id 
  </font>the same as the launch shortcut <font face="Courier New, Courier, mono">id</font>, 
  suffixed with the launch mode. For example, the id of the &quot;Java Application&quot; 
  launch short cut is <font face="Courier New, Courier, mono">org.eclipse.jdt.debug.ui.localJavaShortcut</font>, 
  so the command id for launching in debug mode is <font face="Courier New, Courier, mono">org.eclipse.jdt.debug.ui.localJavaShortcut.debug</font>. 
  Then define a key-binding for your command.</p>
<p>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.</p>
<h3>Source Lookup/Display Facility</h3>
<p>API methods have been added to <code>DebugUITools</code> to facilitate source 
  lookup and display. See the methods <code>lookupSource(Object, ISourceLocator)</code> 
  and <code>displaySource(ISourceLookupResult, IWorkbenchPage)</code>. When a 
  source lookup result for a stack frame is displayed, the open editor is also 
  annotated with an appropriate instruction pointer.</p>
<h3>Watchpoints (IWatchpoint) and Images</h3>
<p>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.</p>
<h3>Colors and Fonts for Debug Elements</h3>
<p>In 3.1, debug model presentations (<code>IDebugModelPresentation</code>) may 
  optionally implement <code>IColorProvider </code>and <code>IFontProvider </code>to 
  override default fonts and colors for debug elements.</p>
<h3>Inserting Elements into Debug View</h3>
<p>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 <code>IWorkbenchAdapter</code> or <code>IDeferredWorkbenchAdapter 
  </code>for the relevant element(s). The debug platform provides default adapters 
  for the standard debug elements.</p>
<p>Debug elements were always required to implement <code>IAdaptable</code>, and 
  now must be subclasses of <code>PlatformObject</code> in order for workbench 
  adapters to be properly registered and retrieved for debug elements.</p>
<h3>Abstract Debug Element</h3>
<p>An abstract implementation of a debug element is provided in 3.1 - <code>DebugElement</code>. 
  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.</p>
<h3>Drop to Frame Platform Action/Interface</h3>
<p>The debug platform provides a &quot;drop to frame&quot; action and corresponding 
  capability interface (<code>IDropToFrame</code>). Debug elements supporting 
  the capability should implement this new interface to share the global action.</p>
<h3>Context Menu Launching in Editors</h3>
<p>Launching from the context menu (for example, &quot;Run As &gt; Java Application&quot;), 
  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 <code>ILaunchable</code> adapter 
  registered for it.</p>
<h3>Support for Unregistered Launch</h3>
<p>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 <code>ILaunchConfiguration</code>, 
  accepting a boolean argument determining whether the launch should be registered 
  (<code>launch(String mode, IProgressMonitor monitor, boolean build, boolean 
  register)</code>), and a new method has been added to <code>ILaunchManager</code> 
  to determine if a launch is registered (<code>isRegistered(ILaunch launch)</code>).</p>
<h3>Reusable Breakpoint Ruler Toggle Actions</h3>
<p>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: <code>RulerToggleBreakpointActionDelegate </code>and <code>ToggleBreakpointAction</code>. 
  A debugger must contribute the <code>RulerToggleBreakpointActionDelegate</code> 
  to the appropriate editor (see javadoc for more details), and also register 
  an <code>IToggleBreakpointsTarget </code>adapter with the editor.</p>
<h3>Environment Variables Case Preservation</h3>
<p>Support has been added to <code>ILaunchManager</code> 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 <code>getNativeEnvironmentCasePreserved()</code> returns 
  mixed-case keys using the variable names recorded by the OS. Use <code>getNativeEnvironment()</code> 
  instead to get a WIN32 system environment where all keys have been normalized 
  to uppercase.</p>
<h3>Closing an Input Stream</h3>
<p>An optional extension, <code>IStreamsProxy2</code>, can be implemented by implementations 
  of <code>IStreamsProxy</code>. 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.</p>
<h3>Launch in Debug Mode when Workspace Contains Breakpoints</h3>
<p>Since 3.0, The user preference &quot;Launch in debug mode when workspace contains 
  breakpoints&quot; is used to control whether a launch should use debug mode 
  even when &quot;run&quot; is pressed by the user, based on the presence of breakpoints 
  in the workspace. A new method, <code>getBreakpoints(ILaunchConfiguration configuration)</code>, 
  has been added to the abstract implementation of <code>LaunchConfigurationDelegate</code>, 
  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.</p>
<h3>Case Insensitive Source Lookup and Relative Paths</h3>
<p>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.</p>
<h2>Changes</h2>
<h3>Debug Event Dispatch</h3>
<p>In releases 3.0 and prior, calling <code>DebugPlugin.fireDebugEventSet(DebugEvent[])</code> 
  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.</p>
<h3>Debug Actions and Content in Background Jobs</h3>
<p>In 3.1, many actions that call debug element APIs (like &quot;stepOver&quot;), 
  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.</p>
<h3>Contextual Launch from Top Level Run/Debug Menus</h3>
<p>The top level menus no longer support the perspective element, and launch shortcuts 
  must specify a &quot;<code>contextualLaunch</code>&quot; element to appear in 
  the Run/Debug cascade menus.</p>
<p>&nbsp;</p>
</body>
</html>