Debug Tutorial Custom Integration

1Copyright © IBM Corp., 2007-2008. All rights reserved. Source code in this presentation is made available under the EPL, v1.0, remainder of the presentation is licensed under Creative Commons Att. Nc Nd 2.5 license.Debug Platform: Custom Integration | March 17th, 2008

Debug Platform: Custom Integration

Darin Wright, Curtis WindattIBM Rational Software

March 17th, 2008


Tutorial Structure

This tutorial Builds on information from “The Basics” tutorial

Is arranged as a set of modules

Examples provided PDA modified to have no threads (since it’s single threaded)

MIDI player (demonstrates non-debug model objects in debug views)

Use the example source code for reference

:pserver:[email protected]:/cvsroot/eclipse org.eclipse.debug.examples.core org.eclipse.debug.examples.ui


Modules – Custom Integration

1. Overview2. Custom Operations3. Custom Content

1. Contents & Labels

2. Columns

3. Viewer Input

4. Detail Panes & Value Editors

4. Custom Updating1. Model Proxy

2. Save/Restore

3. Source Lookup


Module 1:

Custom Integration Overview


Debug Platform 3.1 and Earlier

Common Debug Perspective, Views & Actions

Standard Debug Model Interfaces

Implementation of the Standard Model

Platform defined API

Model defined API


An Inflexible Platform

1. The standard debug model doesn’t represent all architectures Embedded hardware models are different – often there are multiple

processors in multi-core, possibly with DSP configurations

2. Standard debug views and actions place high demands on the underlying target and enforce a synchronous interaction View content and labels are retrieved synchronously in UI thread


A Flexible Platform

An arbitrary element hierarchy in all debug platform views Additionally, support model specified columns

A pluggable update mechanism for all views Models control what gets updated and when

Asynchronous interactions between UI and model Interactions do not block the UI thread and are cancelable

Allows implementations to coalesce requests

Flexible view wiring and retargettable actions For example, the input to the variables view may not be a frame

Pluggable source lookup The platform provides a source lookup framework, but you can override it


Debug Platform @since 3.2



Implementation of theStandard Model

Alternate DebugImplementation

Common Interaction Adapters: Content, Labels, Function

Standard Adapter Implementation Alternate Adapter Implementation


Custom Model Integration

A debugger provides a layer of adapters to interact with the debug platform’s views and actions

Content and label providers for view content

Model proxy and deltas for view update

Command handlers for actions

Source display adapter The debug platform provides adapters for implementations of the

standard model Existing models continue to work; new models have a choice

Additionally the platform provides services for debug context management

Ways to access and provide the active debug context that drives a debug session


Debug Platform 3.3 – Adapters Changed from 3.2



Implementation of theStandard Model

Alternate DebugImplementation

** Common Interaction Adapters: Content, Labels, Function **

Standard Adapter Implementation ** Alternate Adapter Implementation **


Changes in 3.2 -> 3.3

Some provisional APIs evolved to public IDebugContextService & support classes/interfaces

Leverage the JFace viewer framework JFace tree viewer with SWT.VIRTUAL flag, lazy tree content provider, etc.

Debug has less duplicated/custom viewer code

More (but not all) of the viewer framework lives in the right place


Public and Provisional API in 3.4

Public API Debug Context Management

Debug Command Handlers

Source Display

Suspend Trigger

Provisional API Viewers

Content Labels Viewer State Viewer Input Service (new in 3.4)

Viewer framework is still provisional in 3.4 Would like to see a general asynchronous viewer framework plug-in evolve

that is not debug specific


The Eclipse Adapter Pattern

A hook provided by the Eclipse runtime allowing dynamic behavior extensions for objects

IAdaptable - the interface adaptable objects implement

IAdaptable a = [some adaptable object];

IFoo x = (IFoo)a.getAdapter(IFoo.class);

if (x != null)

[do IFoo things with x]


Where do Adapters come from?

An object can implement IAdaptable directly, but in order to be extensible via platform extension points, objects must subclass PlatformObject

Adapters are created by adapter factories (IAdapterFactory)Object getAdapter(Object adaptable, Class adapterType)

Class[]getAdapterList()

You can contribute adapters in two ways: Use code to register an adapter factory for a class

Use the org.eclipse.core.runtime.adapters extension point to register an adapter factory for a class


Adapter Factories: Best Practices

It’s best to use the extension point: Can extend behavior of classes defined in other plug-ins

Allows Eclipse to discover adapters even if plug-in is not loaded

<extension point="org.eclipse.core.runtime.adapters"> <factory class="org.eclipse.jdt.debug.ui.actions.RetargettableActionAdapterFactory" adaptableType="org.eclipse.jdt.internal.ui.javaeditor.CompilationUnitEditor"> <adapter type="org.eclipse.debug.ui.actions.IRunToLineTarget"/> <adapter type="org.eclipse.debug.ui.actions.IToggleBreakpointsTarget"/>

You can use code, but I don’t have a good argument for it: Adapters will only be available if plug-in is loaded

IAdapterManager manager = Platform.getAdapterManager();

manager.registerAdapters(IAdapterFactory, Class)


Summary

The platform provides a layer of pluggable adapters to support non-standard models

Implementation of adapters for standard models

flexibility and extensibility for non-standard models


Module 2:

Custom Operations (Capabilities)


Debug Operation Players

1. Active Debug Context (model) The thing being debugged

Provided by the context service

2. Actions (UI) Step over, into, return, suspend, resume, terminate, etc.

Provided by the platform – buttons, menus, hot keys

3. Command Handlers (behavior proxy) Pluggable implementations of standard actions

Platform provides implementation for standard models


(1) Debug Context Service & (2) Actions

Debug

View

Selection

Actions

(getAdapter IStep, etc)

Source Lookup

(getAdapter ISourceDisplay)

IDebugContextService

Context activated

Context activated

Provides context

(context serviceper window)


(3) Debug Command Handlers

All handlers are subtypes of IDebugCommandHandler with common methods:

canExecute(IEnabledStateRequest request)

execute(IDebugCommandRequest request)

Interfaces defined in org.eclipse.debug.core.commands Standard models can override the platform’s implementation Custom models must provide an implementation Mechanisms:

Provide handlers as adapters (IAdaptable)

Implement handler interfaces directly


Common Handlers

The set of handlers understood/defined by the platform is static: IDisconnectHandler

IDropToFrameHandler

IResumeHandler

IStepFiltersHandler

IStepIntoHandler

IStepOverHandler

IStepReturnHandler

ISuspendHandler

ITerminateHandler

The platform provides standard implementations for these handlers Executes the capabilities (IStep, ITerminate, etc) implemented by the debug model

Clients can provide their own implementation for any handler they wish to customize


Using Standard Handlers Implement standard model interface and use platform handlers Customize capabilities in the model (IStep, ITerminate, etc)

ActiveContext

Step OverHandler

TerminateHandler

ResumeHandler

SuspendHandler

…

Step OverAction

SuspendAction

ResumeAction

TerminateAction

implements IStep, ISuspendResume, ITerminate…

…


Using Custom Handlers

Provide custom handlers as adapters

ActiveContext

Step OverHandler

TerminateHandler

ResumeHandler

SuspendHandler

…

Step OverAction

SuspendAction

ResumeAction

TerminateAction

…


Asynchronous Interaction

Interactions with a command handler are asynchronousUpdating enabled state

Execution

An IRequest object is passed to the handlerSimilar to a result collector

Also accepts a status

Allows for cancellation

Must be notified when request is complete

Specialized requests are used


Update Enabled State

Debug

View

Selection

(fire)CONTEXT

ACTIVATED

ContextService

Step OverAction

(notify)CONTEXT

ACTIVATED

Step OverHandler

Request

canExecute(…)

setEnabled(…)done()

Updateenablement


Execute Command

Step OverAction

Step OverHandler

Request

execute(…)

setStatus(…)done()

Notify errors in dialog

click | key press

remain enabled?


Standard Implementation

The handlers provided by the platform uses jobs to implement asynchronous interactions with the standard synchronous APIs

The handler schedules a job for each request and returns

The job runs asynchronously

When the job is complete, the request is updated with the status, result and done() is called on the request

Enabled state jobs are scheduled serially on the debug context

Execution jobs do not have scheduling rules Allows enabled state to be updated while executing a request


Summary

1. Operations (step, suspend, etc.) are handled by debug command handlers Platform has a static list of handler types: IDisconnectHandler,

IResumeHandler, etc.

2. The platform provides default handlers Only available to the standard debug model

Asynchronously calls capabilities on the selected debug element

Implement capabilities (IStep, ISuspendResume, etc.) on debug model elements to determine behaviour.

3. The platform handlers can be replaced with your own Added as adapters on the debug model elements


Module 3:

Custom Content


Overview

3.1 Contents & Labels

3.2 Columns

3.3 Viewer Input

3.4 Detail Panes & Value Editors


3.1 Content & Label Players

1. Viewer Displays elements from a model

2. Presentation Context Identifies the view or context in which elements are being displayed

3. Model Underlying debugger implementation (or any model)

4. Element Content Provider Identifies which elements have children in a given context, how many

children, and provides children in sub ranges

5. Element Label Provider Provides text and images for model elements in a given context

6. Request Collects results of each request asynchronously


Goal

Client must have complete control over the implementation of content retrieval – i.e. whether requests are processed in parallel vs. sequential, which thread, whether requests are coalesced, etc.


Content & Labels

JFaceTree Viewer

DebugModel

Element

Element

ContentProvider

LabelProvider

update(…)

updateHasChildren(…)

updateChildCount(…)updateElement(…)

ElementContentProvider

update(…)

Request

done()

replace(…), setChildCount(…)setHasChildren(…)

ElementLabel

Provider

update(…)

Request

done()

setText(…), setImage(…), …


Properties of the Interaction

The interaction is extensible Extensibility provided by adapters, allows for arbitrary model API

The interaction is context sensitive The presentation context identifies the part requesting content, allowing for

different content in different views

The interaction is asynchronous The content and label providers retrieve information in a non-blocking

fashion, reporting results to a request and notifying it when done

The interaction is cancelable The request can be canceled by the platform or model

The interaction reports errors The request carries a status to inform the user of failures that arise


The Viewer

The debug platform provides an implementation of a tree viewer with a special content provider to support custom asynchronous content

Based on JFace tree viewer with an ILazyTreePathContentProvider

The viewer is currently provisional API

The viewer is not intended to be subclassed, but can be instantiated

The viewer comes with a content provider that must be used (this is the guts of the asynchronous content mechanism)

See TreeModelViewer for more information


Filtering

JFace does not support filtering in virtual tree viewers Since all elements are not retrieved at once

For backwards compatibility, debug has added support for filters The filters work incrementally – as elements are added to the viewer, filters

are applied

Side effect – scrollbars can grow shrink if many elements are filtered

For a more stable UI, models/content providers can perform filtering

In 3.4, the Java debugger content adapters filter variables Note: Requires all content to be retrieved in order to know what was filtered and

what the filtered child count will be

Sorting is not supported Models/content providers must perform sorting if desired


Presentation Context

Describes the context in which a request has been made:

IPresentationContextpublic String getId();public String[] getColumns();

Allows adapters to provide different content in different contexts The “id” roughly corresponds to view identifiers (but is no longer

tied to a workbench part, to support viewers that are not in parts) A viewer is created with a specific context Clients may specialize a presentation context to provide more

information (subclass base PresentationContext class)


The Model

Any hierarchical model, for example Implementation of standard debug model

Implementation of a non-standard debug model

A file system…

Anything


Element Content Provider

Provides context sensitive content for an element Implement directly, or provided as an adapter

Each update request is a specialized viewer update (which is a specialized IRequest), identifying context and element for the request:


Content Requests


Implementing a Content Provider

Content provider must process requests asynchronously (i.e. non-blocking)

The platform uses jobs to implement asynchronous interactions with the standard synchronous APIs

Schedules a job for each request and returns

The job runs asynchronously and fills in information on request

When the job is complete, the request is updated with any status, and done() is called on the request

@see ElementContentProvider – a base class that uses jobs to generate content from synchronous model APIs


Label Provider

Provides context sensitive labels for elements Implemented directly or provided as an adapter

Provides text, font, image, foreground and background colors

Must be non-blocking, platform uses jobs…


Compatibility with IDebugModelPresentation

The debug platform registers label providers for all standard debug model elements

Delegates to the appropriate model presentation for each object to compute labels for backwards compatibility

Clients may continue using IDebugModelPresentations May choose to separate model presentation into new label providers

Model presentations tend to be large and non-OO in structure, so there may be a benefit in migrating to label providers in terms of code structure

The Java debugger uses a mix Original model presentation for its standard elements Label providers for locks, monitors, thread groups, references


Which thread are labels computed in?

If you provide your own label adapters, the choice is up to you. By default, the platform uses a non-UI thread to compute labels

This sometimes causes problems when populating image registries (which requires the UI thread)

In 3.4, IDebugModelPresentationExtension has been added

Allows models to dynamically control if the UI thread should be used:

public boolean requiresUIThread(Object element);


Same Old Problem

There can only be one adapter (type) per object (type) 3rd parties can’t

Extend adapters for new views Modify or extend content in existing views

Assumption we’ve be going on The debug model implementation provides all adapters (or re-uses the

platform adapters)

Debuggers are not extended in downstream plug-ins

Would require use of an extension point to contribute content and label providers


Customizing Launch Content

The input to the Debug view is the ILaunchManager, which displays all registered launches as root elements

To customize content for a launch object, you must provide your own implementation of an ILaunch and a content adapter for it

The platform registers content/label providers for ILaunch, so you register adapters for your implementation class

Customizing content for elements within a launch is simpler, as you only need to register custom adapters for your objects

MIDI example provides a custom launch implementation


3.1 Summary: Content & Labels

1. Implement content providers For each model element implement an IElementContentProvider

2. Implement label providers For each model element implement an IElementLabelProvider

3. Implement adapter factory Implement an IAdapterFactory to instantiate content and label providers

for the model elements

4. Register adapters and adapter factory with the adapter manager Register in code at plug-in startup, or use extension point


3.2 Columns

Some debug views are capable of displaying arbitrary columns Columns are only supported in homogeneous views (i.e. views that display

elements from one model at a time) Variables view, Registers view

Clients can customize: Columns to display

Cell editors

Labels for each column


3.2 The Column Players

1. Viewer, Model, & Presentation Context (Same as before) Viewer displays elements from a model in a specific

context (view)

2. Column Presentation Defines columns, headers and images for a context and viewer input

3. Column Presentation Factory Creates columns presentations for specific contexts and elements

4. Element Editor Creates cell editors and cell modifiers

5. Element Label Provider (Same as before) Provides column specific labels for an element


Columns

Viewer ModelPresentation

Context

ColumnPresentation

Factory

ElementEditor

Input Element

Element

ColumnPresentation

CellEditor

CellModifier


Column Presentation

A column presentation defines the columns to be displayed Column headers and images

Column identifiers – each column is assigned a unique id (String)

All available columns and initially visible columns Allows many columns to be provided and a default set of columns that should be

displayed The user can select which columns to be displayed in the viewer

Each column presentation also has a unique id (String) to represent its type/kind

The column presentation in a viewer is updated when the viewer input changes The column presentation is only changed when the type of columns presentation

changes

Whether columns are optional – allows users to toggle columns on/off


Column Presentation Factory

A column presentation factory creates column presentations for specific views and elements

For example, the platform provides a factory to create a column presentation for IStackFrame’s in the Variables view with columns for variable name, declared type, value, and actual type

Implement IColumnPresentationFactory Register the factory with an adapter factory for your debug element

public IColumnPresentation createColumnPresentation(IPresentationContext, Object);

public String getColumnPresentationId(IPresentationContext, Object);


Element Editor

A element editor allows users to edit cell values in-line Provides custom cell editors for each element and column

The widgetry to modify a value Uses JFace CellEditor, which provides standard editors for text, check

boxes, combo boxes, etc.

Provides a cell modifier for each element Determines which columns can be modified, and updates the underlying model

after a cell has been edited Uses JFace ICellModifier


Enhance Label Provider

The label provider generates labels for each column The displayed columns are provided by the label update request:

Columns are represented by their identifiers

public String[] getColumnIds();

Labels must be set in the same order as the label request specifies

public void setLabel(String text, int columnIndex);

Each column also supports foreground/background colors font image


3.2 Summary: Displaying and Editing Columns

1. Implement column presentation Implement IColumnPresentation for each context that you want columns

displayed in

2. Register column presentation factory Implement and register IColumnPresentationFactory to create column

presentations on your debug elements

3. Implement element editor Implement IElementEditor for each element that you want to be able to

edit, and register as adapter on your element

4. Update element label provider to consider columns Update your label provider to specify labels for each column being

displayed in a label request


Java Debugger Columns

The debug platform provides standard columns for the Variables view

The Java debugger specializes the support to only allow primitive and string values to be edited

in-line

provides a drop down editor for boolean values using the ComboBoxCellEditor provided by JFace

provides an additional ‘Instance ID’ column


3.3 Viewer Inputs

By default the active debug context is the input for Variables and Registers

the expression manager is the input for Expressions

However, these views support alternate inputs.


3.3 Viewer Input Players

1. Presentation Context (same as before) defines the context where an input is needed

2. Active Debug Context (same as before) defines the active/selected execution context

3. Viewer Input Provider Provides an alternate viewer input given a presentation context and active

debug context


Input + Context (View) = Alternate Input

Viewer InputProvider

Active Context(Default Input)

PresentationContext

ActualViewer Input


Applications

In 3.4, the Registers view uses this support for standard models to avoid collapsing the all register groups when a new frame is selected.

Provides a proxy as a viewer input representing a set of register groups

The proxy maintains equality if all of its register groups are equal

The viewer remains stable (input does not effectively change as each frame is selected)

Can be used to customize content in the Expression view For example, only display expressions relevant to a specific target rather

than displaying all expressions in the workspace


3.3 Viewer Input Summary

1. Implement and register an IViewerInputProvider adapter for objects that you want to translate viewer inputs for (i.e. active debug context) The viewer input provider computes alternate viewer input asynchronously

given an IViewerInputUpdateRequest.


3.4 Detail Panes & Value Editors

Custom detail panes Default pane is a source viewer

Instead use any SWT Control

User can choose between multiple panes

Value editors Default editing dialog just takes a string

Pressing Ctrl-S in the detail pane calls setValue(String expression) on the variable by default.

Instead provide a custom dialog, custom save handling


3.4 Detail Pane Players

1. Detail Pane Manager Manages contributed panes, determines which pane to display for selection

2. Detail Pane Factories Provides possible detail panes for selection, instantiates detail panes

3. Detail Panes Create an SWT control, displays current selection


Detail Pane Manager

Manages all contributed detail panes By default, only one detail pane available: Source Viewer

When selection changes Queries detail pane factories for possible panes to display

Selects which detail pane to use

If pane has changed, instantiate pane and control

Pass selection to the pane

How to choose between panes? Factories can select a pane as the default for a selection

Manager remembers if a user selects a different pane

Otherwise use the default source viewer


Detail Pane Factories

Contribute a factory implementing IDetailPaneFactory At <detailPaneFactories> extension point

Factory provides possible panes for a selection Manager determines which pane to display

Factory is responsible for instantiating the chosen pane

Use enablement expressions on extension Checks if factory should be enabled without instantiating the factory class

<enablement> <with variable="selection"> <count value="1“/> <iterate><or> <instanceof value="org.eclipse…launcher.TempoControl“/> <instanceof value="org.eclipse…launcher.ClockControl“/> </or></iterate> </with></enablement>


Detail Panes

Must implement IDetailPaneReturned by the detail pane factories for a given selection

A detail pane can provide any SWT control as its displayGiven an IWorkbenchPartSite and Composite

Panes must implement dispose method to clean up when pane is switched


3.4 Value Editor Players

1. Variable Value Editors Responsible for editing and saving values


Variable Value Editors

Contributed to the <variableValueEditor> extension point Implement IVariableValueEditor

Only one editor can be contributed per debug model id

Can provide specialized dialogs for variable editing Given the variable and a shell for creating dialogs with

Java debugger provides specialized dialogs for primitives, Strings and Objects

Can provide custom save handling Given the variable, text from the detail pane and a shell

Java debugger handles the save operation by performing an evaluation on the selected text to compute a new value for the selected variable

Use the shell to open error dialogs


3.4 Detail Panes & Value Editors Summary

1. Implement IDetailPane for each custom detail pane Clean up UI elements in the dispose method

2. Contribute an IDetailPaneFactory to <detailPaneFactories> Return a default pane to override the default text viewer

Use enablement expressions to reducing loading

3. Contribute an IVariableValueEditor to <variableValueEditors> Only one value editor per debug model id, so it must handle all custom dialogs and save

handling for the model.


Module 4:

Custom Updating


Introduction: Viewer Updates

The debug views can display any content Most debug models are dynamic in nature

A model changes state often without user interaction

Examples: thread creation, suspension and termination

Debug views needs to show an accurate representation of the model as it changes state

The model needs a way to inform its view when and how things have changed


4.1 Update Players

1. Viewer, Model, & Presentation Context (same as before) Displays elements from a model

2. Model proxy Describes a model for a specific view as it changes

3. Model deltas Description of how a model has changed

4. Model proxy factory Creates a model proxies for specific views

5. Model selection policy Resolves selection conflicts within a model

6. Model selection policy factory Creates selection policies for specific views


Viewer Updates

Viewer Model

PresentationContext

ModelProxy

Element

fires deltas

add, removerefresh, select

expand

Model ProxyFactory

create

modelspecific

interaction

ContentProvider


Model Proxy

A model proxy interfaces a debugger (underlying model) with a specific view: IModelProxy

Fires deltas as the model changes, specific to a view

A model proxy is tied to a presentation context, representing the content your model has provided via its content adapters

A model proxy usually represents all elements for a single instance of a model (for example, it represents a single Java debug session and fires deltas for all elements within that model – threads, frames, etc.)

You could choose to implement model proxies for each element in a model


Tip: Subclass AbstractModelProxy

The debug platform provides an abstract implementation of IModelProxy that should be sub-classed: AbstractModelProxy. It provides support for:

Adding and removing model delta listeners

Firing deltas to all registered listeners

Access to the context and viewer in which it has been installed

The debug platform provides implementations of model proxies for the standard debug model and standard views

For example, a model proxy is provided for IDebugTarget’s in the debug view. The proxy listens to debug events from a specific debug session and fires corresponding deltas.


Model Delta

An IModelDelta describes an incremental change in a model Similar to a resource delta (IResourceDelta)

Hierarchical description of changes – a tree of nodes rooted at the viewer input element

Each node references a model element and describes how the element changed (if at all), and what action (if any) to perform on the element

Changes and actions are described by flags in each delta node Change flags: ADDED, REMOVED, REPLACED, INSERTED, CONTENT,

STATE, NO_CHANGE

Action flags: SELECT, EXPAND, COLLAPSE, INSTALL, UNINSTALL

Platform provides an implementation of model deltas to be instantiated by model proxy implementations: ModelDelta


Model Delta

Model deltas are similar to resource deltas Describe incremental changes in a hierarchical model

Model deltas describe what changed, how it changed, and what action to perform on an element

Debug Target: NO_CHANGE

Thread: CONTENT | STATE | EXPAND

Stack Frame: STATE | SELECT


Delta Details

The model controls proxy installation and disposal A model proxy is installed for the viewer’s root/input element by the viewer

implementation

After that, a model controls what and when model proxies are installed and uninstalled by firing deltas (in 3.2, a proxy was installed automatically when an element was added to a viewer)

New flags exist: INSTALL and UNINSTALL

Deltas must include indexes and child counts to support expand and select

Supports virtual content retrieval (only retrieve visible children)

Allows expand/select to happen in one pass (vs. iterative)


Model Proxy Factory

The IModelProxyFactory instantiates model proxies for elements in specific contexts

(Note: the model proxy itself could not be an adapter because we need to create context specific proxies, and the getAdapter() infrastructure does not allow for creating different adapters based on context)

public interface IModelProxyFactory {public IModelProxy createModelProxy( Object element, IPresentationContext context);

}


Model Selection Policy

An IModelSelectionPolicy resolves selection conflicts for a model

When a model delta instructs a viewer SELECT, and there is an existing selection, the viewer consults the selection policy of the existing selection

The new selection is set only if: The new selection is contained in the same model as the existing selection and

the new selection should override the existing selection Or the new selection is in a different model and the existing selection is not

“sticky”

Also allowed to set a new selection when an existing selection becomes invalid

If a refresh causes an existing selection to be removed, the model selection policy is given a chance to set a new selection


Default Selection Policy

The debug platform provides a default selection policy for debug elements in the debug view

The policy ensures that when a thread suspends, the newly suspended thread is only selected if there is not a currently suspended stack frame selected

The user’s focus on a suspended context is not changed as other contexts suspend


Selection Policy Factory

A selection policy is created from a selection policy factory: IModelSelectionPolicyFactory

Allows context specific selection policies to be created (i.e. for each view and model)

public IModelSelectionPolicy createModelSelectionPolicy(Object element,IPresentationContext context);


4.1 Summary: Custom Viewer Updates

1. Implement model proxy Implement an IModelProxy for your debugger in each context that it will be

displayed

2. Implement model proxy factory Implement IModelProxyFactory to instantiate your model proxies for each

presentation context it supports

3. Implement model selection policy Implement IModelSelectionPolicy to resolve selection conflicts for your model

4. Implement model selection policy factory Implement IModelSelectionPolicyFactory to instantiate your selection policies

5. Register factories Implement an IAdapterFactory to instantiate your model proxy factory and model

selection policy factory


4.2 Save & Restore of Viewer State

The framework supports expansion, selection and scroll position (top visible element) state saving

Models provide element mementos via IElementMementoProvider

Register adapter with viewer input element Can register adapters with each model element, or use root memento provider

for all elements in a viewer

Viewer has LRU cache of 20 states Currently, cache is not persisted – only present for viewer lifecycle

Used by Variables, Registers, and Expressions views Whenever the viewer input changes, state is saved for the previous input if

the previous input has an IElementMementoProvider


Element Memento Provider

Creates mementos for elements Asynchronously builds a memento for an element

A memento request provides an IMemento to store information in

Compares elements to previously created mementos When a viewer attempts to restore state, the memento provider is consulted

to determine if a given element corresponds to a memento previously created by the provider


Default Memento Providers

The debug platform includes memento providers for the Variables, Registers, and Expressions views

Default mementos are name based


4.3 Source Display Players

1. Suspend Trigger Notifies when an execution context has suspended

2. Source Display Adapter Displays source for an execution context in a workbench page

3. Suspend Trigger Listener Listens for suspends, switches perspectives


Perspective Switching

Launch

SourceLookupService

When a launch is registered the source lookup service asks for its suspend trigger adapter and starts listening to it Triggers perspective switch (if any) on each suspend


Source Lookup

Whenever a debug context is activated, the source lookup service displays source using the context’s source display adapter

The platform provides a source display adapter for stack frames

ActiveContext

SourceLookupService


Legal Notices

Copyright © IBM Corp., 2007-2008. All rights reserved. Source code in this presentation is made available under the EPL, v1.0, remainder of the presentation is licensed under Creative Commons Att. Nc Nd 2.5 license.

IBM and the IBM logo are trademarks or registered trademarks of IBM Corporation, in the United States, other countries or both.

Rational and the Rational logo are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries or both.

Java and all Java-based marks, among others, are trademarks or registered trademarks of Sun Microsystems in the United States, other countries or both.

Eclipse and the Eclipse logo are trademarks of Eclipse Foundation, Inc.

Other company, product and service names may be trademarks or service marks of others.

THE INFORMATION DISCUSSED IN THIS PRESENTATION IS PROVIDED FOR INFORMATIONAL PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION, IT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, AND IBM SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, SUCH INFORMATION. ANY INFORMATION CONCERNING IBM'S PRODUCT PLANS OR STRATEGY IS SUBJECT TO CHANGE BY IBM WITHOUT NOTICE.

Technology

Debug Tutorial Custom Integration