EDT:Debug Extensibility

If you are extending the EGL language or Java generator, you may find you need to also extend the Java-based debugger to improve the user experience. For example if you are adding a new Java class to represent an EGL type in the generated application, it will probably not look very nice in the Variables view (by default it will be displayed in the Java way, which might not match how it should be represented to an EGL user).

This document will cover the ways in which the debugger can be extended.  

 Java variable adapters  

Plug-in to check out from Git: org.eclipse.edt.debug.core

If you wish to control how a Java variable is displayed in the Variables view, you will need to contribute a variable adapter to the EDT Java debug framework. This is done with Eclipse extension points. In your plug-in's manifest editor, add an extension for org.eclipse.edt.debug.core.javaVariableAdapters. Take a look at the schema for its definition at org.eclipse.edt.debug.core/schema/javaVariableAdapters.exsd. A reference implementation can be found in org.eclipse.edt.debug.core's plugin.xml file (see the corresponding class org.eclipse.edt.debug.internal.core.java.variables.EDTVariableAdapter).

Your contributed class will need to implement org.eclipse.edt.debug.core.java.variables.IVariableAdapter. Take a look at its source, as well as other relevant classes & interfaces, for Javadocs.

The basic idea behind a variable adapter is, given a Java variable (IJavaVariable), you first determine if it's a type you wish to adapt. If so, you then must return an IEGLJavaVariable that will correctly structure the Java variable. If the Java variable is not a type to be handled by your adapter, simply return null and the next registered adapter will be given a chance to adapt it. Note: first adapter to return a non-null variable wins, and the order of adapters being consulted is not guaranteed!

You may find several methods in org.eclipse.edt.debug.core.java.variables.VariableUtil to be useful. For example, VariableUtil.isInstanceOf() can tell you if a Java variable is of a particular type.

Since you're not working directly with the Java object instance, to execute any code on the variable you need to send messages to the separate Java process using API provided by Eclipse Java Development Tools (JDT). The format for the required information can be cumbersome and hard to determine, but VariableUtil.runSendMessage() should be used for all evaluations. Take a look at org.eclipse.edt.debug.internal.core.java.variables.MapVariable to see how a complex variable can be restructured.

Java type filters

Plug-in to check out from Git: org.eclipse.edt.debug.core

When the debugger is suspended, by default its stack will display all the frames for both Java and EGL. It's less confusing to the EGL programmer to hide the frames that are part of the underlying technology, and show just the frames that have to do with their code. When stepping through code, it's also very tedious to the user to step into our runtime classes (either from the EDT Java runtime, or JRE classes). To get past both these issues there is an extension for contributing type filters. These filters will prevent stepping into certain types, as well as hide the types from the debug stack display.

Filters are organized into various categories. Enabling a category will cause all its contained filters to be enabled. New categories can be defined, or you can add your filter to an existing category (if the category you specify does not exist, the filter will be ignored). Categories can be visible or invisible; when visible it will appear in the EDT Java debug preference page and the user can enable or disable the category; when invisible the user cannot toggle its enablement. When a filter is hit, the category's step type will determine how to proceed - the user can configure the visible filters in preferences to either perform a "step into" or a "step return". The "step return" will perform much better, but prevents you from stepping through the filtered class into a type that wouldn't be filtered.

The extension point for contributing filters and categories is org.eclipse.edt.debug.core.javaTypeFilters. Take a look at the schema for its definition at org.eclipse.edt.debug.core/schema/javaTypeFilters.exsd. Reference implementations can be found in org.eclipse.edt.debug.core's plugin.xml file (several categories and filters are contributed).

You can choose to have your filter class extend org.eclipse.edt.debug.core.java.filters.AbstractTypeFilter to take care of some common properties but it is not required. You can also choose to not write your own category class, in which case org.eclipse.edt.debug.internal.core.java.filters.DefaultTypeFilterCategory will be used. An example of writing your own category class can be found at org.eclipse.edt.debug.internal.core.java.filters.JDTStepFilterCategory; in this case it's a hidden category that determines whether "step into" or "step return" is used based on the JDT step filter setting, rather than coming from the extension in plugin.xml. In most cases you will not need to write your own category class.