| <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <meta name="Author" content="Build"> |
| <title>DRAFT for RFC 0004 - Marker Position Updates</title> |
| </head> |
| <body bgcolor="#FFFFFF" > |
| <div align="right"> |
| <table border=0 cellspacing=0 cellpadding=2 width="100%"> |
| <tr> |
| <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF"> |
| Request For Comment |
| </font></font></b></td> |
| </tr> |
| </table> |
| </div> |
| <div align="left"> |
| <h1><img src="../images/idea.gif" width="120" height="86"></h1> |
| </div> |
| <h1 align="CENTER">DRAFT of RFC 0004</h1> |
| <h1 align="CENTER">Marker Position Updates</h1> |
| <blockquote> |
| <p><b>Summary</b> <br> |
| 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. |
| <p><b> By John Arthorne, OTI.</b> <br> |
| <font size="-1">Created: November 29, 2001</font><br> |
| <font size="-1">Last Modified: December 4, 2001</font><br> |
| </blockquote> |
| <hr> |
| <h2>Motivation</h2> |
| <p> |
| 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 <tt>CHAR_START</tt>, <tt>CHAR_END</tt>, and <tt>LINE_NUMBER</tt> attributes |
| of text markers may need to be updated. |
| </p> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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. |
| </p> |
| <h2>Proposed Solution</h2> |
| <h3>Update API</h3> |
| <p> |
| The initial proposal is to add a method to IFile. This is based on the description provided by Jeem: |
| <pre> |
| /** |
| * 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; |
| </pre> |
| The idea is that this API can describe any single edit to a file. Examples (again from Jeem): |
| <ol> |
| <li>updateMarkers(0, 100, 10) - replace first 100 characters of file with ten characters.</li> |
| <li>updateMarkers(200, 300, 0) - delete the character range from 200 to 300.</li> |
| <li>updateMarkers(400,400, 1) - Add a character at position 400.</li> |
| </ol> |
| <h3>Extensibility API</h3> |
| <p> |
| 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: |
| <pre> |
| <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> |
| </pre> |
| The update class would implement a new interface, |
| <A HREF="IMarkerUpdate.html">IMarkerUpdate</A>. 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). |
| </p> |
| <p> |
| <b>Open Question:</b> 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. |
| </p> |
| <h2>RFC Status</h2> |
| <p>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. |
| <br>Comments should be directed to the core mailing list: |
| <a href="http://dev.eclipse.org/mailman/listinfo/platform-core-dev">platform-core-dev@eclipse.org</a> |
| (<a href="mailto:platform-core-dev@eclipse.org">post</a>, |
| <a href="http://dev.eclipse.org/mhonarc/lists/platform-core-dev/maillist.html">archives</a>). |
| </p> |
| </body> |
| </html> |