platform-core/old/rfc/0004/index.html - www.eclipse.org/eclipse - Git at Google

 <!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:
  * &lt;ul&gt;
  * &lt;li&gt;The given range is invalid.&lt;/li&gt;
  * &lt;/ul&gt;
  */
 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>
 &lt;extension
 	id="mycustommarker"
 	point="org.eclipse.core.resources.markers"
 	name="The Foo Marker"&gt;
   &lt;super type="org.eclipse.core.resources.textmarker" /&gt;
   &lt;persistent value="true" /&gt;
   &lt;update class="org.xyz.foo.FooMarkerUpdate"&gt;
   &lt;/extension&gt;
 </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>
	<!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>