| <!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="GENERATOR" content="Mozilla/4.75 [en] (Windows NT 5.0; U) [Netscape]"> |
| <title>JDT - Java Element Deltas</title> |
| </head> |
| <body> |
| |
| <h2> |
| Java Element Deltas</h2> |
| Last revised 12:00 Thursday September 6, 2001 |
| <p>Original work item: "IJavaElementDelta should carry information about |
| marker changes (ProblemMarkers)."</p> |
| <h3> |
| Markers and Java Elements</h3> |
| The workspace allows markers to be associated with resources. The Java |
| compiler associates Java problem markers with Java source files; these |
| markers locate the error within the compilation unit by source character |
| position. |
| <p>The Java model does not directly support markers on Java elements. It |
| does provide a means (<tt>ICompilationUnit.getElementAt</tt>) for mapping |
| from a source character position within a compilation unit resource to |
| the nearest enclosing Java element. Since all Java problem markers carry |
| a source character position, any Java problem marker can be mapped to the |
| nearest enclosing Java element. In most cases, this element will be a fine-grained |
| Java element corresponding to a declaration of a Java method, field, type, |
| or import. In the worst case, it maps to the compilation unit element itself. |
| Thus it is always possible in principle to associate markers with Java |
| elements.</p> |
| <p>The Java UI visually annotates Java elements that have problems (with |
| a red X).</p> |
| <p>The cost of mapping from a marker position to a fine-grained Java element |
| requires opening (and parsing) the compilation unit. Once opened, additional |
| markers within the same compilation unit can be mapped with negligible |
| additional cost.</p> |
| <h3> |
| Java Element Deltas</h3> |
| Unlike workspace resource deltas, Java element deltas do not currently |
| include information about marker changes. |
| <p>The Java UI needs to maintain the visual annotations on Java elements |
| that have problems.</p> |
| <p>There are three kinds of Java element deltas issued:</p> |
| <ol> |
| <li> |
| By the Java model when <tt>IWorkingCopy.commit</tt> is called to save a |
| compilation unit working copy.</li> |
| |
| <li> |
| By the Java model when <tt>IWorkingCopy.reconcile</tt> is called during |
| editing.</li> |
| |
| <li> |
| By the Java model in response to notification of a workspace resource delta |
| affecting a compilation unit resource.</li> |
| </ol> |
| <p>The first two kinds of Java element delta are always issued against fine-grained |
| Java elements. The previous fine-grained structure of the compilation unit |
| is compared to the current fine-grained structure. These deltas are recognizable |
| as kind <tt>CHANGED</tt> at the compilation unit level with <tt>F_CHILDREN</tt> |
| flag set and <tt>F_CONTENT</tt> flag <i>not</i> set.</p> |
| <p>The last kind of Java element delta is never fine-grained; it goes no |
| finer than the compilation unit element itself. This is because the fine-grained |
| structure of the previous state of the compilation unit is not available |
| (the Java model does not necessarily have a record of the previous structure |
| (although it <i>might </i>be in an internal cache), and cannot compute |
| it since it does not a copy of the previous state of the compilation unit). |
| These deltas are recognizable as kind <tt>CHANGED</tt> at the compilation |
| unit level with <tt>F_CHILDREN</tt> flag <i>not </i>set and with <tt>F_CONTENT</tt> |
| flag set.</p> |
| <h3> |
| Markers and Java Element Deltas</h3> |
| <p>Java problems markers on Java compilation units originate when the Java |
| builder is called. These markers are associated with Java compilation unit |
| files, and come to the attention of the Java model via a problem delta |
| associated with the resource delta that follows the build. The Java builder |
| only deletes or adds Java problem markers; it never changes existing ones. |
| The Java builder does not decorate Java problem markers with information |
| other than the source character position.</p> |
| <p><tt>(IWorkingCopy.reconcile</tt> also returns a set of tranisent markers.) </p> |
| <p>When the user opens a compilation unit, the Java editor creates and |
| locates visual markers corresponding to the Java problem markers. These |
| visual markers are sticky, and move around as the text is edited.</p> |
| <p>When the user navigates into an already open compilatation unit from |
| a problem marker in the Tasks view, the Java editor automatically adjusts |
| the positions to account for recent edits.</p> |
| <p>When the Java editor saves a compilation unit, it permanently adjusts |
| the source positions of Java problem markers associated with the corresponding |
| compilation unit. This is done because the next build may be a ways off |
| and these markers show up in the Tasks view (the Java editor might be closed).</p> |
| <p>Java element deltas also carry information about non-Java resources; |
| this is surfaced by <tt>IJavaElementDelta.getResourceDeltas</tt>. This |
| works as follows: when a non-Java resource is affected, the corresponding |
| resource delta is exposed on the nearest parent Java element. For files |
| directly under the project, the resource delta will be associated with |
| Java element delta for the <tt>IJavaProject</tt>; for files sitting in |
| the same folder as a Java source file, the resource delta will be associated |
| with Java element delta for the <tt>IPackageFragment</tt>; for files sitting |
| inside a source folder but not in any package fragment, the resource delta |
| will be associated with Java element delta for the <tt>IPackageFragmentRoot</tt> |
| (this includes the case where the project itself is a package fragment |
| root. Thus the <tt>IJavaElementDelta.getResourceDeltas</tt> mechanism is |
| only of use for discovering non-resource deltas; it is not useful for discovering |
| marker changes to resources corresponding to Java elements.</p> |
| <p>Thus the only way a client can find out about most marker deltas is |
| to register its own resource change listener with the workspace. Since |
| the client would still need to register a Java model change listener, having |
| to do raises the question of relative ordering of these two notifications |
| (there is no guarantee which will comes first).</p> |
| <h3> |
| Proposal: Expose corresponding resource deltas on Java element delta</h3> |
| The proposed change is to improve the Java element delta to expose the |
| corresponding resource deltas whenever they are available. This would be |
| done via the following new method on <tt>IJavaElementDelta</tt>: |
| <p><tt>/**</tt> |
| <br><tt> * Returns the workspace resource delta for the resource that |
| corresponds directly to the</tt> |
| <br><tt> * Java element, or <code>null</code> if either there |
| is no resource that corresponds</tt> |
| <br><tt> * to the Java element, or there is a corresponding resource |
| but there is no resource delta</tt> |
| <br><tt> * for it.</tt> |
| <br><tt> * <p></tt> |
| <br><tt> * Note that a Java element delta that does not arise from |
| a workspace resource delta will always</tt> |
| <br><tt> * return <code>null</code>.</tt> |
| <br><tt> * </p></tt> |
| <br><tt> * <p></tt> |
| <br><tt> * If the result is non-<code>null</code>, then</tt> |
| <br><tt> * <code>getCorrespondingResourceDelta().getResource()</code> |
| is the same resource as</tt> |
| <br><tt> * <code>getElement().getCorrespondingResource()</code>.</tt> |
| <br><tt> * </p></tt> |
| <br><tt> *</tt> |
| <br><tt> * @return the corresponding workspace resource delta, or |
| <code>null</code> if not applicable or none</tt> |
| <br><tt> */</tt> |
| <br><tt>public IResourceDelta getCorrespondingResourceDelta();</tt></p> |
| <p>Resource deltas will be available when the Java element delta results |
| from the Java model receiving a resource change notification. When this |
| happens, the resource delta for the corresponding will be made available |
| from the Java element delta for the Java element:</p> |
| <ul> |
| <li> |
| Java project: expose resource delta for the corresponding project resource.</li> |
| |
| <li> |
| Java compilation unit: expose resource delta for the corresponding Java |
| source file.</li> |
| |
| <li> |
| Java class file: expose resource delta for the corresponding Java class |
| file.</li> |
| |
| <li> |
| Java package fragment root: expose resource delta for the corresponding |
| source folder, jar or zip file.</li> |
| |
| <li> |
| Java package fragment: expose resource delta for the corresponding package |
| folder under a source package fragment root.</li> |
| </ul> |
| Note that the proposed API change would not break compatibility with Eclipse |
| 1.0. It adds a new method to an interface that is not intended to be implemented |
| by clients. |
| <p>With the proposed change, a client of the Java model would be able to |
| discover marker changes to both Java and non-Java resource by registering |
| for Java model changes and composing <tt>IJavaElementDelta.getCorrespondingResourceDelta</tt> |
| and <tt>IResourceDelta.getMarkerDeltas</tt>. These marker changes will |
| only be present on Java element deltas stemming from workspace resource |
| deltas. They are no marker deltas associated with fine-grained Java element |
| deltas arising from working copy reconciliation or saving (no markers have |
| changes).</p> |
| <p>Other things we considered:</p> |
| <ul> |
| <li> |
| For the case where a coarse-grained Java element deltas is issued, add |
| marker delta information to Java elements finer than the compilation unit. |
| This is not feasible because there would be no way to compute fine-grained |
| Java element or marker deltas since the Java model has no "before" state |
| to compare against.</li> |
| |
| <li> |
| For the cases where a fine-grained Java element deltas is issued, add marker |
| delta information to Java elements finer than the compilation unit. This |
| is not feasible because the markers aren't changing in this case, and the |
| Java model itself is not in the business of adjusting markers.</li> |
| </ul> |
| |
| <h3> |
| Document History</h3> |
| |
| <ul> |
| <li> |
| 13:45 Thursday August 31, 2001 - First proposal send to Erich and Philippe</li> |
| |
| <li> |
| 16:30 Wednesday Sepember 5, 2001 - Modified after discussion with Erich |
| and Martin.</li> |
| |
| <li> |
| 12:00 Thursday September 6, 2001 - Modified after discussion with Jerome |
| who clarified how <tt>IJavaElementDelta.getResourceDeltas</tt> works.</li> |
| </ul> |
| |
| </body> |
| </html> |
