Summary
Support for marker help and marker resolution provides an opportunity to add significant useful functionality to the eclipse platform. Marker help support means that the user will be able to select a marker, press F1, and receive specific help for the selected marker. Resolution support will allow the user to select a resolution for a particular marker. Resolutions could invoke any arbitrary code but would typically involve correcting a problem indicated by the marker or performing a required task.

By Randy Giffen and Karice McIntyre, OTI
Last Modified: 7 Dec, 2001 - Added comments from Nick Edgar

The Details

Problem

Background Info

Markers are defined using the org.eclipse.core.resources.markers extension point. The org.eclipse.core.resources plug-in defines a base marker type and several standard subtypes (problem, task, bookmark, and textmarker). There is currently no general way to identify a specific "kind" of marker (at the granularity needed to associate it with a help context or resolution). IMarker does define a getId method. However, this id is unique relative to the resource with which the marker is associated, it is not globally unique. More importantly, this id is instance-based. Thus two makers which are the same kind of marker will return different values for getId.

The org.eclipse.core.resources.markers extension point allows plug-ins to declare new marker subtypes but, in most cases, marker type is too coarse to use as a way of indicating specific kinds of markers. Marker attributes can be used for such a purpose. However, for most markers there is no defined attribute that would be appropriate for this purpose. For example, the following are the extension declarations in the org.eclipse.core.resources plug-in for problem and task markers:

<extension id="problemmarker" point="org.eclipse.core.resources.markers" name="%problemName">
   <super type="org.eclipse.core.resources.marker"/>
   <persistent value="true"/>
   <attribute name="severity"/>
   <attribute name="message"/>
   <attribute name="location"/>
</extension>
<extension id="taskmarker" point="org.eclipse.core.resources.markers" name="%taskName">
   <super type="org.eclipse.core.resources.marker"/>
   <persistent value="true"/>
   <attribute name="priority"/>
   <attribute name="message"/>
   <attribute name="done"/>
</extension>

Only the message attribute is likely to identify the specific kind of marker to associate with a F1 help context id. However this attribute cannot be used as its value is not unique across maker types and its value will be locale specific.
Other marker types may define an attribute that would be appropriate for this purpose. For example, the following is the extension declaration in the org.eclipse.jdt.core plug-in for java problem markers:

<extension id="problem" point="org.eclipse.core.resources.markers" name="%javaProblemName">
   <super type="org.eclipse.core.resources.problemmarker"/>
   <super type="org.eclipse.core.resources.textmarker"/>
   <persistent value="true"/>
   <attribute name="id"/>
   <attribute name="flags"/>
</extension>

It declares an "id" attribute that is likely to be appropriate for the purpose of associating a marker with a F1 help context id.

Desired Functionality

F1 Marker help

The API would provide a getHelpContextId(IMarker) method. This method could be added to WorkbenchHelp. The API will only return a single help context id. It is up to help context definers to ensure that ids do not overlap. Note that this method will return a static context id. It will not return an IContextComputer. Furthermore the marker help extension point will only support the specification of a static help context id, it will not allow the specification of an IContextComputer. This is to avoid running plug-in code (and thus possibly triggering plug-in loading) when determining a help context id. Thus the marker help extension point must allow for a precise targeting of specific kinds of markers.
 

Marker Resolutions

It is hard to predict exactly how resolutions will appear in the UI. The may be presented as a list in a dialog or perhaps as a submenu. For example, 1) the task list may add a Resolutions item to its context menu 2) code assist may show a dialog listing resolutions when it encounters a problem such as an unresolved type. However, it is unlikely that they would require the full IAction API. Thus it would be reasonable to define an IMarkerResolution interface as follows:

public interface IMarkerResolution {
    /**
    * Initializes the resolution with the given marker.
    * It is assumed that the marker meets all the criteria specified in the
    * extension point which contributed this resolution.
    */
    public void init(IMarker);
    /**
    * Returns true if the resolution is appropriate for its marker
    */
    public boolean isAppropriate();
    /**
    * Returns a short label indicating what the resolution will do.
    */
    public void getLabel();
    /**
    * Runs this resolution, passing the triggering SWT event.
    */
    public void runWithEvent(Event event);
}

The org.eclipse.ui.markerResolution extension point will require a label, class name and targeting criteria to map a particular kind of marker to a resolution (see options below). While the label defined in the extension point (ex. Add import package statement) will be adequate to show the user, it would be more useful to obtain the label programmatically (ex. Add import org.eclipse.swt.widgets). In addition, while targeting criteria can be specified in the extension point, it would be possible to do a further target check programmatically. Thus resolutions will be instantiated before presenting them to the user, if the resolution's plug-in is loaded. Otherwise only the plugin.xml label and targeting will be used. In such a case, if it is later (after plug-in loading and resolution instantiation) determined that a selected resolution is not appropriate, the user will be informed by an info dialog.

An IMarkerResolutionRegistry would be will. API access to this registry could be added to IWorkbench. The registry would return all resolutions appropriate for a given marker (more than one resolution can be offered for a given marker).

Possible Solutions

• It could also be named userId or markerId but id would conflict with the attribute declared by org.eclipse.jdt.core.
• This requires no code changes in core (other than declaring the static field) and would have no impact on size or performance if the attribute was not used.
• This implies that the attribute is relevant for all markers.
• It would be the responsibility of marker creators to set this attribute and publish its value as API so that other plug-ins could reference it.
• The org.eclipse.ui plug-in will define an extension point to associate the value of this attribute with a resolution. The plug-in will create a registry to hold and access this information.
• Difficulties would likely arise with regard to the semantics of the value of this attribute. While we use it as a help id, other plug-ins may want to use it for a different purpose and conflicts could arise (two kinds of markers with the same context help id may require two different ids when the id is used for another purpose).

Example help extension:

1. None required. A help context could be defined for the attribute value using existing help extension points.
2. As an alternative we could provide an extension point to provide a layer of indirection between a marker id and a help context id.

    The level of indirection seems nice and it opens the possibility of mapping one marker id to more than one help context. However, in most cases these would probably seem like pointless extensions that simply slow down plug-in initialization and increase the size of the plug-in registry.

Example resolution extension:

2. The org.eclipse.ui plug-in will define a new marker type called helpmarker. This marker will define a single attribute org.eclipse.ui.helpId (this id would be used for both F1 help contexts and resolutions). This marker would be defined as a super type of any marker for which a helpId would be set.

• This means that several plug-ins might end up declaring a helpfultaskmarker for example (strictly speaking a plug-in would not have to define a subtype since any attribute can be set on any marker type but this is the proper way to do it).
• This approach does not affect the base marker type
• Once again it would be the responsibility of marker creators to set this attribute and publish its value as API so that other plug-ins could reference it.
• The org.eclipse.ui plug-in extension point and registry required to support this option would be similar as for option one.

Example help extension:

1. None required. A help context could be defined for the attribute value using existing help extension points.
2. As an alternative we could provide an extension point to provide a layer of indirection between a marker id and a help context id. However this is probably not needed, developers could always do their own mapping on marker creation if needed.

<extension point="org.eclipse.ui.markerHelp">
   <markerHelp
      helpId="org.eclipse.jdt.core.unresolvedType"
      helpContextId="org.eclipse.jdt.ui.unresolvedType"/>
</extension>
 

Example resolution extension:

3. We leave it up to marker creators to define their markers in such a way (using marker subtypes and attributes) that the markers can be mapped to help context ids and resolutions at the proper granularity.

• The org.eclipse.ui plug-in will define an extension point to associate a help context id or a resolution with a marker. This extension point will allow the specification of:
• a marker type (optional if at least one attribute is specified)
• zero or more key value pairs specifying the attribute name as the key and a value
• It will be complex to create and access a registry for this information (map from marker to help context or resolution).
• Assuming the java problem id attribute has the proper granularity, this would allow help and resolutions to be associated with java problems without any code changes. However, the java problem id attribute values would need to be made public.

Example help extension:

A variation of this is to provide a mapping rule to use the matching attribute value(s) to be substituted as the help context id (or as part of it).
For example, JDT UI could define:

   <markerHelp
      markerType = "org.eclipse.jdt.core.problem">
      <attribute name="id" value="%id%"/>
      <helpContextId value="org.eclipse.jdt.ui.problem%id%"/>
   </markerHelp>

So the actual id value, e.g. "123" would get substituted into the help context id, giving "org.eclipse.jdt.ui.problem123".
This could also be used to implement Proposal 2 in terms of Proposal 3.  For example, Eclipse UI would define an identity mapping:

   <markerHelp
      markerType = "org.eclipse.ui.helpmarker">
      <attribute name="org.eclipse.ui.helpId" value="%helpId%"/>
      <helpContextId value="%helpId%"/>
   </markerHelp>
 

Example resolution extension:

Defense of Solution

RFC

• Provide all comments/feedback to the mailing list.
• Clearly indicate if you are fundamentally opposed to the proposal and provide reasons.

RFC Termination Date