November 26th, 2008

Extending Eclipse: grouping filters for custom problem markers

The Problems view in Eclipse provides filtering and grouping support for quickly navigating large sets of problem markers. If you’re creating custom problem markers, you can register a custom marker group and associate priorities to the different group entries. This will make navigating your custom markers much faster.

There are three extension points that you need to implement:

The first extension point defines your custom marker type, associating a custom ID with it. The persistent attribute should be set to true if you want your markers to be persisted across the workbench invocations. The list of super types would usually include org.eclipse.core.resources.problemmarker and org.eclipse.core.resources.textmarker. If your custom markers are associated with Java classes, use org.eclipse.jdt.core.problem as well.

The second extension point is used to associate the markers with the text documents. Whenever the document is displayed in the associated editor, it will show the marker annotations in the relevant areas (usually the gutters). The markerType attribute should be the ID of the marker type specified above, and the super attribute would usually be org.eclipse.ui.workbench.texteditor.*, where the last segment is info, warning or error.

The third extension point is used to create a custom marker group, and further categorize the custom markers.

The markerTypeCategory sub-element declares the custom category shown in the Types part of the Configure Contents dialog. The name attribute will be used in the relevant tree node. The markerTypeReference should point to the ID of the marker type specified in the first extension point.

The markerGrouping sub-element declares the custom grouping shown in the Group By popup menu. The name attribute will be used for the popup menu entry, and the id attribute will be used to associate the group entries (see below).

The markerGroupingEntry sub-element is used to group the different custom markers when the parent group is selected in the matching Group By popup menu. If you have different validation / analysis rules, you can group the resulting markers to present a clean visual separation. You can have multiple grouping entries. Each entry has the associated priority – groups with higher priority (use values in 0..100 range) are shown first in the Problems view.

The markerGrouping attribute of the markerGroupingEntry sub-element should point to the ID of the markerGrouping sub-element declared above. The label attribute is used in the Problems view parent node that groups all markers belonging to this grouping entry.

The last piece of configuration is the markerAttributeGrouping sub-element. Its markerType points to the ID of the custom marker from the first extension point, and its attribute is used as a custom attribute on the IMarker (see below) to associate the specific marker with its grouping entry. The markerAttributeMapping sub-elements specify the mapping itself.

Suppose the markerAttributeGrouping.attribute is categoryId. Then, the IMarker will have the following:

marker.setAttribute(“categoryId”, 50)

where 50 is a sample value. Then matching markerAttributeMapping will have value attribute equal to 50, and markerGroupingEntry attribute equal to ID of one of the markerGroupingEntry elements above.

How does it work at runtime? Suppose your org.eclipse.core.resources.marker extension point has the id attribute equal to com.my.company.custom.problem. Then, you create the marker with

IMarker marker = resource.createMarker(“com.my.company.custom.problem”)

set all the usual attributes (line number, priority, severity, message), and then set the categoryId attribute (the name must correspond to the matching markerAttributeGrouping.attribute entry) to one of the values of markerAttributeMapping. This marker will:

  • Be associated with the specific resource.
  • Be shown in the problems view with the set message, priority and severity.
  • If the Problems view is grouped with the custom grouping, the marker’s categoryId value will be used to map it to its grouping entry, and the marker will be placed under the relevant parent node in the tree.