org.eclipse.debug.core/core/org/eclipse/debug/core/model/package.html - gerrit/platform/eclipse.platform.debug - Git at Google

 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
 <html>

 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 <title>Eclipse Debug Platform [org.eclipse.debug.core.model]</title>
 </head>

 <body bgcolor="#FFFFFF">

 <p>Defines interfaces for debug model elements, source lookup, and launching.</p>

 <h2>Package Specification</h2>

 <p>This package defines classes and interfaces known as the &quot;debug model&quot;
   which support an extensible set of debug architectures and languages. The debug
   model is a set of interfaces representing common artifacts in debuggable programs.
   The debug plug-in itself does not provide an implementation 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 development
   tooling provides an implementation of a debug model based on the standard Java
   Platform Debug Architecture (JPDA).</p>

 <h4>The Debug Model</h4>

 <p>A client implements a debug model by
 providing an implementation of the interfaces defined in this package. (There is no explicit
 extension point that represents a debug model). Each debug model provides one or more
 launch configuration types capable of initiating a debug session.</p>

 <p>The common elements defined by the debug model are:

 <ul>
   <li>Debug Target - A debug target represents a debuggable program - for example, a virtual
     machine or a process.</li>
   <li>Thread - A debug target may contain one or more threads.</li>
   <li>Stack Frame - A suspended thread may contain one or more stack frames.</li>
   <li>Variable - A stack frame may contain variables.</li>
   <li>Value - Each variable has an associated value, and a value may contain more variables (to
   	represent complex data structures and objects).</li>
   <li>Register Group - A stack frame may (optionally) be associated with one or more register
     groups.</li>
   <li>Register - A register group contains one or more registers.</li>
   <li>Memory Blocks - A debug target may (optionally) support the retrieval of
     arbitrary contiguous segments of memory.</li>
   <li>Breakpoint - Breakpoints suspend the execution of a program.</li>
   <li>Expression -  An expression is a snippet of code that can be evaluated to
   	produce a value.</li>
 </ul>

 <p>A debug model implementation is responsible for firing debug events. A debug event
 corresponds to an event in a program being debugged - for example the creation or
 termination of a thread.</p>

 <h4>Breakpoints</h4>

 <p>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, and the information required to create those breakpoints
 is dictated by each debug architecture. The debug platform supports an extensible
 set of breakpoint via the breakpoints extension point.</p>

 <p>The debug platform provides a breakpoint manager that maintains the collection
   of all registered breakpoints. Clients add and remove breakpoints via this manager.
   Breakpoints are implemented by instances of <b>IBreakpoint</b>. Each breakpoint
   object has an associated marker, which provides persistence and presentation
   in editors. The debug platform defines a generic breakpoint and line breakpoint,
   as well as their corresponding marker definitions. Breakpoint creation is a
   client responsibility - that is, defining the attributes of a breakpoint and
   the resource to associate a breakpoint marker with.</p>

 <p>Breakpoints are persisted via their underlying marker. Breakpoint markers defined
   with the <b>persisted</b> attribute as <b>false</b> will not be persisted. Breakpoints
   are restored at workspace startup time by the breakpoint manager - that is,
   breakpoint objects are created for all persisted markers which are a subtype
   of the root breakpoint marker and are added to the breakpoint manager. To allow
   for selective persistence of breakpoints (of the same kind), the <b>IBreakpoint</b>
   interface and root breakpoint implementation defines a &quot;persisted&quot;
   attribute. If this value is set to false, the breakpoint will not be persisted
   across workspace invocations.</p>

 <p>As breakpoint markers are modified (created, removed, and 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. Debug targets that support breakpoints should
   register for breakpoint change notifications.</p>
 <h4>New Features in the Debug Model, Eclipse 3.0</h4>
 <blockquote>
   <h4>Launch Delegate Enhancements<br>
   </h4>
   <p>Lanuch delegates can optionally implement the new interface <code>ILaunchConfigurationDelegate2</code>.
     This allows launch delegates to provide a launch object to be used for a launch.
     For example, when debugging on a server a delegate could create a new launch
     object or may reuse an existing launch object if the server is already running
     in debug mode. As well, the inteface provides a mechanism for performing a
     scoped build prior to launching (i.e. scoped to the projects in the workspace
     pertaining to the launch), and searching for errors in the workspace which
     may prevent the launch from succeeding (for example, compilation errors).</p>
   <p></p>
   <h4>Extensible Watch Expressions</h4>
   <p>The debug platform provides an implementation of watch expressions. Debug
     models can contribute watch expression delegates if they support watch expressions.
     When a stack frame is selected, the associated delegate is queried to provide
     a value for a watch expression in that context. The debug platform provides
     persistence, enabling, disabling, entering, and editing of watch expressions.</p>
   <h4>Automatic Array Partitioning<br>
   </h4>
   <p>The debug plug-in supports automatic partitioning of indexed collections,
     which partitions large arrays into sub-ranges in the variables view. This
     is supported with the introduction of a new interface in the debug model representing
     an indexed value - <code>IIndexedValue</code>. If a value implements this
     interface, the variables view will automatically partition its elements as
     required, into sub-ranges</p>
   <h4>Logical Structure Types<br>
   </h4>
   <p>Often, it is convenient to navigate complex data structures in terms of a
     logical structure, rather than an implementation structure. For example, no
     matter how a list is implemented (i.e. linked list, collection of arrays,
     etc.), it is often convenient to be able to view the list as an ordered collection.
     To facilitate the display of logical structures in the variables view, an
     extension point has been added (<code>org.eclipse.debug.core.logicalStructureTypes</code>)
     allowing debug models to contribute logical structures of its values, where
     applicable. Debug models may contribute delegates to translate raw implementation
     values into logical values. The variables view will display the logical values,
     when the option to display logical structures is turned on. More than one
     logical structure can be provided for a single value - the user can choose
     which structure to display.</p>
   <h4>Step Filters<br>
   </h4>
   <p>To support step filters on all stepping functions (into, over, return), a
     new interface has been added to the debug platform - <code>IStepFilters</code>
     - which can be implemented by debug targets. This interface replaces <code>IFilteredStep</code>,
     which is now deprecated. The debugger provides a global toggle that turns
     step filters on/off for all stepping functions. Debug targets should implement
     this new interface and honor the step filter enablement setting when stepping.</p>
   <p>This change maintains binary compatibility with previous releases. However,
     targets wishing to leverage the new function must implement the new interface.<br>
   </p>
 </blockquote>
 </body>
 </html>
	<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
	<html>

	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
	<title>Eclipse Debug Platform [org.eclipse.debug.core.model]</title>
	</head>

	<body bgcolor="#FFFFFF">

	<p>Defines interfaces for debug model elements, source lookup, and launching.</p>

	<h2>Package Specification</h2>

	<p>This package defines classes and interfaces known as the "debug model"
	which support an extensible set of debug architectures and languages. The debug
	model is a set of interfaces representing common artifacts in debuggable programs.
	The debug plug-in itself does not provide an implementation 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 development
	tooling provides an implementation of a debug model based on the standard Java
	Platform Debug Architecture (JPDA).</p>

	<h4>The Debug Model</h4>

	<p>A client implements a debug model by
	providing an implementation of the interfaces defined in this package. (There is no explicit
	extension point that represents a debug model). Each debug model provides one or more
	launch configuration types capable of initiating a debug session.</p>

	<p>The common elements defined by the debug model are:

	<ul>
	<li>Debug Target - A debug target represents a debuggable program - for example, a virtual
	machine or a process.</li>
	<li>Thread - A debug target may contain one or more threads.</li>
	<li>Stack Frame - A suspended thread may contain one or more stack frames.</li>
	<li>Variable - A stack frame may contain variables.</li>
	<li>Value - Each variable has an associated value, and a value may contain more variables (to
	represent complex data structures and objects).</li>
	<li>Register Group - A stack frame may (optionally) be associated with one or more register
	groups.</li>
	<li>Register - A register group contains one or more registers.</li>
	<li>Memory Blocks - A debug target may (optionally) support the retrieval of
	arbitrary contiguous segments of memory.</li>
	<li>Breakpoint - Breakpoints suspend the execution of a program.</li>
	<li>Expression - An expression is a snippet of code that can be evaluated to
	produce a value.</li>
	</ul>

	<p>A debug model implementation is responsible for firing debug events. A debug event
	corresponds to an event in a program being debugged - for example the creation or
	termination of a thread.</p>

	<h4>Breakpoints</h4>

	<p>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, and the information required to create those breakpoints
	is dictated by each debug architecture. The debug platform supports an extensible
	set of breakpoint via the breakpoints extension point.</p>

	<p>The debug platform provides a breakpoint manager that maintains the collection
	of all registered breakpoints. Clients add and remove breakpoints via this manager.
	Breakpoints are implemented by instances of <b>IBreakpoint</b>. Each breakpoint
	object has an associated marker, which provides persistence and presentation
	in editors. The debug platform defines a generic breakpoint and line breakpoint,
	as well as their corresponding marker definitions. Breakpoint creation is a
	client responsibility - that is, defining the attributes of a breakpoint and
	the resource to associate a breakpoint marker with.</p>

	<p>Breakpoints are persisted via their underlying marker. Breakpoint markers defined
	with the <b>persisted</b> attribute as <b>false</b> will not be persisted. Breakpoints
	are restored at workspace startup time by the breakpoint manager - that is,
	breakpoint objects are created for all persisted markers which are a subtype
	of the root breakpoint marker and are added to the breakpoint manager. To allow
	for selective persistence of breakpoints (of the same kind), the <b>IBreakpoint</b>
	interface and root breakpoint implementation defines a "persisted"
	attribute. If this value is set to false, the breakpoint will not be persisted
	across workspace invocations.</p>

	<p>As breakpoint markers are modified (created, removed, and 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. Debug targets that support breakpoints should
	register for breakpoint change notifications.</p>
	<h4>New Features in the Debug Model, Eclipse 3.0</h4>
	<blockquote>
	<h4>Launch Delegate Enhancements<br>
	</h4>
	<p>Lanuch delegates can optionally implement the new interface <code>ILaunchConfigurationDelegate2</code>.
	This allows launch delegates to provide a launch object to be used for a launch.
	For example, when debugging on a server a delegate could create a new launch
	object or may reuse an existing launch object if the server is already running
	in debug mode. As well, the inteface provides a mechanism for performing a
	scoped build prior to launching (i.e. scoped to the projects in the workspace
	pertaining to the launch), and searching for errors in the workspace which
	may prevent the launch from succeeding (for example, compilation errors).</p>
	<p></p>
	<h4>Extensible Watch Expressions</h4>
	<p>The debug platform provides an implementation of watch expressions. Debug
	models can contribute watch expression delegates if they support watch expressions.
	When a stack frame is selected, the associated delegate is queried to provide
	a value for a watch expression in that context. The debug platform provides
	persistence, enabling, disabling, entering, and editing of watch expressions.</p>
	<h4>Automatic Array Partitioning<br>
	</h4>
	<p>The debug plug-in supports automatic partitioning of indexed collections,
	which partitions large arrays into sub-ranges in the variables view. This
	is supported with the introduction of a new interface in the debug model representing
	an indexed value - <code>IIndexedValue</code>. If a value implements this
	interface, the variables view will automatically partition its elements as
	required, into sub-ranges</p>
	<h4>Logical Structure Types<br>
	</h4>
	<p>Often, it is convenient to navigate complex data structures in terms of a
	logical structure, rather than an implementation structure. For example, no
	matter how a list is implemented (i.e. linked list, collection of arrays,
	etc.), it is often convenient to be able to view the list as an ordered collection.
	To facilitate the display of logical structures in the variables view, an
	extension point has been added (<code>org.eclipse.debug.core.logicalStructureTypes</code>)
	allowing debug models to contribute logical structures of its values, where
	applicable. Debug models may contribute delegates to translate raw implementation
	values into logical values. The variables view will display the logical values,
	when the option to display logical structures is turned on. More than one
	logical structure can be provided for a single value - the user can choose
	which structure to display.</p>
	<h4>Step Filters<br>
	</h4>
	<p>To support step filters on all stepping functions (into, over, return), a
	new interface has been added to the debug platform - <code>IStepFilters</code>
	- which can be implemented by debug targets. This interface replaces <code>IFilteredStep</code>,
	which is now deprecated. The debugger provides a global toggle that turns
	step filters on/off for all stepping functions. Debug targets should implement
	this new interface and honor the step filter enablement setting when stepping.</p>
	<p>This change maintains binary compatibility with previous releases. However,
	targets wishing to leverage the new function must implement the new interface.<br>
	</p>
	</blockquote>
	</body>
	</html>