Debug Tutorial Custom Integration


Published on

Published in: Technology, Education
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Debug Tutorial Custom Integration

  1. 1. Debug Platform: Custom Integration Darin Wright, Curtis Windatt IBM Rational Software March 17 th , 2008
  2. 2. Tutorial Structure <ul><li>This tutorial </li></ul><ul><ul><li>Builds on information from “The Basics” tutorial </li></ul></ul><ul><ul><li>Is arranged as a set of modules </li></ul></ul><ul><li>Examples provided </li></ul><ul><ul><li>PDA modified to have no threads (since it’s single threaded) </li></ul></ul><ul><ul><li>MIDI player (demonstrates non-debug model objects in debug views) </li></ul></ul><ul><ul><li>Use the example source code for reference </li></ul></ul><ul><ul><li> </li></ul></ul><ul><ul><ul><li>org.eclipse.debug.examples.core </li></ul></ul></ul><ul><ul><ul><li>org.eclipse.debug.examples.ui </li></ul></ul></ul>
  3. 3. Modules – Custom Integration <ul><li>Overview </li></ul><ul><li>Custom Operations </li></ul><ul><li>Custom Content </li></ul><ul><ul><li>Contents & Labels </li></ul></ul><ul><ul><li>Columns </li></ul></ul><ul><ul><li>Viewer Input </li></ul></ul><ul><ul><li>Detail Panes & Value Editors </li></ul></ul><ul><li>Custom Updating </li></ul><ul><ul><li>Model Proxy </li></ul></ul><ul><ul><li>Save/Restore </li></ul></ul><ul><ul><li>Source Lookup </li></ul></ul>
  4. 4. Module 1: Custom Integration Overview
  5. 5. 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
  6. 6. An Inflexible Platform <ul><li>The standard debug model doesn’t represent all architectures </li></ul><ul><ul><li>Embedded hardware models are different – often there are multiple processors in multi-core, possibly with DSP configurations </li></ul></ul><ul><li>Standard debug views and actions place high demands on the underlying target and enforce a synchronous interaction </li></ul><ul><ul><li>View content and labels are retrieved synchronously in UI thread </li></ul></ul>
  7. 7. A Flexible Platform <ul><li>An arbitrary element hierarchy in all debug platform views </li></ul><ul><ul><li>Additionally, support model specified columns </li></ul></ul><ul><li>A pluggable update mechanism for all views </li></ul><ul><ul><li>Models control what gets updated and when </li></ul></ul><ul><li>Asynchronous interactions between UI and model </li></ul><ul><ul><li>Interactions do not block the UI thread and are cancelable </li></ul></ul><ul><ul><li>Allows implementations to coalesce requests </li></ul></ul><ul><li>Flexible view wiring and retargettable actions </li></ul><ul><ul><li>For example, the input to the variables view may not be a frame </li></ul></ul><ul><li>Pluggable source lookup </li></ul><ul><ul><li>The platform provides a source lookup framework, but you can override it </li></ul></ul>
  8. 8. Debug Platform @since 3.2 Common Debug Perspective, Views & Actions Standard Debug Model Interfaces Implementation of the Standard Model Alternate Debug Implementation Common Interaction Adapters: Content, Labels, Function Standard Adapter Implementation Alternate Adapter Implementation
  9. 9. Custom Model Integration <ul><li>A debugger provides a layer of adapters to interact with the debug platform’s views and actions </li></ul><ul><ul><li>Content and label providers for view content </li></ul></ul><ul><ul><li>Model proxy and deltas for view update </li></ul></ul><ul><ul><li>Command handlers for actions </li></ul></ul><ul><ul><li>Source display adapter </li></ul></ul><ul><li>The debug platform provides adapters for implementations of the standard model </li></ul><ul><ul><li>Existing models continue to work; new models have a choice </li></ul></ul><ul><li>Additionally the platform provides services for debug context management </li></ul><ul><ul><li>Ways to access and provide the active debug context that drives a debug session </li></ul></ul>
  10. 10. Debug Platform 3.3 – Adapters Changed from 3.2 Common Debug Perspective, Views & Actions Standard Debug Model Interfaces Implementation of the Standard Model Alternate Debug Implementation ** Common Interaction Adapters: Content, Labels, Function ** Standard Adapter Implementation ** Alternate Adapter Implementation **
  11. 11. Changes in 3.2 -> 3.3 <ul><li>Some provisional APIs evolved to public </li></ul><ul><ul><li>IDebugContextService & support classes/interfaces </li></ul></ul><ul><li>Leverage the JFace viewer framework </li></ul><ul><ul><li>JFace tree viewer with SWT.VIRTUAL flag, lazy tree content provider, etc. </li></ul></ul><ul><ul><li>Debug has less duplicated/custom viewer code </li></ul></ul><ul><ul><li>More (but not all) of the viewer framework lives in the right place </li></ul></ul>
  12. 12. Public and Provisional API in 3.4 <ul><li>Public API </li></ul><ul><ul><li>Debug Context Management </li></ul></ul><ul><ul><li>Debug Command Handlers </li></ul></ul><ul><ul><li>Source Display </li></ul></ul><ul><ul><li>Suspend Trigger </li></ul></ul><ul><li>Provisional API </li></ul><ul><ul><li>Viewers </li></ul></ul><ul><ul><ul><li>Content </li></ul></ul></ul><ul><ul><ul><li>Labels </li></ul></ul></ul><ul><ul><ul><li>Viewer State </li></ul></ul></ul><ul><ul><ul><li>Viewer Input Service (new in 3.4) </li></ul></ul></ul><ul><li>Viewer framework is still provisional in 3.4 </li></ul><ul><ul><li>Would like to see a general asynchronous viewer framework plug-in evolve that is not debug specific </li></ul></ul>
  13. 13. The Eclipse Adapter Pattern <ul><li>A hook provided by the Eclipse runtime allowing dynamic behavior extensions for objects </li></ul><ul><ul><li>IAdaptable - the interface adaptable objects implement </li></ul></ul><ul><ul><li>IAdaptable a = [some adaptable object]; </li></ul></ul><ul><ul><li>IFoo x = (IFoo)a.getAdapter(IFoo.class); </li></ul></ul><ul><ul><li>if (x != null) </li></ul></ul><ul><ul><li>[do IFoo things with x] </li></ul></ul>
  14. 14. Where do Adapters come from? <ul><li>An object can implement IAdaptable directly, but in order to be extensible via platform extension points, objects must subclass PlatformObject </li></ul><ul><li>Adapters are created by adapter factories ( IAdapterFactory ) </li></ul><ul><ul><li>Object getAdapter(Object adaptable, Class adapterType) </li></ul></ul><ul><ul><li>Class[]getAdapterList() </li></ul></ul><ul><li>You can contribute adapters in two ways: </li></ul><ul><ul><li>Use code to register an adapter factory for a class </li></ul></ul><ul><ul><li>Use the org.eclipse.core.runtime.adapters extension point to register an adapter factory for a class </li></ul></ul>
  15. 15. Adapter Factories: Best Practices <ul><li>It’s best to use the extension point: </li></ul><ul><ul><li>Can extend behavior of classes defined in other plug-ins </li></ul></ul><ul><ul><li>Allows Eclipse to discover adapters even if plug-in is not loaded </li></ul></ul><ul><li><extension point= &quot;org.eclipse.core.runtime.adapters&quot; > </li></ul><ul><li><factory </li></ul><ul><li>class= &quot;org.eclipse.jdt.debug.ui.actions.RetargettableActionAdapterFactory&quot; </li></ul><ul><li>adaptableType= &quot;org.eclipse.jdt.internal.ui.javaeditor.CompilationUnitEditor&quot; > </li></ul><ul><li><adapter type= &quot;org.eclipse.debug.ui.actions.IRunToLineTarget&quot; /> </li></ul><ul><li><adapter type= &quot;org.eclipse.debug.ui.actions.IToggleBreakpointsTarget&quot; /> </li></ul><ul><li>You can use code, but I don’t have a good argument for it: </li></ul><ul><ul><li>Adapters will only be available if plug-in is loaded </li></ul></ul><ul><ul><li>IAdapterManager manager = Platform.getAdapterManager(); </li></ul></ul><ul><ul><li>manager.registerAdapters(IAdapterFactory, Class) </li></ul></ul>
  16. 16. Summary <ul><li>The platform provides </li></ul><ul><ul><li>a layer of pluggable adapters to support non-standard models </li></ul></ul><ul><ul><li>Implementation of adapters for standard models </li></ul></ul><ul><ul><li>flexibility and extensibility for non-standard models </li></ul></ul>
  17. 17. Module 2: Custom Operations (Capabilities)
  18. 18. Debug Operation Players <ul><li>Active Debug Context (model) </li></ul><ul><ul><li>The thing being debugged </li></ul></ul><ul><ul><li>Provided by the context service </li></ul></ul><ul><li>Actions (UI) </li></ul><ul><ul><li>Step over, into, return, suspend, resume, terminate, etc. </li></ul></ul><ul><ul><li>Provided by the platform – buttons, menus, hot keys </li></ul></ul><ul><li>Command Handlers (behavior proxy) </li></ul><ul><ul><li>Pluggable implementations of standard actions </li></ul></ul><ul><ul><li>Platform provides implementation for standard models </li></ul></ul>
  19. 19. (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 service per window)
  20. 20. (3) Debug Command Handlers <ul><li>All handlers are subtypes of IDebugCommandHandler with common methods: </li></ul><ul><ul><li>canExecute(IEnabledStateRequest request) </li></ul></ul><ul><ul><li>execute(IDebugCommandRequest request) </li></ul></ul><ul><li>Interfaces defined in org.eclipse.debug.core.commands </li></ul><ul><li>Standard models can override the platform’s implementation </li></ul><ul><li>Custom models must provide an implementation </li></ul><ul><li>Mechanisms: </li></ul><ul><ul><li>Provide handlers as adapters ( IAdaptable ) </li></ul></ul><ul><ul><li>Implement handler interfaces directly </li></ul></ul>
  21. 21. Common Handlers <ul><li>The set of handlers understood/defined by the platform is static: </li></ul><ul><ul><li>IDisconnectHandler </li></ul></ul><ul><ul><li>IDropToFrameHandler </li></ul></ul><ul><ul><li>IResumeHandler </li></ul></ul><ul><ul><li>IStepFiltersHandler </li></ul></ul><ul><ul><li>IStepIntoHandler </li></ul></ul><ul><ul><li>IStepOverHandler </li></ul></ul><ul><ul><li>IStepReturnHandler </li></ul></ul><ul><ul><li>ISuspendHandler </li></ul></ul><ul><ul><li>ITerminateHandler </li></ul></ul><ul><li>The platform provides standard implementations for these handlers </li></ul><ul><ul><li>Executes the capabilities ( IStep , ITerminate , etc) implemented by the debug model </li></ul></ul><ul><li>Clients can provide their own implementation for any handler they wish to customize </li></ul>
  22. 22. Using Standard Handlers <ul><li>Implement standard model interface and use platform handlers </li></ul><ul><li>Customize capabilities in the model ( IStep , ITerminate , etc) </li></ul>Active Context Step Over Handler Terminate Handler Resume Handler Suspend Handler … Step Over Action Suspend Action Resume Action Terminate Action implements IStep , ISuspendResume , ITerminate … …
  23. 23. Using Custom Handlers <ul><li>Provide custom handlers as adapters </li></ul>Active Context Step Over Handler Terminate Handler Resume Handler Suspend Handler … Step Over Action Suspend Action Resume Action Terminate Action …
  24. 24. Asynchronous Interaction <ul><li>Interactions with a command handler are asynchronous </li></ul><ul><ul><li>Updating enabled state </li></ul></ul><ul><ul><li>Execution </li></ul></ul><ul><li>An IRequest object is passed to the handler </li></ul><ul><ul><li>Similar to a result collector </li></ul></ul><ul><ul><li>Also accepts a status </li></ul></ul><ul><ul><li>Allows for cancellation </li></ul></ul><ul><ul><li>Must be notified when request is complete </li></ul></ul><ul><ul><li>Specialized requests are used </li></ul></ul>
  25. 25. Update Enabled State Debug View Selection (fire) CONTEXT ACTIVATED Context Service Step Over Action (notify) CONTEXT ACTIVATED Step Over Handler Request canExecute(…) setEnabled(…) done() Update enablement
  26. 26. Execute Command Step Over Action Step Over Handler Request execute(…) setStatus(…) done() Notify errors in dialog click | key press remain enabled?
  27. 27. Standard Implementation <ul><li>The handlers provided by the platform uses jobs to implement asynchronous interactions with the standard synchronous APIs </li></ul><ul><ul><li>The handler schedules a job for each request and returns </li></ul></ul><ul><ul><li>The job runs asynchronously </li></ul></ul><ul><ul><li>When the job is complete, the request is updated with the status, result and done() is called on the request </li></ul></ul><ul><ul><li>Enabled state jobs are scheduled serially on the debug context </li></ul></ul><ul><ul><li>Execution jobs do not have scheduling rules </li></ul></ul><ul><ul><ul><li>Allows enabled state to be updated while executing a request </li></ul></ul></ul>
  28. 28. Summary <ul><li>Operations (step, suspend, etc.) are handled by debug command handlers </li></ul><ul><ul><li>Platform has a static list of handler types: IDisconnectHandler, IResumeHandler, etc. </li></ul></ul><ul><li>The platform provides default handlers </li></ul><ul><ul><li>Only available to the standard debug model </li></ul></ul><ul><ul><li>Asynchronously calls capabilities on the selected debug element </li></ul></ul><ul><ul><li>Implement capabilities ( IStep , ISuspendResume , etc.) on debug model elements to determine behaviour. </li></ul></ul><ul><li>The platform handlers can be replaced with your own </li></ul><ul><ul><li>Added as adapters on the debug model elements </li></ul></ul>
  29. 29. Module 3: Custom Content
  30. 30. Overview <ul><li>3.1 Contents & Labels </li></ul><ul><li>3.2 Columns </li></ul><ul><li>3.3 Viewer Input </li></ul><ul><li>3.4 Detail Panes & Value Editors </li></ul>
  31. 31. 3.1 Content & Label Players <ul><li>Viewer </li></ul><ul><ul><li>Displays elements from a model </li></ul></ul><ul><li>Presentation Context </li></ul><ul><ul><li>Identifies the view or context in which elements are being displayed </li></ul></ul><ul><li>Model </li></ul><ul><ul><li>Underlying debugger implementation (or any model) </li></ul></ul><ul><li>Element Content Provider </li></ul><ul><ul><li>Identifies which elements have children in a given context, how many children, and provides children in sub ranges </li></ul></ul><ul><li>Element Label Provider </li></ul><ul><ul><li>Provides text and images for model elements in a given context </li></ul></ul><ul><li>Request </li></ul><ul><ul><li>Collects results of each request asynchronously </li></ul></ul>
  32. 32. Goal <ul><li>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. </li></ul>
  33. 33. Content & Labels JFace Tree Viewer Debug Model Element Element Content Provider Label Provider update(…) updateHasChildren(…) updateChildCount(…) updateElement(…) Element Content Provider update(…) Request done() replace(…), setChildCount(…) setHasChildren(…) Element Label Provider update(…) Request done() setText(…), setImage(…), …
  34. 34. Properties of the Interaction <ul><li>The interaction is extensible </li></ul><ul><ul><li>Extensibility provided by adapters, allows for arbitrary model API </li></ul></ul><ul><li>The interaction is context sensitive </li></ul><ul><ul><li>The presentation context identifies the part requesting content, allowing for different content in different views </li></ul></ul><ul><li>The interaction is asynchronous </li></ul><ul><ul><li>The content and label providers retrieve information in a non-blocking fashion, reporting results to a request and notifying it when done </li></ul></ul><ul><li>The interaction is cancelable </li></ul><ul><ul><li>The request can be canceled by the platform or model </li></ul></ul><ul><li>The interaction reports errors </li></ul><ul><ul><li>The request carries a status to inform the user of failures that arise </li></ul></ul>
  35. 35. The Viewer <ul><li>The debug platform provides an implementation of a tree viewer with a special content provider to support custom asynchronous content </li></ul><ul><ul><li>Based on JFace tree viewer with an ILazyTreePathContentProvider </li></ul></ul><ul><ul><li>The viewer is currently provisional API </li></ul></ul><ul><ul><li>The viewer is not intended to be subclassed, but can be instantiated </li></ul></ul><ul><ul><li>The viewer comes with a content provider that must be used (this is the guts of the asynchronous content mechanism) </li></ul></ul><ul><ul><li>See TreeModelViewer for more information </li></ul></ul>
  36. 36. Filtering <ul><li>JFace does not support filtering in virtual tree viewers </li></ul><ul><ul><li>Since all elements are not retrieved at once </li></ul></ul><ul><li>For backwards compatibility, debug has added support for filters </li></ul><ul><ul><li>The filters work incrementally – as elements are added to the viewer, filters are applied </li></ul></ul><ul><ul><li>Side effect – scrollbars can grow shrink if many elements are filtered </li></ul></ul><ul><ul><li>For a more stable UI, models/content providers can perform filtering </li></ul></ul><ul><ul><li>In 3.4, the Java debugger content adapters filter variables </li></ul></ul><ul><ul><ul><li>Note: Requires all content to be retrieved in order to know what was filtered and what the filtered child count will be </li></ul></ul></ul><ul><li>Sorting is not supported </li></ul><ul><ul><li>Models/content providers must perform sorting if desired </li></ul></ul>
  37. 37. Presentation Context <ul><li>Describes the context in which a request has been made: </li></ul><ul><li>IPresentationContext </li></ul><ul><li>public String getId(); </li></ul><ul><li>public String[] getColumns(); </li></ul><ul><li>Allows adapters to provide different content in different contexts </li></ul><ul><li>The “id” roughly corresponds to view identifiers (but is no longer tied to a workbench part, to support viewers that are not in parts) </li></ul><ul><li>A viewer is created with a specific context </li></ul><ul><li>Clients may specialize a presentation context to provide more information (subclass base PresentationContext class) </li></ul>
  38. 38. The Model <ul><li>Any hierarchical model, for example </li></ul><ul><ul><li>Implementation of standard debug model </li></ul></ul><ul><ul><li>Implementation of a non-standard debug model </li></ul></ul><ul><ul><li>A file system… </li></ul></ul><ul><ul><li>Anything </li></ul></ul>
  39. 39. Element Content Provider <ul><li>Provides context sensitive content for an element </li></ul><ul><ul><li>Implement directly, or provided as an adapter </li></ul></ul><ul><li>Each update request is a specialized viewer update (which is a specialized IRequest ), identifying context and element for the request: </li></ul>
  40. 40. Content Requests
  41. 41. Implementing a Content Provider <ul><li>Content provider must process requests asynchronously (i.e. non-blocking) </li></ul><ul><li>The platform uses jobs to implement asynchronous interactions with the standard synchronous APIs </li></ul><ul><ul><li>Schedules a job for each request and returns </li></ul></ul><ul><ul><li>The job runs asynchronously and fills in information on request </li></ul></ul><ul><ul><li>When the job is complete, the request is updated with any status, and done() is called on the request </li></ul></ul><ul><ul><li>@see ElementContentProvider – a base class that uses jobs to generate content from synchronous model APIs </li></ul></ul>
  42. 42. Label Provider <ul><li>Provides context sensitive labels for elements </li></ul><ul><ul><li>Implemented directly or provided as an adapter </li></ul></ul><ul><ul><li>Provides text, font, image, foreground and background colors </li></ul></ul><ul><ul><li>Must be non-blocking, platform uses jobs… </li></ul></ul>
  43. 43. Compatibility with IDebugModelPresentation <ul><li>The debug platform registers label providers for all standard debug model elements </li></ul><ul><ul><li>Delegates to the appropriate model presentation for each object to compute labels for backwards compatibility </li></ul></ul><ul><li>Clients may continue using IDebugModelPresentations </li></ul><ul><ul><li>May choose to separate model presentation into new label providers </li></ul></ul><ul><ul><li>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 </li></ul></ul><ul><ul><li>The Java debugger uses a mix </li></ul></ul><ul><ul><ul><li>Original model presentation for its standard elements </li></ul></ul></ul><ul><ul><ul><li>Label providers for locks, monitors, thread groups, references </li></ul></ul></ul>
  44. 44. Which thread are labels computed in? <ul><li>If you provide your own label adapters, the choice is up to you. </li></ul><ul><li>By default, the platform uses a non-UI thread to compute labels </li></ul><ul><ul><li>This sometimes causes problems when populating image registries (which requires the UI thread) </li></ul></ul><ul><li>In 3.4, IDebugModelPresentationExtension has been added </li></ul><ul><ul><li>Allows models to dynamically control if the UI thread should be used: </li></ul></ul><ul><ul><li>public boolean requiresUIThread(Object element); </li></ul></ul>
  45. 45. Same Old Problem <ul><li>There can only be one adapter (type) per object (type) </li></ul><ul><ul><li>3 rd parties can’t </li></ul></ul><ul><ul><ul><li>Extend adapters for new views </li></ul></ul></ul><ul><ul><ul><li>Modify or extend content in existing views </li></ul></ul></ul><ul><li>Assumption we’ve be going on </li></ul><ul><ul><li>The debug model implementation provides all adapters (or re-uses the platform adapters) </li></ul></ul><ul><ul><li>Debuggers are not extended in downstream plug-ins </li></ul></ul><ul><li>Would require use of an extension point to contribute content and label providers </li></ul>
  46. 46. Customizing Launch Content <ul><li>The input to the Debug view is the ILaunchManager , which displays all registered launches as root elements </li></ul><ul><ul><li>To customize content for a launch object, you must provide your own implementation of an ILaunch and a content adapter for it </li></ul></ul><ul><ul><ul><li>The platform registers content/label providers for ILaunch , so you register adapters for your implementation class </li></ul></ul></ul><ul><ul><li>Customizing content for elements within a launch is simpler, as you only need to register custom adapters for your objects </li></ul></ul><ul><ul><li>MIDI example provides a custom launch implementation </li></ul></ul>
  47. 47. 3.1 Summary: Content & Labels <ul><li>Implement content providers </li></ul><ul><ul><li>For each model element implement an IElementContentProvider </li></ul></ul><ul><li>Implement label providers </li></ul><ul><ul><li>For each model element implement an IElementLabelProvider </li></ul></ul><ul><li>Implement adapter factory </li></ul><ul><ul><li>Implement an IAdapterFactory to instantiate content and label providers for the model elements </li></ul></ul><ul><li>Register adapters and adapter factory with the adapter manager </li></ul><ul><ul><li>Register in code at plug-in startup, or use extension point </li></ul></ul>
  48. 48. 3.2 Columns <ul><li>Some debug views are capable of displaying arbitrary columns </li></ul><ul><ul><li>Columns are only supported in homogeneous views (i.e. views that display elements from one model at a time) </li></ul></ul><ul><ul><ul><li>Variables view, Registers view </li></ul></ul></ul><ul><li>Clients can customize: </li></ul><ul><ul><li>Columns to display </li></ul></ul><ul><ul><li>Cell editors </li></ul></ul><ul><ul><li>Labels for each column </li></ul></ul>
  49. 49. 3.2 The Column Players <ul><li>Viewer, Model, & Presentation Context </li></ul><ul><ul><li>(Same as before) Viewer displays elements from a model in a specific context (view) </li></ul></ul><ul><li>Column Presentation </li></ul><ul><ul><li>Defines columns, headers and images for a context and viewer input </li></ul></ul><ul><li>Column Presentation Factory </li></ul><ul><ul><li>Creates columns presentations for specific contexts and elements </li></ul></ul><ul><li>Element Editor </li></ul><ul><ul><li>Creates cell editors and cell modifiers </li></ul></ul><ul><li>Element Label Provider </li></ul><ul><ul><li>(Same as before) Provides column specific labels for an element </li></ul></ul>
  50. 50. Columns Viewer Model Presentation Context Column Presentation Factory Element Editor Input Element Element Column Presentation Cell Editor Cell Modifier
  51. 51. Column Presentation <ul><li>A column presentation defines the columns to be displayed </li></ul><ul><ul><li>Column headers and images </li></ul></ul><ul><ul><li>Column identifiers – each column is assigned a unique id ( String ) </li></ul></ul><ul><ul><li>All available columns and initially visible columns </li></ul></ul><ul><ul><ul><li>Allows many columns to be provided and a default set of columns that should be displayed </li></ul></ul></ul><ul><ul><ul><li>The user can select which columns to be displayed in the viewer </li></ul></ul></ul><ul><ul><li>Each column presentation also has a unique id ( String ) to represent its type/kind </li></ul></ul><ul><ul><ul><li>The column presentation in a viewer is updated when the viewer input changes </li></ul></ul></ul><ul><ul><ul><li>The column presentation is only changed when the type of columns presentation changes </li></ul></ul></ul><ul><ul><li>Whether columns are optional – allows users to toggle columns on/off </li></ul></ul>
  52. 52. Column Presentation Factory <ul><li>A column presentation factory creates column presentations for specific views and elements </li></ul><ul><ul><li>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 </li></ul></ul><ul><ul><li>Implement IColumnPresentationFactory </li></ul></ul><ul><ul><li>Register the factory with an adapter factory for your debug element </li></ul></ul><ul><ul><li>public IColumnPresentation createColumnPresentation(IPresentationContext, Object); </li></ul></ul><ul><ul><li>public String getColumnPresentationId(IPresentationContext, Object); </li></ul></ul>
  53. 53. Element Editor <ul><li>A element editor allows users to edit cell values in-line </li></ul><ul><ul><li>Provides custom cell editors for each element and column </li></ul></ul><ul><ul><ul><li>The widgetry to modify a value </li></ul></ul></ul><ul><ul><ul><li>Uses JFace CellEditor , which provides standard editors for text, check boxes, combo boxes, etc. </li></ul></ul></ul><ul><ul><li>Provides a cell modifier for each element </li></ul></ul><ul><ul><ul><li>Determines which columns can be modified, and updates the underlying model after a cell has been edited </li></ul></ul></ul><ul><ul><ul><li>Uses JFace ICellModifier </li></ul></ul></ul>
  54. 54. Enhance Label Provider <ul><li>The label provider generates labels for each column </li></ul><ul><ul><li>The displayed columns are provided by the label update request: </li></ul></ul><ul><ul><ul><li>Columns are represented by their identifiers </li></ul></ul></ul><ul><ul><li>public String[] getColumnIds(); </li></ul></ul><ul><ul><li>Labels must be set in the same order as the label request specifies </li></ul></ul><ul><ul><li>public void setLabel(String text, int columnIndex); </li></ul></ul><ul><ul><li>Each column also supports </li></ul></ul><ul><ul><ul><li>foreground/background colors </li></ul></ul></ul><ul><ul><ul><li>font </li></ul></ul></ul><ul><ul><ul><li>image </li></ul></ul></ul>
  55. 55. 3.2 Summary: Displaying and Editing Columns <ul><li>Implement column presentation </li></ul><ul><ul><li>Implement IColumnPresentation for each context that you want columns displayed in </li></ul></ul><ul><li>Register column presentation factory </li></ul><ul><ul><li>Implement and register IColumnPresentationFactory to create column presentations on your debug elements </li></ul></ul><ul><li>Implement element editor </li></ul><ul><ul><li>Implement IElementEditor for each element that you want to be able to edit, and register as adapter on your element </li></ul></ul><ul><li>Update element label provider to consider columns </li></ul><ul><ul><li>Update your label provider to specify labels for each column being displayed in a label request </li></ul></ul>
  56. 56. Java Debugger Columns <ul><li>The debug platform provides standard columns for the Variables view </li></ul><ul><li>The Java debugger </li></ul><ul><ul><li>specializes the support to only allow primitive and string values to be edited in-line </li></ul></ul><ul><ul><li>provides a drop down editor for boolean values using the ComboBoxCellEditor provided by JFace </li></ul></ul><ul><ul><li>provides an additional ‘Instance ID’ column </li></ul></ul>
  57. 57. 3.3 Viewer Inputs <ul><li>By default </li></ul><ul><ul><li>the active debug context is the input for Variables and Registers </li></ul></ul><ul><ul><li>the expression manager is the input for Expressions </li></ul></ul><ul><li>However, these views support alternate inputs. </li></ul>
  58. 58. 3.3 Viewer Input Players <ul><li>Presentation Context </li></ul><ul><ul><li>(same as before) defines the context where an input is needed </li></ul></ul><ul><li>Active Debug Context </li></ul><ul><ul><li>(same as before) defines the active/selected execution context </li></ul></ul><ul><li>Viewer Input Provider </li></ul><ul><ul><li>Provides an alternate viewer input given a presentation context and active debug context </li></ul></ul>
  59. 59. Input + Context (View) = Alternate Input Viewer Input Provider Active Context (Default Input) Presentation Context Actual Viewer Input
  60. 60. Applications <ul><li>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. </li></ul><ul><ul><li>Provides a proxy as a viewer input representing a set of register groups </li></ul></ul><ul><ul><li>The proxy maintains equality if all of its register groups are equal </li></ul></ul><ul><ul><li>The viewer remains stable (input does not effectively change as each frame is selected) </li></ul></ul><ul><li>Can be used to customize content in the Expression view </li></ul><ul><ul><li>For example, only display expressions relevant to a specific target rather than displaying all expressions in the workspace </li></ul></ul>
  61. 61. 3.3 Viewer Input Summary <ul><li>Implement and register an IViewerInputProvider adapter for objects that you want to translate viewer inputs for (i.e. active debug context) </li></ul><ul><ul><li>The viewer input provider computes alternate viewer input asynchronously given an IViewerInputUpdateRequest . </li></ul></ul>
  62. 62. 3.4 Detail Panes & Value Editors <ul><li>Custom detail panes </li></ul><ul><ul><li>Default pane is a source viewer </li></ul></ul><ul><ul><li>Instead use any SWT Control </li></ul></ul><ul><ul><li>User can choose between multiple panes </li></ul></ul><ul><li>Value editors </li></ul><ul><ul><li>Default editing dialog just takes a string </li></ul></ul><ul><ul><li>Pressing Ctrl-S in the detail pane calls setValue(String expression) on the variable by default. </li></ul></ul><ul><ul><li>Instead provide a custom dialog, custom save handling </li></ul></ul>
  63. 63. 3.4 Detail Pane Players <ul><li>Detail Pane Manager </li></ul><ul><ul><li>Manages contributed panes, determines which pane to display for selection </li></ul></ul><ul><li>Detail Pane Factories </li></ul><ul><ul><li>Provides possible detail panes for selection, instantiates detail panes </li></ul></ul><ul><li>Detail Panes </li></ul><ul><ul><li>Create an SWT control, displays current selection </li></ul></ul>
  64. 64. Detail Pane Manager <ul><li>Manages all contributed detail panes </li></ul><ul><ul><li>By default, only one detail pane available: Source Viewer </li></ul></ul><ul><li>When selection changes </li></ul><ul><ul><li>Queries detail pane factories for possible panes to display </li></ul></ul><ul><ul><li>Selects which detail pane to use </li></ul></ul><ul><ul><li>If pane has changed, instantiate pane and control </li></ul></ul><ul><ul><li>Pass selection to the pane </li></ul></ul><ul><li>How to choose between panes? </li></ul><ul><ul><li>Factories can select a pane as the default for a selection </li></ul></ul><ul><ul><li>Manager remembers if a user selects a different pane </li></ul></ul><ul><ul><li>Otherwise use the default source viewer </li></ul></ul>
  65. 65. Detail Pane Factories <ul><li>Contribute a factory implementing IDetailPaneFactory </li></ul><ul><ul><li>At <detailPaneFactories> extension point </li></ul></ul><ul><li>Factory provides possible panes for a selection </li></ul><ul><ul><li>Manager determines which pane to display </li></ul></ul><ul><ul><li>Factory is responsible for instantiating the chosen pane </li></ul></ul><ul><li>Use enablement expressions on extension </li></ul><ul><ul><li>Checks if factory should be enabled without instantiating the factory class </li></ul></ul><ul><ul><li><enablement> </li></ul></ul><ul><ul><li><with variable=&quot;selection&quot;> </li></ul></ul><ul><ul><li><count value=&quot;1“/> </li></ul></ul><ul><ul><li><iterate><or> </li></ul></ul><ul><ul><li><instanceof value=&quot;org.eclipse…launcher.TempoControl“/> </li></ul></ul><ul><ul><li><instanceof value=&quot;org.eclipse…launcher.ClockControl“/> </li></ul></ul><ul><ul><li></or></iterate> </li></ul></ul><ul><ul><li></with> </li></ul></ul><ul><ul><li></enablement> </li></ul></ul>
  66. 66. Detail Panes <ul><li>Must implement IDetailPane </li></ul><ul><ul><li>Returned by the detail pane factories for a given selection </li></ul></ul><ul><li>A detail pane can provide any SWT control as its display </li></ul><ul><ul><li>Given an IWorkbenchPartSite and Composite </li></ul></ul><ul><ul><li>Panes must implement dispose method to clean up when pane is switched </li></ul></ul>
  67. 67. 3.4 Value Editor Players <ul><li>Variable Value Editors </li></ul><ul><ul><li>Responsible for editing and saving values </li></ul></ul>
  68. 68. Variable Value Editors <ul><li>Contributed to the <variableValueEditor> extension point </li></ul><ul><ul><li>Implement IVariableValueEditor </li></ul></ul><ul><ul><li>Only one editor can be contributed per debug model id </li></ul></ul><ul><li>Can provide specialized dialogs for variable editing </li></ul><ul><ul><li>Given the variable and a shell for creating dialogs with </li></ul></ul><ul><ul><li>Java debugger provides specialized dialogs for primitives, Strings and Objects </li></ul></ul><ul><li>Can provide custom save handling </li></ul><ul><ul><li>Given the variable, text from the detail pane and a shell </li></ul></ul><ul><ul><li>Java debugger handles the save operation by performing an evaluation on the selected text to compute a new value for the selected variable </li></ul></ul><ul><ul><li>Use the shell to open error dialogs </li></ul></ul>
  69. 69. 3.4 Detail Panes & Value Editors Summary <ul><li>Implement IDetailPane for each custom detail pane </li></ul><ul><ul><li>Clean up UI elements in the dispose method </li></ul></ul><ul><li>Contribute an IDetailPaneFactory to <detailPaneFactories> </li></ul><ul><ul><li>Return a default pane to override the default text viewer </li></ul></ul><ul><ul><li>Use enablement expressions to reducing loading </li></ul></ul><ul><li>Contribute an IVariableValueEditor to <variableValueEditors> </li></ul><ul><ul><li>Only one value editor per debug model id, so it must handle all custom dialogs and save handling for the model. </li></ul></ul>
  70. 70. Module 4: Custom Updating
  71. 71. Introduction: Viewer Updates <ul><li>The debug views can display any content </li></ul><ul><li>Most debug models are dynamic in nature </li></ul><ul><ul><li>A model changes state often without user interaction </li></ul></ul><ul><ul><li>Examples: thread creation, suspension and termination </li></ul></ul><ul><li>Debug views needs to show an accurate representation of the model as it changes state </li></ul><ul><ul><li>The model needs a way to inform its view when and how things have changed </li></ul></ul>
  72. 72. 4.1 Update Players <ul><li>Viewer, Model, & Presentation Context </li></ul><ul><ul><li>(same as before) Displays elements from a model </li></ul></ul><ul><li>Model proxy </li></ul><ul><ul><li>Describes a model for a specific view as it changes </li></ul></ul><ul><li>Model deltas </li></ul><ul><ul><li>Description of how a model has changed </li></ul></ul><ul><li>Model proxy factory </li></ul><ul><ul><li>Creates a model proxies for specific views </li></ul></ul><ul><li>Model selection policy </li></ul><ul><ul><li>Resolves selection conflicts within a model </li></ul></ul><ul><li>Model selection policy factory </li></ul><ul><ul><li>Creates selection policies for specific views </li></ul></ul>
  73. 73. Viewer Updates Viewer Model Presentation Context Model Proxy Element fires deltas add, remove refresh, select expand Model Proxy Factory create model specific interaction Content Provider
  74. 74. Model Proxy <ul><li>A model proxy interfaces a debugger (underlying model) with a specific view: IModelProxy </li></ul><ul><ul><li>Fires deltas as the model changes, specific to a view </li></ul></ul><ul><ul><li>A model proxy is tied to a presentation context, representing the content your model has provided via its content adapters </li></ul></ul><ul><ul><li>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.) </li></ul></ul><ul><ul><ul><li>You could choose to implement model proxies for each element in a model </li></ul></ul></ul>
  75. 75. Tip: Subclass AbstractModelProxy <ul><li>The debug platform provides an abstract implementation of IModelProxy that should be sub-classed: AbstractModelProxy . It provides support for: </li></ul><ul><ul><li>Adding and removing model delta listeners </li></ul></ul><ul><ul><li>Firing deltas to all registered listeners </li></ul></ul><ul><ul><li>Access to the context and viewer in which it has been installed </li></ul></ul><ul><li>The debug platform provides implementations of model proxies for the standard debug model and standard views </li></ul><ul><ul><li>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. </li></ul></ul>
  76. 76. Model Delta <ul><li>An IModelDelta describes an incremental change in a model </li></ul><ul><ul><li>Similar to a resource delta ( IResourceDelta ) </li></ul></ul><ul><ul><li>Hierarchical description of changes – a tree of nodes rooted at the viewer input element </li></ul></ul><ul><ul><li>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 </li></ul></ul><ul><li>Changes and actions are described by flags in each delta node </li></ul><ul><ul><li>Change flags: ADDED, REMOVED, REPLACED, INSERTED, CONTENT, STATE, NO_CHANGE </li></ul></ul><ul><ul><li>Action flags: SELECT, EXPAND, COLLAPSE, INSTALL, UNINSTALL </li></ul></ul><ul><li>Platform provides an implementation of model deltas to be instantiated by model proxy implementations: ModelDelta </li></ul>
  77. 77. Model Delta <ul><li>Model deltas are similar to resource deltas </li></ul><ul><ul><li>Describe incremental changes in a hierarchical model </li></ul></ul><ul><ul><li>Model deltas describe what changed, how it changed, and what action to perform on an element </li></ul></ul>Debug Target: NO_CHANGE Thread: CONTENT | STATE | EXPAND Stack Frame: STATE | SELECT
  78. 78. Delta Details <ul><li>The model controls proxy installation and disposal </li></ul><ul><ul><li>A model proxy is installed for the viewer’s root/input element by the viewer implementation </li></ul></ul><ul><ul><li>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) </li></ul></ul><ul><ul><li>New flags exist: INSTALL and UNINSTALL </li></ul></ul><ul><li>Deltas must include indexes and child counts to support expand and select </li></ul><ul><ul><li>Supports virtual content retrieval (only retrieve visible children) </li></ul></ul><ul><ul><li>Allows expand/select to happen in one pass (vs. iterative) </li></ul></ul>
  79. 79. Model Proxy Factory <ul><li>The IModelProxyFactory instantiates model proxies for elements in specific contexts </li></ul><ul><ul><li>(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) </li></ul></ul><ul><li>public interface IModelProxyFactory { </li></ul><ul><li>public IModelProxy createModelProxy( </li></ul><ul><li> Object element, IPresentationContext context); </li></ul><ul><li>} </li></ul>
  80. 80. Model Selection Policy <ul><li>An IModelSelectionPolicy resolves selection conflicts for a model </li></ul><ul><ul><li>When a model delta instructs a viewer SELECT, and there is an existing selection, the viewer consults the selection policy of the existing selection </li></ul></ul><ul><ul><li>The new selection is set only if: </li></ul></ul><ul><ul><ul><li>The new selection is contained in the same model as the existing selection and the new selection should override the existing selection </li></ul></ul></ul><ul><ul><ul><li>Or the new selection is in a different model and the existing selection is not “sticky” </li></ul></ul></ul><ul><li>Also allowed to set a new selection when an existing selection becomes invalid </li></ul><ul><ul><li>If a refresh causes an existing selection to be removed, the model selection policy is given a chance to set a new selection </li></ul></ul>
  81. 81. Default Selection Policy <ul><li>The debug platform provides a default selection policy for debug elements in the debug view </li></ul><ul><ul><li>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 </li></ul></ul><ul><ul><ul><li>The user’s focus on a suspended context is not changed as other contexts suspend </li></ul></ul></ul>
  82. 82. Selection Policy Factory <ul><li>A selection policy is created from a selection policy factory: IModelSelectionPolicyFactory </li></ul><ul><li>Allows context specific selection policies to be created (i.e. for each view and model) </li></ul><ul><li>public IModelSelectionPolicy createModelSelectionPolicy( </li></ul><ul><li>Object element, </li></ul><ul><li>IPresentationContext context); </li></ul>
  83. 83. 4.1 Summary: Custom Viewer Updates <ul><li>Implement model proxy </li></ul><ul><ul><li>Implement an IModelProxy for your debugger in each context that it will be displayed </li></ul></ul><ul><li>Implement model proxy factory </li></ul><ul><ul><li>Implement IModelProxyFactory to instantiate your model proxies for each presentation context it supports </li></ul></ul><ul><li>Implement model selection policy </li></ul><ul><ul><li>Implement IModelSelectionPolicy to resolve selection conflicts for your model </li></ul></ul><ul><li>Implement model selection policy factory </li></ul><ul><ul><li>Implement IModelSelectionPolicyFactory to instantiate your selection policies </li></ul></ul><ul><li>Register factories </li></ul><ul><ul><li>Implement an IAdapterFactory to instantiate your model proxy factory and model selection policy factory </li></ul></ul>
  84. 84. 4.2 Save & Restore of Viewer State <ul><li>The framework supports expansion, selection and scroll position (top visible element) state saving </li></ul><ul><ul><li>Models provide element mementos via IElementMementoProvider </li></ul></ul><ul><ul><li>Register adapter with viewer input element </li></ul></ul><ul><ul><ul><li>Can register adapters with each model element, or use root memento provider for all elements in a viewer </li></ul></ul></ul><ul><ul><li>Viewer has LRU cache of 20 states </li></ul></ul><ul><ul><ul><li>Currently, cache is not persisted – only present for viewer lifecycle </li></ul></ul></ul><ul><li>Used by Variables, Registers, and Expressions views </li></ul><ul><ul><li>Whenever the viewer input changes, state is saved for the previous input if the previous input has an IElementMementoProvider </li></ul></ul>
  85. 85. Element Memento Provider <ul><li>Creates mementos for elements </li></ul><ul><ul><li>Asynchronously builds a memento for an element </li></ul></ul><ul><ul><li>A memento request provides an IMemento to store information in </li></ul></ul><ul><li>Compares elements to previously created mementos </li></ul><ul><ul><li>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 </li></ul></ul>
  86. 86. Default Memento Providers <ul><li>The debug platform includes memento providers for the Variables, Registers, and Expressions views </li></ul><ul><ul><li>Default mementos are name based </li></ul></ul>
  87. 87. 4.3 Source Display Players <ul><li>Suspend Trigger </li></ul><ul><ul><li>Notifies when an execution context has suspended </li></ul></ul><ul><li>Source Display Adapter </li></ul><ul><ul><li>Displays source for an execution context in a workbench page </li></ul></ul><ul><li>Suspend Trigger Listener </li></ul><ul><ul><li>Listens for suspends, switches perspectives </li></ul></ul>
  88. 88. Perspective Switching <ul><li>When a launch is registered the source lookup service asks for its suspend trigger adapter and starts listening to it </li></ul><ul><ul><li>Triggers perspective switch (if any) on each suspend </li></ul></ul>Launch Source Lookup Service
  89. 89. Source Lookup <ul><li>Whenever a debug context is activated, the source lookup service displays source using the context’s source display adapter </li></ul><ul><ul><li>The platform provides a source display adapter for stack frames </li></ul></ul>Active Context Source Lookup Service
  90. 90. Legal Notices <ul><li>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. </li></ul><ul><li>IBM and the IBM logo are trademarks or registered trademarks of IBM Corporation, in the United States, other countries or both. </li></ul><ul><li>Rational and the Rational logo are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries or both. </li></ul><ul><li>Java and all Java-based marks, among others, are trademarks or registered trademarks of Sun Microsystems in the United States, other countries or both. </li></ul><ul><li>Eclipse and the Eclipse logo are trademarks of Eclipse Foundation, Inc. </li></ul><ul><li>Other company, product and service names may be trademarks or service marks of others. </li></ul><ul><li>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 &quot;AS IS&quot; 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. </li></ul>