IResourceDelta


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.core.resources;
12  
13  import org.eclipse.core.internal.watson.IElementComparator;
14  import org.eclipse.core.resources.mapping.IResourceChangeDescriptionFactory;
15  import org.eclipse.core.runtime.*;
16  
17  /**
18   * A resource delta represents changes in the state of a resource tree
19   * between two discrete points in time.
20   * <p>
21   * This interface is not intended to be implemented by clients.
22   * </p>
23   * <p>
24   * Resource deltas implement the <code>IAdaptable</code> interface;
25   * extensions are managed by the platform's adapter manager.
26   * </p>
27   *
28   * @see IResource
29   * @see Platform#getAdapterManager()
30   */
31  public interface IResourceDelta extends IAdaptable {
32  
33      /*====================================================================
34       * Constants defining resource delta kinds:
35       *====================================================================*/
36  
37      /**
38       * Delta kind constant indicating that the resource has not been changed in any way.
39       * 
40       * @see IResourceDelta#getKind()
41       */
42      public static final int NO_CHANGE = IElementComparator.K_NO_CHANGE;
43  
44      /**
45       * Delta kind constant (bit mask) indicating that the resource has been added
46       * to its parent. That is, one that appears in the "after" state,
47       * not in the "before" one.
48       * 
49       * @see IResourceDelta#getKind()
50       */
51      public static final int ADDED = 0x1;
52  
53      /**
54       * Delta kind constant (bit mask) indicating that the resource has been removed
55       * from its parent. That is, one that appears in the "before" state,
56       * not in the "after" one. 
57       * 
58       * @see IResourceDelta#getKind()
59       */
60      public static final int REMOVED = 0x2;
61  
62      /**
63       * Delta kind constant (bit mask) indicating that the resource has been changed. 
64       * That is, one that appears in both the "before" and "after" states.
65       * 
66       * @see IResourceDelta#getKind()
67       */
68      public static final int CHANGED = 0x4;
69  
70      /**
71       * Delta kind constant (bit mask) indicating that a phantom resource has been added at
72       * the location of the delta node. 
73       * 
74       * @see IResourceDelta#getKind()
75       */
76      public static final int ADDED_PHANTOM = 0x8;
77  
78      /**
79       * Delta kind constant (bit mask) indicating that a phantom resource has been removed from 
80       * the location of the delta node. 
81       * 
82       * @see IResourceDelta#getKind()
83       */
84      public static final int REMOVED_PHANTOM = 0x10;
85  
86      /**
87       * The bit mask which describes all possible delta kinds,
88       * including ones involving phantoms.
89       * 
90       * @see IResourceDelta#getKind()
91       */
92      public static final int ALL_WITH_PHANTOMS = CHANGED | ADDED | REMOVED | ADDED_PHANTOM | REMOVED_PHANTOM;
93  
94      /*====================================================================
95       * Constants which describe resource changes:
96       *====================================================================*/
97  
98      /**
99       * Change constant (bit mask) indicating that the content of the resource has changed.
100      * 
101      * @see IResourceDelta#getFlags() 
102      */
103     public static final int CONTENT = 0x100;
104 
105     /**
106      * Change constant (bit mask) indicating that the resource was moved from another location.
107      * The location in the "before" state can be retrieved using <code>getMovedFromPath()</code>.
108      * 
109      * @see IResourceDelta#getFlags()
110      */
111     public static final int MOVED_FROM = 0x1000;
112 
113     /**
114      * Change constant (bit mask) indicating that the resource was moved to another location.
115      * The location in the new state can be retrieved using <code>getMovedToPath()</code>.
116      * 
117      * @see IResourceDelta#getFlags()
118      */
119     public static final int MOVED_TO = 0x2000;
120 
121     /**
122      * Change constant (bit mask) indicating that the resource was copied from another location.
123      * The location in the "before" state can be retrieved using <code>getMovedFromPath()</code>.
124      * This flag is only used when describing potential changes using an {@link IResourceChangeDescriptionFactory}.
125      * 
126      * @see IResourceDelta#getFlags()
127      * @since 3.2
128      */
129     public static final int COPIED_FROM = 0x800;
130     /**
131      * Change constant (bit mask) indicating that the resource was opened or closed.
132      * This flag is also set when the project did not exist in the "before" state.
133      * For example, if the current state of the resource is open then it was previously closed
134      * or did not exist.
135      * 
136      * @see IResourceDelta#getFlags()
137      */
138     public static final int OPEN = 0x4000;
139 
140     /**
141      * Change constant (bit mask) indicating that the type of the resource has changed.
142      * 
143      * @see IResourceDelta#getFlags()
144      */
145     public static final int TYPE = 0x8000;
146 
147     /**
148      * Change constant (bit mask) indicating that the resource's sync status has changed.
149      * This type of change is not included in build deltas, only in those for resource notification.
150      * 
151      * @see IResourceDelta#getFlags()
152      */
153     public static final int SYNC = 0x10000;
154 
155     /**
156      * Change constant (bit mask) indicating that the resource's markers have changed.
157      * This type of change is not included in build deltas, only in those for resource notification.
158      * 
159      * @see IResourceDelta#getFlags()
160      */
161     public static final int MARKERS = 0x20000;
162 
163     /**
164      * Change constant (bit mask) indicating that the resource has been
165      * replaced by another at the same location (i.e., the resource has 
166      * been deleted and then added). 
167      * 
168      * @see IResourceDelta#getFlags()
169      */
170     public static final int REPLACED = 0x40000;
171 
172     /**
173      * Change constant (bit mask) indicating that a project's description has changed. 
174      * 
175      * @see IResourceDelta#getFlags()
176      */
177     public static final int DESCRIPTION = 0x80000;
178 
179     /**
180      * Change constant (bit mask) indicating that the encoding of the resource has changed.
181      * 
182      * @see IResourceDelta#getFlags() 
183      * @since 3.0
184      */
185     public static final int ENCODING = 0x100000;
186 
187     /**
188      * Accepts the given visitor.
189      * The only kinds of resource deltas visited 
190      * are <code>ADDED</code>, <code>REMOVED</code>, 
191      * and <code>CHANGED</code>.
192      * The visitor's <code>visit</code> method is called with this
193      * resource delta if applicable. If the visitor returns <code>true</code>,
194      * the resource delta's children are also visited.
195      * <p>
196      * This is a convenience method, fully equivalent to 
197      * <code>accept(visitor, IResource.NONE)</code>.
198      * Although the visitor will be invoked for this resource delta, it will not be
199      * invoked for any team-private member resources.
200      * </p>
201      *
202      * @param visitor the visitor
203      * @exception CoreException if the visitor failed with this exception.
204      * @see IResourceDeltaVisitor#visit(IResourceDelta)
205      */
206     public void accept(IResourceDeltaVisitor visitor) throws CoreException;
207 
208     /** 
209      * Accepts the given visitor.
210      * The visitor's <code>visit</code> method is called with this
211      * resource delta. If the visitor returns <code>true</code>,
212      * the resource delta's children are also visited.
213      * <p>
214      * This is a convenience method, fully equivalent to:
215      * <pre>
216      *   accept(visitor, includePhantoms ? INCLUDE_PHANTOMS : IResource.NONE);
217      * </pre>
218      * Although the visitor will be invoked for this resource delta, it will not be
219      * invoked for any team-private member resources.
220      * </p>
221      *
222      * @param visitor the visitor
223      * @param includePhantoms <code>true</code> if phantom resources are
224      *   of interest; <code>false</code> if phantom resources are not of
225      *   interest
226      * @exception CoreException if the visitor failed with this exception.
227      * @see #accept(IResourceDeltaVisitor)
228      * @see IResource#isPhantom()
229      * @see IResourceDeltaVisitor#visit(IResourceDelta)
230      */
231     public void accept(IResourceDeltaVisitor visitor, boolean includePhantoms) throws CoreException;
232 
233     /** 
234      * Accepts the given visitor.
235      * The visitor's <code>visit</code> method is called with this
236      * resource delta. If the visitor returns <code>true</code>,
237      * the resource delta's children are also visited.
238      * <p>
239      * The member flags determine which child deltas of this resource delta will be visited.
240      * The visitor will always be invoked for this resource delta.
241      * <p>
242      * If the <code>INCLUDE_PHANTOMS</code> member flag is not specified
243      * (recommended), only child resource deltas involving existing resources will be visited
244      * (kinds <code>ADDED</code>, <code>REMOVED</code>, and <code>CHANGED</code>).
245      * If the <code>INCLUDE_PHANTOMS</code> member flag is specified,
246      * the result will also include additions and removes of phantom resources
247      * (kinds <code>ADDED_PHANTOM</code> and <code>REMOVED_PHANTOM</code>).
248      * </p>
249      * <p>
250      * If the <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code> member flag is not specified
251      * (recommended), resource deltas involving team private member resources will be 
252      * excluded from the visit. If the <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code> member
253      * flag is specified, the visit will also include additions and removes of
254      * team private member resources.
255      * </p>
256      *
257      * @param visitor the visitor
258      * @param memberFlags bit-wise or of member flag constants
259      *   (<code>IContainer.INCLUDE_PHANTOMS</code> and <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code>)
260      *   indicating which members are of interest
261      * @exception CoreException if the visitor failed with this exception.
262      * @see IResource#isPhantom()
263      * @see IResource#isTeamPrivateMember()
264      * @see IContainer#INCLUDE_PHANTOMS
265      * @see IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS
266      * @see IResourceDeltaVisitor#visit(IResourceDelta)
267      * @since 2.0
268      */
269     public void accept(IResourceDeltaVisitor visitor, int memberFlags) throws CoreException;
270 
271     /**
272      * Finds and returns the descendent delta identified by the given path in
273      * this delta, or <code>null</code> if no such descendent exists.
274      * The supplied path may be absolute or relative; in either case, it is
275      * interpreted as relative to this delta.   Trailing separators are ignored.
276      * If the path is empty this delta is returned.
277      * <p>
278      * This is a convenience method to avoid manual traversal of the delta
279      * tree in cases where the listener is only interested in changes to
280      * particular resources.  Calling this method will generally be
281      * faster than manually traversing the delta to a particular descendent.
282      * </p>
283      * @param path the path of the desired descendent delta
284      * @return the descendent delta, or <code>null</code> if no such
285      *      descendent exists in the delta
286      * @since 2.0
287      */
288     public IResourceDelta findMember(IPath path);
289 
290     /**
291      * Returns resource deltas for all children of this resource 
292      * which were added, removed, or changed. Returns an empty
293      * array if there are no affected children.
294      * <p>
295      * This is a convenience method, fully equivalent to:
296      * <pre>
297      *   getAffectedChildren(ADDED | REMOVED | CHANGED, IResource.NONE);
298      * </pre>
299      * Team-private member resources are <b>not</b> included in the result; neither are
300      * phantom resources.
301      * </p>
302      *
303      * @return the resource deltas for all affected children
304      * @see IResourceDelta#ADDED
305      * @see IResourceDelta#REMOVED
306      * @see IResourceDelta#CHANGED
307      * @see #getAffectedChildren(int,int)
308      */
309     public IResourceDelta[] getAffectedChildren();
310 
311     /**
312      * Returns resource deltas for all children of this resource 
313      * whose kind is included in the given mask. Kind masks are formed
314      * by the bitwise or of <code>IResourceDelta</code> kind constants.
315      * Returns an empty array if there are no affected children.
316      * <p>
317      * This is a convenience method, fully equivalent to:
318      * <pre>
319      *   getAffectedChildren(kindMask, IResource.NONE);
320      * </pre>
321      * Team-private member resources are <b>not</b> included in the result.
322      * </p>
323      *
324      * @param kindMask a mask formed by the bitwise or of <code>IResourceDelta </code> 
325      *    delta kind constants
326      * @return the resource deltas for all affected children
327      * @see IResourceDelta#ADDED
328      * @see IResourceDelta#REMOVED
329      * @see IResourceDelta#CHANGED
330      * @see IResourceDelta#ADDED_PHANTOM
331      * @see IResourceDelta#REMOVED_PHANTOM
332      * @see IResourceDelta#ALL_WITH_PHANTOMS
333      * @see #getAffectedChildren(int,int)
334      */
335     public IResourceDelta[] getAffectedChildren(int kindMask);
336 
337     /**
338      * Returns resource deltas for all children of this resource 
339      * whose kind is included in the given mask. Masks are formed
340      * by the bitwise or of <code>IResourceDelta</code> kind constants.
341      * Returns an empty array if there are no affected children.
342      * <p>
343      * If the <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code> member flag is not specified,
344      * (recommended), resource deltas involving team private member resources will be 
345      * excluded. If the <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code> member
346      * flag is specified, the result will also include resource deltas of the 
347      * specified kinds to team private member resources.
348      * </p>
349      * <p>
350      * Specifying the <code>INCLUDE_PHANTOMS</code> member flag is equivalent
351      * to including <code>ADDED_PHANTOM</code> and <code>REMOVED_PHANTOM</code>
352      * in the kind mask.
353      * </p>
354      *
355      * @param kindMask a mask formed by the bitwise or of <code>IResourceDelta </code> 
356      *    delta kind constants
357      * @param memberFlags bit-wise or of member flag constants
358      *   (<code>IContainer.INCLUDE_PHANTOMS</code> and <code>INCLUDE_TEAM_PRIVATE_MEMBERS</code>)
359      *   indicating which members are of interest
360      * @return the resource deltas for all affected children
361      * @see IResourceDelta#ADDED
362      * @see IResourceDelta#REMOVED
363      * @see IResourceDelta#CHANGED
364      * @see IResourceDelta#ADDED_PHANTOM
365      * @see IResourceDelta#REMOVED_PHANTOM
366      * @see IResourceDelta#ALL_WITH_PHANTOMS
367      * @see IContainer#INCLUDE_PHANTOMS
368      * @see IContainer#INCLUDE_TEAM_PRIVATE_MEMBERS
369      * @since 2.0
370      */
371     public IResourceDelta[] getAffectedChildren(int kindMask, int memberFlags);
372 
373     /**
374      * Returns flags which describe in more detail how a resource has been affected.
375      * <p>
376      * The following codes (bit masks) are used when kind is <code>CHANGED</code>, and
377      * also when the resource is involved in a move:
378      * <ul>
379      * <li><code>CONTENT</code> - The bytes contained by the resource have 
380      *      been altered, or <code>IResource.touch</code> has been called on 
381      *      the resource.</li>
382      * <li><code>ENCODING</code> - The encoding of the resource may have been altered.
383      * This flag is not set when the encoding changes due to the file being modified, 
384      * or being moved.</li>
385      * <li><code>DESCRIPTION</code> - The description of the project has been altered,
386      *      or <code>IResource.touch</code> has been called on the project.
387      *      This flag is only valid for project resources.</li>
388      * <li><code>OPEN</code> - The project's open/closed state has changed.
389      *      If it is not open, it was closed, and vice versa.  This flag is only valid for project resources.</li>
390      * <li><code>TYPE</code> - The resource (a folder or file) has changed its type.</li>
391      * <li><code>SYNC</code> - The resource's sync status has changed.</li>
392      * <li><code>MARKERS</code> - The resource's markers have changed.</li>
393      * <li><code>REPLACED</code> - The resource (and all its properties)
394      *  was deleted (either by a delete or move), and was subsequently re-created
395      *  (either by a create, move, or copy).</li>
396      * </ul>
397      * The following code is only used if kind is <code>REMOVED</code>
398      * (or <code>CHANGED</code> in conjunction with <code>REPLACED</code>):
399      * <ul>
400      * <li><code>MOVED_TO</code> - The resource has moved.
401      *  <code>getMovedToPath</code> will return the path of where it was moved to.</li>
402      * </ul>
403      * The following code is only used if kind is <code>ADDED</code>
404      * (or <code>CHANGED</code> in conjunction with <code>REPLACED</code>):
405      * <ul>
406      * <li><code>MOVED_FROM</code> - The resource has moved.
407      *  <code>getMovedFromPath</code> will return the path of where it was moved from.</li>
408      * </ul>
409      * A simple move operation would result in the following delta information.
410      * If a resource is moved from A to B (with no other changes to A or B), 
411      * then A will have kind <code>REMOVED</code>, with flag <code>MOVED_TO</code>, 
412      * and <code>getMovedToPath</code> on A will return the path for B.  
413      * B will have kind <code>ADDED</code>, with flag <code>MOVED_FROM</code>, 
414      * and <code>getMovedFromPath</code> on B will return the path for A.
415      * B's other flags will describe any other changes to the resource, as compared
416      * to its previous location at A.
417      * </p>
418      * <p>
419      * Note that the move flags only describe the changes to a single resource; they
420      * don't necessarily imply anything about the parent or children of the resource.  
421      * If the children were moved as a consequence of a subtree move operation, 
422      * they will have corresponding move flags as well.
423      * </p>
424      * <p>
425      * Note that it is possible for a file resource to be replaced in the workspace
426      * by a folder resource (or the other way around).
427      * The resource delta, which is actually expressed in terms of
428      * paths instead or resources, shows this as a change to either the
429      * content or children.
430      * </p>
431      *
432      * @return the flags
433      * @see IResourceDelta#CONTENT
434      * @see IResourceDelta#DESCRIPTION
435      * @see IResourceDelta#ENCODING
436      * @see IResourceDelta#OPEN
437      * @see IResourceDelta#MOVED_TO
438      * @see IResourceDelta#MOVED_FROM
439      * @see IResourceDelta#TYPE
440      * @see IResourceDelta#SYNC
441      * @see IResourceDelta#MARKERS
442      * @see IResourceDelta#REPLACED
443      * @see #getKind()
444      * @see #getMovedFromPath()
445      * @see #getMovedToPath()
446      * @see IResource#move(IPath, int, IProgressMonitor)
447      */
448     public int getFlags();
449 
450     /**
451      * Returns the full, absolute path of this resource delta.
452      * <p>
453      * Note: the returned path never has a trailing separator.
454      * </p>
455      * @return the full, absolute path of this resource delta
456      * @see IResource#getFullPath()
457      * @see #getProjectRelativePath()
458      */
459     public IPath getFullPath();
460 
461     /**
462      * Returns the kind of this resource delta.
463      * Normally, one of <code>ADDED</code>, 
464      * <code>REMOVED</code>, <code>CHANGED</code>.
465      * When phantom resources have been explicitly requested,
466      * there are two additional kinds: <code>ADDED_PHANTOM</code> 
467      * and <code>REMOVED_PHANTOM</code>.
468      *
469      * @return the kind of this resource delta
470      * @see IResourceDelta#ADDED
471      * @see IResourceDelta#REMOVED
472      * @see IResourceDelta#CHANGED
473      * @see IResourceDelta#ADDED_PHANTOM
474      * @see IResourceDelta#REMOVED_PHANTOM
475      */
476     public int getKind();
477 
478     /**
479      * Returns the changes to markers on the corresponding resource.
480      * Returns an empty array if no markers changed.
481      *
482      * @return the marker deltas
483      */
484     public IMarkerDelta[] getMarkerDeltas();
485 
486     /**
487      * Returns the full path (in the "before" state) from which this resource 
488      * (in the "after" state) was moved.  This value is only valid 
489      * if the <code>MOVED_FROM</code> change flag is set; otherwise,
490      * <code>null</code> is returned.
491      * <p>
492      * Note: the returned path never has a trailing separator.
493      *
494      * @return a path, or <code>null</code>
495      * @see #getMovedToPath()
496      * @see #getFullPath()
497      * @see #getFlags()
498      */
499     public IPath getMovedFromPath();
500 
501     /**
502      * Returns the full path (in the "after" state) to which this resource 
503      * (in the "before" state) was moved.  This value is only valid if the 
504      * <code>MOVED_TO</code> change flag is set; otherwise,
505      * <code>null</code> is returned.
506      * <p>
507      * Note: the returned path never has a trailing separator.
508      * 
509      * @return a path, or <code>null</code>
510      * @see #getMovedFromPath()
511      * @see #getFullPath()
512      * @see #getFlags()
513      */
514     public IPath getMovedToPath();
515 
516     /**
517      * Returns the project-relative path of this resource delta.
518      * Returns the empty path for projects and the workspace root.
519      * <p>
520      * A resource's project-relative path indicates the route from the project
521      * to the resource.  Within a workspace, there is exactly one such path
522      * for any given resource. The returned path never has a trailing separator.
523      * </p>
524      * @return the project-relative path of this resource delta
525      * @see IResource#getProjectRelativePath()
526      * @see #getFullPath()
527      * @see Path#EMPTY
528      */
529     public IPath getProjectRelativePath();
530 
531     /**
532      * Returns a handle for the affected resource.
533      * <p> 
534      * For additions (<code>ADDED</code>), this handle describes the newly-added resource; i.e.,
535      * the one in the "after" state.
536      * <p> 
537      * For changes (<code>CHANGED</code>), this handle also describes the resource in the "after"
538      * state. When a file or folder resource has changed type, the
539      * former type of the handle can be inferred.
540      * <p>
541      * For removals (<code>REMOVED</code>), this handle describes the resource in the "before" 
542      * state. Even though this resource would not normally exist in the
543      * current workspace, the type of resource that was removed can be
544      * determined from the handle.
545      * <p> 
546      * For phantom additions and removals (<code>ADDED_PHANTOM</code>
547      * and <code>REMOVED_PHANTOM</code>), this is the handle of the phantom resource.
548      *
549      * @return the affected resource (handle)
550      */
551     public IResource getResource();
552 }
553
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags