Request For Comment

DRAFT of RFC 0004

Marker Position Updates

Summary
When files in the workspace are modified, attributes of markers in those files, such as character and line positions, may become invalid. A general, centralized mechanism is needed for updating marker attributes after file modifications.

By John Arthorne, OTI.
Created: November 29, 2001
Last Modified: December 4, 2001

Motivation

There are many different components that perform textual manipulation of files. Some examples in the Eclipse Platform SDK include: editors, the JDOM API for manipulating java elements, the java refactoring API, and the compare framework. When file contents are changed, it may cause some of the attributes of markers on those files to become invalid. For example, if lines are added to a text file in an editor, the CHAR_START, CHAR_END, and LINE_NUMBER attributes of text markers may need to be updated.

Currently, each component that performs text manipulations is responsible for updating any marker attributes that may be affected by the change. This leads to a duplication of the update algorithms in several places. Furthermore, different marker types may need to be updated in different ways. For example, if an extra comment line is added to a java source file, it may be appropriate to move any breakpoints on that line down to the next line with a valid java statement, but it might make sense to leave a bookmark at its original location. In the current story, if marker-specific updates are needed, each component that manipulates files would need to know how to update each marker type. This knowledge is not always possible; for example the text editor does not know about java breakpoints.

The purpose of this proposal is to provide a central point where components that manipulate files can trigger the file's markers to be updated. This central point should know how to update each marker type that has a unique update strategy.

Proposed Solution

Update API

The initial proposal is to add a method to IFile. This is based on the description provided by Jeem: 

/**
 * Updates the text markers in this file, based on the provided edit information.
 * @param replaceStart The character position at the start of the replaced range. This value
 *		is zero-relative and inclusive.
 * @param replaceEnd The character position at the end of the replaced range.  This value
 *		is zero-relative and exclusive.
 * @param replaceSize The size of the new block that replaced the range described by
 *		replaceStart and replaceEnd.
 * @throws CoreException If this method fails.  Reasons include:
 * <ul>
 * <li>The given range is invalid.</li>
 * </ul>
 */
public void updateMarkers(int replaceStart, int replaceEnd, int replaceSize) throws CoreException;
The idea is that this API can describe any single edit to a file. Examples (again from Jeem):
  1. updateMarkers(0, 100, 10) - replace first 100 characters of file with ten characters.
  2. updateMarkers(200, 300, 0) - delete the character range from 200 to 300.
  3. updateMarkers(400,400, 1) - Add a character at position 400.

Extensibility API

Some marker types may require a special update algorithm. The idea is to provide a way for marker types to define how marker updates occur through the markers extension point. The proposal is to add an extra optional element to a marker definition, to plug in a marker update algorithm. Here is an example marker definition: 

<extension 
	id="mycustommarker" 
	point="org.eclipse.core.resources.markers" 
	name="The Foo Marker">
  <super type="org.eclipse.core.resources.textmarker" />
  <persistent value="true" />
  <update class="org.xyz.foo.FooMarkerUpdate">
  </extension>
The update class would implement a new interface, IMarkerUpdate. This interface has a method similar to the updateMarkers method described above. Markers with no update class specified inherit a marker update from one of their marker supertypes. Supertypes would be searched breadth-first, in the order the supertypes appear in the marker declaration (or perhaps in an indeterminate order). Core will provide IMarkerUpdates for the standard marker types that it defines (marker, text marker, problem, task, bookmark).

Open Question: Line number update. How the LINE_NUMBER attribute will be updated is an open question. One possibility is that there would be two separate methods, one for character updates, and one for line updates. It is not known if or how the various marker types make use of the LINE_NUMBER attribute. Perhaps it is redundant information and can be recomputed on demand when needed. A character update algorithm could theoretically infer the line number changes, but this would require knowledge of line terminators, etc. This would also be significantly slower if it required an independent scan of the file to recompute line numbers during update.

RFC Status

This RFC has been shelved for consideration after the 2.0 release. The interested parties have not yet achieved consensus on the form a marker update mechanism should take.
Comments should be directed to the core mailing list: platform-core-dev@eclipse.org (post, archives).